Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python
27.4 KB
Raw Blame
//! Root and subagent `bash` dispatch. Split out of exec.zig so the grok-build
//! auto-background path (#620) has room without growing exec.zig.
//!
//! Root foreground: spawn a job, wait up to 120s unattended (interactive
//! REPL/TUI/GUI: 15s, ADR 0154). Unattended, a shorter `timeout` may promote
//! earlier, not below 5s; interactive surfaces ignore it (ADR 0233). A larger
//! one cannot extend the wait. Then promote rather than kill — the
//! process keeps running and the model gets a job id. Interactive parked
//! jobs yield the parent like subagents. Subagents stay on the #93
//! kill-at-120s path (no TTY, no /jobs UI).

const std = @import("std");
const builtin = @import("builtin");
const Io = std.Io;
const Allocator = std.mem.Allocator;
const Value = std.json.Value;

const tools = @import("tools.zig");
const ToolCtx = tools.ToolCtx;
const ToolOutput = tools.ToolOutput;
const strField = tools.strField;
const intField = tools.intField;
const missingArg = tools.missingArg;
const bash_stdout_cap = tools.bash_stdout_cap;
const bash_stderr_cap = tools.bash_stderr_cap;

const jobs = @import("jobs.zig");
const job_wait = @import("job_wait.zig");
const exec_bash_stream = @import("exec_bash_stream.zig");

/// grok-build's default foreground wait. After this, root bash is moved to
/// the job registry instead of being killed (xai-org/grok-build BashTool).
pub const root_wait_ms: u64 = 120 * 1000;

/// Lean `-p` has no human watching a hung test (ADR 0055). DeepSeek flash
/// SWE sat 120s on `python3 test_json_stream.py`. Interactive REPL/TUI/GUI
/// uses the same 15s bound so a `gh run watch` parks and yields (ADR 0154).
pub const lean_oneshot_wait_ms: u64 = 15 * 1000;

/// Wall-clock ceiling for one *subagent* bash command. Subagents run on pool
/// threads with no TTY, so there is no Esc to kill a runaway command — without
/// this, a codedb refusal that pushes a subagent onto an unfiltered `grep ~/`
/// hangs the whole workflow for ~48 min (#93).
pub const subagent_deadline_ms: u64 = 120 * 1000;

const cancel_hint =
    "If this was a server, drill, or anything that should outlive one turn, restart with run_in_background: true — do not wait in the foreground again.";

/// #266: killing a local `ssh` proves nothing about the remote command it was
/// running — a cancelled or timed-out ssh result carries a caveat saying so.
fn isSshCommand(cmd: []const u8) bool {
    var it = std.mem.tokenizeAny(u8, cmd, " \t\r\n");
    const first = it.next() orelse return false;
    return std.mem.eql(u8, std.fs.path.basename(first), "ssh");
}

test "isSshCommand: bare and pathed ssh, not scp or substrings" {
    try std.testing.expect(isSshCommand("ssh host uptime"));
    try std.testing.expect(isSshCommand("  /usr/bin/ssh -T host"));
    try std.testing.expect(!isSshCommand("scp file host:"));
    try std.testing.expect(!isSshCommand("echo ssh"));
    try std.testing.expect(!isSshCommand(""));
}

