Filesystem-native agent workflows

A user can start a fairly substantial coding procedure with one ordinary command:

/execute-plan Add empty-input handling to the parser and run focused checks

What appears on screen is neither a graph editor nor an undifferentiated stream of agent messages. The workflow creates a plan, shows the resulting worklist, runs an agent for each implementation step, and keeps the current step visible until it can return a final result.

● Plan r1 · 1/3 · active
✓ 1. Inspect parser behavior
● 2. Add empty-input handling and coverage
○ 3. Run focused checks

This small interaction already explains why the rest of the system exists. The interface can show a worklist because worklists are part of the workflow language, rather than something guessed from an agent’s prose. The run survives a closed terminal because the Linux service manager, systemd, owns the process. The implementation agents work on a private copy of the project, and when they finish, the host—not the workflow—decides whether their changes are safe to apply.

Five questions lead from source to live files

Taken in order, the design answers five fairly ordinary questions. Each answer creates the problem handled by the next one.

1. DEFINE

   How should workflows be expressed?

   Authors use a restricted form of TypeScript, but keep the familiar parts: branches, bounded loops, helpers, and typed values. Anything that talks to a model, changes durable state, or reaches outside the workflow remains an explicit flow.* call.

2. DERIVE

   What can the interface know?

   The definition already contains enough information to build launch forms and basic status views. When the language has a real concept such as a worklist, experiment, or human question, the interface can show that richer meaning without asking the workflow to describe pixels or terminal rows.

3. RUN

   How does procedure become agent work?

   When someone launches a reviewed workflow, the host saves everything needed to run it again. A coordinator owned by systemd then follows the TypeScript procedure and starts each model call in its own bounded service.

4. ISOLATE

   Which files may each agent change?

   Agents that run one after another continue in the same private workspace. Agents that run at the same time cannot safely do that, so each branch gets its own writable workspace. A read-only checkpoint records the exact files left at every completed boundary.

5. SETTLE

   How does successful work reach the live project?

   The workflow returns a typed result, but that result is not permission to overwrite the project. The host separately captures the final filesystem, selects the allowed changes, verifies them, and checks that the live project has not changed underneath the run.

The order matters. If we started with snapshots and databases, most of the machinery would look arbitrary. Starting with the workflow makes the need for it easier to see: as soon as agents can run for a long time or work in parallel, the runtime has to preserve their complete coding state without allowing one branch to erase another.

What each layer is allowed to decide

One word appears throughout the study: authority. Here it simply means a fact or capability that the host has checked and is willing to act on. An agent may describe a checkpoint, claim that a command succeeded, or recommend that a proposal be applied; none of that text becomes authority merely because it sounds convincing.

This distinction is the thread connecting the rest of the study. The next chapter starts where a workflow author starts, with the language. From there we can derive the interface, turn a reviewed definition into running agents, and only then introduce the workspace, recovery, and settlement machinery needed to keep those agents honest.

A useful workflow can be very small. The example below declares one write-capable agent, calls it, and returns its typed output. There is no snapshot code, no workspace setup, and no “apply these files” step.

import { agent, schema as s, workflow } from "pi/workflows";

const implement = agent({
  profile: "builtin:implementer",
  access: "write",
  network: "research",
  output: s.object({
    summary: s.string({ minLength: 1, maxLength: 4_000 }),
  }),
});

export default workflow({
  description: "Implement one reviewed objective.",
  input: s.object({
    objective: s.string({ minLength: 1, maxLength: 20_000 }),
  }),
  output: s.object({
    summary: s.string({ minLength: 1, maxLength: 4_000 }),
  }),
  async run(flow, { objective }) {
    const result = await flow.agent(implement, { prompt: objective });
    return result.output;
  },
});

The short source does not mean that the safety machinery disappeared. The runtime still creates a private workspace, remembers the state from which it started, checkpoints the agent’s result, freezes the final proposal, verifies it, checks for conflicts, and cleans up afterward. Workflow authors do not have to reproduce that sequence every time.

Keep ordinary control flow; make effects explicit

The language has to satisfy two audiences at once. Humans and agents should be able to read and write it without translating every idea into a scheduler graph, but the runtime still has to know—before anything starts—which calls may reach models, commands, networks, people, measurements, or writable project state.

The compromise is restricted TypeScript: ordinary computation remains ordinary, while every durable or external effect goes through the flow object.

This is deliberately less permissive than general TypeScript and less ceremonial than an authored graph. A graph is useful when the graph itself is the product, but it is awkward when the procedure is naturally “loop over these plan points until we need to replan.” Unrestricted JavaScript would feel pleasant at first, yet it would also make ambient I/O, dynamic loading, and runtime effect discovery part of the security boundary. The restricted language keeps normal control flow while closing those escape routes.

One table defines the operation contracts

The API exposes the things an author actually wants to do—run an agent, ask a question, measure a proposal—rather than the storage operations needed underneath. The author states the intent; the host decides what evidence is required before the call can count as complete.

This is what makes the operations pleasant to combine. An author can place an agent inside parallel, or follow it with measureProposal, without threading workspace IDs, checkpoint paths, and recovery tokens through the source.

Review the possible effects without calling run()

Before a workflow can run, static review reads its module shape and every declared flow.* call. It does not execute run() and hope to discover dangerous behavior only when a particular branch happens to be taken.

The result is a finite description of what the workflow may do: where effects can occur, which capabilities they require, and which resources they may use. Input can choose among options that were already reviewed, but it cannot add a new kind of effect after launch.

Installation and model exposure are separate

Definitions live in builtin:, user:, or trusted project: namespaces, but installation alone does not put a workflow in front of the model. A strict registry.json chooses the names exposed through the model-facing workflow tool; other valid definitions can still be launched by a person.

Drafting is separate again. The workflow_draft tool can create, replace, and validate inert source, but a person must answer a review challenge before that source can be promoted or exposed. A model can therefore propose new automation without quietly granting its own proposal permission to run.

The calls compose without workspace boilerplate

The table above is the exact reference, but the source is easier to understand as a story. This sketch asks two reviewers to work in parallel, walks through a durable worklist, lets an implementer edit the project, measures the result, keeps or rejects the experiment, and optionally waits for a person.

import { agent, schema as s, workflow } from "pi/workflows";

const inspect = agent({ profile: "builtin:reviewer",
  access: "read", output: Finding });
const implement = agent({ profile: "builtin:implementer",
  access: "write", output: Result });

export default workflow({
  async run(flow, input) {
    const views = await flow.parallel({
      design: () => flow.agent(inspect, { prompt: input.goal }),
      tests: () => flow.agent(inspect, { prompt: input.goal })
    });
    await flow.unroll(input.points, async () => {
      for (const point of input.points)
        await flow.item(point.key, async () => { /* ordered work */ });
    });
    const done = await flow.agent(implement, {
      prompt: `Integrate ${Object.keys(views).length} reviewed views`
    });
    const measurement = await flow.measureProposal(…);
    await flow.settleExperiment({ measurement, … });
    if (needsInput) await flow.ask({ … });
    return done.output;
  }
});

Optimization shows the pieces working together

Optimization is a useful stress test because it repeatedly edits the project, measures the result, and then either keeps the change or rolls it back. optimize.flow.ts expresses that loop with ordinary agents, immutable measurements, and one explicit accept-or-reject decision.

const baseline = await flow.measureProposal(
  args.evaluator, args.metrics, sampling, args.writePaths,
);
await flow.settleExperiment({
  measurement: baseline,
  disposition: "accepted",
  report: { conclusion: "Established the immutable baseline." },
});

let best = baseline;
for (let iteration = 0;
     iteration < maximum && !best.evaluation.targetReached;
     iteration++) {
  const trial = await flow.agent(experiment, {
    prompt: "Form one hypothesis and make one bounded workspace change.",
  });
  const measured = await flow.measureProposal(
    args.evaluator, args.metrics, sampling, args.writePaths,
  );
  const disposition = measured.evaluation.acceptable
    ? "accepted" : "rejected";
  await flow.settleExperiment({
    measurement: measured,
    disposition,
    report: {
      hypothesis: trial.output.hypothesis,
      intervention: trial.output.changeSummary,
      conclusion: trial.output.conclusion,
    },
  });
  if (disposition === "accepted") best = measured;
}

