graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
//! 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);
}