execd

const (
	PolicyLaunchBurst    = 4
	PolicyLaunchInterval = 500 * time.Millisecond
)

PolicyLaunchBurst and PolicyLaunchInterval pace how fast policy-controlled commands may be launched: PolicyLaunchBurst of them may start with no wait at all, and the budget refills at one launch per PolicyLaunchInterval. See launchPacer for what is being rationed and how the numbers were arrived at.

const (
	ExitSyntaxError = 2
	// ExitTimeout is the status a timed-out request reports. It follows GNU
	// timeout(1), so a caller that already knows that convention reads it
	// right.
	//
	// Two ways it is weaker than GNU timeout(1), both measured on nono 0.74.0,
	// 2026-09-20. It does not return AT the timeout: cancellation tears the
	// process groups down then, but the request still pays out whatever of
	// DrainGrace the drains have left, so it returns at the timeout plus up to
	// that grace. Measured with `git log --oneline | git cat-file
	// --batch-check` at a 1000ms timeout, 5 runs (probe log set bt1-5): the 4
	// that hit a stall reported 124 at 2017-2024ms, and the 1 that did not
	// finished 0 at 18ms.
	// And what it kills is what execd started: a policy-controlled command's
	// own children survive it — `sh -c 'sleep 60'` at a 3000ms timeout
	// reported 124 at 5004-5005ms and left the sleep running, 3/3 (log set
	// ss1-3). See Job and DrainGrace for both.
	ExitTimeout     = 124
	ExitCannotStart = 126
	ExitNotFound    = 127
)

The statuses execd reports for outcomes that are not the command's own. They are collected here because a caller reads them as one vocabulary:

the command's own   the last command's exit status
128 + signum        died from a signal
127                 command not found
126                 could not be started (exec or wiring failure)
124                 timed out
2                   syntax error
1                   the interpreter failed for a reason that is not an exit status

An error frame is never used for any of these: it reports a fault of execd itself, and a command that fails is not a fault of execd.

const DrainGrace = 2 * time.Second

DrainGrace bounds how long a finished command's output is waited for once its process tree is gone. Exceeding it means something outside the group still holds a write end; the request ends with a truncation note rather than hanging, which is what the old wiring did.

This is the bound a pipeline with a policy-controlled command on both ends now runs into, and it is why this package no longer refuses that shape outright. Measured on nono 0.74.0 against this repository's command-profile.json, 2026-09-20, with `git log --oneline | git cat-file --batch-check` — the writer exits, the reader blocks on stdin — run 21 times. Sixteen of those carried a 5000ms request timeout and five carried 20000ms; both are far above this grace, so the grace is the only bound in play either way. Probe log set: runB1-6, full, full2, bb1-10, plus three runs that reached the transcript only.

14 runs   the writer's drain never saw EOF: something on nono's side still
          held a duplicate of the write end, so waitDrains gave up and its
          forced close is what released the blocked reader. Requests ended
          at 2018-2023ms.
 7 runs   no stall at all; requests ended at 15-20ms.

Only 9 of those 14 recorded per-stage timings — runs 1-6 of the set predate the instrumentation — and over those 9 the writer's own Wait returned in 14-16ms, waitDrains gave up at 2000-2001ms, and the reader's Wait then returned at 2018-2020ms. The stalled/clean split above needs no timing line, being read off elapsed time alone, which is why its denominator is 14 and this one is 9.

All 21 returned. Three other aggregates have smaller denominators, because not every run recorded every figure: 18 of the 21 have a byte count, and all 18 are identical at 30585 bytes; 16 had a survivor check afterwards, and all 16 were clean. The remaining runs were not measured for those, which is not the same as having been measured clean.

Three further run sets, each separate from those 21 and from each other. `git log --oneline | cat | git cat-file --batch-check`, a floor command between the two policy stages, 5 runs at a 5000ms timeout (log set cc1-5): 3 stalled, ending at 2023-2029ms, and 2 clean at 15-16ms, all complete. `git log --oneline | cat` — a policy writer into a floor reader — 8 runs (log set dd1-8): 14-19ms, 27361 bytes, and not one stall. That last set is the discriminator: the same writer stalls above and never stalls there, so what the stall takes is a policy-controlled *reader*, not merely piping a shim's output somewhere. The third set is the timeout leg (log set bt1-5), cited on ExitTimeout, and is deliberately not folded in here: those runs ended on a timeout mid-flight and cannot support a claim about complete output.