The loop reads like a normal experiment notebook: establish a baseline, ask an agent to try one bounded change, measure it, and either keep it or reject it. The source does not mention the full workspace restoration needed after a rejection because that is part of settleExperiment, not part of every optimization workflow.

Six built-ins, one runtime model

The six built-ins feel quite different in use. Research fans out into independent lines of inquiry, coding makes one implementation pass, and optimization repeats measured trials. Underneath those different procedures, however, the same rules govern workspaces, evidence, recovery, authority, and final application.

Adding a seventh workflow should not require inventing a seventh storage model. What changes is the procedure; the physical guarantees remain the same. That shared vocabulary also gives the interface something stable to present, which is where the next chapter begins.

Once workflows have a real language, the interface no longer has to start from an empty screen. The definition tells it what may run—through schemas, agent descriptions, and declared operations—while the run database tells it what actually happened. In this chapter, projection simply means turning those checked facts into a read-only view.

Some useful views need more structure than a list of generic calls. A worklist has ordered items, an experiment has a baseline and accepted result, and a human question has one current response challenge. The operations unroll and item, measureProposal and settleExperiment, and ask make those concepts part of the runtime contract. The interface calls the resulting specialized view a facet.

There is one important constraint: a run can detach, recover after a crash, and outlive the terminal that launched it. The interface must therefore rebuild every view from saved state instead of depending on events that happened to be seen in memory.

Derivation happens at three levels

“Derived UI” can easily promise too much. The source cannot predict which side of a branch will run or how many loop iterations will occur; it can only describe the possible operations. The records created during execution fill in the rest.

Every workflow gets the middle layer, even if it has no special UI at all. The last layer is deliberately rarer: a concept earns a facet only when it is useful in the workflow language itself, not merely because a renderer would like another card.

The diagram shows both views coming from the same database snapshot. The generic side can report lifecycle, current work, attempts, resources, artifacts, checkpoints, cross-run lineage, and anything that needs attention. A facet adds domain-specific meaning, such as the active plan item or the best experiment so far.

That richer path is intentionally expensive. A new facet needs code to validate its records, reduce them to current state, expose a bounded projection, render it, and test the whole chain. Letting a workflow emit a convenient string would be much easier, but the interface could no longer know whether the string was true.

Protocols define what a view may claim

Today, only three concepts clear that bar. Each starts with operations written by the workflow author, but the UI reports only what the host has actually checked and saved.

This is why the console can call an experiment “rejected” rather than “failed,” or identify one worklist item as active. Those are facts recorded by the protocol, not labels guessed from log messages.

One language construct can feed several views

execute-plan.flow.ts uses unroll to declare an ordered list and item to identify the point currently being executed. Titles and labels belong naturally in that definition; glyphs, colors, columns, and terminal widths do not.

await flow.unroll(
  remaining.map(point => ({
    key: point.id,
    label: point.objective,
  })),
  async () => {
    for (const point of remaining) {
      await flow.item(point.id, async () =>
        await flow.agent(executePoint, {
          title: `Point ${point.id}`,
          prompt: point.objective,
        }));
    }
  },
  { title: `Plan r${planRevision}` },
);

● Plan r1 · 1/3 · active
✓ 1. Inspect parser behavior
● 2. Add empty-input coverage
○ 3. Run focused checks

The same worklist can appear as one line in a live tool widget, a compact receipt after completion, or a detailed section in /flow open. The amount of detail changes, but the item order and state do not.

Measurements need enough context to explain themselves

Experiments make the same point more forcefully. A value such as “12.8” says almost nothing unless we also know what was measured, whether lower or higher is better, which unit and aggregation were used, how many samples were taken, and what the value should be compared with.

Latency · median · 3 samples + 1 warmup
  – Candidate 2 rejected
  2 candidates · 1 accepted · 1 rejected
  Baseline 12.8 ms · Latest 11.6 ms
  Best 10.9 ms · Gain +14.8438%
  Target · relative gain 10% · reached

Guardrails
  Memory · reference best · maximum regression 5%

A completed measurement therefore stores the metric definition alongside the observed values. The runtime also checks the sample count, aggregate, evaluator profile, environment, writable paths, and whether this result can honestly be compared with earlier ones.

Only the primary metric and its guardrails decide whether a candidate is acceptable. Extra observations provide context, and the report records what the agent thinks it learned, but neither can quietly turn a rejected result into an accepted one.

Projection rules

Once saved facts become UI, four simple rules keep the result trustworthy.

COHERENT One database snapshot

Operations, progress, worklists, measurements, and settlements come from one database snapshot. The UI cannot accidentally combine an old operation list with a newer experiment result.

BOUNDED Exact omission

Large runs must be shortened for display, but the current item, reference state, exact counters, and recent history remain visible. When details are omitted, the UI says how much it left out.

FAIL-CLOSED Corruption becomes an issue

If saved records contradict one another, the UI omits that facet and reports the problem. It does not invent the most plausible history.

PRESENTATION-ONLY No execution authority

Colors, widths, rows, sparklines, and elapsed-time text remain presentation choices. Changing them cannot change workflow identity or saved domain state.

With those rules enforced earlier, the shared renderer can focus on presentation: fitting the real terminal width, clipping by visible character width, sanitizing control characters, preserving units, and keeping rejected experiments distinct from failed runs. Tool receipts and the console use the same underlying status logic, just at different densities.

A detached run still has to report completion

Detached runs create one small but important usability problem: the model session that started the work still needs to hear when it finishes. While the run is active, the interface keeps one stable live widget. When the run ends, that widget disappears and Pi queues one short follow-up message after the current foreground work has settled.

The notification belongs to the interface, not to the workflow. Losing or repeating it must not change the result, resume the run, or require another prompt from the user.

We now know what the interface can honestly report, but not yet what keeps the work alive after Pi detaches. For that we have to leave the UI and look at the processes underneath it.

A reviewed definition and a derived interface still do not run anything. To start real work, the host must save the exact definition and arguments, prepare the project state, start a coordinator under systemd, and give every agent its own bounded service.

Some of those steps genuinely require root privileges: snapshots have to be created, filesystems mounted, identities assigned, and services started. Rather than pretending that this privilege can disappear, the implementation keeps the root-facing interface deliberately boring. Each process gets enough access for one job and, just as importantly, no access to the neighboring jobs.

Three ways to launch, one kind of run

The caller may be a model, a person, or a timer, but the resulting run has the same shape. In every case, the launcher resolves one reviewed definition and saves enough information for the run to be understood and recovered later.

Once the caller-specific checks pass, all three paths converge.

1. RESOLVE

   Select reviewed code

   Resolve the exact namespace, definition, input schema, and caller authority. Missing, ambiguous, untrusted, or unexposed definitions fail before a run exists.

2. FREEZE

   Save the launch description

   Save the source, arguments, project, runtime API, profiles, model route, resources, safety policy, and hashes. Recovery reads this frozen description instead of whatever Pi happens to be configured to use later.

3. START

   Give the coordinator its own lifetime

   The fixed privileged launcher receives only the run ID. It prepares the project state and starts pi-workflow-coordinator-<id>.service, which systemd continues to own after the initiating Pi session has detached.

4. EXECUTE

   Follow the saved procedure

   The coordinator starts a restricted control worker, which re-executes the reviewed TypeScript and reads completed calls back from SQLite. It asks for new outside work only when the procedure reaches a call that has not already completed.

5. SPAWN

   Run one bounded agent

   An agent operation becomes pi-workflow-agent-<id>.service. That service receives one project view, its predecessor evidence, the selected provider and tools, one credential channel, and fixed limits on resources and filesystem visibility.

6. SETTLE

   Prove that the agent really finished

   The runtime validates the terminal result, proves that the worker and all of its child processes have stopped, captures the evidence and checkpoint, and only then marks the workflow call complete.

A live process identifier (PID) is therefore not enough to describe a run. systemd can say which service and control group (cgroup) exist; SQLite says which workflow call that process belongs to and whether it is still allowed to complete it.

Each process gets one job

The exclusions are the important part of the table. The process that understands workflow source is not root, while the root services do not interpret TypeScript or execute shell commands chosen by a model.

The privileged request carries only a run ID

Calls across the root boundary are intentionally uninteresting: an operation version followed by one validated run ID.

launch-v1  flow_<32 lowercase hex>
storage-v1 flow_<32 lowercase hex>
delete-v1  flow_<32 lowercase hex>

