#Processes: nested jobs and authority

Status: implemented. Any process in a Kit job can call registered commands, marsh run, or marsh split. Each call or split argv branch starts a fresh job, subject to admission. The daemon records its parent and cancels the tree together. Kit jobs keep their image's own shells.

The model is docs/model/Process.tla. This builds on workspaces; acceptance scenarios define the external checks. Section 11 summarizes acceptance, section 12 the design decisions, section 13 the exact contract details and formats, section 14 implementation limits, and section 15 Kit job shells and CLI fanout.

#1. Principle: one protocol, many authorities

One protocol. The marsh shell runs where marsh starts a shell: the root shell in the shell VM and split shell branches. Inside a Kit job every shell is the image's own (section 15). Every client (the session shell, the marsh CLI, and the per-name links) speaks one request protocol (Envelope<PublicRequest>) over one local socket.

The daemon binds authority to the caller's socket:

What works in which shell:

• Registered commands and the marsh CLI work in every shell. That covers marsh run, split, join, fanout, collect, jobs, and context. They are executables first on PATH: the links in /run/marsh/bin, the session command dir in the shell VM. So they work from real bash, dash, busybox, zsh, env, Node, Python, or a direct execvp.
• Brush sugar works only in the Brush session shell. That is fanout { } | collect, split { } | join, and in-process dispatch. The CLI forms (marsh fanout ... | marsh collect, marsh split ... | marsh join) work from bash and zsh too. Inside a Kit job, they accept argv branches only; a job cannot start a session-shell branch with wider authority.

The job capability covers both process and split requests (section 3). marsh-local remains the static job artifact. Kit jobs use process admission; split execution also retains its branch pool (workspaces.md, section 4).

#2. Process model

session ─ job ─ job ...            (registered name or marsh run: own container)
        │     └ split ─ branch job (argv branch: a child with a fork view)
        └ split ─ shell branch ─ job ...

• Identities. Session, job, attempt, worker, VM, container, split, and branch ids stay distinct. A job is one attempt and is never retried.
• Records. Each job record gains parent, root, depth, spawn (the names it may start). They are journaled before mark_execution_submitted.
• What creates a node. Only registered names, marsh run, and split branches do. Shell-local concurrency inside a job (pipelines, &, marsh fanout branches) stays in that job's container and is charged to it; a fanout branch that names a registered command starts a child job.
• Capability. Each job has one: a daemon record {job, rights, generation, live|revoked}, never a bearer secret. It is delivered through the worker's per-attempt socket (marsh-worker/src/capability.rs, backend CapabilityBridges). Every Kit job receives that socket.

#3. Requests by authority

ProcessRun is admission (section 6), then an internal Execute through the daemon's own endpoint (as split argv branches do in split.rs), then frame relay.

• Ordering against cancel. Under the process-table lock, the daemon re-checks that the parent's capability is live and not cancelling, inserts the child record, and only then submits. A cancel that takes the lock first sees no child. A cancel that takes it later finds the record and cancels the child (Spawn is atomic in the model).
• stdin. The implementation uses a bounded per-connection queue. The proposed 256 KiB replenished stdin-credit window remains deferred (section 14). stdout and stderr use per-attempt credits.

Capability socket (capability.rs): blocking accept, at most MaxFan + 4 (8) open connections per attempt. An excess connection receives marsh: too many concurrent daemon requests in this job and closes.

#4. The links and the in-job marsh

Artifact. The static musl marsh-local binary is installed on each Kit VM's local disk alongside the worker binaries and bound read-only at /run/marsh/marsh. The session-shell marsh remains a glibc build. Runtime tests check that the job artifact's bind is read-only.

Per attempt, inside the existing capability dir /run/marsh/, which is root-owned and read-only to the job:

• cap.sock.
• job.json: job id, own command name, spawn set, limits, socket path, the names and salted value digests of the container's starting environment, and the names it received from its parent (format in section 13).
• context.md: this job's agent context (section 9), generated by the worker from the shared text with the job's name and spawn set.
• bin/: one two-line stub per name. Stubs exist for marsh and every registered name (a name outside the spawn set is refused by its link, section 13); never for bash or sh. For example #!/run/marsh/marsh --link=codex. The kernel passes the mode and the stub path to the binary, so the mode comes from the kernel and the link name, never from a caller-supplied argv0. /proc/self/exe confirms that the process is the artifact.