fn spawnFailText(gpa: Allocator, err: anyerror) ![]u8 {
    // #122: backgrounding costs MORE fds (pipes + pump task), so the generic
    // "run it in the foreground" advice is right for every error except the
    // fd-quota ones. #253: SYSTEM-wide exhaustion is not a ulimit problem.
    if (err == error.ShellIdentityUnavailable) {
        const shell_identity = @import("shell_identity.zig");
        const cause = shell_identity.last_cause orelse error.Unexpected;
        // #1619: name the cause; only a storage fault is a permissions problem.
        if (!shell_identity.storageFault(cause))
            return std.fmt.allocPrint(gpa, "could not reserve a durable shell handle (ShellIdentityUnavailable: {t}); no command was started. This was retried and is usually transient: run the command again.", .{cause});
        return std.fmt.allocPrint(gpa, "could not reserve a durable shell handle (ShellIdentityUnavailable: {t}); no command was started. Check HOME and its .codegraff directory permissions. Preserve existing shell-id files when repairing storage.", .{cause});
    }
    if (err == error.ShellIdentityHomeRequired or err == error.ShellIdentityStoreInvalid or err == error.ShellIdentityExhausted)
        return std.fmt.allocPrint(gpa, "could not reserve a durable shell handle ({t}); no command was started. Check HOME and its .codegraff directory permissions. Preserve existing shell-id files when repairing storage.", .{err});
    return if (err == error.ProcessFdQuotaExceeded)
        try gpa.dupe(u8, "could not start background job (ProcessFdQuotaExceeded) — graff hit its open-file limit. Wait for running jobs/tools to finish, then retry with less parallel fan-out; if it recurs, raise the limit (`ulimit -n 4096`) before starting graff.")
    else if (err == error.SystemFdQuotaExceeded)
        try gpa.dupe(u8, "could not start background job (SystemFdQuotaExceeded) — the SYSTEM-wide open-file table is full, so neither foregrounding nor `ulimit` helps. Wait for other processes to release files (or close some applications), then retry.")
    else
        try std.fmt.allocPrint(gpa, "could not start background job ({t}) — run it in the foreground instead", .{err});
}

/// How a job got to the background: started there as a server or as a
/// finite command (#1349), or parked after the foreground wait as a
/// server-like or a finite command (#1324).
const Started = enum { background, background_finite, server, finite };

/// A finite job's next move (ADR 0215): its result arrives by itself, so the
/// model keeps working or ends its reply to wait. Servers never report.
const reports_back = "Its exit status and output reach you when it finishes: continue with independent work, or end your reply to wait for it.";

fn startedText(gpa: Allocator, id: u64, cmd: []const u8, ssh: bool, how: Started, wait_s: u64, partial: []const u8) ![]u8 {
    var aw: Io.Writer.Allocating = .init(gpa);
    errdefer aw.deinit();
    const w = &aw.writer;
    try w.print("[job {d} started: {s}]\n", .{ id, cmd });
    if (@import("job_wait.zig").followup_pending.load(.acquire)) {
        try w.print("Follow-up received while this was running; it was moved to the background so you can talk. Process is still running as job {d}. You are notified on exit — do not poll. action=output is a snapshot; action=kill stops it.", .{id});
    } else if (how == .server) {
        try w.print("Command exceeded the {d}s foreground wait and was automatically moved to the background. Process is still running as job {d}. You are notified on exit with the status and output — do not poll. action=output is a snapshot; leave it on /jobs or action=kill it.", .{ wait_s, id });
    } else if (how == .background_finite) {
        try w.print("Running in the background as job {d}. {s} To block on it instead, call action=output id {d} with wait_ms>0 once; action=kill stops it.", .{ id, reports_back, id });
    } else if (how == .finite) {
        try w.print("Command exceeded the {d}s foreground wait and was automatically moved to the background. Process is still running as job {d}. {s} To block on it instead, call action=output id {d} with wait_ms>0 once; action=kill stops it.", .{ wait_s, id, reports_back, id });
    } else {
        try w.print("This is a persistent server. It runs in the background across turns. You are notified on exit — do not poll. action=output id {d} reads unread output. action=kill stops it.", .{id});
    }
    if (ssh) try w.writeAll(" Killing the local SSH job cannot prove a detached remote process stopped; verify the remote host.");
    if (partial.len > 0) {
        try w.writeAll("\n");
        try w.writeAll(partial);
    }
    return aw.toOwnedSlice();
}

fn defaultRootWaitMs(interactive: bool) u64 {
    const main_mod = @import("main.zig");
    if (interactive) return lean_oneshot_wait_ms;
    if (main_mod.unattended and @import("no_local_tools.zig").lean) return lean_oneshot_wait_ms;
    return root_wait_ms;
}

fn rootWaitMs(input: Value) u64 {
    return rootWaitMsFor(input, false);
}

/// ADR 0233: the shortest foreground wait a model's `timeout` may ask for.
/// Some models send `timeout: 1000` as a read-output-after habit; honored,
/// it parked half of those commands (git, gh, node) after one second.
pub const min_model_wait_ms: u64 = 5 * 1000;