The root service looks up everything else itself: paths, reviewed capabilities, storage policy, service properties, identities, and allowed executables. Those values come from the sealed release, the saved launch description, and fixed host configuration—not from extra arguments supplied by the caller. There is no place to smuggle in “just one more” path or executable.

Agent resources are sealed by content, not discovered from home

An agent still needs extensions, provider access, and a useful process environment. The runtime assembles those resources explicitly instead of letting the worker discover whatever happens to be installed in the interactive user’s home directory.

Together, these pieces make the worker environment predictable. Trusted extension code comes from the read-only capsule, one provider credential arrives through a private channel, and the service limits what either can reach. The same boundary also makes checkpointing possible: before taking a snapshot, the runtime can prove that no child process is still changing the workspace.

The run continues when Pi detaches

Closing a terminal should not silently kill a workflow that was meant to continue. Pi can detach once a boundary has been saved because the coordinator owns the run and systemd owns the process. Pause, resume, stop, and human responses are written as durable requests rather than sent as fragile signals to whichever process happens to be alive.

“Background” is therefore a presentation choice, not a weaker kind of execution. The same service continues to run, and reconnecting simply rebuilds its view from saved facts.

Human question handoff. flow.ask() commits a waiting interaction. A response command binds the current challenge, schema-valid value, actor, run transition, and wakeup. A stale response cannot resume a newer question.

A schedule saves a reviewed launch for later

A schedule is best understood as an interactive launch saved for later. It points to the same reviewed definition and arguments, but a person grants permission for several future launches rather than just one. Because that is a substantial delegation of authority, /schedule is available only to a human or RPC caller, never to a workflow worker.

The following command prepares a recurring builtin:research job. It fixes the workflow, arguments, project, calendar and timezone, catch-up behavior, and two limits on how long the permission remains valid.

/schedule create nightly-research builtin:research \
  --args '{"question":"Summarize changes since yesterday"}' \
  --calendar "*-*-* 09:00:00 UTC" \
  --timezone UTC \
  --catch-up once \
  --max-runs 30 \
  --valid-until 2028-01-01T00:00:00.000Z

/schedule confirm create sha256:<exact-review-hash>
/schedule resume <schedule-id>

Creation does not enable the timer immediately. It returns an exact review challenge and stores the schedule paused; after confirmation, a separate resume command checks it once more before future activations are enabled. Replacing or renewing a schedule sends it through the same paused, reviewed, then resumed sequence.

systemd wakes; SQLite admits

The schedule creates a persistent systemd user timer. For the example above, the relevant properties are equivalent to:

[Timer]
OnCalendar         *-*-* 09:00:00 UTC
Unit               pi-workflow-schedule@<schedule-id>.service
Persistent         yes
AccuracySec        1min
RandomizedDelaySec 0
DeferReactivation  yes
WakeSystem         no

Persistent=yes implements catch-up once, while catch-up none uses Persistent=no. Notice what the timer does not contain: no workflow source, arguments, project path, executable choice, or general permission to launch work. It can start only the fixed schedule worker for one schedule ID.

A timer wakeup is only a reminder to check the schedule. Under a machine-wide lock, the schedule database verifies that the saved permission is still valid and that another run is allowed; only then does it create an ordinary workflow run.

1. WAKE

   Start the fixed worker

   The timer starts the fixed schedule service with one validated schedule ID. systemd gives that service a lifetime and an invocation identity, but does not decide whether a workflow may launch.

2. LOCK

   Serialize admission

   The worker takes the schedule and machine-wide admission locks, repairs any occurrence left halfway through preparing, and reads one coherent schedule revision.

3. ADMIT

   Check the saved permission

   SQLite checks that the schedule is enabled, still refers to the reviewed definition and project, has not exhausted its lease, is not launching too soon or overlapping itself, and does not duplicate an occurrence already admitted. It also enforces the machine-wide limit on scheduled runs.

4. MATERIALIZE

   Create an ordinary run

   An accepted occurrence gets a fresh run ID and project baseline, while retaining the exact schedule revision that authorized it. From that point onward, its coordinator follows the same path as an interactive run.

5. REPORT

   Separate launch from workflow outcome

   If a run is created successfully, the launch-failure counter resets even if the workflow itself later fails. Repeated launch failures can block the schedule; a workflow that launched and then failed or started waiting instead produces an attention item for the project.

The command surface exposes those saved objects instead of hiding everything behind the timer:

/schedule list
a1b2c3d4 · nightly-research · enabled · *-*-* 09:00:00 UTC

/schedule inspect a1b2c3d4
/schedule run-now a1b2c3d4
/schedule inbox
/schedule doctor

run-now is not an escape hatch: it passes through the same lease, spacing, overlap, and machine-wide limits as a timer occurrence. Pausing or deleting a schedule prevents future launches but does not revoke a run that has already been created. When the user manager starts, a reconciler repairs incomplete timers and half-prepared occurrences, then relaunches coordinators that should be active; waiting and paused runs remain dormant.

The practical result is a recurring job whose permission is visible and finite. It expires, cannot overlap itself, survives a closed terminal, and keeps three very different events separate: a timer wakeup, a failed launch, and a workflow that launched correctly but later needs attention.

We now know who may start a process and how long that process can live. The next problem is more physical: how can sequential agents share their files while concurrent agents remain isolated from one another?

Long-running agents create a simple physical problem: they need the complete project, but they should not edit the live copy or erase one another’s work. The easiest way to understand the solution is to follow one workspace. Agent A edits it, the runtime takes a checkpoint, and Agent B carries on in the same place. The checkpoint remembers what A completed without forcing B into another freshly copied workspace.

Work begins at Q, continues in W, and records S

Three symbols describe project state while the workflow is running. The important difference is simple: agents can change W, while Q and S are frozen.

The runtime calls each independent strand of workflow control a scope. The root run is one scope; every parallel lane or mapped item gets another. Each scope owns one W, although sequential agents inside that scope use the workspace one after another.

Q gives the run a known starting point, W carries the ongoing work, and S records a completed boundary. Taking S does not replace W; the next sequential agent simply continues in the same workspace.

That small detail—S branches off while W continues—keeps the common case cheap. A Btrfs snapshot records the exact files, directories, modes, and project roots as immutable Sₐ, while W remains the place where Agent B works. Creating another writable workspace after every sequential step would add machinery without providing any additional isolation.

New writable workspaces are reserved for cases that actually need a branch: parallel work, a clean retry, restoration after a rejected experiment, disposable evaluation, or an explicit restore. There is one final snapshot at successful write completion, when the root W becomes immutable proposal P. A read-only run keeps its useful checkpoints but can discard the private workspace.

A project is a verified root set

A project is not always one convenient directory-shaped Btrfs subvolume. It may begin partway through a larger subvolume, and it may include approved auxiliary roots on other Btrfs filesystems. The runtime combines those pieces into one project view and carries the whole verified set through checkpoints, cross-run import, final application, and cleanup. Sibling directories and storage-control data remain outside the agent’s view.

The details below all support the same rule: every writable scope receives the complete project view, but workflow code never chooses the physical storage objects behind it.

Notice what does not appear in the authority column: a path invented by workflow code, a claim in model output, or the current contents of a mutable Git index. All three can be useful information, but none proves which filesystem state the runtime should trust.

Snapshots also need storage limits

Snapshots are cheap, not free, so the workspace model also needs a storage limit. The runtime never turns on Btrfs quotas by itself. If traditional quota groups (qgroups) are already enabled, the broker creates one predictable level-1 qgroup for the run, limits its exclusive use to 4 GiB, and assigns every run-owned filesystem object to it.

If quotas are disabled, a run can proceed without its own qgroup, but the host still keeps admission and emergency free-space reserves and checks checkpoint size. If quota information is inconsistent, being rescanned, changes during inspection, or already exceeds the limit, the runtime refuses to create the checkpoint rather than promising storage it cannot retain.

Agents work inside a narrow mount namespace

Inside this boundary, the worker should still feel like a normal coding agent. It gets Pi’s usual filesystem tools and full Bash, but only inside its isolated W. Nothing becomes checkpoint evidence until the worker, and every process it started, has exited.

The namespace makes that separation visible: one place to edit, one place for private notes, and several read-only locations containing the task and evidence left by earlier agents.

/workspace
/evidence/
  index.json
  current/
    instruction.md
    invocation.json
    notes/
  incoming/
    <causal-boundary>/
      boundary.json
      handoff.md
      result.json
      instruction.md
      transcript.jsonl
      artifacts/
      workspace/      # optional, immutable