Environment:

• PATH=/run/marsh/bin: followed by the PATH from the image config. The worker reads only the image config (Env); there is no probe container.
• MARSH_JOB and MARSH_ENTRY=1. SHELL is left as the image sets it.

The image's shells, system tools, and entrypoint are unchanged. Only registered names and marsh get links; there is no bash or sh link.

What each caller gets:

The in-job marsh starts from job.json alone (no USER, HOME, or daemon), so env -i /run/marsh/bin/codex … and env -i /run/marsh/bin/marsh jobs work. It connects to cap.sock per request. type codex in the image's bash prints codex is /run/marsh/bin/codex. A login profile that resets PATH hides the links; marsh run NAME and the absolute link path still work. The in-job CLI parses marsh splits, but the capability refuses its SplitShow request (section 3).

#5. The links: name resolution and the job's own command

A link L invoked for name N works as follows.

1. Entry case. If N is the job's own name, MARSH_ENTRY=1 is set, and getppid() is docker-init (pid 1; the worker always passes --init), the link:

   • unsets MARSH_ENTRY;
   • resolves N by searching PATH with /run/marsh/bin excluded;
   • execs that image binary by absolute path.

   PATH stays intact, so registered names the agent's later shells run still route through their links.

   The worker sets the marker for every entrypoint. This works for any entrypoint: a #!/bin/sh script's exec claude, real bash, busybox, env, tini, or an exec-form ENTRYPOINT ["claude"] that Docker resolves through PATH.

2. Image tool case. Otherwise, if N is not the job's own name and the image provides N on its PATH without /run/marsh/bin, the link execs the image's N. A registered python or node therefore stays local inside an image that ships it.

3. Child case. Otherwise the link sends ProcessRun and relays stdio and exit status.

marsh run N always takes the child case.

So the unchanged claude entrypoint (exec claude …) starts the real claude once. Claude's Bash tool running claude -p is a new process whose parent is not docker-init, and its marker is gone anyway. It gets a child claude job.

ELF entrypoints. Docker execs an absolute ELF entrypoint directly, so the marker stays in its environment. That is harmless: its descendants' parent is not docker-init.

Assumption A6 (stated, not modeled). An orphan reparented to docker-init that still carries the marker, or a job that forges the marker, can only run its own image binary in its own container. That is a lineage miss, not an authority change. Authority is enforced at the daemon.

Model. EntryOnce (the own name resolves locally at most once per job) and NoEntryRecursion (an entrypoint never spawns its own Kit), with controls linkIgnoresMarker and linkIgnoresPpid. Every job's first step is the entry step: an ELF exec, or a script exec through the link.

Own-name subcommands. An own-name call such as codex exec … from a codex job's shell is a child case, so it runs as a child job that can write only what its mounts allow, which includes the selected home. Kit images pin agent versions, and anything a job installs into its container is discarded when the container is deleted. The packaged Claude Kit refuses claude update and claude upgrade in its entrypoint (exit 125, self-updates are disabled) and sets DISABLE_AUTOUPDATER=1; the child job starts and exits without updating.

#6. Authority and budgets

Rights are (view, spawn set). A child gets its parent's recorded rights or fewer, never rights recomputed from the session's grants. The view is checked by Attenuation (control widen) and the spawn set by SpawnSetAttenuates (control spawnWiden).

Cross-Kit spawning is allowed by default. Any job may spawn any registered command, so the core use (claude → codex) works with no flags. The user's command registry is the trust boundary: registering a Kit means trusting it to be started by any job in any session.

A spawned child runs under its own Kit's policy, not its parent's. It gets its own Kit's SBX network egress policy and SBX-proxied credentials, in its own VM. A claude job that runs codex thereby causes a container with OpenAI egress and credentials to run, with the same files as the claude job. A prompt-injected agent can use any registered Kit's egress in this way. To prevent that, narrow the spawn set.

Narrowing only. These set a smaller spawn set:

• MARSH_SPAWN=a,b, exported in the root shell and read at invocation like MARSH_PLACE;
• marsh run --spawn a,b;
• --no-spawn or MARSH_SPAWN=none: the empty spawn set. The socket and the links stay (splits and jobs still work); admission refuses every spawn.

A child's set is its parent's set or a subset of it. Nothing can widen it, from the cap socket or from the session (SpawnSetAttenuates, control spawnWiden). marsh does not send proxy-held credentials over this socket. Frames carry caller-supplied argv, filtered environment, and stream bytes; callers can still put sensitive data in those fields.

