jeo-code 0.12.13 → 0.12.16

package/src/agent/config-schema.ts

@@ -93,6 +93,14 @@ export const ConfigSchema = z
     lmstudioBaseUrl: z.string().optional(),
     defaultModel: z.string().min(1),
     theme: z.string().optional(),
+    sandbox: z.object({
+      image: z.string().min(1),
+      limits: z.object({
+        memoryBytes: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+        pids: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+        cpus: z.number().finite().positive(),
+      }).strict(),
+    }).strict().optional(),
     /** Terminal-bell notifications (gajae-code 0.7.8 parity): emit an ASCII BEL
      *  (\x07) at notable interaction points so a backgrounded session pings the
      *  user. Off by default; `bell` is the master toggle, per-event flags refine it.

package/src/agent/context-files.ts

@@ -3,6 +3,23 @@ import * as os from "node:os";
 import * as path from "node:path";
 
 import { IGNORED_DIRS } from "./tools";
+import { currentSandboxExecution } from "./hooks";
+
+async function sandboxContext(operation: "loadContext", cwd: string): Promise<ProjectContextFile[]>;
+async function sandboxContext(operation: "discoverGuidance", cwd: string): Promise<Array<{ filePath: string; displayPath: string }>>;
+async function sandboxContext(operation: "loadContext" | "discoverGuidance", cwd: string): Promise<ProjectContextFile[] | Array<{ filePath: string; displayPath: string }>> {
+  const sandbox = currentSandboxExecution();
+  if (!sandbox) throw new Error("SANDBOX_CONTEXT: missing execution scope");
+  const result = await sandbox.supervisor.call("__workflow", { operation }, { cwd, signal: sandbox.signal });
+  if (!result.success) throw new Error(result.error || "SANDBOX_CONTEXT: context read failed");
+  const value: unknown = JSON.parse(result.output);
+  const keys = operation === "loadContext" ? ["path", "content"] : ["filePath", "displayPath"];
+  if (!Array.isArray(value) || !value.every(item => item !== null && typeof item === "object" &&
+      keys.every(key => typeof item[key] === "string"))) {
+    throw new Error("SANDBOX_CONTEXT: invalid guest response");
+  }
+  return value as ProjectContextFile[] | Array<{ filePath: string; displayPath: string }>;
+}
 
 /**
  * The user's home directory, or `undefined` when it genuinely cannot be determined.
@@ -293,6 +310,7 @@ export function invalidateWorkspaceScan(cwd?: string): void {
 }
 
 export async function discoverAgentGuidanceFiles(cwd = process.cwd()): Promise<Array<{ filePath: string; displayPath: string }>> {
+  if (currentSandboxExecution()) return sandboxContext("discoverGuidance", cwd);
   const scan = await getWorkspaceScan(cwd);
   const out: Array<{ filePath: string; displayPath: string }> = [...scan.localGuidance];
   // No resolvable home → NO home roots. Previously this fell back to `path.join("", …)`,
@@ -325,6 +343,7 @@ export async function discoverAgentGuidanceFiles(cwd = process.cwd()): Promise<A
 // cache. This keeps the result disk-truthful — a guidance/AGENTS.md edit is reflected on the
 // next spawn — while still avoiding the dominant per-spawn cost (re-reading every file).
 export async function loadProjectContext(cwd = process.cwd()): Promise<ProjectContextFile[]> {
+  if (currentSandboxExecution()) return sandboxContext("loadContext", cwd);
   const result: ProjectContextFile[] = [];
   let baseChars = 0;
   let guidanceChars = 0;

package/src/agent/engine.ts

@@ -25,14 +25,14 @@ import { createDebugTool } from "./debug-tool";
 import { createBrowserTool } from "./browser-tool";
 import { isRateLimitError, isTransientStreamDropError, isProviderStreamError, waitAbortable } from "../util/retry";
 import { isContextOverflowError, isRefusalError, friendlyProviderError } from "../util/provider-error";
-import { runPreToolHooks, runPostTurnHooksForBatch } from "./hooks";
+import { currentSandboxExecution, withSandboxExecution, runPreToolHooks, runPostTurnHooksForBatch } from "./hooks";
 import { truncateToolOutput, formatToolResultBody } from "./tool-output";
 export { TOOL_OUTPUT_MAX, READ_OUTPUT_MAX, TOOL_SPILL_THRESHOLD, MAX_TOOL_ARTIFACTS, truncateToolOutput, spillToolResult } from "./tool-output";
 import { StepBudget, dynamicStepBudgetConfig, resolveStepBudgetConfig, hashSignature, toolTarget, type StepBudgetConfig } from "./step-budget";
 
 import { historyTokens, trimToolResultsInPlace, stripReasoningArtifactsInPlace } from "./compaction";
 import { jeoEnv } from "../util/env";
-import { GUARD_LIMITS, isVerificationSignal, repeatHint, classifyDoneGate } from "./loop-guards";
+import { GUARD_LIMITS, isVerificationSignal, verificationProducedEvidence, repeatHint, classifyDoneGate } from "./loop-guards";
 import { stripLeakedReasoningTags } from "../ai/think-tags";
 
 
@@ -111,6 +111,17 @@ export const DEFAULT_TOOLS: Record<string, ToolHandler> = {
   calc: a => calcTool(Array.isArray(a.calculations) ? a.calculations : []),
 };
 
+/** Trusted wrappers that preserve role checks before forwarding to hands. */
+export const SANDBOX_MEDIATED_TOOLS = new WeakSet<ToolHandler>();
+// Engine and workflow callers share these handlers; the async scope is session-local.
+for (const [name, handler] of Object.entries(DEFAULT_TOOLS)) {
+  DEFAULT_TOOLS[name] = (args, cwd, onProgress) => {
+    const sandbox = currentSandboxExecution();
+    return sandbox ? sandbox.supervisor.call(name, args, { cwd, signal: sandbox.signal, onProgress }) : handler(args, cwd, onProgress);
+  };
+  SANDBOX_MEDIATED_TOOLS.add(DEFAULT_TOOLS[name]);
+}
+
 /** Tool names whose calls have no workspace side effects. Shared by execution,
  *  failure accounting, and the refusal-recovery replay exemption. */
 const READONLY_TOOL_NAMES: Record<string, true> = {
@@ -520,6 +531,8 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
     history.unshift({ role: "system", content: opts.systemPrompt });
   }
   const tools = opts.tools ?? DEFAULT_TOOLS;