fn rootWaitMsFor(input: Value, interactive: bool) u64 {
    const bound = defaultRootWaitMs(interactive);
    // An interactive park ends the turn (ADR 0154), so a shorter wait only
    // stops the agent sooner; the 15s bound stands (ADR 0233).
    if (interactive) return bound;
    const t = intField(input, "timeout") orelse return bound;
    if (t <= 0) return bound;
    // #850: timeout may shorten the foreground wait; it must not recreate the
    // #620 hang by stretching it toward the 10h job-wait cap.
    return std.math.clamp(@as(u64, @intCast(t)), @min(min_model_wait_ms, bound), bound);
}

test "rootWaitMs: omitted/zero use 120s; a shorter timeout may promote earlier" {
    const empty = try std.json.parseFromSlice(Value, std.testing.allocator, "{}", .{});
    defer empty.deinit();
    try std.testing.expectEqual(root_wait_ms, rootWaitMs(empty.value));
    const zero = try std.json.parseFromSlice(Value, std.testing.allocator, "{\"timeout\":0}", .{});
    defer zero.deinit();
    try std.testing.expectEqual(root_wait_ms, rootWaitMs(zero.value));
    const custom = try std.json.parseFromSlice(Value, std.testing.allocator, "{\"timeout\":5000}", .{});
    defer custom.deinit();
    try std.testing.expectEqual(@as(u64, 5_000), rootWaitMs(custom.value));
}

test "#850: a large explicit timeout cannot extend the foreground bound" {
    const huge = try std.json.parseFromSlice(Value, std.testing.allocator, "{\"timeout\":999999999}", .{});
    defer huge.deinit();
    try std.testing.expectEqual(root_wait_ms, rootWaitMs(huge.value));
    try std.testing.expect(rootWaitMs(huge.value) < job_wait.wait_cap_ms);
    const schema = @embedFile("schema.zig");
    try std.testing.expect(std.mem.indexOf(u8, schema, "max 36000000") == null);
}

// The behavior half of #850: a wait bounded at the default promotes rather than
// parking the turn, the child is NOT killed, and it stays reachable through the
// same bash_output/bash_kill the auto-background result points the model at.
// The bound itself is the pure-function assertion above; 200ms stands in for
// the expiry so the test does not sleep for the real one.
test "#850: promotion at the bound leaves the child alive and reachable" {
    if (builtin.os.tag == .windows or builtin.os.tag == .wasi) return error.SkipZigTest;
    jobs.g_jobs = .{};
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    const id = (try jobs.spawnJob(gpa, io, "sleep 5; printf never")).id;
    defer jobs.jobsReap(gpa, io);
    const waited = try jobs.waitForeground(gpa, io, id, 200);
    defer switch (waited) {
        .running => |r| gpa.free(r.output),
        .done => |d| gpa.free(d.output),
        .cancelled => |c| gpa.free(c.output),
    };
    try std.testing.expect(waited == .running);
    try std.testing.expectEqual(id, waited.running.id);
    const snap = try jobs.jobOutput(gpa, io, id, 0);
    defer gpa.free(snap.text);
    try std.testing.expect(std.mem.indexOf(u8, snap.text, "running") != null);
    const killed = try jobs.jobKill(gpa, io, id);
    defer gpa.free(killed.text);
    try std.testing.expect(std.mem.indexOf(u8, killed.text, "killed") != null);
}

test "rootWaitMs: lean unattended oneshot defaults to 15s; shorter timeout still wins" {
    const main_mod = @import("main.zig");
    const nlt = @import("no_local_tools.zig");
    const saved_u = main_mod.unattended;
    const saved_l = nlt.lean;
    defer {
        main_mod.unattended = saved_u;
        nlt.lean = saved_l;
    }
    main_mod.unattended = true;
    nlt.lean = true;
    const empty = try std.json.parseFromSlice(Value, std.testing.allocator, "{}", .{});
    defer empty.deinit();
    try std.testing.expectEqual(lean_oneshot_wait_ms, rootWaitMs(empty.value));
    const custom = try std.json.parseFromSlice(Value, std.testing.allocator, "{\"timeout\":5000}", .{});
    defer custom.deinit();
    try std.testing.expectEqual(@as(u64, 5_000), rootWaitMs(custom.value));
    const huge = try std.json.parseFromSlice(Value, std.testing.allocator, "{\"timeout\":60000}", .{});
    defer huge.deinit();
    try std.testing.expectEqual(lean_oneshot_wait_ms, rootWaitMs(huge.value));
    main_mod.unattended = false;
    try std.testing.expectEqual(root_wait_ms, rootWaitMs(empty.value));
}