/outputs
/runtime/capsule
/state
/run/pi-workflow/agent.sock

An agent therefore needs no special “artifact API” to preserve its work; it edits /workspace normally. Evidence remains available when needed without being mixed into the proposed project changes.

One terminal call closes the agent run

When the agent is done, it makes one terminal call. The call contains a typed result for the workflow and a short handoff for the next agent.

await finish_work({
  output: typedOutput,
  handoff: "Concise downstream orientation: decisions, paths, checks, and remaining risk.",
});

output drives the workflow, while handoff helps the next agent find the relevant decisions, paths, checks, and risks. Neither piece of text proves what happened to the files. The immutable checkpoint is the project state actually left by the agent.

A successful boundary is more than a model result

Receiving valid JSON from the model is only the first step. Before the call can count as complete, the runtime must prove that the worker is gone, freeze the filesystem, assemble the evidence, and save the handoff—in that order.

1. FINISH

   Validate terminal receipt

   The exact typed output schema and complete finish-wrapper schema are checked and hashed separately.

2. QUIESCE

   Prove process absence

   The service and every descendant must exit; the cgroup must be inactive and empty.

3. SNAPSHOT

   Capture immutable S

   Every project root is inspected, snapshotted read-only, and bound to deterministic operation and scope identity.

4. MATERIALIZE

   Build boundary.json

   Instruction, invocation, output, handoff, transcript, tools, resources, activities, notes, artifacts, causal index, and checkpoint become one canonical boundary.

5. COMMIT

   Advance semantic control

   The handoff row commits the boundary hash and checkpoint before the agent operation can become a completed call.

Only then can the next workflow operation see the call as complete. This ordering ties the typed result to the exact files that accompanied it.

Concurrency creates physical branches

Sequential calls can share W because only one uses it at a time. Concurrent calls cannot, so every lane receives its own writable branch while the parent waits at the fork.

The key phrase in the diagram is “mount, do not merge.” When the lanes finish, the parent workspace resumes unchanged and each lane appears beside it as read-only evidence. A joining agent—not a blind text merge in the host—decides whether to combine that work, use it only as advice, or ignore it.

OUTCOME Every terminal lane is represented

Successful, failed, and cancelled terminal checkpoints can be mounted as outcome-bearing evidence. Failed state remains observational and never becomes continuation state implicitly.

NESTING The same rule recurses

Parallel branches and mapped items own child scopes, local cursors, workspace generations, terminal keys, and exact join edges.

The join record must agree with the files

Forking creates two matching records. One says which lanes existed and how they ended; the other identifies the workspaces and checkpoints belonging to those outcomes.

Neither record is enough by itself. A complete list of lane keys cannot prove that their checkpoints still exist, while a pile of snapshots cannot explain which lanes they belong to or how the join ordered them.

The same replacement mechanism supports a clean retry, a rejected experiment, an explicit restore, and cross-run replay, where a new run imports a completed prefix from an older one. In every case, the new workspace is saved before control continues, so the workflow cannot advance while still pointing at the old files.

Rejected experiments restore the last accepted workspace

The optimization loop from the language chapter repeatedly edits, measures, accepts, and rejects project state. Underneath that simple source, every measurement evaluates an immutable S rather than a workspace that might still be changing.

1. BASELINE

   Measure immutable accepted state

   The first measurement establishes metric definitions, samples, environment, write paths, and the accepted reference checkpoint.

2. INTERVENE

   Agent edits current W

   The implementer is instructed to use declared write paths. Measurement detects any changed path outside them and makes the trial unacceptable.

3. MEASURE

   Capture and evaluate S

   The host snapshots exact state, runs warmups and samples, aggregates outputs, and applies primary and guardrail policy.

Acceptance is cheap because W already contains the measured state. Rejection does more work: the runtime replaces the whole workspace from the best accepted checkpoint, so an undeclared leftover from the rejected trial cannot leak into the next one.

The workspace layer now preserves the files, but files alone cannot tell us which workflow call produced a checkpoint or which call should run next. That is the job of the control journal.

The workspace layer preserves files across agent calls, but recovery has an extra complication: after a crash, the TypeScript procedure starts again from the beginning while the retained workspace does not rewind. The runtime needs a way to recognize work that already finished and reconnect it to the repeated procedure.

A journal tells each checkpoint where it belongs

A checkpoint answers “which files existed?” but not “where was the workflow?” To resume safely, the runtime must know which scope produced the checkpoint, which call it belongs to, what request that call made, and which completed call came before it. Together those fields give the checkpoint a stable place in program order.

The fields overlap on purpose because they catch different mistakes. A source location can identify the wrong request, a matching request can run under different resources, and a result can exist without a completed checkpoint. One convenient hash would hide those distinctions rather than remove them.

When the TypeScript procedure reaches a call for the second time, these fields let the runtime answer a precise question: “Is this the same call, under the same reviewed conditions?” The answer still does not prove that the call finished; for that, the runtime also needs its saved result and checkpoint.

Save the effect before committing the call

Each operation has different completion rules, as the operation table showed, but they all enter the journal in the same order. First, the operation adapter saves the outside work’s result or failure; this is effect settlement. The engine then records that settled result at the current place in program order and commits the call.

Why split this into two commits? Because a crash can happen after “the outside work finished” but before “the workflow moved on.” If the result was already settled, the restarted procedure can validate it and commit the call without launching the outside work a second time.

1. BEFORE EFFECT SETTLEMENT

   Execution may be uncertain

   If an external service has neither idempotency nor a recoverable receipt, a crash can leave ambiguity. Local journaling cannot manufacture exactly-once semantics.

2. AFTER EFFECT SETTLEMENT

   Recovery does not reinvoke

   The result or failure, the evidence needed for recovery, and the checkpoint identity are already saved.

3. AFTER CALL COMMIT

   Program order advances

   The next operation’s predecessor binds this exact terminal outcome and local sequence.

This sequence reduces the uncertain window; it cannot abolish it. Once effect settlement is durable, recovery only has to validate saved evidence. Before that point, an external service still needs its own idempotency key or some receipt that can be recovered after a crash.

Progress is observable, not semantic. Warmup/sample counters and host messages wake projections but never enter semantic keys, result hashes, or replay decisions.

Recovery reuses a result saved before the crash

Suppose the coordinator crashes after saving the agent’s result and checkpoint but before committing the call. On restart, it reaches the same call, validates the saved boundary, commits it, and continues without launching another agent.

This is the point of “two control passes, one agent launch” in the diagram. Repeating the TypeScript is harmless; repeating the agent and its filesystem changes may not be.

Replay imports a complete prefix into a new run

Recovery and replay both reuse earlier work, but only recovery stays inside the same run. Recovery asks whether the current run can continue from its own saved state. Replay creates a new run and asks whether it may import a completed prefix from an older one.

SAME-RUN RECOVERY Validate existing authority

Re-execute the exact admitted source, consume this run’s effect-settled calls, validate W generations, checkpoints, joins, handoffs, and physical identities, then continue.

CROSS-RUN REPLAY Import a selected prefix

Create a new run, import a completed source prefix, remint its checkpoints as target-owned objects, replace target root W at the selected boundary, then execute later calls fresh.

The new ownership is the important part. Replay preserves the earlier typed results and records where they came from, but the new run creates its own checkpoints and runs the remaining suffix under its own current configuration and authority.

A replay point must include every branch

A replay point must include a complete root boundary. A caller cannot select one attractive parallel lane while omitting its siblings and the join that gave the lane its meaning.

1. ADMIT

   Resolve checkpoint

   Verify source completion, root ownership, operation boundary, source definition, resources, and structural closure.

2. IMPORT

   Copy completed calls

   Copy attempts, typed results, handoffs, transcripts, artifacts, and causal evidence while recording the source run they came from.

3. REMINT S

   Create checkpoints owned by the new run

   Derive new immutable checkpoints from the source checkpoints. The files and logical outputs remain the same, but the physical receipts now belong to the new run.

4. CUT OVER

   Replace root W

   Create a fresh writable workspace from the imported checkpoint, install it as the new root W, record the replay link, and retire the workspace it replaces.

5. CONTINUE

   Execute the suffix

   Run every later call normally against the imported workspace and the new run’s current configuration.

Replay is therefore more than copying files. The completed calls, their evidence, the checkpoints, and the new writable workspace must all agree before fresh execution begins.

