@wildorder/nightshift 0.16.0 → 0.18.0

package/dist/agent-runner.js

@@ -1,8 +1,13 @@
 import { spawn } from "node:child_process";
 import { randomBytes } from "node:crypto";
+import { createWriteStream } from "node:fs";
 import { mkdir, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import crossSpawn from "cross-spawn";
+import { deriveResumeInvocation, hasPinnedSessionFlag, } from "./permits.js";
+import { createTelemetryAccumulator, parseConfiguredModel, providerLabelFromCommand, providerTelemetryPoints, } from "./provider-telemetry.js";
+import { NOOP_RUN_RECORDER, } from "./run-analytics.js";
+import { describeSessionDecline, } from "./agent-session.js";
 // In-memory output is kept to a bounded tail; full output belongs in the
 // per-workstream log via onOutput streaming.
 const OUTPUT_TAIL_LIMIT = 200_000;
@@ -54,7 +59,10 @@ export function runProcess(command, args, options) {
             push(chunk);
             options.onStdout?.(chunk);
         });
-        child.stderr.on("data", push);
+        child.stderr.on("data", (chunk) => {
+            push(chunk);
+            options.onStderr?.(chunk);
+        });
         child.on("error", rejectPromise);
         let inputError;
         child.stdin.on("error", (error) => {
@@ -169,7 +177,7 @@ function toolResultText(block) {
  * transcript's `commands` list therefore means "ran", never "asked to run" —
  * a denied command appears under `denials` only.
  */
-function createClaudeStreamJsonDemultiplexer() {
+function createClaudeStreamJsonDemultiplexer(telemetryInputs) {
     let carry = "";
     let firstLineSeen = false;
     let isNdjson = true;
@@ -180,10 +188,30 @@ function createClaudeStreamJsonDemultiplexer() {
     const errorResults = new Map();
     let resultText;
     let assistantText = "";
+    // WS-08: the authoritative source is the `system`/`init` event; any other
+    // event carrying a `session_id` sets it only if nothing is held yet, so a
+    // stream that lost its init line (an operator who pinned
+    // `--output-format=stream-json` without `--verbose`) still yields an id.
+    let sessionId;
+    const telemetry = createTelemetryAccumulator({
+        configuredModel: parseConfiguredModel(telemetryInputs?.configuredArgs ?? []),
+        commandProviderGuess: providerLabelFromCommand(telemetryInputs?.command),
+    });
     function routeEvent(event) {
         if (event === null || typeof event !== "object")
             return;
         const record = event;
+        // WS-03 rides the same already-parsed event this function routes for
+        // commands/denials — never a second parse of the underlying text.
+        telemetry.observeEvent(record);
+        if (typeof record.session_id === "string") {
+            if (record.type === "system" && record.subtype === "init") {
+                sessionId = record.session_id;
+            }
+            else if (sessionId === undefined) {
+                sessionId = record.session_id;
+            }
+        }
         if (record.type === "assistant") {
             const content = record.message?.content;
             if (Array.isArray(content)) {
@@ -326,9 +354,13 @@ function createClaudeStreamJsonDemultiplexer() {
                     commands,
                     denials: finalDenials,
                     ...(corrupted ? { corrupted: true } : {}),
+                    ...(sessionId === undefined ? {} : { sessionId }),
                 },
             };
         },
+        finishTelemetry() {
+            return telemetry.finish({ observed: firstLineSeen && isNdjson, corrupted });
+        },
     };
 }
 /**
@@ -341,13 +373,84 @@ export function demultiplexClaudeStreamJson(raw) {
     demux.feed(raw);
     return demux.finish();
 }
+// ---------------------------------------------------------------------------
+// Codex session id capture (WS-08 §2.3/§2.4) — verified against codex
+// v0.149.0 on 2026-09-11. Codex writes its startup header, including the
+// `session id:` line, and its entire running transcript to stderr, writing
+// only the agent's final message to stdout; with `--json` (never added by
+// nightshift, but an operator may configure it) the id instead arrives as
+// `thread_id` on a stdout `thread.started` event, and a resumed run reprints
+// the same value on its `session id:` line either way.
+// ---------------------------------------------------------------------------
+const UUID_PATTERN = "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}";
+const CODEX_SESSION_ID_LINE = new RegExp(`^\\s*session id:\\s*(${UUID_PATTERN})\\s*$`, "iu");
+const UUID_ONLY = new RegExp(`^${UUID_PATTERN}$`, "iu");
+/** The session id from one codex stderr line, when it is the anchored
+ *  `session id: <uuid>` header line — an embedded or prefixed occurrence
+ *  inside ordinary prose does not match. */
+export function captureCodexSessionIdFromStderr(line) {
+    return CODEX_SESSION_ID_LINE.exec(line)?.[1];
+}
+/** The `thread_id` from one codex `--json`-mode stdout line, when it is a
+ *  well-formed `thread.started` event. */
+export function captureCodexSessionIdFromStdout(line) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+    if (parsed === null || typeof parsed !== "object")
+        return undefined;
+    const record = parsed;
+    if (record.type !== "thread.started")
+        return undefined;
+    const threadId = record.thread_id;
+    return typeof threadId === "string" && UUID_ONLY.test(threadId) ? threadId : undefined;
+}
+/** Line-buffered, like the Claude demultiplexer; stops at the first match —
+ *  codex prints its header before any model output, so the first match is
+ *  structurally the header's, never the agent's own prose. */
+function createCodexSessionScanner() {
+    let sessionId;
+    let stderrCarry = "";
+    let stdoutCarry = "";
+    function scanLines(carry, chunk, setCarry, capture) {
+        if (sessionId !== undefined)
+            return;
+        let buffer = carry + chunk;
+        let newline;
+        while (sessionId === undefined && (newline = buffer.indexOf("\n")) !== -1) {
+            const line = buffer.slice(0, newline);
+            buffer = buffer.slice(newline + 1);
+            const found = capture(line);
+            if (found !== undefined)
+                sessionId = found;
+        }
+        setCarry(sessionId === undefined ? buffer : "");
+    }
+    return {
+        feedStderr(chunk) {
+            scanLines(stderrCarry, chunk, (value) => (stderrCarry = value), captureCodexSessionIdFromStderr);
+        },
+        feedStdout(chunk) {
+            scanLines(stdoutCarry, chunk, (value) => (stdoutCarry = value), captureCodexSessionIdFromStdout);
+        },
+        sessionId: () => sessionId,
+    };
+}
 export const defaultAgentRunner = async (invocation) => {
     const finalArgs = invocation.promptMode === "argument"
         ? [...invocation.args, invocation.prompt]
         : invocation.args;
     const demux = claudeStreamJsonRequested(invocation.args)
-        ? createClaudeStreamJsonDemultiplexer()
+        ? createClaudeStreamJsonDemultiplexer({ configuredArgs: invocation.args, command: invocation.command })
         : undefined;
+    // Gated on the command so a non-codex spawn's stderr is never scanned —
+    // an operator's chatty stderr elsewhere must never be mistaken for a
+    // codex session header (WS-08).
+    const codexScanner = providerLabelFromCommand(invocation.command).value === "codex" ? createCodexSessionScanner() : undefined;
     const result = await runProcess(invocation.command, finalArgs, {
         cwd: invocation.cwd,
         // Never a shell: agent args are structured argv from the config, and
@@ -362,21 +465,39 @@ export const defaultAgentRunner = async (invocation) => {
         // Stdout-only: stderr can carry plain-text CLI warnings ahead of or
         // interleaved with the NDJSON stream, and feeding those into the line
         // parser would corrupt or invalidate a stream that is, on stdout alone,
-        // perfectly well-formed.
-        onStdout: (chunk) => demux?.feed(chunk),
+        // perfectly well-formed. The raw tee (when the caller wants one
+        // retained, WS-03) rides the same stdout-only callback, in arrival
+        // order, so the sidecar and the demultiplexer never disagree about what
+        // the process actually printed.
+        onStdout: (chunk) => {
+            demux?.feed(chunk);
+            codexScanner?.feedStdout(chunk);
+            try {
+                invocation.rawTranscript?.write(chunk);
+            }
+            catch (error) {
+                invocation.rawTranscript?.onError(error);
+            }
+        },
+        onStderr: (chunk) => {
+            codexScanner?.feedStderr(chunk);
+        },
         ...(invocation.promptMode === "stdin"
             ? { input: invocation.prompt }
             : {}),
     });
-    if (!demux)
-        return result;
+    const codexSessionId = codexScanner?.sessionId();
+    if (!demux) {
+        return codexSessionId === undefined ? result : { ...result, sessionId: codexSessionId };
+    }
     const demultiplexed = demux.finish();
+    const telemetry = demux.finishTelemetry();
     if (demultiplexed === undefined) {
         // Not NDJSON at all (an older CLI ignored the flag, or the process
         // crashed before its first event) — the raw tail stays `output` exactly
         // as it works today; `observed: false` distinguishes this from a spawn
         // this module never asked to be observed in the first place.
-        return { ...result, transcript: { observed: false, commands: [], denials: [] } };
+        return { ...result, transcript: { observed: false, commands: [], denials: [], telemetry } };
     }
     return {
         ...result,
@@ -385,7 +506,10 @@ export const defaultAgentRunner = async (invocation) => {
         // falls back to the raw tail rather than handing the parsers an empty
         // string.
         output: demultiplexed.output !== "" ? demultiplexed.output : result.output,
-        transcript: demultiplexed.transcript,
+        transcript: { ...demultiplexed.transcript, telemetry },
+        ...(demultiplexed.transcript.sessionId === undefined
+            ? {}
+            : { sessionId: demultiplexed.transcript.sessionId }),
     };
 };
 export const defaultVerifyRunner = (command, cwd) => runProcess(command, [], { cwd, shell: true });
@@ -393,13 +517,17 @@ export function tail(output, limit = 2000) {
     return output.length > limit ? output.slice(-limit) : output;
 }
 /** JSONL body: a header line naming role/label, then one line per command and one per denial. */
-async function writeTranscript(sink, role, transcript) {
+async function writeTranscript(sink, role, transcript, nonce) {
     const dir = join(sink.root, "build-logs", sink.programId);
     await mkdir(dir, { recursive: true });
-    const nonce = randomBytes(4).toString("hex");
     const fileName = `${sink.label}-${nonce}.jsonl`;
     const lines = [
-        JSON.stringify({ role, label: sink.label, ...(transcript.corrupted ? { corrupted: true } : {}) }),
+        JSON.stringify({
+            role,
+            label: sink.label,
+            ...(transcript.corrupted ? { corrupted: true } : {}),
+            ...(transcript.sessionId === undefined ? {} : { sessionId: transcript.sessionId }),
+        }),
         ...transcript.commands.map((command) => JSON.stringify({ kind: "command", ...command })),
         ...transcript.denials.map((denial) => JSON.stringify({ kind: "denial", ...denial })),
     ];
@@ -413,21 +541,156 @@ async function writeTranscript(sink, role, transcript) {
  * invocation and so cannot go through `invokeAgent` itself). A no-op when the
  * result carries no transcript at all (a non-Claude spawn, an operator-
  * configured or operator-`--output-format` role — never asked to be
- * observed).
+ * observed). Returns the repo-relative path actually written, so a caller
+ * (WS-03) can cite it as evidence; `undefined` when nothing was written.
+ *
+ * `nonce`, when given, names the file so it shares its stem with a raw
+ * sidecar `invokeAgent` allocated up front (WS-03); the probe has no such
+ * sidecar and lets this mint its own, exactly as it did before this
+ * parameter existed.
  */
-export async function recordAgentTranscript(observe, role, result) {
+export async function recordAgentTranscript(observe, role, result, nonce = randomBytes(4).toString("hex")) {
     if (!result.transcript)
-        return;
+        return undefined;
     if (result.transcript.observed) {
-        const path = await writeTranscript(observe, role, result.transcript);
+        const path = await writeTranscript(observe, role, result.transcript, nonce);
         observe.log(result.transcript.corrupted
             ? `transcript: ${path} (warning: a line mid-stream could not be parsed — ` +
                 "this transcript may be missing a command or denial)"
             : `transcript: ${path}`);
+        return path;
     }
-    else {
-        observe.log(`transcript: ${observe.label}'s stream-json output did not parse as NDJSON — falling back to raw text`);
+    observe.log(`transcript: ${observe.label}'s stream-json output did not parse as NDJSON — falling back to raw text`);
+    return undefined;
+}
+/**
+ * Ties a spawn's normalized transcript and raw sidecar to one `<label>-
+ * <nonce>` stem, allocated before the process starts (WS-03) — the nonce
+ * `writeTranscript` used to mint itself, after the process had already
+ * exited, could never be shared with a raw tee that must be live while the
+ * stream is still arriving.
+ */
+function allocateTranscriptStem(sink) {
+    const nonce = randomBytes(4).toString("hex");
+    const base = `${sink.label}-${nonce}`;
+    return {
+        nonce,
+        rawPath: join(sink.root, "build-logs", sink.programId, `${base}.raw.jsonl`),
+        rawRelPath: `build-logs/${sink.programId}/${base}.raw.jsonl`,
+    };
+}
+/**
+ * A gitignored write-stream sidecar for one spawn's raw stdout (WS-03,
+ * SC-08) — fail-open throughout: an open/write/close failure is logged and
+ * flips `failed()`, but never throws into the run.
+ */
+function createRawTranscriptSink(path, log) {
+    let failed = false;
+    let stream;
+    function fail(error) {
+        failed = true;
+        try {
+            log(`run-analytics: raw transcript sidecar failed: ${error.message}`);
+        }
+        catch {
+            // Logging must never be the reason this failure escapes fail-open.
+        }
     }
+    try {
+        stream = createWriteStream(path);
+        stream.on("error", fail);
+    }
+    catch (error) {
+        fail(error);
+    }
+    return {
+        write(chunk) {
+            if (failed || !stream)
+                return;
+            try {
+                stream.write(chunk);
+            }
+            catch (error) {
+                fail(error);
+            }
+        },
+        async close() {
+            if (failed || !stream)
+                return;
+            try {
+                await new Promise((resolvePromise) => {
+                    stream.once("error", (error) => {
+                        fail(error);
+                        resolvePromise();
+                    });
+                    stream.end(() => resolvePromise());
+                });
+            }
+            catch (error) {
+                // A synchronous throw out of `stream.end()` itself (a corrupted
+                // stream state, not just an emitted "error" event) rejects the
+                // executor's promise; caught here so `close()` never throws into
+                // `invokeAgent` (SC-13) and the raw evidence ref is correctly
+                // omitted via `failed()`.
+                fail(error);
+            }
+        },
+        onError: fail,
+        failed: () => failed,
+    };
+}
+/**
+ * A defensible, not-exhaustive default stage per spawn seat — enough for a
+ * WS-01 reference span proving the recorder API end-to-end (see the
+ * WS-01/WS-02 emission-boundary decision). WS-02 owns the full dimension set
+ * (attempt seat, index, reason, workstream) that distinguishes an
+ * implementer attempt from a recovery or informed-retry one; this mapping is
+ * not meant to survive that instrumentation unchanged.
+ */
+const STAGE_FOR_ROLE = {
+    agent: "implementer",
+    recoveryAgent: "recovery",
+    authorAgent: "author",
+    deciderAgent: "decision-review",
+    reviewerAgent: "test-critique",
+};
+function sameArgs(a, b) {
+    return a.length === b.length && a.every((value, index) => value === b[index]);
+}
+/**
+ * The §3.3.2 checks, in order, and the §3.4 resume derivation (WS-08).
+ * `originalAgent` is the operator's configured agent, pre-`permits.derive` —
+ * the pinned-session-flag check reads that, never the derived args, because
+ * an operator-authored session flag is what it exists to detect. Every other
+ * comparison is on the derived, pre-resume invocation, which is stable for a
+ * given role/config across a run (`permits.derive` is deterministic).
+ */
+function resolveSessionContinuity(request, originalAgent, derivedAgent, cwd) {
+    const decline = (reason) => ({
+        continuity: { mode: "fresh", declineReason: reason },
+        spawnAgent: derivedAgent,
+    });
+    const handle = request.handle;
+    if (handle === undefined)
+        return decline("no-session-captured");
+    if (handle.command !== derivedAgent.command)
+        return decline("provider-mismatch");
+    if (!sameArgs(handle.args, derivedAgent.args) || handle.promptMode !== derivedAgent.promptMode) {
+        return decline("invocation-mismatch");
+    }
+    if (handle.cwd !== cwd)
+        return decline("cwd-mismatch");
+    if (hasPinnedSessionFlag(originalAgent))
+        return decline("operator-pinned-session-flag");
+    const resumeDerivation = deriveResumeInvocation(derivedAgent, handle.id);
+    if (!resumeDerivation.supported)
+        return decline("unsupported-resume-argv");
+    return { continuity: { mode: "resumed" }, spawnAgent: resumeDerivation.agent };
+}
+/** First 8 characters of a session id, for a log line — enough to tell two
+ *  sessions apart at a glance without printing the whole machine-local id. */
+function shortSessionId(id) {
+    return id.slice(0, 8);
 }
 /**
  * Spawns a configured agent role with a prompt; shared by every brief
@@ -439,20 +702,167 @@ export async function recordAgentTranscript(observe, role, result) {
  *
  * `observe`, when given, writes the spawn's transcript (if one was observed)
  * as JSONL under `build-logs/<programId>/` and logs the path — the one place
- * this happens, rather than duplicated across every spawning call site.
+ * this happens, rather than duplicated across every spawning call site. It
+ * also names a raw stdout sidecar (WS-03, SC-08), teed during the spawn and
+ * `close()`-awaited before any evidence reference resolves to it.
+ *
+ * `recorder`, when given, opens a span around the spawn (WS-01) and — after
+ * the spawn returns — receives one `provider-telemetry` point per
+ * SC-08-enumerated metric (WS-03), correlated by the `role` dimension and
+ * the normalized/raw transcript paths as evidence. A caller with no
+ * run-scoped recorder to hand gets a shared, permanently disarmed default
+ * that buffers harmlessly and performs no I/O — telemetry emission is then
+ * simply a no-op, never a thrown error.
+ *
+ * `spanDims`, when given, overrides the role-derived default stage/dimensions
+ * (WS-02) — the call site is the only party that knows which of a reused
+ * role's several stages (e.g. `reviewerAgent` driving `test-critique`,
+ * `failure-diagnosis`, or `whole-program-review`) this particular spawn is,
+ * plus the workstream/attempt dimensions. A caller that passes nothing keeps
+ * today's `STAGE_FOR_ROLE` default, so every pre-WS-02 call site (the doctor
+ * probe, standalone tests) is unaffected.
  */
-export async function invokeAgent(runner, agent, prompt, cwd, permits, role, observe) {
-    const derived = await permits.derive(role, agent);
-    const result = await runner({
-        command: derived.agent.command,
-        args: derived.agent.args,
-        prompt,
-        promptMode: derived.agent.promptMode,
-        cwd,
-    });
-    if (observe)
-        await recordAgentTranscript(observe, role, result);
-    return result;
+export async function invokeAgent(runner, agent, prompt, cwd, permits, role, observe, recorder = NOOP_RUN_RECORDER, spanDims, 
+/** Present only for the three seats that may continue a session (SC-13,
+ *  WS-08); its presence is the permission and its `handle` is the
+ *  candidate. Omitted everywhere else, which is how reviewer, decider,
+ *  recovery and informed-retry seats are structurally incapable of
+ *  resuming — not by a runtime check they could forget. */
+continuityRequest) {
+    const span = recorder.span({ stage: STAGE_FOR_ROLE[role], role, ...spanDims });
+    try {
+        const derived = await permits.derive(role, agent);
+        // WS-08: resolved *after* `permits.derive` (so a resumed Claude spawn
+        // still carries `observabilityFlags`'s stream-json/verbose pair) and
+        // applied to whatever `permits.derive` returned — never to `agent`
+        // directly — so this works identically under the real context, the
+        // no-op context, and a test double (§2.7).
+        let spawnAgent = derived.agent;
+        let continuity;
+        if (continuityRequest) {
+            const resolved = resolveSessionContinuity(continuityRequest, agent, derived.agent, cwd);
+            continuity = resolved.continuity;
+            spawnAgent = resolved.spawnAgent;
+            if (continuity.mode === "resumed" && continuityRequest.handle) {
+                observe?.log(`resumed session ${shortSessionId(continuityRequest.handle.id)}`);
+            }
+            else if (continuity.declineReason) {
+                observe?.log(`session continuity declined for ${role}: ${describeSessionDecline(continuity.declineReason)}`);
+            }
+        }
+        const stem = observe ? allocateTranscriptStem(observe) : undefined;
+        // Only a spawn that actually requests structured stream-json output has
+        // raw provider events worth retaining — a codex (or any non-Claude)
+        // spawn writes no plaintext sidecar, matching its already-`unavailable`
+        // telemetry rather than littering build-logs/ with an empty file.
+        let rawSink;
+        if (observe && stem && claudeStreamJsonRequested(spawnAgent.args)) {
+            try {
+                await mkdir(dirname(stem.rawPath), { recursive: true });
+                rawSink = createRawTranscriptSink(stem.rawPath, observe.log);
+            }
+            catch (error) {
+                observe.log(`run-analytics: raw transcript sidecar could not be opened: ${error.message}`);
+            }
+        }
+        let result;
+        try {
+            result = await runner({
+                command: spawnAgent.command,
+                args: spawnAgent.args,
+                prompt,
+                promptMode: spawnAgent.promptMode,
+                cwd,
+                ...(rawSink ? { rawTranscript: rawSink } : {}),
+            });
+        }
+        finally {
+            // Awaited whether the runner resolved or rejected — a raw sink opened
+            // before the spawn must never be left dangling on a rejected promise
+            // (SC-13: fail-open, not leak-open), and awaited before the raw path
+            // is ever cited as evidence, so a reference to it never resolves
+            // before the bytes are durable (WS-03). `createRawTranscriptSink`'s
+            // own `close()` never throws, but this call site guards independently
+            // (defense in depth, SC-13) so a future sink implementation's close
+            // failure cannot escape into the run's outcome.
+            try {
+                await rawSink?.close();
+            }
+            catch (error) {
+                observe?.log(`run-analytics: raw transcript sidecar close failed: ${error.message}`);
+            }
+        }
+        let transcriptPath;
+        if (observe && stem) {
+            // A normalized-transcript write failure (full disk, EACCES) is a
+            // persistence defect, not a spawn failure — diagnosed and swallowed so
+            // it never flips a successful attempt's outcome (SC-13); the point
+            // still emits below, simply without this evidence ref.
+            try {
+                transcriptPath = await recordAgentTranscript(observe, role, result, stem.nonce);
+            }
+            catch (error) {
+                observe.log(`run-analytics: normalized transcript persistence failed: ${error.message}`);
+            }
+        }
+        const evidence = [];
+        if (transcriptPath)
+            evidence.push({ kind: "transcript", locality: "local", ref: transcriptPath });
+        if (stem && rawSink && !rawSink.failed()) {
+            evidence.push({ kind: "transcript", locality: "local", ref: stem.rawRelPath, note: "raw stdout" });
+        }
+        // Every spawn gets its enumerated provider-telemetry point set — a
+        // spawn whose runner attached no transcript at all (a non-Claude
+        // command, never asked for stream-json) still normalizes to a fully
+        // `unavailable` record rather than emitting nothing (the codex dogfood
+        // signal, SC-08). `recorder.point()` itself is guaranteed non-throwing
+        // (WS-01), but the telemetry it is fed here — a transcript's `.telemetry`
+        // shape, and the fan-out over it — comes from this workstream and is not;
+        // wrapped so a normalizer or fan-out defect is diagnosed and swallowed
+        // rather than propagating out of invokeAgent as if the agent itself had
+        // failed to spawn (SC-13).
+        try {
+            const telemetry = result.transcript?.telemetry ??
+                createTelemetryAccumulator({
+                    configuredModel: parseConfiguredModel(spawnAgent.args),
+                    commandProviderGuess: providerLabelFromCommand(spawnAgent.command),
+                }).finish({ observed: false, corrupted: false });
+            for (const point of providerTelemetryPoints(telemetry, { role }, evidence)) {
+                recorder.point(point);
+            }
+        }
+        catch (error) {
+            observe?.log(`run-analytics: provider telemetry emission failed: ${error.message}`);
+        }
+        span.close({
+            outcome: result.exitCode === 0 ? "success" : "failed",
+            ...(evidence.length === 0 ? {} : { evidence }),
+        });
+        // WS-08: assembled from the spawn's own reported id and the *pre-resume*
+        // derived invocation (`derived`, never `spawnAgent`) — so a handle
+        // captured from a resumed spawn compares equal to one captured from a
+        // fresh spawn of the same seat, which is what lets a fix-now fix resume
+        // a test-critique fix's session rather than re-declining on its own
+        // `--resume` argument (§3.3.3).
+        const session = result.sessionId
+            ? {
+                id: result.sessionId,
+                command: derived.agent.command,
+                cwd,
+                args: derived.agent.args,
+                promptMode: derived.agent.promptMode,
+            }
+            : undefined;
+        return {
+            ...result,
+            ...(session ? { session } : {}),
+            ...(continuityRequest ? { continuity: continuity ?? { mode: "fresh", declineReason: "no-session-captured" } } : {}),
+        };
+    }
+    catch (error) {
+        span.close({ outcome: "failed" });
+        throw error;
+    }
 }
 /**
  * The implementer: the `agent` block, or the environment fallback for hosts