agent-nuvira 3.3.3 → 3.3.5

package/dist/tools/subagent-refusal.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The refusal a subagent raises when it cannot do real work.
+ *
+ * A subagent that cannot run must say so with a machine-readable reason — the
+ * same contract every tool follows (`tool-refusal.ts`). It exists as its own
+ * module because it crosses a process boundary: the child throws it, serialises
+ * its `code` + message over IPC, and the parent records it as the task's error
+ * instead of reporting a task that never ran as completed.
+ */
+import type { ToolRefusalCode } from './tool-refusal.js';
+export declare class SubagentRefusalError extends Error {
+    readonly code: ToolRefusalCode;
+    constructor(code: ToolRefusalCode, message: string);
+}
+//# sourceMappingURL=subagent-refusal.d.ts.map

package/dist/tools/subagent-refusal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-refusal.d.ts","sourceRoot":"","sources":["../../src/tools/subagent-refusal.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;gBAEnB,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM;CAKnD"}

package/dist/tools/subagent-refusal.js

@@ -0,0 +1,18 @@
+/**
+ * The refusal a subagent raises when it cannot do real work.
+ *
+ * A subagent that cannot run must say so with a machine-readable reason — the
+ * same contract every tool follows (`tool-refusal.ts`). It exists as its own
+ * module because it crosses a process boundary: the child throws it, serialises
+ * its `code` + message over IPC, and the parent records it as the task's error
+ * instead of reporting a task that never ran as completed.
+ */
+export class SubagentRefusalError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'SubagentRefusalError';
+        this.code = code;
+    }
+}
+//# sourceMappingURL=subagent-refusal.js.map

package/dist/tools/subagent-refusal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-refusal.js","sourceRoot":"","sources":["../../src/tools/subagent-refusal.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IACpC,IAAI,CAAkB;IAE/B,YAAY,IAAqB,EAAE,OAAe;QAChD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF"}

package/dist/tools/subagent-spawner.d.ts

@@ -38,7 +38,27 @@ export interface SubagentConfig {
     cwd?: string;
     /** Environment variables */
     env?: Record<string, string>;
+    /**
+     * WS5 (#27) — run this child in its OWN git worktree of `cwd`, and return the
+     * diff against the commit it started from.
+     *
+     * The isolation is made by the PARENT, not asked of the child: the child is a
+     * separate process that resolves its own config and could decline, and a child
+     * that quietly declined would be the worst outcome — a parent that believes the
+     * work happened in a worktree while it happened in the real tree. So the parent
+     * creates the worktree, forks INTO it, and measures the diff itself.
+     */
+    worktree?: boolean;
+    /** Keep the worktree after the run instead of removing it (default: remove). */
+    keepWorktree?: boolean;
 }