Importing another run adds four checks

After the ordinary recovery checks pass, replay adds four rules that are specific to importing another run.

The rules forbid four tempting shortcuts: selecting a lane by itself, pretending the old run’s snapshot already belongs to the new one, replacing W only partially, or quietly reusing calls beyond the selected prefix.

The imported checkpoint receipts are not part of logical result hashing because the new run owns different Btrfs objects. Source provenance is stored separately, preserving the original result without pretending that the old physical identity carried over.

Four durable authorities remain separate

No single file or process can prove an entire run valid. SQLite records where the procedure is, Btrfs identifies the project state, proposal receipts describe final application, and systemd identifies the processes that performed the work.

Checking all four is more work, but it prevents a convenient record from standing in for evidence it does not contain. A SQLite row cannot resurrect a missing snapshot, and a correctly named snapshot cannot prove that the workflow ever reached it.

Files that enforce the run are separate from files that explain it

A run leaves behind databases, explanatory files, and Btrfs objects. They are all evidence in a broad sense, but they do different jobs: databases enforce the current workflow and settlement state, bounded files explain what happened at agent boundaries, and Btrfs preserves the actual project files. The inventory groups them by purpose rather than pretending that they form one literal directory tree.

When investigating a run, the useful order is to start with the reviewed source and current database state, follow an agent boundary when an explanation is needed, and consult the Btrfs receipts when the question depends on exact project files.

An event log is excellent for explanation, but it does not override the tables that enforce current state. The interface reads both and reports an integrity problem if they disagree.

At this point the runtime can tell which work completed, which files belong to it, and whether recovery or replay may continue. One question remains: how does a successful private workspace become a safe change to the live project?

An agent may report that it changed three files, but the host does not use that report as the change list. It compares the complete starting state Q with the final workspace W, derives the proposal from the files themselves, and applies only the result allowed by fixed host policy.

Successful write completion adds P, C, and F

The workspace chapter introduced Q, W, and S and briefly showed P at successful completion. Settlement finishes that sequence. P is the frozen proposal left in W; C is a temporary workspace containing only the changes selected by host policy; F is the immutable result after that projection has passed verification.

The full protocol has seven stages. Read the diagram from top to bottom: each stage answers one question before the next stage is allowed to act.

Three kinds of settlement remain distinct

The preceding chapters used the word “settlement” for three related but different transitions.

Effect settlement

One operation’s result or failure becomes durable before the workflow call commits.

Experiment disposition

settleExperiment records whether one measured trial is accepted or rejected.

Proposal settlement

The host runs the terminal Q→P→C→F→live protocol after a successful write-capable run.

Completing one agent call does not apply a proposal, and rejecting one valid experiment does not mean that the workflow failed.

Live application uses a three-way comparison

Verification proves that F passed the configured checks, but it does not make an overwrite safe. Someone may have edited the live project since Q was captured, so the apply service compares every selected path with both Q and F.

The rule is deliberately conservative. If the live path still matches Q, replacing it with F cannot erase an intervening edit. If it already matches F, recovery can recognize that the change was applied earlier. If it matches neither, the host stops instead of guessing.

An empty proposal is a no-op only when the complete inventories of Q and P are equal. “The agent says there were no changes” is not enough. Conversely, a write-capable workflow cannot report success while leaving an unclassified mutable proposal behind.

That completes the path from a TypeScript procedure to verified live files. The remaining chapters are reference material: first the systems and papers that influenced the design, then the much less tidy question of what the prototype has actually proved.

Earlier versions of this study had a rather short related-work note, which made the project look much more self-contained than it really is. The design borrows from agent harnesses, workflow engines, graph frameworks, optimization loops, distributed-systems literature, version control, and ordinary Linux storage. Some of those systems provided ideas worth keeping; others were useful because they made an alternative concrete enough to try and eventually reject.

This chapter records those relationships without claiming equivalence. “Inspired by” does not mean API-compatible, based on the same code, or remotely equal in maturity. It only means that a project or paper changed the question I was asking, the interface I tried, or the boundary the prototype eventually chose.

If you only want the short version, the influence map below is enough. The rest of the chapter is an annotated source list for readers who want to check a particular comparison; it is not required to understand the implementation story.

An influence map before the details

The table is the shortest honest account of that lineage. Each later section names the primary sources, the useful lesson, and the point where this prototype does something different.

Coding-agent systems supplied the workload and the first ergonomics

The project began as an extension to an agent harness, not as an attempt to build a general workflow engine. The original question was practical: how can one coding agent hand work to several successors without losing files, context, or control of the live project?

1. Pi. Pi is the host and dependency, not merely an analogy. Its extensible coding-agent loop, model and tool abstractions, session model, and embeddable agent runtime make the experiment possible. This extension adds a durable workflow and filesystem authority layer around Pi agents; it does not claim to replace or generalize the Pi harness.
2. Claude Code dynamic workflows and subagents. The earliest implemented generation followed this pattern closely: the main agent wrote a task-specific JavaScript orchestration script that launched focused subagents, including parallel workers. That trial established the usefulness of generated fan-out and cross-checking. It was later rejected as the authority model because each task invented a new control program and patch-oriented handoffs did not preserve the complete project state. The current workflow_draft surface retains model-assisted authoring only as inert source pending human review.
3. OpenAI Codex cloud tasks. Codex’s user-facing distinction between interactive work and delegated longer work in a dedicated environment informed the “goal continuation” use case: a person should be able to hand off a substantial objective and keep using the foreground interface. This prototype narrows that idea to bounded, reviewed, local workflows; it does not use Codex cloud execution or adopt its environment and review protocol.
4. Flue workflows and durable execution. Flue’s distinction between a continuing durable agent and a finite program that drives an agent sharpened the boundary between ordinary Pi sessions, agent effects, and saved workflow runs. Its model of durable admission followed by later settlement also helped name two facts that must not be collapsed. Flue deliberately delegates multi-step program durability to a workflow engine; this prototype keeps a separate workflow kernel because checkpointed project mutation, replay, and proposal settlement give that kernel additional semantic work.

The lesson was not simply “use more agents.” Delegation creates an ownership problem: returned prose may explain what a subagent did, but a coding successor often needs the exact files, ignored artifacts, generated output, and build products that existed when the predecessor stopped. That gap is what pushed the design away from text and selected patches and toward complete W and S filesystems.

“Checkpoint” names several different recovery units

“Checkpoint” is an unfortunately overloaded word. It may mean a saved conversation, the files touched by an editing tool, a shadow-Git project tree, a mounted workspace, or an entire suspended virtual machine. Those mechanisms fail in very different ways, so the useful questions are what they capture, which changes they can observe, and what restoring them is actually allowed to imply.

The table has two largely independent axes. Capture breadth ranges from selected edits to the state of a whole machine. Semantic binding ranges from a convenient save point to a checkpoint tied to a specific predecessor, effect result, authority, and later decision. A system can be broad on one axis and deliberately narrow on the other.

1. Claude Code checkpointing, Gemini CLI checkpointing, and Cline checkpoints. These are the clearest mainstream precedents for aligning a conversation position with restorable project files. Their documented exclusions are as important as their restore buttons: a file-tool journal or shadow Git repository is not automatically a record of every shell, process, mount, or service effect.
2. Nous Research, Hermes Agent checkpoints and rollback. Hermes adds several mature operational details: a shared content-addressed shadow-Git store, bounded retention, pre-rollback snapshots, diff preview, and an agent-write ledger that avoids overwriting later human edits by default. It remains intentionally bounded by maximum file size, project size, command recognition, and Git’s file model.
3. Stefano Tafuri, pi-chrono. pi-chrono is the closest Pi-native checkpoint utility found in the expanded search. It captures manifests before a Pi agent turn, stores before/after contents in a content-addressed blob store, records create/modify/delete journals, previews rollback diffs, restores the workspace, and forks the Pi session. Its extensive default ignores and size limits make it a practical session safety net rather than complete physical continuity.
4. Replit checkpoints and rollbacks. Replit demonstrates a broader product-level unit: project state, conversation, runtime configuration, agent memory, and optional development-database state can move together, with rollback and roll-forward through alternate history. Its platform scope and optional database restore differ from a local protocol over a separately changing project tree.
5. Dagger, Container Use and its design overview. Container Use combines one Git branch per agent, Git worktrees, Dagger containers, logs, direct intervention, and merge-or-discard review. It is a strong precedent for isolated parallel coding and observable command history. It also preserves the exact boundary that motivated this runtime’s later design: repository branches are not complete workspace snapshots, and branch merge is not operation replay.

