The first five posts in this series worked from the execution boundary upward. Blog 0 chose the live workspace boundary. Blog 1 reconstructed process trees and shared memory. Blog 2 extended copy-on-write into files and the page cache. Blog 3 handled GUI and network identity. Blog 4 defined merge, promotion, rollback, and discard.
Blog 5 moves into Gensee Crate. The systems primitive can clone a running workspace, but an agent-facing runtime must also decide when to fork, preserve the user’s request, divide source and child responsibilities, track results, and ensure that one explicit resolution choice controls what survives.
Gensee Crate treats workspace fork as an operation protocol: classify the requested effect, capture the task, reach a stable source turn, create a same-authority child with a new identity, continue the task inside that child, collect changed files and test evidence, then consume one later user choice to merge, promote, or discard.
A fork is one execution path inside a larger control plane
Gensee Crate models consequential work as a capability request with an effect scope and typed authority requirements. Dependency upgrades, broad refactors, lockfile changes, destructive cleanup, local database mutations, and remote database mutations can all look “risky,” yet they need different execution paths.
| Operation shape | Current preferred path | Why |
|---|---|---|
| Work depends on live process, memory, and workspace state | Live workspace fork | Preserves the running environment while keeping the child inside the parent operation’s existing authority. |
| Untrusted or staged work needs exact temporary local authority | Fresh capability cell | Starts from a fresh environment with an exact command, bounded paths, short lifetime, measured effects, and explicit output promotion. |
| An external effect can be performed through a constrained service | Trusted mediator | Binds the remote target, identity, action, and receipt outside the agent’s ambient execution environment. |
| The requested scope remains unresolved or cannot be bounded | Deny or require approval | Empty selectors mean authority has not been granted. Missing mediators and unbounded effects fail closed. |
This separation matters because a workspace fork can reverse local divergence by discarding the branch, but it cannot unsend an email, reverse a deployment, or restore a remote database. The current policy path keeps external mutations blocked in both sources and forks until a broker can enforce the declared target, identity, and effect scope.
1. Gensee Crate identifies fork-worthy work before execution
At prompt time and again before a command runs, Gensee Crate looks for operations that benefit from isolation or comparison. The current rules recognize dependency upgrades, schema migrations, broad refactors, destructive file cleanup, lockfile changes, destructive database commands, and broad test-strategy changes. Each finding includes a provider-neutral capability request that describes filesystem, network, process, identity, untrusted-code, and external-mutation needs.
For reversible local work, the agent receives guidance to ask the user for a fork. If two materially different approaches could be useful, the guidance asks the agent to name both strategies before requesting one grouped fork. The labels remain bounded strategy labels and never become trusted lifecycle or security instructions.
The source-side command rule provides a second checkpoint. In the current Codex integration, a block on matching source commands prevents the agent from acknowledging the fork guidance and then performing the same work locally. Irreversible local mutations require an isolated environment, while external mutations continue toward the brokered path.
2. The original request is captured before the source becomes a branch point
A useful handoff must preserve intent as well as machine state. When a user submits a fork-worthy request, Gensee Crate records the original prompt together with the source run identity and observation time. The source agent proposes the fork, receives approval, and runs the fork command once.
The command may return scheduled=true together with job and status metadata. At that point the source agent ends its turn normally so Gensee Crate can clone the idle session; it neither starts another fork nor performs the task locally. Host-side status consumers that encounter a transient capability rotation retry the same job rather than creating a replacement. This keeps one approval bound to one fork operation.
Gensee Crate waits for two lifecycle markers: the fork command completed, and the source turn stopped. This creates a stable handoff boundary. A tmux-backed session can briefly detach its active client while the runtime captures the process tree, then reconnect after the source is ready.
Store the task and classify its intended effect before changes begin.
Require the fork command and the source stop marker before cloning.
Rebind identity and continue the saved task inside inherited live state.
Match one later approval to merge, promotion, or discard.
3. Host control creates the fork and replaces inherited identity
A host-side Gensee Crate process owns the virtualization layer: it starts sources, invokes the live-clone runtime, records lineage, prepares per-child context, and performs lifecycle operations. A source requests a fork through a signed host-control channel whose command surface excludes arbitrary host execution.
Before the clone begins, Gensee Crate prepares a distinct run context for every planned child and revokes the source’s current host-control capability. The live clone can therefore inherit only an already-revoked source credential. After the runtime returns, Gensee Crate installs each child’s run identity and capability, attaches its root process to a new operation cgroup, and restores the source with a newly rotated capability.
This ordering turns identity rebinding into part of fork correctness. Process memory and configuration are copied by the live runtime; authorization comes from fresh host-installed context. Each child receives its own run ID, operation ID, cgroup, result marker, terminal attachment, and direct parent relationship.
source request
→ save task and wait for a stable turn
→ revoke source host-control capability
→ clone live workspace state
→ attach each child to a new operation identity
→ install child-scoped capability
→ rotate and restore source capabilityThe host-control capability is signed, short-lived, and replay-protected. Its target scope follows lineage: a source can inspect and send work to direct children; a fork can act on itself and merge only into its direct source. Siblings and unrelated workspaces remain outside the child’s control scope.
4. The forked agent continues the same task
The handoff avoids a second user prompt. The live clone already contains the agent’s conversation, process memory, files, tool state, and terminal session. Gensee Crate submits the saved request with trusted child context after the clone becomes authoritative. If an in-flight fork-status observer is inherited by a child, its response becomes another role boundary: this session is the live-cloned fork, so it stops source orchestration, continues the original approved task, and avoids scheduling another fork.
A stop-hook continuation covers a subtler failure mode. A cloned Codex session may try to end the inherited orchestration turn before beginning real work. While the child result remains queued, Gensee Crate returns a continuation instruction that tells the child to execute and verify the task. The first real tool call advances the child from queued to running.
During execution, the fork result marker accumulates work tool calls, test commands, exit codes, interruption state, output excerpts, and the last observed work result. When the task completes, the agent runs:
gensee run summary <fork-id> --json --completeThe summary exposes the branch’s changed files, tests, readiness, and assistant result. The normal merge path rejects failed, stalled, interrupted, or otherwise unready work. This evidence establishes workflow state; the user and agent still interpret what the tests and diff mean for program correctness.
5. Parallel forks turn one task into an explicit comparison
A single speculative branch answers “Can this approach work?” Parallel branches answer “Which approach should survive?” The source agent can propose two distinct strategies and create a grouped fork:
gensee run fork <source-id> --copies 2 --name try-upgrade \
--approach 'minimal compatible upgrade' \
--approach 'upgrade to the latest major version' \
--attach tmux:right --jsonEach child receives the original request plus one assigned approach and reports only its own work. When every candidate reaches a terminal state, Gensee Crate returns control to the source session. The source runs gensee run compare <group-id> --json and presents the approaches, changed files, tests, and readiness together.
The current comparison may recommend the smallest passing diff. This size-and-test-status heuristic covers a narrow evidence set; architecture, product intent, hidden regressions, and long-term maintainability remain part of the user’s decision. The source presents the recommendation as one input to that choice.
6. Resolution requires evidence and a later matching approval
Completion produces evidence. Adoption requires a later user decision after the fork presents its result and offers three distinct outcomes:
- Merge transfers eligible Git or filesystem changes into the continuing source.
- Promote makes the selected live fork the new source and retires the old one.
- Discard marks the fork resolved and schedules its environment for cleanup while retaining lifecycle history.
A later user prompt must identify the offered action. Gensee Crate records the choice only after the result and options were presented, verifies that the action still matches the same fork or parallel group, checks direct lineage and current readiness, and rejects stale or already-consumed approval. A successful lifecycle command consumes the approval once.
Parallel resolution adds the selected branch identity to the approval. gensee run choose merges or promotes that winner and schedules the remaining group members for discard. The user can also discard the entire group.
The agent may produce evidence and recommend a branch. The user decides which result survives, and Gensee Crate binds that choice to one current lineage-scoped lifecycle action.
Live forks stay within the source authority ceiling
Gensee Crate admits a live fork only as a same-authority continuation. The parent must be an active supervised operation with its process/cgroup boundary attached, no active leases, no recorded violations, and no successful boundary effects. The child policy decision must select the live-fork executor with an empty authority delta and no new mediator or lease attachment.
Promotion repeats the check. Gensee Crate verifies parent and child operation identity, active cgroup attachment, process identity, capability equality, empty leases, clean effect history, and the stored live-fork policy decision. Promotion rotates the chosen child into the source role, revokes the old source capability, and closes the old operation.
The public code also records an important caveat: inherited ambient authority is currently unattested. A live fork copies process memory and environment configuration, so it is suitable for speculative work inside one authority domain. Work requiring additional secret, identity, network, cloud, database, browser, kernel, or external-application authority must use a fresh capability cell or trusted mediator until the runtime can prove that inherited authority was stripped and rebound.
What the current integration guarantees—and where it remains incomplete
The current public implementation provides a concrete workflow-integrity protocol, lineage-scoped host control, same-authority admission, result readiness checks, approval matching, and transactional resolution mechanisms. Several boundaries remain active engineering work:
- Codex has the deepest automatic continuation path today. Gensee Crate supports hooks and runtime observation across multiple coding agents, while equivalent live-turn handoff behavior varies by provider.
- The approval gate protects workflow integrity. Any same-user process that can read the in-environment run context inherits that run’s limited host-control capability. The current gate stops an ordinary confused agent from skipping the user-choice turn; a malicious same-user process requires a separate containment boundary.
- Fresh capability cells currently provide the fail-closed confinement path. Long-lived live-fork environments still lack the complete fanotify, Landlock, operation-scoped nftables, seccomp, and AppArmor policy applied to those cells.
- Merge should run at a known source checkpoint. A continuing source can race with conflict detection or apply if it writes the same files during merge.
- External effects remain outside local rollback. A workspace branch can isolate local divergence; remote systems require mediated effects, receipts, and their own transaction or compensation semantics.
These limits define the architecture rather than weakening it. Workspace fork handles live same-authority exploration. Capability cells handle bounded temporary authority. Trusted mediators handle external effects. Evidence and promotion rules decide which outputs may cross back.
The complete series now reaches the agent workflow
The systems path now runs end to end: select the workspace boundary, share process and file state, isolate GUI and network identity, resolve heterogeneous state, then connect the lifecycle to an agent without losing request lineage or user control.
The central lesson is that workspace fork becomes an agent primitive only when five things travel together: intent, live state, operation identity, evidence, and an explicit resolution decision. Gensee Crate supplies that coordination layer around the low-level fork runtime.
Inspect the implementation. The public repository contains the operation classifier, host-control protocol, fork handoff, capability rotation, result tracking, parallel comparison, approval gate, and lifecycle commands described here.
Get Gensee Crate on GitHubFrequently asked questions
Does the user need to resend the original task after the fork?
In the current Codex path, no. Gensee Crate captures the original request before cloning and uses the live child’s inherited conversation plus trusted fork context to continue the task. A follow-up run send remains available for later source-to-child prompts.
Can a live fork request more authority than its source?
The current admission path requires an empty authority delta and no new leases. Authority-expanding work uses a fresh capability cell or a trusted mediator, depending on whether the effect is local and stageable or external and brokerable.
What happens if a fork fails or stalls?
Its result remains failed or stalled and normal merge readiness fails. The user can inspect or discard it. A host-side status consumer that encounters transient capability rotation retries the same job rather than scheduling another fork.
How does Gensee Crate choose among parallel forks?
Gensee Crate assembles changed files, tests, readiness, and approach labels, then may identify the smallest passing diff as a heuristic. The source agent presents the comparison, and the user makes the final branch and lifecycle selection.
Can workspace fork contain external effects?
A fork can contain local workspace divergence. Effects already accepted by another system require a trusted mediator, a receipt, and remote-system semantics for commit or compensation. The current policy blocks known external mutations when that path is unavailable.
Source code and further reading
This post reflects the public Gensee Crate main branch at commit f69be80. Read the workspace-fork integration documentation, the current host-control and lifecycle implementation, the operation classifier, and the same-authority capability lifecycle.