Environment for children. A child receives the variables its parent received from its parent (or, for a root job, the user's exported shell variables), plus those the parent set or changed. A variable the user exports reaches the whole tree, and a child re-exporting a received name with the same value still passes it on. Image ENV is never forwarded unless the job changed it, and the split filter (workspaces.md s13) drops credential-shaped names daemon-side.

• The worker records the received names in job.json (forwarded, from the request's environment) and, for every starting variable, an HMAC-SHA256 of NAME=VALUE under a per-daemon random key that the worker receives in the capability and never writes into the container. The job therefore cannot test guesses of a value against job.json.
• The link offers every variable except Docker-set ones ("" digests), with the starting digests of offered names it did not receive. The daemon (ProcessRun, and SplitCreate from a job) drops an offered variable whose value still matches its digest. A forged offer can only forward the job's own variables, which it could do by changing them.
• Limitation: a job that sets an image ENV variable to its image value is indistinguishable from not setting it; that variable is not forwarded.

The child gets its own image's environment.

Budgets. Process admission covers top-level Kit jobs, Run children, and split argv jobs. Split execution also has a separate branch pool (workspaces.md, section 4). Admission fails fast and never queues, because a parent waiting on a queued child would deadlock the pool.

No TTY children in v1. A job's child gets no PTY. A ProcessRun whose link has a terminal on stdin or stdout is refused with marsh: interactive child jobs are not supported yet: NAME has a terminal on stdin or stdout; run it non-interactively with neither attached, e.g. \NAME ... </dev/null | cat`. PTY frames on cap.sock` come later.

Refusals happen at admission, before any record: a refused spawn leaves no receipt, is printed on the caller's stderr, exits 125 (126 from a link refused by the spawn set), and is counted in marsh status (processes.refused).

#7. Workspace inheritance

• View. A child's mounts are its parent's recorded PublicMount list, copied verbatim and never re-derived from the cwd or the session grants; each is bound from the prepared grant that covers it (as a subpath when narrower). The one addition is narrowing: a project .marsh created after the parent started is bound read-only. A top-level job's child sees the project and the selected home. A branch job's child sees, of the project, only the fork and its Git metadata (split_confinement.rs), plus the selected home read-write as every Kit job does (agents keep settings and session state there).
• cwd. The child's cwd must lie inside those mounts.
• Narrowing. Splits narrow the project view; the late .marsh read-only bind also reduces writes. Nothing widens a child's view.
• Splits. A split created by a job snapshots the job's view root. Capture waits for the creating branch's whole subtree (workspaces.md s13).
• No new writable paths. The artifact and /run/marsh are read-only binds.

#8. Cancellation, revocation, restart

• Job end. A job ends by exit, cancel, or VM transport loss. Its end revokes the capability of the job and all its descendants in one step, then sends INT, waits 10 s, and sends KILL to each descendant container, and verifies deletion in every VM (LiveUnderLive, NoOrphanRunning, CancelPropagates; controls orphanChildren, revokeOnly, noPropagate). This generalizes cancel_children_of in split.rs.
• Lost parent. It becomes cleanup_uncertain, and its children are cancelled.
• Ctrl-C. Daemon-driven. In the root shell, the client's INT (or TERM/HUP) signal frame, or its disconnect, makes the daemon cancel the job's whole tree at once (DaemonStore::cancel_tree): every live descendant is marked cancelling (admission refuses its spawns) and gets INT in its own container now, everything still running gets KILL after 10 s, and each executor verifies deletion. Every job in the tree is recorded cancelled, exit 130, and the root client returns 130. Inside a job, Ctrl-C to a link (or the link's death, or its parent job's end) does the same for that child's subtree. One grace covers every depth.
• Unconfirmed deletion. The job becomes unreaped, its VM is quarantined, and its slot stays held. Held slots are derived from the receipts (cleanup: uncertain after the last successful workers reset of that Kit, persisted in process-resets.json), so they survive a daemon restart and are released only after a reset succeeds.
• Daemon restart. All capabilities are revoked. Unfinished jobs become uncertain and retain held admission slots until verified reset. Nothing is resubmitted (RevokedAtRestart, RestartUncertain, NoReplay). The adapter's in-memory VM quarantine is not restored from receipts (results.md). The root client attached to an in-flight tree exits 125 with job uncertain; its children are listed uncertain.
• Restart under --dev. make dev reinstalls and restarts marshd. Jobs that were running, nested ones included, become uncertain and hold their slots until marsh workers reset KIT. Stop agent trees before reinstalling. The dev broker's grants are revoked at restart (self-development.md).

#9. Lineage and awareness

Lineage.

• Receipts' lineage becomes {parent, root, depth, spawn, split?, label?} (section 13). marsh jobs show prints it (text: parent, root, depth, spawn, split) and adds children (child ids); marsh results adds a PARENT column (the parent job's short id, - for a root).
• marsh jobs --tree [--all] [--json] prints the forest, or inside a job its own subtree. marsh jobs [--all] lists the same jobs flat. The text forms are scoped (section 13): in a session, trees rooted in that session; from a host terminal, running trees, trees started in the last hour, and the five newest trees; --all, every tree. --json is not scoped by session or age. Inside a job, every form, --all and --json included, covers only the job's own subtree (the capability filters Jobs and ProcessShow).
• Splits are nodes of the forest. A split created by a session (or the host CLI) is a root whose children are its branches; a branch's children are the jobs it started: an argv branch's job, or every Kit command its shell ran (the daemon records the branch session at OpenShell and gives such a job lineage.parent = split:<id>/<label>), with their own descendants, and any split the branch created. A session's scoped listing includes the splits it created and everything under them, also after join removed the split (the daemon keeps the 64 newest splits' lineage in split-lineage.json). A root job started by a stage after join (it sees SPLIT_ID) records lineage.consumes and is drawn with (consumes split ID). A job's own split (argv branches only) stays under the job: its branches are the job's children.
• Fanouts are display nodes. marsh fanout gives each branch FANOUT_BRANCH=<fanout id>/<label>; a root job or split-branch job started with it records lineage.fanout, and the tree draws those jobs under one fanout node at the first job's place. A registered command in a fanout branch inside a job is an ordinary child of that job and gets no fanout node. The grouping is for display only; it adds no authority or lifecycle.
• An interactive shell's background job (stderr a terminal whose foreground process group is not the job's) does not print the cold-start notice [starting NAME worker VM…]. A foreground job prints it as before.
• marsh status adds processes: {running, refused, held} (text: processes: N running, N refused, N held). Ended shells (detached, their authority released) are no longer listed in shells.