Agent-native filesystems move undo below the harness

A shadow Git repository can capture only the paths its scanner knows about. A filesystem layer sits lower: the same mechanism can observe a write made by an editor, shell command, package script, or generated program. Several systems published in 2026 expose that idea directly to agents instead of keeping snapshots as invisible storage plumbing.

1. Zhong et al., “Information and Control in Agent-Native Filesystems” and YoloFS (2026 preprint). This is the strongest conceptual comparator for filesystem safety and final decision. The paper studies 290 reports across 13 agent harnesses and argues for three filesystem-owned primitives: introspect effects, undo mutations, and gate accesses. YoloFS stages arbitrary filesystem mutations until user commit or abort, snapshots after commands, supports inspection and travel to an earlier state, and progressively refines path permissions. The overlap with proposal isolation is substantial. The divergence is that this workflow runtime binds project snapshots to reviewed control execution, model-effect settlement, verification, and three-state live application; YoloFS instead presents a general staged filesystem session over the paths visible to an agent.
2. Turso, AgentFS, its specification, and announcement. AgentFS stores a POSIX-like filesystem, key-value agent state, and tool-call audit trail in one SQLite database, mountable through FUSE or NFS. Copying that logical unit provides a portable snapshot, and its overlay form gives copy-on-write isolation beyond Git-tracked files. The beta documentation’s time-travel claims should not be read as proof that an arbitrary live database copy is atomic or that host state outside the mount is captured.
3. Tsinghua Storage Research Group, ContextFS / AgentVFS. ContextFS is a checkpointable, branchable, content-addressed FUSE filesystem with per-agent views, three-way merge, telemetry, and CAS-backed semantic continuation records. It can pair a filesystem checkpoint with a cooperatively parked process template at an explicit quiescent boundary. Its own documentation carefully excludes arbitrary PID rollback, descendants, sockets, devices, and crash durability for live templates. That separation closely supports this study’s insistence on naming semantic, filesystem, and process continuity independently.
4. nono undo and rollback. nono walks every file in the sandbox scope into a SHA-256 content-addressed snapshot before an agent session, captures a second state afterward, exposes a diff, and can restore the earlier state. It shows that agent-independent recovery can be attached to the sandbox boundary without requiring Btrfs or a particular harness. Its granularity is a session and its admitted scope, rather than every durable operation.
5. Tilde filesystem isolation and service retrospective. Tilde mounted GitHub, object-store, and document data into a versioned FUSE session whose writes stayed isolated until an atomic repository commit. It combined that storage transaction with container and network mediation. Although the hosted service was discontinued, it remains useful prior art for extending staged agent changes beyond a local source repository.

ANOLISA ws-ckpt, discussed again with the Linux precedents below, takes an especially direct approach: it turns a real workspace into a managed Btrfs subvolume and exposes checkpoint, diff, rollback, lineage, retention, and crash recovery through a privileged daemon.

Hosted sandboxes broaden continuity from project to machine

Hosted sandboxes make a different tradeoff. They capture more of the machine and let a controller restore or fork it, which is valuable for warm continuation and large search trees. A broad machine snapshot does not, by itself, say which workflow prefix, external effect, or project proposal that state is allowed to represent.

1. E2B sandbox snapshots. E2B captures filesystem and memory from a running sandbox, briefly pausing it, then permits one snapshot to spawn many exact-state sandboxes. Its documented uses explicitly include checkpointing agent work, rollback before a risky refactor, and parallel exploration. Restoration creates a new sandbox; it does not settle changes into a concurrently evolving local project.
2. Fly.io, Sprites checkpoints and lifecycle. Sprites separates persistent filesystem checkpoints from warm suspension. A checkpoint is a copy-on-write filesystem save point for rollback, while warm sleep preserves process state for fast wake. The distinction is a useful corrective to calling both mechanisms “resume.”
3. Daytona snapshots and persistence. Daytona distinguishes cold filesystem snapshots from VM hot snapshots that also retain memory, and exposes independent forks for divergent experiments. Container, virtual-machine, and GPU sandbox classes have different persistence contracts. This explicit matrix is a strong precedent for stating capture scope rather than promising generic “state.”
4. Modal Sandbox snapshots and CodeSandbox persistence. Modal separates filesystem, directory, and preview memory snapshots, each with retention and restoration constraints. CodeSandbox uses Firecracker memory and filesystem snapshots for hibernation, templates, forking, and process resume. Both optimize hosted environment lifecycle; neither is a semantic workflow journal or live-project merge authority.

Native control flow won over authored graphs

The authoring language changed several times while I rewrote the same research, coding, goal, plan, and optimization workflows against different APIs. Ordinary control flow around explicit typed model calls remained easy to read. Graph APIs were much less convincing whenever the procedure was naturally a loop or branch and the graph mostly exposed scheduler bookkeeping.

1. Khattab et al., “DSPy: Compiling Declarative Language Model Calls into Self-Improving Pipelines” (2023). DSPy showed how typed signatures and reusable model modules can live inside normal Python composition, and how an objective can govern optimization of an LM pipeline. This project borrowed the separation between reusable model declarations and program control. It did not adopt tagged-string signatures, teleprompters, or prompt compilation; its descriptors primarily declare authority, resources, and strict output contracts.
2. Pydantic AI multi-agent applications. Pydantic AI explicitly presents programmatic handoff—application code calling one typed agent after another—as a simpler option before graph machinery. Typed structured outputs and a uniform agent result were important ergonomic precedents. Here those calls also cross durable workspace and evidence boundaries that Pydantic AI can delegate to separate durable-execution integrations.
3. Prefect 3. Prefect’s move away from mandatory explicit directed acyclic graph (DAG) authoring toward native Python if, loops, and dynamically discovered tasks was strong evidence that runtime structure can be observed without making a graph the source language. This prototype applies that lesson to a much smaller, single-host, agentic coding domain and accepts a restricted TypeScript subset rather than general Python.
4. Pydantic Graph and LangGraph. Both make stateful agent topology explicit through nodes, edges, state, persistence, and graph execution. They were serious design alternatives, especially for pre-execution inspection and human editing. The prototype rejected node and edge authoring because loops, replanning, and experiment policy became scheduler-shaped source; it still owes these systems credit for clarifying when an explicit graph is the better product.
5. Vercel Workflow. The "use workflow" and "use step" directives are an ergonomics benchmark for durable TypeScript that looks like ordinary async code. This project kept that surface goal but rejected directive-driven extraction and broad source transformation: its operations already have domain names such as agent, measureProposal, and ask, and keeping them explicit makes static authority review and source-to-operation diagnostics easier.

The resulting system is not “graphless.” Execution still creates an operation graph and a workspace graph. The narrower claim is simply that authors should not have to encode those graphs twice—once as a TypeScript procedure and again as explicit nodes, paths, or storage instructions.

Durable-execution systems supplied the control model

The central recovery technique is well established: run deterministic code, save the results of outside operations, and reconstruct control by returning those saved results instead of repeating the work. Temporal, DBOS, Restate, and Inngest have very different architectures and guarantees, but all show that ordinary-looking control flow can sit on top of durable operation boundaries.

1. Temporal Workflow replay and Activity idempotency. Temporal is the clearest direct precedent for re-executing deterministic workflow code against event history. Its documentation also makes the crucial limit explicit: an Activity can execute more than once, so idempotency belongs in the effect contract. This prototype adopts the replay distinction but not Temporal’s service architecture, worker model, workflow versioning, retries, signals, availability, or operational maturity.
2. DBOS workflows. DBOS demonstrates durable ordinary functions reconstructed from stored step results and gives workflow identity an idempotency role. The relevant lesson is that application-looking TypeScript can be durable without authoring a separate state machine. This runtime instead keeps multiple local authority stores and binds model or filesystem effects to host-specific receipts.
3. Restate workflows. Restate wraps regular functions with a durable context whose actions and results are journaled. Its separation between normal control constructs and explicit durable actions closely matches the desired authoring feel. This project is not a Restate service and does not inherit its keyed workflow, state, event, retry, or distributed execution semantics.
4. Inngest execution, steps, and versioning. Inngest’s explicit step IDs, per-ID counters for repeated loop calls, memoization, and code-evolution model were a useful counterpoint during operation-identity design. Because every run here pins exact source and cross-run replay stops at the first semantic mismatch, routine author-supplied IDs were judged unnecessary; sequential identity is runtime-owned, while dynamic concurrent items still require stable keys.
5. Flue durability. Flue explicitly states that it does not checkpoint arbitrary TypeScript line-by-line and recommends durable tool steps or an external workflow engine when that boundary is needed. That subtraction is an important warning: a workflow abstraction should exist only when it owns meaningful durability. In this prototype, operation settlement, workspace checkpoints, proposal settlement, and replay are the reasons the abstraction remains separate from an ordinary agent call.