test "ADR 0233: a one-second timeout waits 5s unattended and the full 15s interactive" {
    const one_second = try std.json.parseFromSlice(Value, std.testing.allocator, "{\"timeout\":1000}", .{});
    defer one_second.deinit();
    try std.testing.expectEqual(min_model_wait_ms, rootWaitMs(one_second.value));
    try std.testing.expectEqual(lean_oneshot_wait_ms, rootWaitMsFor(one_second.value, true));
    const ten_seconds = try std.json.parseFromSlice(Value, std.testing.allocator, "{\"timeout\":10000}", .{});
    defer ten_seconds.deinit();
    try std.testing.expectEqual(@as(u64, 10_000), rootWaitMs(ten_seconds.value));
    try std.testing.expectEqual(lean_oneshot_wait_ms, rootWaitMsFor(ten_seconds.value, true));
}

test "rootWaitMs: interactive REPL parks at 15s (ADR 0154)" {
    const empty = try std.json.parseFromSlice(Value, std.testing.allocator, "{}", .{});
    defer empty.deinit();
    try std.testing.expectEqual(lean_oneshot_wait_ms, rootWaitMsFor(empty.value, true));
    try std.testing.expectEqual(root_wait_ms, rootWaitMsFor(empty.value, false));
    const huge = try std.json.parseFromSlice(Value, std.testing.allocator, "{\"timeout\":120000}", .{});
    defer huge.deinit();
    try std.testing.expectEqual(lean_oneshot_wait_ms, rootWaitMsFor(huge.value, true));
}

fn formatJobDone(gpa: Allocator, cmd: []const u8, wait: jobs.FgDone) !ToolOutput {
    defer gpa.free(wait.output);
    var aw: Io.Writer.Allocating = .init(gpa);
    errdefer aw.deinit();
    const w = &aw.writer;
    if (wait.output.len > 0) try w.writeAll(wait.output);
    if (wait.dropped) try w.print("\n[oldest unread output was dropped at the {d} KB cap]", .{jobs.job_unread_cap / 1024});
    if (wait.killed) {
        try w.writeAll("\n[cancelled by user; local process group killed]\n");
        try w.writeAll(cancel_hint);
        if (isSshCommand(cmd)) try w.writeAll("\n[ssh note: the local SSH client was killed, but a detached or disconnect-resistant remote process may survive; verify it on the remote host]");
        if (wait.output.len == 0) try w.writeAll("\n(no output)");
        return .{ .text = try aw.toOwnedSlice(), .is_error = true, .cancelled = true };
    }
    if (wait.exit_code) |code| {
        if (code != 0) try w.print("\n[exit code {d}]", .{code});
    } else try w.writeAll("\n[terminated abnormally]");
    if (wait.output.len == 0 and (wait.exit_code orelse 1) == 0) try w.writeAll("(no output)");
    const code = wait.exit_code;
    return .{ .text = try aw.toOwnedSlice(), .is_error = code == null or code.? != 0 };
}

fn formatCancelled(gpa: Allocator, cmd: []const u8, wait: jobs.FgPartial) !ToolOutput {
    defer gpa.free(wait.output);
    var aw: Io.Writer.Allocating = .init(gpa);
    errdefer aw.deinit();
    const w = &aw.writer;
    if (wait.output.len > 0) {
        try w.writeAll(wait.output);
        try w.writeAll("\n");
    }
    try w.writeAll("[cancelled by user; local process group killed]\n");
    try w.writeAll(cancel_hint);
    if (isSshCommand(cmd)) try w.writeAll("\n[ssh note: the local SSH client was killed, but a detached or disconnect-resistant remote process may survive; verify it on the remote host]");
    return .{ .text = try aw.toOwnedSlice(), .is_error = true, .cancelled = true };
}

test "cancel hint tells the model to restart with run_in_background" {
    try std.testing.expect(std.mem.indexOf(u8, cancel_hint, "run_in_background") != null);
}