Every figure above names the log set it came from, and that is deliberate. Three successive revisions of this comment carried numbers belonging to a neighbouring set — the 2028-2029ms pair above is exactly what leaked into the 21-run range twice. If you change a number here, re-derive it from the named set rather than from this comment's previous wording; docs/superpowers/probes/2026-09-19-policy-pipe-hang.md carries the per-run tables each log set above is named for.

So the hazard is unchanged — the fd is still leaked, inside nono's own machinery — but it is a bounded incident now rather than a permanent one.

What this bound no longer reaches is the outer boundary, and that changed with descriptor passing. A top-level simple command's cmd.Stdout is now the caller's own file, so nothing is interposed there and waitDrains has no read end to force-close. A descendant that outlives Job.Terminate — `sh -c 'sleep 60'` does, 3/3, inside nono's child sandbox; see the Job doc above — therefore holds a duplicate of the *caller's* pipe, which this package cannot touch. Pre-branch it held execd's interposed pipe instead, and this grace force-closing that pipe is why those runs returned at 5004ms. Post-branch the request itself returns sooner, ~3000ms, the timeout alone; but `agent-sandbox exec … | downstream` leaves `downstream` waiting for an EOF for as long as the strand lives, and nothing here bounds that.

Accepted, not overlooked. It is inherent to handing a descriptor to a command — ssh has the same shape — and the only way to bound it again is to re-interpose a pipe at the boundary, which is the relay this branch removed. The shape that produces it is narrow and nameable: a command that leaves a descendant running past its own exit, with the caller's stdout a pipe rather than a terminal or a file. What stays bounded is the request; what is not bounded is whoever reads the other end of the caller's pipe.

What that split does and does not say about this constant's value. EOF either arrived within ~15ms or had not arrived by 2000ms; nothing landed in between. So shortening the grace would not make stalls rarer or commoner — it would only make each one cheaper. The hazard in shortening it is elsewhere: waitDrains ends a stall by force-closing the read ends, so a producer still writing at that moment loses its tail. That did not bite in any of the 18 runs that have a byte count — the producer had exited ~2s earlier and its bytes were already in the pipe — but a grace short enough to land while output is still in flight would truncate for real. The note saying so does reach the caller (below), and is the only thing that would tell them; revisions of this comment before 2026-09-21 argued from the opposite premise, so do not resurrect it. Raising the grace lengthens every stalled request by the same amount. Re-measure before moving it either way.

That note is the last thing to know here, and what this comment said about it until 2026-09-21 was false. It claimed the note never reaches the caller from a non-final pipeline stage, because mvdan.cc/sh drops such a stage's stderr entirely, so a policy-to-policy pipe presents as a silent ~2s stall. The drop is real but belongs to the harness that measured it: 2026-09-19 drove ShellExecutor.Execute in-process with a bytes.Buffer as stderr. Through the client, where stderr is a real descriptor, the note arrives — 80 bytes, one distinct text, in 69 of 69 stalled runs across three log sets, on this branch and on the pre-branch binary alike (docs/superpowers/probes/2026-09-21-fd-passing.md §8, which is never committed, so this sentence is where that correction survives). A user of `agent-sandbox exec` therefore sees a ~2s stall, the note naming the command that caused it, complete output, and — unless the request timeout fired first — a correct exit status.

const SandboxNotRunningHint = "exec daemon is not available; run Claude via `agent-sandbox claude`, which starts it automatically"

SandboxNotRunningHint is the actionable message shown when execd is not reachable. It is exported because the situation is detected before any command runs: `agent-sandbox exec` and the MCP server both fail to build a client when AGENT_SANDBOX_EXECD_SOCKET is unset, and must print this rather than a raw dial error.

const SocketEnvVar = "AGENT_SANDBOX_EXECD_SOCKET"

SocketEnvVar names the environment variable that carries the execd socket path into the sandbox.

const TerminateGrace = 200 * time.Millisecond

TerminateGrace is how long a process gets to act on SIGTERM before SIGKILL. It is long enough for a handler to run and short enough that a cancelled request still returns promptly. Terminate does not spend it when nothing is alive to spend it on.