+  const sandbox = currentSandboxExecution();
+  const parentTools: Record<string, true> = { task: true, subagent: true, irc: true, todo: true, sandbox_request: true };
   const maxSteps = opts.maxSteps ?? 15;
   // gjc-style retry flow: the step limit is a flexible BUDGET, not a bare counter.
   // While the recent window shows real progress the budget extends itself; a stalled
@@ -1277,7 +1290,12 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
           } else {
             try {
               const onProgress = ev.onToolProgress ? (partial: string) => ev.onToolProgress!(tool, partial) : undefined;
-              const res = await handler(args ?? {}, cwd, onProgress);
+              const sandboxedHandler = sandbox && !Object.hasOwn(parentTools, tool) && !SANDBOX_MEDIATED_TOOLS.has(handler)
+                ? (input: Record<string, any>, _cwd: string, progress?: (text: string) => void) => sandbox.supervisor.call(tool, input, { cwd, signal: opts.signal, onProgress: progress })
+                : handler;
+              const res = await (sandbox
+                ? withSandboxExecution({ ...sandbox, signal: opts.signal }, () => sandboxedHandler(args ?? {}, cwd, onProgress))
+                : sandboxedHandler(args ?? {}, cwd, onProgress));
               success = res.success;
               images = res.images;
               output = res.success ? res.output : (res.error ? (res.output ? `${res.error}\n${res.output}` : res.error) : res.output);
@@ -1463,9 +1481,10 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
     for (let i = 0; i < toolCalls.length; i++) {
       if (!results[i].executed) continue;
       const t = toolCalls[i].tool;
-      const verificationCall = t === "bash" && isVerificationSignal(String(toolCalls[i].arguments?.command ?? toolCalls[i].arguments?.cmd ?? ""));
+      const command = String(toolCalls[i].arguments?.command ?? toolCalls[i].arguments?.cmd ?? "");
+      const verificationCall = t === "bash" && isVerificationSignal(command);
       if (verificationCall) {
-        if (results[i].success) {
+        if (results[i].success && verificationProducedEvidence(command, String(results[i].output ?? ""))) {
           sawVerification = true;
           lastVerificationSeq = ++mutVerSeq;
         } else {
@@ -1514,7 +1533,7 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
         sawMutation = true;
         lastMutationSeq = ++mutVerSeq;
       } else if (t === "bash") {
-        // Non-verification shell commands may mutate files even when they exit unsuccessfully.
+        // Even simple commands can run shell startup hooks or inherited functions.
         sawMutation = true;
         lastMutationSeq = ++mutVerSeq;
       }

package/src/agent/eval-tool.ts

@@ -49,6 +49,7 @@ import {
 } from "./task-tool";
 import { getSubagentRole, defaultSubagentRole, subagentRoleIds } from "./subagents";
 import { loadProjectContext, type ProjectContextFile } from "./context-files";
+import { currentSandboxExecution } from "./hooks";
 
 export interface EvalToolOptions {
   config: SubagentTaskConfig;
@@ -101,6 +102,9 @@ const DEFAULT_EVAL_TIMEOUT_MS = 300_000; // 5 minutes
 const MAX_EVAL_TIMEOUT_MS = 1_800_000; // 30 minutes — same outer ceiling as JEO_CALL_TIMEOUT_MS's default
 
 export function evalToolProtocolLine(config?: Pick<import("./state").Config, "subagents">): string {
+  if (currentSandboxExecution()) {
+    return "eval {code, timeoutMs?} executes JavaScript in the persistent session hands kernel at the mapped working directory. Filesystem/process access stays inside the container. task(), parallel(), and pipeline() orchestration are not available there; use the parent task tool to delegate model work.";
+  }
   return (
     `eval    {code, timeoutMs?}  — Dynamic Workflows: write an async JS function BODY (return value or throw) ` +
     `composing subagent dispatch with REAL control flow (loops/conditionals/sequencing) instead of one static tool call. ` +
@@ -224,6 +228,8 @@ type WorkerMsg = TaskRequestMsg | LogMsg | DoneMsg;
 
 export function createEvalTool(opts: EvalToolOptions): ToolHandler {
   return async (args: Record<string, any>, cwd: string): Promise<ToolResult> => {
+    const sandbox = currentSandboxExecution();
+    if (sandbox) return sandbox.supervisor.call("eval", args, { cwd, signal: opts.signal ?? sandbox.signal });
     const code = typeof args.code === "string" ? args.code : "";
     if (!code.trim()) {
       return { success: false, output: "", error: `eval requires a non-empty 'code' body (an async function BODY — the last expression or an explicit 'return' becomes the result).` };

package/src/agent/goal-verifier.ts

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 
-import { callLlm, type Message } from "./loop";
+import { callLlm } from "./loop";
+import type { Message } from "./loop";
 
 export interface GoalVerdict {
   verdict: "MET" | "NOT_MET" | "IMPOSSIBLE";
@@ -204,25 +205,42 @@ export function applyPendingEvidence(state: GoalState, evidence: TurnEvidence):
 
 import * as path from "node:path";
 import * as fs from "node:fs/promises";
-import { getLocalJeoDir } from "./state";
+import { getLocalJeoDir, readWorkflowFile, writeWorkflowFile } from "./state";
+import { currentSandboxExecution } from "./hooks";
 
 export function getGoalPath(cwd: string = process.cwd()): string {
   return path.join(getLocalJeoDir(cwd), "state", "goal.json");
 }
 
-export async function readGoalState(cwd: string = process.cwd()): Promise<GoalState | null> {
+/** Return exact persisted bytes (or absence) so corruption is classified in the brain. */
+export async function readGoalFile(cwd: string = process.cwd()): Promise<string | null> {
+  const sandbox = currentSandboxExecution();
+  if (sandbox) {
+    const result = await sandbox.supervisor.call("__workflow", { operation: "readGoal" }, { cwd, signal: sandbox.signal });
+    if (!result.success) throw new Error(result.error || "SANDBOX_WORKFLOW: goal read failed");
+    const value: unknown = JSON.parse(result.output);
+    if (value !== null && typeof value !== "string") throw new Error("SANDBOX_WORKFLOW: invalid goal file response");
+    return value;
+  }
   const p = getGoalPath(cwd);
-  let data: string;
   try {
-    data = await fs.readFile(p, "utf-8");
+    return await readWorkflowFile(p, cwd);
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
     throw error;
   }
-  return parseGoalState(data, p);
+}
+
+export async function readGoalState(cwd: string = process.cwd()): Promise<GoalState | null> {
+  const data = await readGoalFile(cwd);
+  return data === null ? null : parseGoalState(data, getGoalPath(cwd));
 }
 
 export async function writeGoalState(state: GoalState, cwd: string = process.cwd()): Promise<void> {
+  if (currentSandboxExecution()) {
+    await writeWorkflowFile(getGoalPath(cwd), JSON.stringify(state, null, 2), cwd);
+    return;
+  }
   const p = getGoalPath(cwd);
   await fs.mkdir(path.dirname(p), { recursive: true });
   const tempPath = `${p}.${randomUUID()}.tmp`;
@@ -235,6 +253,12 @@ export async function writeGoalState(state: GoalState, cwd: string = process.cwd
 }
 
 export async function clearGoalState(cwd: string = process.cwd()): Promise<void> {
+  const sandbox = currentSandboxExecution();
+  if (sandbox) {
+    const result = await sandbox.supervisor.call("__workflow", { operation: "clearGoal" }, { cwd, signal: sandbox.signal });
+    if (!result.success) throw new Error(result.error || "SANDBOX_WORKFLOW: goal clear failed");
+    return;
+  }
   const p = getGoalPath(cwd);
   await fs.unlink(p).catch(() => {});
 }

package/src/agent/hooks.ts

@@ -1,3 +1,24 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { SandboxSupervisor } from "./sandbox/types";
+import type { GrantAuthority } from "./sandbox/authority";
+
+export interface SandboxExecutionScope {
+  supervisor: SandboxSupervisor;
+  authority?: GrantAuthority;
+  signal?: AbortSignal;
+  requestAccess?: (host: string, mode: "ro" | "rw") => Promise<unknown>;
+}
+
+const sandboxExecution = new AsyncLocalStorage<SandboxExecutionScope>();
+
+export function currentSandboxExecution(): SandboxExecutionScope | undefined {
+  return sandboxExecution.getStore();
+}
+
+export function withSandboxExecution<T>(scope: SandboxExecutionScope, run: () => T): T {
+  return sandboxExecution.run(scope, run);
+}
+
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { readGlobalConfig } from "./state";
@@ -63,12 +84,25 @@ async function readLocalHooks(localPath: string): Promise<LocalHooks> {
   return result;
 }
 
-export async function loadHooks(cwd: string): Promise<NonNullable<HookConfig["hooks"]>> {
+export async function loadHooks(cwd: string, signal?: AbortSignal): Promise<NonNullable<HookConfig["hooks"]>> {
   const config = await readGlobalConfig();
   if (!config.hooks?.enabled) {
     return [];
   }
 
+  const sandbox = currentSandboxExecution();
+  if (sandbox) {
+    const result = await sandbox.supervisor.exec(["bun", "-e", "const file=Bun.file('.jeo/hooks.json');let value={};try{if(await file.exists())value=await file.json()}catch{}process.stdout.write(JSON.stringify(value));"], { cwd, signal: signal ?? sandbox.signal });
+    if (!result.success || result.exitCode !== 0) throw new Error(`Sandbox project hook configuration read failed (exit code ${result.exitCode ?? "unavailable"}): ${result.error || result.output}`);
+    let local: unknown;
+    try { local = JSON.parse(result.stdout ?? result.output); }
+    catch { throw new Error("Malformed sandbox project hook configuration"); }
+    if (local && typeof local === "object") {
+      if ("enabled" in local && local.enabled === false) return [];
+      if ("hooks" in local && Array.isArray(local.hooks)) return local.hooks;
+    }
+    return config.hooks.hooks || [];
+  }
   const local = await readLocalHooks(path.join(cwd, ".jeo", "hooks.json"));
   if (local.kind === "disabled") return [];
   if (local.kind === "hooks") return local.hooks;
@@ -86,6 +120,19 @@ async function runHookCommand(
   if (signal?.aborted) {
     return { stdout: "", stderr: "", output: "", exitCode: null, timedOut: false, aborted: true };
   }
+  const sandbox = currentSandboxExecution();
+  if (sandbox) {
+    const timeout = AbortSignal.timeout(timeoutMs);
+    const result = await sandbox.supervisor.exec(["/bin/sh", "-c", runCmd], {
+      cwd, stdin: JSON.stringify(payload), signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
+    });
+    if (result.exitCode === undefined) throw new Error(result.error || "Malformed sandbox hook result: missing exitCode");
+    return {
+      stdout: result.stdout ?? result.output, stderr: result.stderr ?? "", output: result.output,
+      exitCode: result.exitCode, timedOut: result.timedOut === true || timeout.aborted,
+      aborted: result.aborted === true || signal?.aborted === true,
+    };
+  }
 
   const proc = Bun.spawn(["bash", "-c", runCmd], {
     cwd,
@@ -154,6 +201,7 @@ async function runHookCommand(
   };
 }
 
+
 /** True when a hook's `match.tool` selects `tool`. Accepts a single name or a
  *  `|`-separated list (`"edit|write"`) — so one post-edit tsc hook can cover
  *  every mutating tool without duplicate entries. No match = all tools. */
@@ -170,7 +218,7 @@ export async function runPreToolHooks(
   onNotice?: (msg: string) => void
 ): Promise<{ vetoed: boolean; error?: string; output?: string }> {
   try {
-    const hooks = await loadHooks(cwd);
+    const hooks = await loadHooks(cwd, signal);
     const preToolHooks = hooks.filter(
       h => h.event === "pre-tool" && hookMatchesTool(h.match?.tool, tool)
     );
@@ -243,7 +291,7 @@ export async function runPostTurnHooksForBatch(
   // "hooks ran clean" (clear a pending failure) differently from "no hook ran".
   let ran = 0;
   try {
-    const hooks = await loadHooks(cwd);
+    const hooks = await loadHooks(cwd, signal);
     const jobs = hooks
       .filter(h => h.event === "post-turn")
       .map(hook => ({ hook, matched: calls.filter(c => hookMatchesTool(hook.match?.tool, c.tool)) }))
@@ -311,7 +359,7 @@ export async function runPostImplementationHooks(
   onNotice?: (msg: string) => void
 ): Promise<{ success: boolean; output: string }> {
   try {
-    const hooks = await loadHooks(cwd);
+    const hooks = await loadHooks(cwd, signal);
     const postImplHooks = hooks.filter(h => h.event === "post-implementation");
     
     let combinedOutput = "";

package/src/agent/job-registry.ts

@@ -1,7 +1,7 @@
 /**
  * In-process registry for BACKGROUND shell processes (gjc `job`/async-bash parity,
  * scoped down to one runtime). Unlike the synchronous `bash` tool, `start()` spawns
- * a real parallel OS process via `Bun.spawn` and returns immediately — the parent
+ * a real parallel OS process (see `shell-lease.ts`) and returns immediately — the parent
  * can keep working and later list / tail / await / cancel it via the `job` control
  * tool while stdout/stderr drain into a bounded buffer in the background.
  *
@@ -12,6 +12,8 @@
  *
  */
 
+import { settlesWithin, spawnLeasedShell, type LeasedShell } from "./shell-lease";
+
 export type JobStatus = "running" | "exited" | "killed" | "failed";
 
 export interface JobRecord {
@@ -27,17 +29,25 @@ export interface JobRecord {
 
 interface Entry {
   record: JobRecord;
-  proc: Bun.Subprocess<"ignore", "pipe", "pipe">;
   promise: Promise<void>;
+  cancel?: () => boolean;
+  /** SIGKILL reached the pinned process group. */
+  killDelivered?: boolean;
+  /** Termination of every process holding the job's group or pipes cannot be confirmed. */
+  incomplete?: boolean;
 }
 
 const OUTPUT_CAP = 20000;
 const TRUNCATION_MARKER = "[…output truncated…]\n";
+const PIPE_LINGER_MS = 500;
 
 export class JobRegistry {
   private readonly entries = new Map<string, Entry>();
   private readonly buffers = new Map<string, string>();
   private readonly truncated = new Set<string>();
+  private readonly reported = new Set<string>();
+  private readonly pendingMutations = new Set<string>();
+  private readonly active = new Set<string>();
   private seq = 0;
 
   private append(id: string, chunk: string): void {
@@ -66,42 +76,91 @@ export class JobRegistry {
     };
     this.buffers.set(id, "");
 
-    let proc: Bun.Subprocess<"ignore", "pipe", "pipe">;
+    let shell: LeasedShell;
     try {
-      proc = Bun.spawn(["bash", "-c", command], { cwd, stdin: "ignore", stdout: "pipe", stderr: "pipe" });
+      shell = spawnLeasedShell(command, cwd);
     } catch (err) {
       record.status = "failed";
       record.finishedAt = Date.now();
       this.append(id, err instanceof Error ? err.message : String(err));
+      this.pendingMutations.add(id);
       // No process handle to store — nothing further to drain or cancel.
-      this.entries.set(id, { record, proc: undefined as any, promise: Promise.resolve() });
+      this.entries.set(id, { record, promise: Promise.resolve() });
       return record;
     }
+    this.active.add(id);
 
-    const drain = async (stream: ReadableStream<Uint8Array>) => {
+    const entry: Entry = { record, promise: Promise.resolve() };
+    entry.cancel = (): boolean => {
+      const outcome = shell.killGroup();
+      if (outcome === "delivered") { entry.killDelivered = true; return true; }
+      entry.incomplete = true;
+      this.append(id, outcome === "unpinned"
+        ? "\n[job process group is no longer pinned; termination cannot be confirmed]\n"
+        : outcome === "unsupported"
+          ? "\n[job process tree termination cannot be confirmed on Windows]\n"
+          : `\n[job process group termination attempt failed: ${String(outcome.error)}]\n`);
+      shell.killDirect();
+      return false;
+    };
+    const drain = async (reader: { read: () => Promise<{ done?: boolean; value?: Uint8Array }> }) => {
       const decoder = new TextDecoder();
-      for await (const chunk of stream) {
-        this.append(id, decoder.decode(chunk, { stream: true }));
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        if (value) this.append(id, decoder.decode(value, { stream: true }));
       }
+      this.append(id, decoder.decode());
     };
+    const drains = Promise.all([drain(shell.stdout), drain(shell.stderr)]);
+    void drains.catch(() => {});
 
     const promise = (async () => {
       try {
-        await Promise.all([drain(proc.stdout), drain(proc.stderr)]);
-        const exitCode = await proc.exited;
-        if (record.status === "killed") return;
-        record.status = "exited";
+        const exitCode = await shell.exit;
+        let lingered = false;
+        if (!(await settlesWithin(drains, PIPE_LINGER_MS))) {
+          lingered = true;
+          // A descendant still holds stdout/stderr. Only the pinned group may be signalled; if EOF does
+          // not follow the delivered SIGKILL, the holder left the group and stays unresolved.
+          if ((entry.killDelivered || entry.cancel!()) && !(await settlesWithin(drains, PIPE_LINGER_MS))) {
+            entry.incomplete = true;
+            this.append(id, "\n[job pipe remains open outside the process group; termination cannot be confirmed]\n");
+          }
+          shell.dispose();
+          await drains;
+        }
+        if (exitCode === null && !entry.killDelivered && !entry.incomplete) {
+          entry.incomplete = true;
+          this.append(id, "\n[job process group lease ended without an exit report; termination cannot be confirmed]\n");
+        }
+        if (record.status === "killed" && !entry.incomplete) return;
+        if (!lingered && !entry.incomplete) {
+          record.status = "exited";
+          record.exitCode = exitCode;
+          return;
+        }
+        record.status = "failed";
         record.exitCode = exitCode;
+        if (lingered) this.append(id, "\n[job output incomplete: a descendant kept stdout or stderr open after the shell exited]\n");
       } catch (err) {
+        // Output can no longer be observed: stop the group now so the holder can be reaped.
+        if (!entry.killDelivered) entry.cancel!();
         if (record.status === "killed") return;
         record.status = "failed";
         this.append(id, err instanceof Error ? err.message : String(err));
       } finally {
+        shell.release();
+        await shell.reaped;
+        shell.dispose();
+        if (!entry.incomplete) this.active.delete(id);
+        this.pendingMutations.add(id);
         if (record.finishedAt === undefined) record.finishedAt = Date.now();
       }
     })();
 
-    this.entries.set(id, { record, proc, promise });
+    entry.promise = promise;
+    this.entries.set(id, entry);
     return record;
   }
 
@@ -117,6 +176,34 @@ export class JobRegistry {
     return this.list().filter(r => r.status === "running");
   }
 
+  /** Include running jobs and terminal jobs not yet reported by await. */
+  awaiting(): JobRecord[] {
+    return this.list().filter(r => r.status === "running" || !this.reported.has(r.id));
+  }
+
+  markReported(records: JobRecord[]): void {
+    for (const record of records) {
+      if (record.status !== "running") this.reported.add(record.id);
+    }
+  }
+
+  /** Report each process completion once to invalidate earlier verification. */
+  consumeMutations(ids?: string[]): boolean {
+    if (ids === undefined) {
+      const pending = this.pendingMutations.size > 0;
+      this.pendingMutations.clear();
+      return pending;
+    }
+    let pending = false;
+    for (const id of ids) pending = this.pendingMutations.delete(id) || pending;
+    return pending;
+  }
+
+  /** Processes not yet settled or whose completion has not reached the engine. */
+  unobserved(): JobRecord[] {
+    return this.list().filter(record => this.active.has(record.id) || this.pendingMutations.has(record.id));
+  }
+
   /** Current buffered output for one job (empty string if the id is unknown). */
   tail(id: string): string {
     return this.buffers.get(id) ?? "";
@@ -142,25 +229,30 @@ export class JobRegistry {
     return targets.map(e => e.record);
   }
 
-  /** Cancel the given ids: SIGTERM via `proc.kill()` and mark killed. Already-terminal
-   *  records are returned unchanged. */
+  /** Cancel the process group on POSIX, or the direct process on Windows. */
   cancel(ids: string[]): JobRecord[] {
     const out: JobRecord[] = [];
     for (const id of ids) {
       const e = this.entries.get(id);
       if (!e) continue;
+      if (e.incomplete) { out.push(e.record); continue; }
       if (e.record.status === "running") {
-        e.record.status = "killed";
+        const killed = e.cancel?.();
+        e.record.status = killed ? "killed" : "failed";
         e.record.finishedAt = Date.now();
-        e.proc?.kill();
       }
       out.push(e.record);
     }
     return out;
   }
 
+  /** Include unresolved process groups even if their shell has exited. */
+  cancellable(): JobRecord[] {
+    return this.list().filter(r => r.status === "running" || this.entries.get(r.id)?.incomplete);
+  }
+
   /** Kill every still-running job (session teardown / Ctrl-C). */
   cancelAll(): JobRecord[] {
-    return this.cancel(this.running().map(r => r.id));
+    return this.cancel(this.cancellable().map(r => r.id));
   }
 }

package/src/agent/job-tool.ts

@@ -6,13 +6,17 @@
 import type { ToolHandler } from "./engine";
 import type { ToolResult } from "./tools";
 import type { JobRegistry, JobRecord } from "./job-registry";
+import { settlesWithin } from "./shell-lease";
+
+/** Upper bound on pipe-linger, escape detection and notice-queue drain after a cancel. */
+const CANCEL_SETTLE_MS = 3000;
 
 /** One-line protocol description appended to the launch system prompt. */
 export const JOB_TOOL_PROTOCOL_LINE =
   `job {action:"start", command, cwd?} runs a shell command in the BACKGROUND as a real ` +
   `parallel OS process and returns a job id immediately. job {action:"list"|"tail"|"await"|"cancel", ` +
   `ids?, timeoutMs?} — 'tail' shows buffered output so far; 'await' blocks (optionally up to timeoutMs ` +
-  `ms) until it exits; 'cancel' kills it; omit ids to target all running.`;
+  `ms) until it exits; 'cancel' kills it; omit ids to target all running, plus unreported completions for 'await'.`;
 
 function truncate(s: string, n: number): string {
   return s.length > n ? s.slice(0, n - 1) + "…" : s;
@@ -24,7 +28,8 @@ function elapsed(rec: JobRecord): string {
 }
 
 function rowLine(rec: JobRecord): string {
-  return `- ${rec.id} [${rec.status.toUpperCase()}] ${elapsed(rec)} · ${truncate(rec.command, 100)}`;
+  const exit = rec.exitCode != null ? ` (exit code ${rec.exitCode})` : "";
+  return `- ${rec.id} [${rec.status.toUpperCase()}]${exit} ${elapsed(rec)} · ${truncate(rec.command, 100)}`;
 }
 
 function idsOf(args: Record<string, any>): string[] {
@@ -33,8 +38,8 @@ function idsOf(args: Record<string, any>): string[] {
   return [];
 }
 
-export function createJobTool(registry: JobRegistry): ToolHandler {
-  return async (args: Record<string, any>, cwd: string): Promise<ToolResult> => {
+export function createJobTool(registry: JobRegistry, reportMutations = true): ToolHandler {
+  const handle: ToolHandler = async (args: Record<string, any>, cwd: string): Promise<ToolResult> => {
     const action = String(args.action ?? "list").trim().toLowerCase();
     const ids = idsOf(args);
 
@@ -79,28 +84,57 @@ export function createJobTool(registry: JobRegistry): ToolHandler {
     }
 
     if (action === "await") {
-      const targets = ids.length ? ids : registry.running().map(r => r.id);
+      const targets = ids.length ? ids : registry.awaiting().map(r => r.id);
       if (targets.length === 0) {
-        return { success: true, output: "No running jobs to await." };
+        return { success: true, output: "No jobs to await." };
+      }
+      const unknown = targets.filter(id => !registry.get(id));
+      if (unknown.length > 0) {
+        return { success: false, output: "", error: `No job matches ${unknown.join(", ")}.` };
       }
       const timeoutMs = typeof args.timeoutMs === "number" && args.timeoutMs > 0 ? args.timeoutMs : undefined;
       const recs = await registry.awaitIds(targets, timeoutMs);
+      if (reportMutations) registry.markReported(recs);
       const stillRunning = recs.filter(r => r.status === "running").length;
       const head = stillRunning > 0
         ? `Awaited ${recs.length} job(s); ${stillRunning} still running after the ${timeoutMs}ms timeout — await again or cancel.`
         : `Awaited ${recs.length} job(s); all settled.`;
-      return { success: stillRunning === 0, output: `${head}\n\n${recs.map(rowLine).join("\n")}` };
+      const success = recs.every(r => r.status === "exited" && r.exitCode === 0);
+      return { success, output: `${head}\n\n${recs.map(rowLine).join("\n")}\n\nUse job {action:"tail", ids:[...]} to inspect output.` };
     }
 
     if (action === "cancel") {
-      const targets = ids.length ? ids : registry.running().map(r => r.id);
+      const cancellable = new Set(registry.cancellable().map(r => r.id));
+      const targets = ids.length ? [...new Set(ids)] : [...cancellable];
       if (targets.length === 0) {
         return { success: true, output: "No running jobs to cancel." };
       }
+      const unknown = targets.filter(id => !registry.get(id));
+      if (unknown.length > 0) {
+        return { success: false, output: "", error: `No job matches ${unknown.join(", ")}.` };
+      }
+      const attempted = targets.filter(id => cancellable.has(id));
       const recs = registry.cancel(targets);
-      return { success: true, output: `Cancelled ${recs.length} job(s):\n${recs.map(rowLine).join("\n")}` };
+      // A delivered SIGKILL is only verified once the output pipes close; settlement can still
+      // downgrade `killed` to `failed` (a holder that left the group), so wait before judging.
+      const settled = attempted.length === 0 || await settlesWithin(registry.awaitIds(attempted), CANCEL_SETTLE_MS);
+      const failed = recs.filter(r => cancellable.has(r.id) && (!settled || r.status !== "killed")).length;
+      const head = attempted.length ? `Cancelled ${attempted.length - failed} job(s); ${failed} cancellation(s) failed; ${recs.length - attempted.length} already settled.` : "No running jobs to cancel; requested jobs are already settled.";
+      return { success: failed === 0, output: `${head}\n${recs.map(rowLine).join("\n")}`, mutationMayHaveOccurred: attempted.length > 0 };
     }
 
     return { success: false, output: "", error: `Unknown job action '${action}'. Use start | list | tail | await | cancel.` };
   };
+  return async (args, cwd) => {
+    const action = String(args.action ?? "list").trim().toLowerCase();
+    const ids = idsOf(args);
+    const targets = action === "list" ? registry.list().map(r => r.id)
+      : action === "await" ? (ids.length ? ids : registry.awaiting().map(r => r.id))
+      : action === "tail" ? (ids.length ? ids : registry.running().map(r => r.id))
+      : action === "cancel" ? (ids.length ? ids : registry.cancellable().map(r => r.id))
+      : [];
+    const result = await handle(args, cwd);
+    if (reportMutations && !result.error && registry.consumeMutations(targets)) result.mutationMayHaveOccurred = true;
+    return result;
+  };
 }