test "an auto-parked server snapshots instead of inheriting wait-until-exit" {
    const gpa = std.testing.allocator;
    const text = try startedText(gpa, 7, "npm run dev", false, .server, 15, "partial");
    defer gpa.free(text);
    try std.testing.expect(std.mem.indexOf(u8, text, "do not poll") != null);
    try std.testing.expect(std.mem.indexOf(u8, text, "snapshot") != null);
    try std.testing.expect(std.mem.indexOf(u8, text, "wait_ms>0") == null);
    try std.testing.expect(std.mem.indexOf(u8, text, "job 7") != null);
}

test "an auto-parked finite command offers the wait-until-exit read (#1324)" {
    const gpa = std.testing.allocator;
    const text = try startedText(gpa, 8, "cargo test", false, .finite, 15, "");
    defer gpa.free(text);
    try std.testing.expect(std.mem.indexOf(u8, text, "action=output id 8 with wait_ms>0") != null);
    try std.testing.expect(std.mem.indexOf(u8, text, "end your reply to wait for it") != null);
    try std.testing.expect(std.mem.indexOf(u8, text, "snapshot") == null);
    try std.testing.expect(std.mem.indexOf(u8, text, "persistent server") == null);
}

test "a finite command backgrounded on purpose offers the wait-until-exit read (#1349)" {
    const gpa = std.testing.allocator;
    const text = try startedText(gpa, 9, "cargo test", false, .background_finite, 0, "");
    defer gpa.free(text);
    try std.testing.expect(std.mem.indexOf(u8, text, "action=output id 9 with wait_ms>0") != null);
    try std.testing.expect(std.mem.indexOf(u8, text, "end your reply to wait for it") != null);
    try std.testing.expect(std.mem.indexOf(u8, text, "persistent server") == null);
    try std.testing.expect(std.mem.indexOf(u8, text, "do not poll") == null);
}

test "persistent start text parks the server and forbids polling" {
    const gpa = std.testing.allocator;
    const text = try startedText(gpa, 446, "npm run dev", false, .background, 0, "");
    defer gpa.free(text);
    try std.testing.expect(std.mem.indexOf(u8, text, "[job 446 started: npm run dev]") != null);
    try std.testing.expect(std.mem.indexOf(u8, text, "persistent server") != null);
    try std.testing.expect(std.mem.indexOf(u8, text, "do not poll") != null);
    try std.testing.expect(std.mem.indexOf(u8, text, "omit wait_ms") == null);
}

fn formatCapped(gpa: Allocator, cmd: []const u8, run: jobs.CappedRun) !ToolOutput {
    const exit_code: ?u8 = switch (run.term) {
        .exited => |code| code,
        else => null,
    };
    var aw: Io.Writer.Allocating = .init(gpa);
    errdefer aw.deinit();
    const w = &aw.writer;
    if (run.stdout.len > 0) try w.writeAll(run.stdout);
    // #1271: the capture kept head and tail; say the MIDDLE went, not the end.
    if (run.stdout_truncated) try w.print("\n[stdout over the {d} KB cap: head and tail kept, middle truncated]", .{bash_stdout_cap / 1024});
    if (run.stderr.len > 0) try w.print("\n[stderr]\n{s}", .{run.stderr});
    if (run.stderr_truncated) try w.print("\n[stderr over the {d} KB cap: head and tail kept, middle truncated]", .{bash_stderr_cap / 1024});
    if (run.cancelled) {
        try w.writeAll("\n[cancelled by user; local process group killed]\n");
        try w.writeAll(cancel_hint);
    } else if (run.timed_out) {
        try w.print("\n[timed out after {d}s and was killed — too long for a subagent. Don't retry as-is: scope it to specific paths or globs instead of scanning the whole directory, or report back what you need run.]", .{subagent_deadline_ms / 1000});
    } else if (exit_code) |code| {
        if (code != 0) try w.print("\n[exit code {d}]", .{code});
    } else try w.writeAll("\n[terminated abnormally]");
    if ((run.cancelled or run.timed_out) and isSshCommand(cmd)) {
        try w.writeAll("\n[ssh note: the local SSH client was killed, but a detached or disconnect-resistant remote process may survive; verify it on the remote host]");
    }
    if (run.stdout.len == 0 and run.stderr.len == 0 and exit_code == 0) try w.writeAll("(no output)");
    return .{ .text = try aw.toOwnedSlice(), .is_error = exit_code == null or exit_code.? != 0, .cancelled = run.cancelled };
}