+/**
+ * WS5 (#27) — how the resume request reaches the child: the inherited
+ * `NUVIRA_RESUME` (see `SubagentRuntimeConfig.resume`). The child resolves it from
+ * its own environment, exactly as an in-process surface does, so one request
+ * means the same thing on both sides of the fork.
+ */
+export declare const SUBAGENT_RESUME_ENV = "NUVIRA_RESUME";
 export interface SubagentState {
     /** Subagent ID */
     id: string;
@@ -52,6 +72,42 @@ export interface SubagentState {
     result?: string;
     /** Error */
     error?: string;
+    /**
+     * Typed refusal code when the child refused (see `tool-refusal.ts`), carried
+     * across the process boundary so the caller sees WHY, not just an exit code.
+     */
+    refusalCode?: string;
+    /** Provider that actually served the run (reported by the child). */
+    provider?: string;
+    /** Model that actually served the run, when the child named one. */
+    model?: string;
+    /** How tool calls travelled: `native`, `json` (fallback) or `none`. */
+    transport?: string;
+    /**
+     * WS1 — the findings the child recorded, in call order, with the gate's
+     * verdict. Accumulated from its `finding` progress frames so a subagent run
+     * reports the same wire shape every other surface reports.
+     */
+    findings?: import('../findings/verdicts.js').WireFinding[];
+    /** WS5 (#27) — the isolated worktree this run used, when it was isolated. */
+    worktree?: string;
+    /** WS5 (#27) — the commit the isolated run's diff is measured against. */
+    worktreeBase?: string;
+    /** WS5 (#27) — what the isolated run changed (filled in when it ends). */
+    worktreeDiff?: import('./worktree.js').WorktreeDiff;
+    /** WS5 (#27) — true when the worktree was removed after the run. */
+    worktreeRemoved?: boolean;
+    /** WS5 (#27) — the child's own resume report, when it was asked to resume. */
+    resume?: import('../learning/step-checkpoint.js').ResumeOutcome;
+    /**
+     * G1 — the child's own verification verdict: it mutated the workspace and
+     * nothing observed the result. Recorded from the child's result frame, so a
+     * delegated run's unverified edit is visible to the parent's dashboard, CLI and
+     * findings the same way an in-process turn's is.
+     */
+    unverifiedEdit?: boolean;
+    /** G1/G2 — the child's answer claimed a code change no verification backed. */
+    unverifiedEditClaim?: boolean;
     /** LLM calls made */
     llmCalls: number;
     /** Tokens used */
@@ -65,6 +121,21 @@ export interface SubagentState {
     /** Duration in ms */
     durationMs?: number;
 }
+/**
+ * Decide a child's terminal state from what it actually reported.
+ *
+ * `handleExit` used to synthesise a success here — a child that exited 0 having
+ * sent no `result` message was marked `completed` with
+ * `result: 'Task completed successfully'`, so `subagent wait` returned success
+ * for a run whose output never existed. That is the fabricated-success defect of
+ * TOOL_TRUTHFULNESS_TRACKER finding #4, and it is the reason this decision is a
+ * separate, exported, tested function rather than three inline branches: no
+ * result means the child reported nothing, which is a failure, never a success.
+ */
+export declare function classifyChildExit(result: string | undefined, code: number | null, signal: NodeJS.Signals | null): {
+    status: SubagentStatus;
+    error?: string;
+};
 export interface SubagentResult {
     /** Subagent ID */
     id: string;
@@ -74,6 +145,19 @@ export interface SubagentResult {
     result: string;
     /** Error if failed */
     error?: string;
+    /** Typed refusal code when the child refused, when it reported one. */
+    refusalCode?: string;
+    /** Provider that served the run. */
+    provider?: string;
+    /** Model that served the run, when the child reported one. */
+    model?: string;
+    /** Tool transport the run used: `native`, `json` or `none`. */
+    transport?: string;
+    /**
+     * WS1 — the findings this run recorded, in call order, with the gate's
+     * verdict — the child's own report, carried across the process boundary.
+     */
+    findings?: import('../findings/verdicts.js').WireFinding[];
     /** LLM calls made */
     llmCalls: number;
     /** Tokens used */
@@ -84,9 +168,36 @@ export interface SubagentResult {
     durationMs: number;
     /** Full log */
     log: string[];
+    /**
+     * WS5 (#27) — the isolation this run had, and what it changed. Present only
+     * when isolation was asked for; `removed` says whether the directory is still
+     * on disk, so a caller can point at it or say it is gone.
+     */
+    worktree?: {
+        dir: string;
+        base: string;
+        diff: import('./worktree.js').WorktreeDiff;
+        removed: boolean;
+    };
+    /**
+     * WS5 (#27) — what the CHILD's resume replayed, and what it saved. Present only
+     * when a resume was asked for; read from the frame the child sent, so it is the
+     * child's own count rather than something the parent inferred.
+     */
+    resume?: import('../learning/step-checkpoint.js').ResumeOutcome;
+    /**
+     * G1 — the child's own verification verdict, carried across the fork. Present
+     * (and `true`) only when the child reported it: like `findings`, an absent flag
+     * means the child did not claim it, never that the edit was verified.
+     */
+    unverifiedEdit?: boolean;
+    /** G1/G2 — the child's answer claimed a code change no verification backed. */
+    unverifiedEditClaim?: boolean;
 }
 export declare class SubagentManager extends EventEmitter {
     private subagents;
+    /** WS5 (#27) — the live worktree of each isolated run, keyed by subagent id. */
+    private worktrees;
     private processes;
     private maxConcurrent;
     private maxDepth;
@@ -132,6 +243,17 @@ export declare class SubagentManager extends EventEmitter {
      */
     readResult(id: string): SubagentResult | null;
     private handleMessage;
+    /**
+     * Record which provider/model/transport the child is serving this run with.
+     *
+     * The child announces them on its FIRST frame — before it can fail — and repeats
+     * them on the result and error frames. Recording from every frame (not just the
+     * result) is what makes a FAILED run attributable: a subagent that its provider
+     * rejected used to land as a bare error with no provider, model or transport, so
+     * the dashboard showed a failure with nothing to debug it by — exactly backwards,
+     * since a run that produced no output is the one that needs the attribution.
+     */
+    private recordIdentity;
     private handleExit;
     private buildResult;
     private saveState;

package/dist/tools/subagent-spawner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"subagent-spawner.d.ts","sourceRoot":"","sources":["../../src/tools/subagent-spawner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAQH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAK3C,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEpG,MAAM,WAAW,cAAc;IAC7B,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0BAA0B;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uBAAuB;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,sCAAsC;IACtC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,oBAAoB;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oBAAoB;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wBAAwB;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAED,MAAM,WAAW,aAAa;IAC5B,kBAAkB;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,iBAAiB;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,aAAa;IACb,MAAM,EAAE,cAAc,CAAC;IACvB,WAAW;IACX,IAAI,EAAE,MAAM,CAAC;IACb,aAAa;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qBAAqB;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,sBAAsB;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qBAAqB;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,kBAAkB;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,cAAc;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,kBAAkB;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,sBAAsB;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qBAAqB;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,sBAAsB;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,qBAAqB;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe;IACf,GAAG,EAAE,MAAM,EAAE,CAAC;CACf;AASD,qBAAa,eAAgB,SAAQ,YAAY;IAC/C,OAAO,CAAC,SAAS,CAAyC;IAC1D,OAAO,CAAC,SAAS,CAAwC;IACzD,OAAO,CAAC,aAAa,CAAa;IAClC,OAAO,CAAC,QAAQ,CAAa;IAC7B,OAAO,CAAC,UAAU,CAAkB;;IAQpC,8BAA8B;IAC9B,SAAS,CAAC,OAAO,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;IAM7F,oCAAoC;IACpC,QAAQ,IAAI;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;IAOjD;;OAEG;IACG,KAAK,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IA6F3D;;OAEG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI;IAI1C;;OAEG;IACH,MAAM,IAAI,aAAa,EAAE;IAIzB;;OAEG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,GAAE,MAAiB,GAAG,OAAO;IAepD;;OAEG;IACG,iBAAiB,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,GAAE,MAAgB,GAAG,OAAO,CAAC,cAAc,CAAC;IAkCzF;;OAEG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE;IAM5B;;OAEG;IACH,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAY7C,OAAO,CAAC,aAAa;IAqBrB,OAAO,CAAC,UAAU;IAgClB,OAAO,CAAC,WAAW;IAcnB,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,YAAY;IAkBpB,OAAO,CAAC,iBAAiB;CAK1B;AAMD,wBAAgB,kBAAkB,IAAI,eAAe,CAGpD;AAED,wBAAgB,oBAAoB,IAAI,IAAI,CAK3C"}
+{"version":3,"file":"subagent-spawner.d.ts","sourceRoot":"","sources":["../../src/tools/subagent-spawner.ts"],"names":[],"mappings":"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"}

package/dist/tools/subagent-spawner.js

@@ -14,19 +14,89 @@
  * Hermes equivalent: delegate_tool.py (3931 lines) — actual agent spawning
  */
 import { fork } from 'node:child_process';
-import { resolveNuviraHome } from '../config/paths.js';
+import { resolveNuviraDataPath } from '../config/paths.js';
 import { randomUUID } from 'node:crypto';
-import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from 'node:fs';
+import { createWriteStream, existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { EventEmitter } from 'node:events';
 import { logger } from '../utils/logger.js';
+// WS3 (#25) — the W3C parent this child should continue, read from the ACTIVE
+// span (the tool call that spawned it), plus the env key it travels in.
+import { childTraceEnv, TRACEPARENT_ENV } from '../observability/otel.js';
+// WS5 (#27) — the env key the child resolves its resume request from.
+import { RESUME_ENABLE_ENV } from '../learning/step-checkpoint.js';
+// WS5 (#27) — delegation-level isolation: the parent makes the worktree, forks
+// INTO it, and measures the diff itself (see SubagentConfig.worktree).
+import { createIsolatedWorktree, discardWorktree, worktreeDiff, worktreeEnv, worktreeRefusal, } from './worktree.js';
+/**
+ * How long the exit path may spend on git.
+ *
+ * Deliberately far below the creation budget: this runs inside the child's exit
+ * handler, so every millisecond here is a millisecond the manager's own event
+ * loop is blocked. A diff that cannot be produced in five seconds is reported as
+ * "no changes could be measured", which is honest, rather than stalling a
+ * server that may be answering other sessions.
+ */
+const WORKTREE_EXIT_TIMEOUT_MS = 5_000;
+/**
+ * WS5 (#27) — how the resume request reaches the child: the inherited
+ * `NUVIRA_RESUME` (see `SubagentRuntimeConfig.resume`). The child resolves it from
+ * its own environment, exactly as an in-process surface does, so one request
+ * means the same thing on both sides of the fork.
+ */
+export const SUBAGENT_RESUME_ENV = RESUME_ENABLE_ENV;
+/**
+ * Decide a child's terminal state from what it actually reported.
+ *
+ * `handleExit` used to synthesise a success here — a child that exited 0 having
+ * sent no `result` message was marked `completed` with
+ * `result: 'Task completed successfully'`, so `subagent wait` returned success
+ * for a run whose output never existed. That is the fabricated-success defect of
+ * TOOL_TRUTHFULNESS_TRACKER finding #4, and it is the reason this decision is a
+ * separate, exported, tested function rather than three inline branches: no
+ * result means the child reported nothing, which is a failure, never a success.
+ */
+export function classifyChildExit(result, code, signal) {
+    if (result)
+        return { status: 'completed' };
+    if (code === 0)
+        return { status: 'failed', error: 'Subagent exited without reporting a result' };
+    return { status: 'failed', error: signal ? `Killed by ${signal}` : `Exit code ${code}` };
+}
 // ─── Subagent Manager ─────────────────────────────────────────────────────
-const SUBAGENT_DIR = join(resolveNuviraHome(), 'cache', 'subagents');
+// `resolveNuviraDataPath` (not `resolveNuviraHome`) so a process pointed at an
+// isolated config dir writes its subagent state there too — every other state file
+// the agent persists resolves through it, and a test can then inspect a run without
+// touching the developer's real ~/.nuvira.
+const SUBAGENT_DIR = resolveNuviraDataPath('cache', 'subagents');
 const STATE_DIR = join(SUBAGENT_DIR, 'state');
 const LOG_DIR = join(SUBAGENT_DIR, 'logs');
 const RESULT_DIR = join(SUBAGENT_DIR, 'results');
+/**
+ * The file to fork.
+ *
+ * A compiled build has `dist/tools/child-agent-entry.js` beside this module and
+ * plain `node` runs it. A source run (tsx/vitest) has the TypeScript original
+ * instead, which node cannot parse — it is forked through the tsx loader. The two
+ * layouts used to be handled by one hardcoded `.js` path, which failed BOTH ways:
+ * compiled, the build never emitted that file (allowJs is false, so `fork()` threw
+ * ENOENT); from source, it was a CommonJS file inside a `"type": "module"`
+ * package and died on `require is not defined`. That is why no subagent ever ran.
+ */
+function resolveChildEntry() {
+    const dir = import.meta.dirname;
+    const compiled = join(dir, 'child-agent-entry.js');
+    if (existsSync(compiled))
+        return { entry: compiled };
+    const source = join(dir, 'child-agent-entry.ts');
+    if (existsSync(source))
+        return { entry: source, execArgv: ['--import', 'tsx'] };
+    throw new Error(`subagent entry not found beside ${dir} (expected child-agent-entry.js or .ts) — the build is incomplete`);
+}
 export class SubagentManager extends EventEmitter {
     subagents = new Map();
+    /** WS5 (#27) — the live worktree of each isolated run, keyed by subagent id. */
+    worktrees = new Map();
     processes = new Map();
     maxConcurrent = 3;
     maxDepth = 1;
@@ -62,6 +132,8 @@ export class SubagentManager extends EventEmitter {
         const check = this.canSpawn();
         if (!check.allowed)
             throw new Error(check.reason);
+        /** WS5 — the worktree this run is isolated in, when one was asked for. */
+        let worktree = null;
         const id = randomUUID();
         const state = {
             id,
@@ -75,29 +147,80 @@ export class SubagentManager extends EventEmitter {
         this.subagents.set(id, state);
         this.saveState(state);
         try {
+            // WS5 (#27) — isolation, made by the parent BEFORE the fork. A refusal is a
+            // FAILED spawn rather than an unisolated run: the caller asked for isolation
+            // on purpose, and a run that silently happened in the real tree is the exact
+            // outcome this capability exists to prevent.
+            if (config.worktree) {
+                const repoCwd = config.cwd || process.cwd();
+                worktree = createIsolatedWorktree({ repoCwd, label: config.goal });
+                if (!worktree) {
+                    const why = worktreeRefusal(repoCwd) ?? 'the worktree could not be created';
+                    throw new Error(`Cannot isolate this subagent: ${why}`);
+                }
+                state.worktree = worktree.dir;
+                state.worktreeBase = worktree.base;
+                this.worktrees.set(id, { handle: worktree, keep: config.keepWorktree === true });
+                this.emit('progress', id, {
+                    phase: 'worktree',
+                    dir: worktree.dir,
+                    base: worktree.base,
+                    sourceDirty: worktree.sourceDirty,
+                });
+            }
             // Spawn child process
-            const child = fork(join(import.meta.dirname, 'child-agent-entry.js'), [], {
-                cwd: config.cwd || process.cwd(),
-                env: {
-                    ...process.env,
-                    ...config.env,
-                    SUBAGENT_ID: id,
-                    SUBAGENT_GOAL: config.goal,
-                    SUBAGENT_PROVIDER: config.provider || 'auto',
-                    SUBAGENT_MODEL: config.model || 'auto',
-                    SUBAGENT_MAX_LLM_CALLS: String(config.maxLlmCalls || 50),
-                    SUBAGENT_MAX_TOKENS: String(config.maxTokens || 100_000),
-                    SUBAGENT_TOOLS: JSON.stringify(config.tools || []),
-                    SUBAGENT_BLOCKED_TOOLS: JSON.stringify(config.blockedTools || []),
-                },
+            const { entry, execArgv } = resolveChildEntry();
+            // WS3 (#25) — hand the child the trace it belongs to. The loop makes the
+            // tool span ACTIVE around this call, so `childTraceEnv()` reads the real
+            // parent out of the active context (never out of module state, which two
+            // interleaved turns in one server would share). It is set or DELETED
+            // explicitly rather than merged: a `TRACEPARENT` inherited from this
+            // process's own environment is not the child's parent, and a stale one
+            // would graft the child onto a trace nobody is running.
+            const traceEnv = childTraceEnv();
+            const childEnv = {
+                ...process.env,
+                ...config.env,
+                SUBAGENT_ID: id,
+                SUBAGENT_GOAL: config.goal,
+                SUBAGENT_PROVIDER: config.provider || 'auto',
+                SUBAGENT_MODEL: config.model || 'auto',
+                SUBAGENT_MAX_LLM_CALLS: String(config.maxLlmCalls || 50),
+                SUBAGENT_MAX_TOKENS: String(config.maxTokens || 100_000),
+                SUBAGENT_TOOLS: JSON.stringify(config.tools || []),
+                SUBAGENT_BLOCKED_TOOLS: JSON.stringify(config.blockedTools || []),
+            };
+            const traceparent = traceEnv[TRACEPARENT_ENV];
+            if (traceparent)
+                childEnv[TRACEPARENT_ENV] = traceparent;
+            else
+                delete childEnv[TRACEPARENT_ENV];
+            // WS5 — the resume request travels as the environment the child resolves it
+            // from. INHERITED when the caller does not name one (unlike the traceparent
+            // above, which is explicitly cleared): a parent run that was asked to resume
+            // is asking for its children's model calls to be replayed too, and a child
+            // with no record of its own simply records a fresh one. An explicit
+            // `false` is how a caller opts a child out of that.
+            // WS5 — the child's cwd IS the isolation, and it is told so in its
+            // environment: a tool inside the run can then report which worktree it is
+            // working in instead of guessing, and a nested spawn can isolate from it.
+            if (worktree)
+                Object.assign(childEnv, worktreeEnv(worktree));
+            const child = fork(entry, [], {
+                cwd: worktree?.dir ?? config.cwd ?? process.cwd(),
+                ...(execArgv ? { execArgv } : {}),
+                env: childEnv,
                 stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
             });
+            logger.info(`Subagent: forked ${entry}${execArgv ? ` (via ${execArgv.join(' ')})` : ''}`);
             state.pid = child.pid;
             state.status = 'running';
             this.processes.set(id, child);
-            // Set up log file
+            // Set up log file. This used to be `require('node:fs')` INSIDE an ESM
+            // module, so it threw `require is not defined` immediately after the fork
+            // and `spawn()` rejected before the child was ever tracked.
             const logFile = join(LOG_DIR, `${id}.log`);
-            const logStream = require('node:fs').createWriteStream(logFile, { flags: 'a' });
+            const logStream = createWriteStream(logFile, { flags: 'a' });
             // Pipe stdout/stderr to log file
             child.stdout?.pipe(logStream);
             child.stderr?.pipe(logStream);
@@ -131,6 +254,15 @@ export class SubagentManager extends EventEmitter {
             return state;
         }
         catch (err) {
+            // A spawn that failed AFTER the worktree was made leaves nothing behind:
+            // the run never happened, so neither should its directory.
+            if (worktree) {
+                const kept = this.worktrees.get(id)?.keep === true;
+                if (!kept)
+                    discardWorktree(worktree, { timeoutMs: WORKTREE_EXIT_TIMEOUT_MS });
+                if (!kept)
+                    this.worktrees.delete(id);
+            }
             state.status = 'failed';
             state.error = String(err);
             state.endedAt = Date.now();
@@ -232,6 +364,17 @@ export class SubagentManager extends EventEmitter {
                 state.llmCalls = msg.llmCalls || state.llmCalls;
                 state.tokensUsed = msg.tokensUsed || state.tokensUsed;
                 state.toolCalls = msg.toolCalls || state.toolCalls;
+                // WS1 — a finding the child recorded. Appended, never replaced: a run
+                // can record several, and the order is part of what it did.
+                if (msg.finding && typeof msg.finding === 'object') {
+                    state.findings = [...(state.findings ?? []), msg.finding];
+                }
+                // WS5 (#27) — the child's own resume report. A frame, not a return value:
+                // the child is a separate process, and this is its only channel back.
+                if (msg.resume && typeof msg.resume === 'object') {
+                    state.resume = msg.resume;
+                }
+                this.recordIdentity(state, msg);
                 this.saveState(state);
                 this.emit('progress', id, msg);
                 break;
@@ -240,25 +383,80 @@ export class SubagentManager extends EventEmitter {
                 state.llmCalls = msg.llmCalls || state.llmCalls;
                 state.tokensUsed = msg.tokensUsed || state.tokensUsed;
                 state.toolCalls = msg.toolCalls || state.toolCalls;
+                // G1 — the child's verification verdict, read off its result frame. Only
+                // a truthy flag is recorded: the child omits it when the edit WAS verified,
+                // so `undefined` here means "not claimed", and never `false`.
+                if (msg.unverifiedEdit === true)
+                    state.unverifiedEdit = true;
+                if (msg.unverifiedEditClaim === true)
+                    state.unverifiedEditClaim = true;
+                this.recordIdentity(state, msg);
+                this.saveState(state);
+                break;
+            case 'error':
+                // The child's OWN reason. Without this the message was dropped and the
+                // parent could only report "Exit code 1".
+                state.error = msg.error || 'Subagent reported an error';
+                if (msg.code)
+                    state.refusalCode = msg.code;
+                this.recordIdentity(state, msg);
+                this.saveState(state);
                 break;
         }
     }
+    /**
+     * Record which provider/model/transport the child is serving this run with.
+     *
+     * The child announces them on its FIRST frame — before it can fail — and repeats
+     * them on the result and error frames. Recording from every frame (not just the
+     * result) is what makes a FAILED run attributable: a subagent that its provider
+     * rejected used to land as a bare error with no provider, model or transport, so
+     * the dashboard showed a failure with nothing to debug it by — exactly backwards,
+     * since a run that produced no output is the one that needs the attribution.
+     */
+    recordIdentity(state, msg) {
+        if (msg.provider)
+            state.provider = String(msg.provider);
+        if (msg.model)
+            state.model = String(msg.model);
+        if (msg.transport)
+            state.transport = String(msg.transport);
+    }
     handleExit(id, code, signal) {
         const state = this.subagents.get(id);
         if (!state)
             return;
         state.endedAt = Date.now();
         state.durationMs = state.endedAt - state.startedAt;
-        if (state.result) {
-            state.status = 'completed';
+        if (state.status === 'killed' || state.status === 'timeout') {
+            // The killer already recorded why; do not overwrite it with an exit code.
         }
-        else if (code === 0) {
-            state.status = 'completed';
-            state.result = 'Task completed successfully';
+        else if (state.error) {
+            // The child said why it failed — that reason outranks its exit code.
+            state.status = 'failed';
         }
         else {
-            state.status = 'failed';
-            state.error = signal ? `Killed by ${signal}` : `Exit code ${code}`;
+            const outcome = classifyChildExit(state.result, code, signal);
+            state.status = outcome.status;
+            if (outcome.error)
+                state.error = outcome.error;
+        }
+        // WS5 (#27) — what an isolated run changed, measured from the parent, and the
+        // teardown. Both happen BEFORE the result is built and emitted, so the diff
+        // rides on the result its caller is waiting for: a diff reported later (or by
+        // a separate command) is a diff most callers never see. A KILLED run is
+        // measured too — "what had it changed when you stopped it" is exactly the
+        // question a teardown needs answered.
+        const isolated = this.worktrees.get(id);
+        if (isolated) {
+            state.worktreeDiff = worktreeDiff(isolated.handle, { timeoutMs: WORKTREE_EXIT_TIMEOUT_MS });
+            if (isolated.keep) {
+                state.worktreeRemoved = false;
+            }
+            else {
+                state.worktreeRemoved = discardWorktree(isolated.handle, { timeoutMs: WORKTREE_EXIT_TIMEOUT_MS });
+            }
+            this.worktrees.delete(id);
         }
         this.saveState(state);
         this.processes.delete(id);
@@ -269,8 +467,13 @@ export class SubagentManager extends EventEmitter {
             this.emit(`completed:${id}`, result);
         }
         else {
-            this.emit('failed', id, new Error(state.error));
-            this.emit(`failed:${id}`, new Error(state.error));
+            // The child's typed refusal (when it reported one) rides on the error, so
+            // `waitForCompletion`'s rejection is actionable instead of a bare message.
+            const failure = new Error(state.error);
+            if (state.refusalCode)
+                failure.code = state.refusalCode;
+            this.emit('failed', id, failure);
+            this.emit(`failed:${id}`, failure);
         }
     }
     buildResult(state) {
@@ -279,6 +482,24 @@ export class SubagentManager extends EventEmitter {
             success: state.status === 'completed',
             result: state.result || '',
             error: state.error,
+            ...(state.refusalCode ? { refusalCode: state.refusalCode } : {}),
+            ...(state.provider ? { provider: state.provider } : {}),
+            ...(state.model ? { model: state.model } : {}),
+            ...(state.transport ? { transport: state.transport } : {}),
+            ...(state.findings && state.findings.length > 0 ? { findings: state.findings } : {}),
+            ...(state.resume ? { resume: state.resume } : {}),
+            ...(state.unverifiedEdit ? { unverifiedEdit: true } : {}),
+            ...(state.unverifiedEditClaim ? { unverifiedEditClaim: true } : {}),
+            ...(state.worktree && state.worktreeBase && state.worktreeDiff
+                ? {
+                    worktree: {
+                        dir: state.worktree,
+                        base: state.worktreeBase,
+                        diff: state.worktreeDiff,
+                        removed: state.worktreeRemoved === true,
+                    },
+                }
+                : {}),
             llmCalls: state.llmCalls,
             tokensUsed: state.tokensUsed,
             toolCalls: state.toolCalls,