Two distinctions from the control chapter follow directly from this literature. First, saving an effect result and advancing program order are separate commits; neither can pull an arbitrary provider request inside a SQLite transaction. Second, an agent result is larger than its JSON output. Reuse may also require the predecessor evidence and matching filesystem checkpoint, because a valid transcript paired with the wrong files is not a valid recovery point.

Agent checkpoint/restore is now a systems research topic

Recent systems research treats agent recovery as more than saving chat history. It asks where checkpoints should be placed, whether files and process state must move together, what can be learned from a failed suffix, and how cheap branching needs to become for search or reinforcement learning.

1. Li et al., “Generator-Assistant Stepwise Rollback Framework for Large Language Model Agent” (EMNLP 2025). GA-Rollback pairs a generator with an assistant that checks each action and triggers stepwise rollback in replayable benchmark environments. It is an important reasoning-level predecessor for letting an agent abandon a bad suffix. It does not claim complete operating-system or coding-workspace recovery.
2. Wu et al., “Crab: A Semantics-Aware Checkpoint/Restore Runtime for Agent Sandboxes” (2026 preprint). Crab identifies an agent–OS semantic gap: application recovery sees turns but misses OS effects, while the OS sees mutations without knowing which turn they belong to. It uses eBPF observation to classify recovery-relevant effects, aligns container or microVM checkpoints with turn boundaries, and overlaps work with LLM latency. Crab’s reported result that most turns need no physical checkpoint is an important challenge to unconditional per-turn snapshotting. This prototype instead checkpoints at the smaller set of durable operations whose workspace identity enters later control.
3. Dong et al., “DeltaBox: Scaling Stateful AI Agents with Millisecond-Level Sandbox Checkpoint/Rollback” (2026 preprint). DeltaBox captures both filesystem and process state for search and reinforcement-learning branches. DeltaFS freezes and switches copy-on-write overlay layers; DeltaCR restores from a frozen process template backed by CRIU. The paper reports roughly 10.83 ms of checkpoint work hidden under inference and roughly 1.86 ms fast-path rollback. It is the clearest performance precedent for the goal of fast checkpoint and rollback. This runtime chooses restartable control reconstruction instead of process-memory restoration, trading machine breadth for execution records that remain inspectable.
4. Zhuang et al., “AgentRewind: Recoverable Execution for Long-Horizon LLM Agents” (2026 preprint). AgentRewind records aligned pairs of agent context and workspace state, restores a selected prefix from logs without re-calling the model or tools, and injects a summary of the failed suffix as rewind memory. Its implementation uses shadow Git and explicitly excludes effects outside the workspace, root Git metadata, empty directories, and most permission bits. The alignment principle directly supports pairing semantic and physical state; the exclusions show why a Git checkpoint is still not complete W continuity.
5. Yu et al., “Shepherd: Enabling Programmable Meta-Agents via Reversible Agentic Execution Traces” (2026 preprint). Shepherd makes model actions, tool calls, and environment changes first-class events in a reversible Git-like trace that meta-agents can inspect, fork, edit, and replay. It demonstrates supervision, counterfactual workflow repair, and rollout branching. This prototype shares the goal of an inspectable execution object, but keeps control changes behind reviewed workflow installation and reserves project acceptance to a fixed host protocol.

These papers preserve different pairs of things: thought and action, context and workspace, or filesystem and process. None makes “exact restore” meaningful without saying what was captured. Restoring a process can still be unsafe after an external commitment, restoring a conversation can leave the wrong files, and restoring a project tree can omit a service or remote side effect.

Restoring bytes does not restore authority or the outside world

The most important correction from the expanded search is that rollback is not automatically safe. A restore can duplicate an irreversible request, reuse permission that should remain consumed, invalidate later work, or erase the evidence needed to decide whether continuing is legal.

1. Yang et al., “DART: Semantic Recoverability for Structured Tool Agents” (2026 preprint). DART distinguishes a mechanically available checkpoint from a semantically admissible restore point after downstream consumers have committed work. It localizes the failed instance, checks dependency and effect constraints, and blocks recovery when no boundary preserves downstream commitments. That is close to this runtime’s rule that causal predecessors, dispositions, and applied state constrain replay; DART targets structured tool instances rather than complete coding workspaces.
2. Zheng et al., “ACRFence: Preventing Semantic Rollback Attacks in Agent Checkpoint-Restore” (2026 preprint). ACRFence shows how a restored nondeterministic model can synthesize a slightly different request and bypass ordinary idempotency keys, duplicating payments or reviving consumed authority. It proposes recording irreversible effects and enforcing replay-or-explicit-fork behavior. The paper validates the attack, while the proposed analyzer remains future implementation work; its warning is nevertheless fundamental. This runtime avoids regenerating settled provider effects during semantic replay and treats uncertain settlement as durable state.
3. Zheng et al., “When Can Agents Safely Checkpoint, Fork, Restore, and Merge? Exact Checking for Execution Edits” (2026 preprint). This work calls checkpoint, fork, restore, and merge “execution edits” and gives a mechanized checker for what an edit must preserve after authorizations, in-flight calls, and required results. It is a formal contemporary analogue to host-owned admissibility checks. The prototype here does not implement that paper’s general exact checker and should not inherit its proof claims.
4. Chen et al., “Cordon: Semantic Transactions for Tool-Using LLM Agents” (2026 preprint). Cordon introduces a task-level transaction that binds tool intent, result lineage, reversible local state, staged outward effects, delegated authority, and audit metadata before commit. Its effect outbox is a close research comparator for proposal capture followed by validation and release. This project’s narrower transaction is a project-tree transition; it does not stage every possible external tool effect.
5. Mohammadi et al., “Atomix: Timely, Transactional Tool Use for Reliable Agentic Workflows” (2026 preprint). Atomix groups reads and effects, seals their footprint, waits on per-resource progress frontiers, and treats commit as the point where bufferable or irreversible-gated effects may leave. It addresses concurrency and speculative losing branches beyond this prototype’s single-project proposal protocol. Its explicit limit—heterogeneous endpoints cannot be made atomically commit by a wrapper—supports the refusal here to label arbitrary provider and filesystem crossings exactly once.
6. Gensee Crate. Gensee is a close open-source operational comparator: its alpha Linux path offers Btrfs-backed whole-workspace forks, parallel approaches, host-observed effects, scoped capability leases, evidence, and merge/promote/discard decisions. It also states which controls are strongest today and which remain under development. The overlap is significant, but no reviewed workflow language, checkpoint-bound semantic replay protocol, or Q/W/S/P/C/F object graph should be inferred from its documentation.
7. AgentTX and Atrium. These young implementations package Git isolation as an agent transaction with diff, verification, rollback, and conflict-aware acceptance. AgentTX explicitly limits its guarantee to supported repository changes and states that ignored files, the operating system, and external actions remain outside it. Atrium adds a durable event log, snapshots, branching, verification, and a commit gate, but its broad README-level atomicity language should be read within its Git-backed adapters and current roadmap, not as proof of atomic arbitrary effects.

This literature makes the local claim much narrower. The prototype is not a general “transaction system for agents,” nor does it solve rollback for arbitrary external effects. Its target is the particular combination of reviewed workflow source, saved effect results, complete immutable project checkpoints, proposal verification, and conservative application to a live tree that may have changed separately.

The optimization workflow belongs to the autoresearch family

The optimize built-in is not a new experimental method. Its loop—try one change, measure it, keep an improvement, reject a regression, and repeat—comes directly from the autoresearch family and metric-driven program optimization more generally.