const server_port = @import("server_port.zig");

test {
    _ = server_port;
}

/// #1270: spawn copies argv into NUL-terminated C strings, so a NUL inside
/// the command (JSON `\u0000`) ended the string there: `make test\u0000 &&
/// git push` ran only `make test` and reported its success. Refuse before
/// anything is gated or spawned, naming the offset so the model can fix it.
pub fn nulRejection(gpa: Allocator, cmd: []const u8) !?ToolOutput {
    const at = std.mem.indexOfScalar(u8, cmd, 0) orelse return null;
    return .{
        .text = try std.fmt.allocPrint(gpa, "command refused: it contains a NUL byte at offset {d}. The shell would stop reading there and run only the text before it. Remove the NUL and retry.", .{at}),
        .is_error = true,
    };
}

pub fn exec(ctx: ToolCtx, call: tools.ToolCall) !ToolOutput {
    const cmd = strField(call.input, "command") orelse return missingArg(ctx.gpa, "command");
    if (try nulRejection(ctx.gpa, cmd)) |refused| return refused;
    if (try @import("publish_gate.zig").beforeExec(ctx, cmd)) |denied| return denied;
    // Respect the subagent gate before running even a read-only probe.
    const approved = if (ctx.from_sub) (if (ctx.approvals) |ap| ap.allowed(ctx.io, cmd) else true) else true;
    var warning = false;
    if (approved) if (server_port.requested(cmd)) |port| {
        switch (server_port.probe(ctx.gpa, ctx.io, port)) {
            .conflict => return .{
                .text = try std.fmt.allocPrint(ctx.gpa, "server launch refused: TCP port {d} already has a listener (IPv4 or IPv6). No process was stopped. Reuse the intended server or choose another port after checking ownership.", .{port}),
                .is_error = true,
            },
            .unknown => warning = true,
            .clear => {},
        }
    };
    // #1801: a simulator test must not overwrite the Mac's clipboard.
    if (approved) if (@import("sim_pasteboard.zig").refusal(ctx.gpa, ctx.io, cmd)) |why| {
        return .{ .text = try ctx.gpa.dupe(u8, why), .is_error = true };
    };
    // #407: a simulator this command boots is shut down when the session ends.
    const sim_ledger = @import("sim_ledger.zig");
    const sim_bracket = if (approved) sim_ledger.g.before(ctx.gpa, ctx.io, cmd) else null;
    var result = try execUnchecked(ctx, call);
    errdefer ctx.gpa.free(result.text);
    if (sim_bracket) |b| sim_ledger.g.after(ctx.gpa, ctx.io, b, !result.pending);
    try @import("cli_path_hint.zig").append(ctx.gpa, ctx.io, cmd, &result);
    if (warning) {
        const text = try std.mem.concat(ctx.gpa, u8, &.{ server_port.unknown_warning, result.text });
        ctx.gpa.free(result.text);
        result.text = text;
    }
    return result;
}