Awareness.

• Inside a job: type codex, marsh --help, /run/marsh/context.md, and MARSH_JOB. The context file is one source text (crates/marsh-contracts/src/context.md, at most about 60 lines) that the worker fills in per job with the job's name and spawn set (process::job_context). It covers starting one child (codex exec "…"), parallel private attempts (marsh split -n ::: a … ::: b … | marsh join and applying a branch's patch), shared-workspace parallel work (marsh fanout … | marsh collect), marsh jobs --tree, narrowing, the limits, confinement, and when not to spawn.
• marsh context prints the same text (outside a job: the generic text). It only prints; it never writes.
• Delivery to agents. The packaged agent Kits pass the file to their agent for that run, the way the agent reads instructions: Claude Code --append-system-prompt (CLI; in ACP mode claude-cli.sh appends it to the Agent SDK's value), Codex -c developer_instructions= (CLI) and codex-acp's CODEX_CONFIG (ACP), Pi --append-system-prompt FILE (both modes). Nothing is written into the project, the selected home, CLAUDE.md, AGENTS.md, ~/.codex, or ~/.pi (agents.md). Stock SBX's agent-context@1 capability is not used by marsh jobs (it writes into the agent's home); third-party Kits read /run/marsh/context.md or run marsh context.

#10. Model

model/Process.tla models:

• Launches by the session, or by any running job that holds a live capability and has finished its entry step.
• Rights narrowing: the view and the spawn set.
• The pool, depth, same-Kit chain, fan-out, total, and per-tree Kit VM caps.
• The exit, cancel, and loss cascades, with grace and unreaped.
• A daemon restart between any two steps.
• Per-Kit entrypoint kind (script or ELF), a mandatory entry step, and the link's own-name decision.

Invariants:

• LineageWF, Attenuation, BudgetBound, FanOutBound, TotalBound;
• LiveUnderLive, NoOrphanRunning, CancelPropagates;
• RevokedAtRestart, RestartUncertain, NoReplay;
• EntryOnce, NoEntryRecursion, SameKitBound, SpawnSetAttenuates, KitVMBound;
• the liveness property EventuallySettled.