1. Andrej Karpathy, autoresearch. Autoresearch made the autonomous experiment loop unusually concrete: give a coding agent a small real training setup, a fixed evaluation target, and an instruction document; let it edit, run, inspect the metric, retain winners, and continue. This prototype generalizes the control shape beyond model training, bounds its iterations, and makes the evaluator, metric definitions, sampling, guardrails, and writable paths reviewed invocation authority.
2. David Cortés, pi-autoresearch. pi-autoresearch is the closest Pi-native precedent: it generalizes the loop to arbitrary optimization targets and adds persistent experiment records, keep/revert behavior, resumability, and a live dashboard. The workflow runtime carries that practical lineage into its semantic kernel, but replaces Git commit/revert as the experiment authority with immutable Btrfs checkpoints, host-measured evidence, explicit disposition, and complete W restoration after rejection.

The extra machinery does not make an experiment scientifically valid; it only makes the state changes and measurement record inspectable. A poor evaluator, noisy samples, adaptive overfitting, or failure to converge remain ordinary experimental problems.

Concurrency, causality, and authority use older foundations

Several implementation terms are easy to overstate without their intellectual source. The runtime borrows small, application-specific pieces of these ideas; it does not claim to implement the general theories behind them.

1. Leslie Lamport, “Time, Clocks, and the Ordering of Events in a Distributed System” (1978). Lamport’s happened-before relation separates causal partial order from an imposed total order. That distinction motivated lane-local predecessors and deterministic joins instead of treating concurrent completion order as execution identity. This is a local analogue, not a distributed logical-clock implementation.
2. Nathaniel J. Smith, “Notes on structured concurrency, or: Go statement considered harmful” (2018). Structured concurrency argues that child task lifetime, cancellation, and completion should remain nested inside the parent abstraction. parallel and map predeclare bounded lanes, wait for every terminal outcome, and make the join durable for exactly that reason; unrestricted Promise.all is not the workflow concurrency model.
3. Miller, Yee, and Shapiro, “Capability Myths Demolished” (2003). The object-capability distinction between ambient naming and possession of an unforgeable reference informed host-minted, run-bound result types. A model may describe a candidate ID in JSON, but it cannot construct the reference required to settle or apply it. This is a capability discipline, not a formally verified capability system.
4. Martin Fowler, “Event Sourcing”. Event sourcing provides the useful idea that a durable change history can reconstruct state and support alternate projections. The runtime keeps operation and provenance records and derives read models from them, but it is deliberately not a pure event-sourced system: normalized current state, immutable files, and Btrfs objects are also authority.
5. Chris Richardson, Transactional Outbox. The outbox pattern atomically stores business state and publication intent, then relays the message. It is a useful contrast, not the name of this protocol. Here an arbitrary external effect occurs outside SQLite; its result is settled durably; only then is the call committed into program order. A crash before settlement can therefore leave an uncertain external outcome.

These sources also explain why the implementation has several records instead of one overloaded completed flag. A process can exit before its result is accepted; an external effect can settle before the workflow advances; a branch can finish before its join commits; and a proposal can verify before it reaches the live project. Recording those moments separately is more verbose, but pretending they form one atomic event would be false.

Git and Linux supplied the physical vocabulary

The filesystem model combines familiar version-control ideas with mechanisms that also work outside repositories. Git supplied the early prototypes and the vocabulary of isolated work trees and three-way comparison. Btrfs made complete checkpoints cheap enough to take at agent boundaries, while SQLite and systemd supplied local transactions and process supervision. ANOLISA’s ws-ckpt is one of the clearest contemporary systems built around the same basic premise for agent workspaces.

1. Git worktrees and three-way merge. Early parallel workers used disposable Git worktrees and returned patches. Git proved the value of isolated working directories and base/current/proposed comparison. It also exposed the boundary: worktrees require a repository, and patch handoff does not automatically include ignored files or every filesystem object. Current live application uses a conservative three-state comparison, but it is a project-tree settlement protocol rather than git merge.
2. Btrfs subvolumes and snapshots. Btrfs provides independent subvolume hierarchies whose snapshots begin with shared extents. That copy-on-write mechanism is the direct physical basis for Q, W, S, P, C, and F and for millisecond-scale checkpoint creation from an existing boundary. The object graph, receipts, selection policy, and semantic meaning of those snapshots belong to this runtime, not to Btrfs.
3. Alibaba, ANOLISA Workspace Checkpoints (ws-ckpt) and its design document. ws-ckpt is a close purpose-built comparator for the physical layer: it gives AI agents fast, complete-workspace checkpoint, diff, rollback, retention, lineage, and interrupted-operation recovery through Btrfs copy-on-write snapshots. It also concentrates privileged mount and subvolume operations in a systemd-managed daemon and can supply Btrfs through a loop image when the host filesystem is not Btrfs. This work was discovered after the prototype’s initial filesystem design rather than serving as its source, but it independently demonstrates the same central premise: Git history and selected patches are not sufficient short-term recovery state for an agent that mutates a workspace. The boundary is scope. ws-ckpt is a general agent-facing checkpoint and undo service, with plugins and a CLI; this runtime binds several immutable snapshot roles to operation causality, deterministic control reconstruction, proposal measurement and verification, and conservative application to a separately changing live tree. Neither project thereby inherits the other’s guarantees.
4. SQLite write-ahead logging and synchronous modes. SQLite supplies local transactions, constraints, coherent read snapshots, and crash recovery. WAL with synchronous=FULL informs the durability policy, but it cannot include provider requests, systemd operations, or Btrfs mutations in one transaction; those crossings still require intents, receipts, reconciliation, and explicit uncertainty.
5. systemd transient units and control-group interfaces. systemd supplies process supervision, cgroup ownership, D-Bus launch, resource controls, and a lifetime independent of the Pi presentation process. It is deliberately a wakeup and process authority, not the semantic scheduler: SQLite decides whether a run or schedule occurrence may advance.
6. Linux mount namespaces, cgroup v2, and fs-verity. These mechanisms constrain filesystem visibility, account for resource use, and authenticate sealed read-only files. They narrow the local execution boundary; they do not turn a same-user coding-agent setup into a hostile multi-tenant sandbox.

The project-specific work is the composition, not the ingredients

The most defensible project-specific claim is a narrow one: the prototype connects three kinds of continuity that other systems often address separately.

Putting those layers together on one Linux workstation may be useful even if none of them is new. I did not find a primary source describing this exact combination of reviewed control code, settled-result replay, complete immutable project roots, proposal verification, and conservative Q/live/F application. That is not a novelty proof—the field moves quickly, systems capture different things, and several close projects appeared during 2026. The useful question is therefore not whether the ingredients are original, but whether this particular integration gives better handoffs and safer unattended work than a simpler combination of an agent harness, Git, an agent-native filesystem, and an existing durable-execution engine.

It is tempting to end an architecture study with a tidy verdict; however, I do not currently have one. I am still in the early testing phase to determine if the current shape of this experiment actually accomplishes its ultimate goal: being useful.

In order to answer decisively, I still need to accomplish three distinct things:

• Prove that each claim (technical, semantic, or behavioral) is indeed correct.
• Use the extension and decide from feel if it has the right shape.
• Benchmark the harness with and without the extension in order to establish whether it improves model quality or not.

The second and last points in particular are the more uncertain ones: while proving that the code actually works and does what it is supposed to do is indeed not trivial and most definitely time-consuming, it is still a fairly well-defined exercise. However, despite all the effort I've put into implementing what I think to be a good workflow model, I am still not entirely convinced that they actually help, other than potentially achieving some increased speed through parallelization and burning through tokens in the process. There is even some evidence that the optimize//goal workflow may not even achieve better performance compared to a normal agentic loop. Benchmarks are therefore the only way to answer that question, and benchmarks are hard to design and implement correctly.

Four implemented trials were abandoned

The current design was not my first attempt. I built and exercised four earlier approaches, then abandoned them when their handoff models became too awkward or simply failed to meet the constraints I cared about. “Tested” is doing fairly modest work here: it means that I used each design enough to learn something from it, not that every generation received a controlled benchmark.

The dates show how the implementation moved, but the recurring question matters more: what exactly can one agent hand to the next without losing useful state or quietly granting too much authority?

Not every idea was discarded. Strict TypeScript control, SQLite call settlement, systemd-owned lifetime, Btrfs identity, and Q→P→C→F settlement all survived. The decisive change was the handoff: instead of asking each workflow to describe selected artifacts, complete W and S filesystems now carry coding continuity and the host owns checkpointing and final settlement.