fn execUnchecked(ctx: ToolCtx, call: tools.ToolCall) !ToolOutput {
    const gpa = ctx.gpa;
    const io = ctx.io;
    const input = call.input;
    const cmd = strField(input, "command") orelse return missingArg(gpa, "command");
    // Subagents have no stdin to prompt on; their gate is the allowlist.
    if (ctx.from_sub) if (ctx.approvals) |ap| if (!ap.allowed(ctx.io, cmd)) return .{
        .text = try gpa.dupe(u8, "command not pre-approved — subagents may only run user-approved or read-only commands, with no chaining/pipes/redirection. Use read_file/edit_file/write_file, or report back what you need run."),
        .is_error = true,
    };
    const ssh = isSshCommand(cmd);
    const bg = tools.json_args.flag(input, "run_in_background");
    const server_like = @import("job_class.zig").looksPersistent(cmd);
    if (bg or !ctx.from_sub) {
        var live = exec_bash_stream.Ctx{ .io = io };
        const job = jobs.spawnJobOpts(gpa, io, cmd, .{
            .cwd = ctx.agent_cwd,
            .stream = if (!ctx.from_sub and !bg) exec_bash_stream.emit else null,
            .stream_ctx = if (!ctx.from_sub and !bg) &live else null,
            .quiet = !bg, // foreground wait is not a /jobs event until auto-bg
            // #1349: only a server-like command is persistent; a finite one
            // backgrounded on purpose keeps the wait-until-exit `action=output`.
            .persistent = bg and server_like,
            // ADR 0218: a finite root job started in the background outlives a crash.
            .session = if (bg and !server_like and !ctx.from_sub) ctx.session_name else "",
        }) catch |err| return .{ .text = try spawnFailText(gpa, err), .is_error = true };
        if (bg) {
            @import("subagent_interactive.zig").request(ctx);
            return .{ .text = try startedText(gpa, job.id, job.cmd, ssh, if (server_like) .background else .background_finite, 0, ""), .pending = true };
        }
        const wait_ms = rootWaitMsFor(input, ctx.interactive_children);
        const waited = jobs.waitForeground(gpa, io, job.id, wait_ms) catch |err| return .{
            .text = try std.fmt.allocPrint(gpa, "could not wait on job {d} ({t})", .{ job.id, err }),
            .is_error = true,
        };
        return switch (waited) {
            .done => |d| blk: {
                defer jobs.reapFinished(gpa, io, job.id);
                break :blk try formatJobDone(gpa, cmd, d);
            },
            .running => |r| blk: {
                defer gpa.free(r.output);
                // #1324: only a server-like command parks as persistent; a
                // finite one keeps the wait-until-exit `action=output`.
                const server = server_like;
                if (server) jobs.markPersistent(io, r.id);
                jobs.markParked(io, r.id); // #1486
                @import("subagent_interactive.zig").request(ctx);
                break :blk .{ .text = try startedText(gpa, r.id, cmd, ssh, if (server) .server else .finite, wait_ms / 1000, r.output), .pending = true };
            },
            .cancelled => |c| blk: {
                defer jobs.reapFinished(gpa, io, c.id);
                break :blk try formatCancelled(gpa, cmd, c);
            },
        };
    }
    const sh = jobs.shellArgv(cmd);
    // ADR 0232: a read-only child's command runs under the sandbox; with none, only the allowlist runs.
    const ro = @import("readonly_sandbox.zig");
    var sandboxed: ro.Argv = .{};
    const argv: []const []const u8 = if (!ctx.read_only_shell) &sh else ro.build(io, ctx.agent_cwd, cmd, &sandboxed) orelse
        if (ro.allowlisted(cmd)) &sh else return .{ .text = try gpa.dupe(u8, ro.refusal), .is_error = true };
    var opts = jobs.toolRunOptions(ctx.agent_cwd);
    var live = exec_bash_stream.Ctx{ .io = io };
    exec_bash_stream.attach(&opts, false, &live); // subagents stay quiet (#93)
    opts.keep_tail = true; // #1271: the ending is where failures land
    const run = try jobs.runCappedWithOptions(gpa, io, argv, bash_stdout_cap, bash_stderr_cap, subagent_deadline_ms, opts);
    defer gpa.free(run.stdout);
    defer gpa.free(run.stderr);
    return formatCapped(gpa, cmd, run);
}

test "#1619 a shell handle failure names its cause and blames storage only for storage faults" {
    const shell_identity = @import("shell_identity.zig");
    defer shell_identity.last_cause = null;
    shell_identity.last_cause = error.ProcessFdQuotaExceeded;
    const transient = try spawnFailText(std.testing.allocator, error.ShellIdentityUnavailable);
    defer std.testing.allocator.free(transient);
    try std.testing.expect(std.mem.indexOf(u8, transient, "ShellIdentityUnavailable: ProcessFdQuotaExceeded") != null);
    try std.testing.expect(std.mem.indexOf(u8, transient, "permissions") == null);
    shell_identity.last_cause = error.AccessDenied;
    const storage = try spawnFailText(std.testing.allocator, error.ShellIdentityUnavailable);
    defer std.testing.allocator.free(storage);
    try std.testing.expect(std.mem.indexOf(u8, storage, "ShellIdentityUnavailable: AccessDenied") != null);
    try std.testing.expect(std.mem.indexOf(u8, storage, "permissions") != null);
}