Each invariant has one negative control that removes a guard in a real action.

Not modeled:

• assumption A6 and Bash semantics;
• the read-only artifact (a runtime test checks it);
• mount paths, credentials, streams and credit;
• wall time: there is no clock. A deadline is one of the environment's Cancel(j, Session) steps at any time, which already reaches every descendant (CancelPropagates). That a child's deadline is never later than its parent's is a value fixed at admission, checked by process_tests.rs and P35, not by TLC;
• Workspace.tla's fork and capture, which compose through the shared cascade and the pool.

#11. Acceptance

The acceptance goals, with real callers and any Kit, are below. processes-acceptance.md lists the maintained black-box scenarios and the gaps they do not cover.

• claude, then the Bash tool runs claude -p, which runs codex exec: three containers with lineage. Ctrl-C in the root shell gives verified deletion in each VM.
• With MARSH_SPAWN=claude, codex from claude is refused, with the message, and a child cannot widen its set.
• An unchanged third-party Kit (for example Alpine, with a #!/bin/sh entrypoint wrapper) runs registered names, and split from bash -c.
• env -i /run/marsh/bin/NAME and env -i /run/marsh/bin/marsh jobs work.
• A self-replicating marsh run shell -c stops at the caps.
• A branch job's child cannot see the project.
• A restart mid-tree leaves uncertain jobs and no replay.
• Exported variables reach the whole tree; image ENV and secrets never do.
• The artifact bind is read-only.

#12. Design decisions

• The link holds the entry rule. The marker and docker-init parent check live in the artifact, not in a shell, so the rule works for any entrypoint (section 5).
• Nothing is shadowed. Only registered names and marsh get links; /bin/sh, /bin/bash, PATH bash, and SHELL are the image's own (sections 4 and 15).
• Cross-Kit spawning is on by default; only narrowing exists. A child runs under its own Kit's egress and credentials. MARSH_SPAWN, --spawn, and --no-spawn narrow; nothing widens (SpawnSetAttenuates, section 6).
• The link mode comes from the kernel. The shebang stub and /proc/self/exe select the mode, never a caller-supplied argv0, and job mode starts from job.json alone (section 4).
• Children receive only what the job received or changed. Unchanged image ENV is never forwarded; digests are keyed so a job cannot test guesses (section 6).
• The capability socket refuses, never drops. It uses a blocking accept, at least MaxFan + 4 connections, and a refusal frame (section 3).
• Spawn is ordered against cancel by re-checking the parent's capability under the process-table lock (section 3).
• Loops are bounded and refusals explain themselves. The same-Kit chain cap is 2; messages name the chain, context.md, and marsh workers reset KIT.
• No TTY children; image-provided names stay local; marsh context only prints (sections 5, 6, and 9).
• The model checks the link decision. Per-Kit entrypoint kind and a mandatory entry step make EntryOnce and NoEntryRecursion non-vacuous; shell integrity is a runtime test, not an invariant (section 10).

#13. Contract details

1. Entry rule keeps PATH. The link takes the entry path, clears MARSH_ENTRY, and execs the image binary by absolute path (PATH searched with /run/marsh/bin excluded). PATH is not stripped (section 5).
2. Same-Kit chain counts consecutive parent→child steps whose Kit identity (the Kit reference the job ran from) is equal; cap 2. A split argv branch is not such a step: nested splits are already bounded by the split depth limit 3 (workspaces.md), and counting them would refuse the third level of an all-fixture nested split. The chain walk stops at a branch job.
3. Depth base. A root job is depth 1.
4. Refusals leave no receipt; they go to the caller's stderr and processes.refused.
5. Spawn set. Every registered name has a link. A name outside the spawn set prints marsh: spawn refused: NAME not in this job's spawn set (MARSH_SPAWN) and exits 126 (125 from marsh run). --spawn beyond the parent's set narrows to the intersection and warns on stderr.
6. Splits from a job. Any job may split; the snapshot is its view. From a job a split is argv-only: the daemon refuses shell branches (-b, and the sugar) for every job creator, top-level or nested, because a shell branch is a session shell with the session's full spawn set (split: LABEL: shell branches (-b, split { }) run only from the session shell; from a job or a split branch use argv branches: ::: LABEL CMD [ARG...]). Argv branches are child jobs of the creating job (lineage.parent = job:<creator>). Inside a job, marsh fanout ::: … is the in-container, shared-workspace form (argv branches only, refused locally for -b).
7. Pool scope is per daemon (selected home).
8. Formats.
   • Receipt lineage: {"parent": "session:<id>" | "job:<id>" | "split:<id>/<label>", "root": "<root job id>", "depth": 1.., "spawn": ["name", ...], "split"?: "<id>", "label"?: "<label>", "deadline_unix_ms"?: N, "parent_deadline"?: true, "consumes"?: "<split id>", "fanout"?: "<fanout id>/<label>"}; jobs show adds "children": ["<job id>", ...]. split: is the parent of a job a split branch started without a parent job (an argv branch of a session's split, or a Kit command run by a shell branch); consumes marks a root job started by a stage after join; fanout marks a job without a job parent that a marsh fanout branch started (display grouping only).
   • Receipts carry "args": ["...", ...] for display: the invocation's first 16 arguments, each cut to 200 characters (lossy UTF-8; omitted when empty).
   • marsh jobs --tree --json: {"schema": "marsh.jobs.tree/v1", "jobs": [NODE]}, roots newest first, every tree (not scoped by session or age; inside a job, the job's subtree). A NODE is one of
     • a job: {"node": "job", "job_id", "session_id", "command", "args", "state", "cleanup", "exit_code", "created_unix_ms", "finished_unix_ms", "lineage", "children": [NODE]};
     • a split: {"node": "split", "split_id", "session_id" (the creating session), "state" (run, await, joined, kept, cancelled, uncertain), "status", "created_unix_ms", "finished_unix_ms" (all branches captured), "parent": {"split", "label"} | null, "timing_ms", "children": [BRANCH]};
     • a branch: {"node": "branch", "split_id", "label", "kind" (shell|argv), "command", "state" (pending, running, captured, rejected, failed, cancelled, uncertain), "status", "exit_code", "job_id" (an argv branch's job), "files", "created_unix_ms", "finished_unix_ms", "children": [NODE]};
     • a fanout: {"node": "fanout", "fanout_id", "session_id", "state" (running|finished), "status" (the first nonzero branch exit, else 0 once finished), "created_unix_ms", "finished_unix_ms", "children": [FANOUT BRANCH]}, where a fanout branch is {"node": "branch", "fanout_id", "label", "kind": "argv", "job_id", "state", "children": [the job's NODE]}. A daemon restart may forget a split whose jobs remain: it is drawn from their lineage with state: null. marsh jobs --json stays the marsh.jobs/v1 document.
   • Text (jobs, jobs --tree): a header ID STARTED STATE EXIT RUN [PARENT] COMMAND, then one line per job: the first 8 characters of the job id, start as Ns|Nm|Nh|Nd ago, state, exit code or -, RUN (from the job record's creation, when its Kit VM is ready, to its end: 12.3s, 2m13s, 1h05m), and command arg... with each argument shell-quoted, cut to 64 characters with …, then cleanup uncertain (run marsh workers reset KIT) when it applies. Trees containing a queued or running job come first, then newest first. --tree keeps children under their parent in launch order, drawn with ├─ /└─ (and │ ) in the command column; the flat form sorts every job the same way and adds PARENT (the parent's short id, - for a root). A split row shows the split's first 8 id characters, joined (or running, awaiting, kept, cancelled, uncertain), its status, its run time, and split (LABEL, ...). A fanout row shows the fanout's first 8 id characters, running or finished, its status, its run time, and fanout (LABEL, ...). An argv branch row is its job's row (id and fields) with LABEL: COMMAND; a shell branch row has the ID <split8>/LABEL, the branch state in job words (queued for pending, finished for captured, unknown for uncertain, otherwise as recorded), and LABEL: COMMAND. The flat form lists jobs only; a branch's job shows the split's short id as PARENT. Scoped-out trees end the listing with (N older job trees not shown; marsh jobs [--tree] --all lists every job); an empty listing prints no jobs in this session or no jobs recorded.
   • marsh status --json: "processes": {"running": N, "refused": N, "held": N}.
   • /run/marsh/job.json: {"version": 1, "job", "name", "spawn": [...], "registered": [...], "socket": "/run/marsh/cap.sock", "path": "<starting PATH>", "limits": {"pool", "depth", "same_kit", "fan_out", "total"}, "env": {"NAME": "<HMAC-SHA256 hex of NAME=VALUE under the daemon's key>" | "" (set by Docker, never forwarded)}, "forwarded": ["NAME", ...] (received from the parent)}. Every Kit job retains the socket and links, including with --no-spawn; an empty spawn set narrows admission rather than removing the channel.
9. Restart. The root client attached to an in-flight tree exits 125 with job uncertain; children are listed uncertain.
10. Connection cap counts open connections including idle ones; an excess connection reads one error frame (too many concurrent daemon requests in this job) and is closed.
11. TTY. A child is refused if its stdin or stdout is a terminal.

#14. Implementation notes and deferrals

• The worker installs marsh-local-linux-arm64 at /usr/local/libexec/marsh-local on the Kit VM's disk.
• Process admission is checked before VM preparation and again under the store lock in begin_job_process, before submission.
• The artifact is mandatory: the worker install and identity and the job's container setup fail without it; a failed /run/marsh setup fails the attempt (SetupFailed), never runs it without one.
• The same-Kit pre-check uses the Kit identity resolved before VM work; refused launches count toward their tree's total.
• The daemon applies the split environment filter to ProcessRun itself.
• A connection slot on cap.sock is freed only when the daemon side closes; a link retries a refused connection briefly (nothing was started).
• job uncertain is reported only for transport loss after the daemon accepted the job or shell.
• Deferred: the stdin credit window (stdin uses the existing per-connection queue).
• Wall-time inheritance: DaemonStore::set_job_deadline (process.rs) fixes each job's deadline just before launch and the backend passes the remaining seconds as the worker's wall_seconds; child_lineage copies the parent's deadline and refuses a child with under a second left. The Kit VM cap is kit_vm_cap, counted over the tree's live receipts by Kit identity (kit_ref), in both the pre-check and begin_job_process.

#15. Kit job shells, CLI fanout, agent context

A Kit job's shells are the image's own. marsh adds no bash or sh link and no SHELL override to a job, and the artifact has no job-shell mode (Brush is not a job shell). Rationale:

• Compatibility. Agents and build tools run whatever Bash the image ships; no classified Brush divergence (bash-compatibility.md) can reach an agent's tool calls, scripts, or bash -lc profiles.
• Performance. No wrapper sits between an agent and its shell (P24 checks PATH bash is within 2 ms of /bin/bash).
• Debuggability. What runs in a job is what the image author tested; a failing tool call reproduces with docker run of the same image.
• CLI forms cover composition. Registered names (links), marsh run, marsh split | marsh join, marsh fanout | marsh collect, marsh jobs, and marsh context work from any shell. Only the Brush sugar syntax is unavailable in jobs.

The static artifact (marsh-local, musl) provides the links and the in-job CLI, and it is the Brush binary that the Bash-compatibility tests use. The Brush patches serve the session shell.

marsh fanout [-n] [-b LABEL=STRING]... [::: LABEL CMD ARG...]... | marsh collect [--json] [--timing] [--stderr] has the sugar's semantics: branches run at once in the caller's place on the same files (no fork), each reads the same spooled stdin (-n or a terminal: empty), and collect renders them in declaration order with Brush's own renderer (brush_core::render_collected, patches 0045, 0046): per branch the header, its stdout, then a failed branch's stderr under == LABEL stderr ==, all on stdout (as join does; --stderr shows successful branches' stderr too); the exit status is the first nonzero branch status. Limits: 16 branches, 64 MiB input, 16 MiB combined output; INT, TERM, and HUP are forwarded to every branch's process group (10 s, then KILL) and fanout exits 128+signal. fanout writes one JSON line (marsh.fanout/v1, branch bytes base64) for collect, or the rendering itself when its stdout is a terminal.

• In a job: argv branches only (as for split); -b is refused locally with the session-shell message. A registered name in a branch is a child job through its link.
• In the shell VM: -b runs STRING with the session shell (a child guest marsh attached to the same session, as Brush runs a shebang-less script).
• On the host: the same fanout runs in a session shell in the shell VM (marsh -c 'exec marsh fanout …'); the host picks the output form and passes -n when its stdin is a terminal.

No daemon request is involved: fanout is local concurrency, so the Brush sugar and the CLI share the renderer rather than a protocol.

Agent context is generated per job and delivered by the agent Kits (section 9, agents.md).