agentleFS
ashfulcraashfulcra/fulcra-tools/skills/fulcra-agent-durable-state/SKILL.md

fulcra-agent-durable-state

Skill10 starsChanged 2 months agoMITView on GitHub

Keep an agent's tooling and working state alive across ephemeral machines by treating the Fulcra File Store as the durable home and local disk as cache: restore on wake, push on change, and never stash a secret in a shared team path.

  • Reads credentials

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Before touching the stash, probe how far this session already got.

    line 29
  2. Distinctive:

    All probes pass → your tooling is durable and current.

    line 41
  3. Very specific:

    Self-heal first: Keep a restore-tooling.sh in the stash that downloads the rest of the bundle, and make it the first line of any scheduled …

    line 74
  4. Very specific:

    Treat filenames as a first filter: if it's called .env, *.key, *token*, or holds a known credential prefix (lin_oauth_…, sk-…, PEM …

    line 88

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Fulcra Agent Durable State

Ephemeral compute + durable Fulcra state = agents that survive their machines.

Cloud agent containers get reclaimed and rolled back. Desktop hosts sleep, reboot, and disappear. Any agent whose tooling lives only on local disk is one filesystem event away from amnesia — and worse than losing a script is silently regaining an old one: a rollback can revert a patched loop to the unpatched version, or restore a rotated credential's stale predecessor, and nothing errors until it misbehaves.

The Fulcra File Store is the piece of the platform that doesn't share the machine's fate. It's the same substrate the coordination bus runs on (versioned, last-writer-wins, survives every container the fleet has lost so far), and fulcra-api auth persists independently of scratch disk. So the pattern is:

Local disk is a cache. The store is the truth.

Where to start — the re-entrancy probes

Before touching the stash, probe how far this session already got. Enter at the first probe that fails (per the repo's skill-quality pattern, docs/skill-quality-pattern.md); every step is safely re-runnable (uploads/downloads are whole-file overwrites, last-writer-wins). Auth probes on fulcra-api (the engine inherits its credentials); the stash probes run on the engine's stash verb:

Probe (run in order)CommandPasses whenIf it fails, enter at
Auth usable?fulcra-api auth print-access-token >/dev/null && echo AUTH-OKprints AUTH-OK (exit 0)fulcra-api auth login — browser sign-in; a headless agent that can't complete it should surface to its operator, not improvise
Stash exists?coord-engine stash list <team> --agent <agent>lists at least one file (not empty)First adoption — nothing durable yet: push your bundle now (see On change below)
Local cache complete?test -x <local-path> for each tool the stash listsevery tool you depend on exists locally and is executableRestore — coord-engine stash pull <team> --agent <agent> --dest <dir> (see On wake below)

All probes pass → your tooling is durable and current; work normally and push on change. A freshly rolled-back container typically fails the third probe and enters at Restore.

The stash convention

Each agent keeps its durable bundle under a per-agent path in the team namespace:

team/<team>/_coord/agents/<agent>/stash/
    manifest.json         # written by `stash push`: per-file sha256 + size + exec bit
    linear-sync.sh        # scripts, loops, config templates
    listener-loop.sh
    restore-tooling.sh    # the self-heal entrypoint (see below)

Three behaviors, mirroring the continuity lifecycle contract:

  1. On wake (fresh session, cron fire, post-rollback): if a tool you expect is missing from local disk, restore before improvising:
    coord-engine stash pull <team> --agent <agent> --dest <dir>
    Pull re-applies each file's executable bit from the manifest and verifies its sha256 — checksum drift exits loud (rc 1) instead of handing you a silently-diverged restore. (No engine on the host yet? The plain fulcra-api file download path still works; the stash is ordinary files.)
  2. On change (you edit a script, fix a bug in a loop): push the canonical copy back immediately — an unstashed fix is a fix a rollback will undo:
    coord-engine stash push <team> <local-path> --agent <agent>
    One step uploads the file and refreshes manifest.json; the push runs the fail-closed secrets guard below.
  3. Self-heal first. Keep a restore-tooling.sh in the stash that downloads the rest of the bundle, and make it the first line of any scheduled job's missing-file branch. A scheduled task's prompt should say "restore from the stash", not "rebuild from memory" — session memory compacts; the store doesn't.

The secrets rule (this is most of the lesson)

Never put a secret in the stash. team/<team>/** is readable by every agent on the bus — that is the point of a bus. A token in a shared path is a token every agent (and every prompt-injection that lands on any agent) can read. Fail closed:

  • Credentials go in the harness's environment configuration (injected env vars), the OS keychain (as Collect does), or an operator-held channel — never *.env files in the stash, no matter how convenient the restore would be.
  • Treat filenames as a first filter: if it's called .env, *.key, *token*, or holds a known credential prefix (lin_oauth_…, sk-…, PEM headers), it does not get uploaded. When in doubt, it's a secret. stash push enforces exactly this, fail-closed: secret-shaped names and credential-shaped content are refused with the tripped rule named; --unsafe-allow-secrets exists for a false positive only, never for a real credential.
  • Config templates with the secret redacted are fine — the restore path then needs only the secret from env config, not the whole file from memory.

The asymmetry is deliberate: losing a script costs one download; leaking a credential costs a rotation and an incident.

Case study (why this skill exists)

One fleet coordinator running in a rollback-prone cloud container lost its scratch tooling to filesystem reverts repeatedly — three times in a single day at the worst. Each loss cost a from-memory rebuild, and two reverts were silent downgrades: a listener loop whose disabled escalation step came back armed, and a credentials file whose rotated-out key came back looking healthy (the first symptom would have been a mystery 401 an hour later). Moving the bundle into a File Store stash turned recovery into one download, made the store copy the arbiter of "which version is current", and kept the rotated token out of shared paths entirely — it rides in environment configuration instead.

Relationship to the other skills

  • fulcra-agent-continuity checkpoints narrative state (objective, decisions, next actions). This skill durably stores operational state (the scripts and config that let you act at all). A waking agent wants both: continuity resume for what it was doing, a stash restore for what it works with.
  • fulcra-agent-automation installs the scheduled jobs; this skill is where those jobs' self-heal branches point.
  • The deterministic bookkeeping for this pattern is the engine's stash push/pull/list verb (manifest + sha256 checksums + the fail-closed secrets guard); the plain fulcra-api file commands remain the no-engine fallback — the stash is ordinary files either way.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.