agent-dealer 1.2.9 → 1.2.10

package/bundle/server/dist/coordinator/muse-spawn.test.js

@@ -2,30 +2,36 @@
 // arrival-stamped normalized events, and the five-field stall metadata object.
 // The full `runMuseDeveloperSession` needs a Muse binary + credentials, so these
 // test the pure pieces it wires together (plus the parser contract it relies on).
-import { test } from "node:test";
+import { test, after } from "node:test";
 import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { parseMuseRun } from "../runners/muse-code-jsonl.js";
-import { museIdleTimeoutMs, DEFAULT_MUSE_IDLE_TIMEOUT_MS } from "./session-timeouts.js";
-import { museIdleMinutes, museStallMetadata, sessionLogActivityMs, writeMuseNormalizedLog, } from "./muse-spawn.js";
+import { fileURLToPath } from "node:url";
+import { MUSE_CODE_CONTRIBUTOR_MODEL } from "@agent-dealer/shared";
+import { parseMuseRun, isMuseTerminalStdoutLine, createMusePrimaryTerminalMatcher, } from "../runners/muse-code-jsonl.js";
+import { museIdleTimeoutMs, museTerminalGraceMs, DEFAULT_MUSE_IDLE_TIMEOUT_MS, DEFAULT_MUSE_TERMINAL_GRACE_MS, } from "./session-timeouts.js";
+import { museIdleMinutes, museStallMetadata, runMuseDeveloperSession, sessionLogActivityMs, writeMuseNormalizedLog, } from "./muse-spawn.js";
 const MODEL = "muse-spark-1.3-contributor";
 // ── MUSE_IDLE_TIMEOUT_MS parsing ─────────────────────────────────────────────
 function withIdleEnv(raw, fn) {
-    const prev = process.env.MUSE_IDLE_TIMEOUT_MS;
+    withEnv("MUSE_IDLE_TIMEOUT_MS", raw, fn);
+}
+function withEnv(name, raw, fn) {
+    const prev = process.env[name];
     try {
         if (raw === undefined)
-            delete process.env.MUSE_IDLE_TIMEOUT_MS;
+            delete process.env[name];
         else
-            process.env.MUSE_IDLE_TIMEOUT_MS = raw;
+            process.env[name] = raw;
         fn();
     }
     finally {
         if (prev === undefined)
-            delete process.env.MUSE_IDLE_TIMEOUT_MS;
+            delete process.env[name];
         else
-            process.env.MUSE_IDLE_TIMEOUT_MS = prev;
+            process.env[name] = prev;
     }
 }
 test("museIdleTimeoutMs defaults to 30 minutes when unset or blank", () => {
@@ -97,19 +103,21 @@ test("museIdleMinutes measures silence from last activity, else the bound", () =
     assert.equal(museIdleMinutes({ lastActivityAt: null, idleTimeoutMs: undefined }), null, "disabled watchdog has no idle kill to explain");
 });
 // ── stall metadata object ────────────────────────────────────────────────────
-test("museStallMetadata carries exactly the five worker_sessions fields", () => {
+test("museStallMetadata carries stall-evidence fields including lingeredAfterTerminal", () => {
     assert.deepEqual(museStallMetadata({
         lastActivityAt: "2026-10-01T19:00:00.000Z",
         toolCallCount: 24,
         lastToolName: "npm_test",
         firstOutputMs: 1234,
         idleTimedOut: true,
+        lingeredAfterTerminal: false,
     }), {
         lastActivityAt: "2026-10-01T19:00:00.000Z",
         toolCallCount: 24,
         lastToolName: "npm_test",
         firstOutputMs: 1234,
         idleTimedOut: true,
+        lingeredAfterTerminal: false,
     });
 });
 // ── arrival-stamped normalized events ────────────────────────────────────────
@@ -185,6 +193,7 @@ test("the written ndjson carries ts on every event and durationMs on completed t
         firstOutputMs: 900,
         lastActivityAt: new Date(t0 + 63_000).toISOString(),
         idleTimedOut: false,
+        lingeredAfterTerminal: false,
         toolCallCount: r.tools.length,
         lastToolName: "npm_test",
     };
@@ -206,5 +215,152 @@ test("the written ndjson carries ts on every event and durationMs on completed t
     assert.equal(muse.toolCallCount, 2);
     assert.equal(muse.lastToolName, "npm_test");
     assert.equal(muse.idleTimedOut, false);
+    assert.equal(muse.lingeredAfterTerminal, false);
     assert.equal(muse.lastActivityAt, new Date(t0 + 63_000).toISOString());
 });
+// ── MUSE_TERMINAL_GRACE_MS parsing ───────────────────────────────────────────
+test("museTerminalGraceMs defaults to 30 seconds when unset or blank", () => {
+    withEnv("MUSE_TERMINAL_GRACE_MS", undefined, () => assert.equal(museTerminalGraceMs(), DEFAULT_MUSE_TERMINAL_GRACE_MS));
+    withEnv("MUSE_TERMINAL_GRACE_MS", "", () => assert.equal(museTerminalGraceMs(), DEFAULT_MUSE_TERMINAL_GRACE_MS));
+    withEnv("MUSE_TERMINAL_GRACE_MS", "   ", () => assert.equal(museTerminalGraceMs(), DEFAULT_MUSE_TERMINAL_GRACE_MS));
+    assert.equal(DEFAULT_MUSE_TERMINAL_GRACE_MS, 30_000);
+});
+test("MUSE_TERMINAL_GRACE_MS=0 disables the post-terminal kill", () => {
+    withEnv("MUSE_TERMINAL_GRACE_MS", "0", () => assert.equal(museTerminalGraceMs(), undefined));
+});
+test("isMuseTerminalStdoutLine matches completed and failed envelopes only", () => {
+    assert.equal(isMuseTerminalStdoutLine(JSON.stringify({ payload_type: "run.terminal.failed", payload: { terminal: "failed", reason: "x" } })), true);
+    assert.equal(isMuseTerminalStdoutLine(JSON.stringify({ payload_type: "run.terminal.completed", payload: {} })), true);
+    assert.equal(isMuseTerminalStdoutLine(JSON.stringify({ payload_type: "tool.result", payload: {} })), false);
+    assert.equal(isMuseTerminalStdoutLine("not json"), false);
+});
+// ── NOT-342: linger after terminal, through the Muse spawn ───────────────────
+const FAKE_MUSE = path.join(path.dirname(fileURLToPath(import.meta.url)), "fixtures", "fake-muse.mjs");
+const LINGER_HOME = fs.mkdtempSync(path.join(os.homedir(), ".dealer-muse-linger-"));
+after(() => {
+    fs.rmSync(LINGER_HOME, { recursive: true, force: true });
+});
+function lingerScratchWorktree() {
+    const wt = fs.mkdtempSync(path.join(LINGER_HOME, "wt-"));
+    execFileSync("git", ["init", "-q", "-b", "main"], { cwd: wt });
+    execFileSync("git", ["config", "user.email", "t@example.com"], { cwd: wt });
+    execFileSync("git", ["config", "user.name", "T"], { cwd: wt });
+    fs.writeFileSync(path.join(wt, "a.txt"), "a\n");
+    execFileSync("git", ["add", "."], { cwd: wt });
+    execFileSync("git", ["-c", "user.email=t@example.com", "-c", "user.name=T", "commit", "-q", "-m", "init"], {
+        cwd: wt,
+    });
+    return wt;
+}
+async function runLingeringMuse(opts) {
+    const keys = [
+        "MUSE_CLI",
+        "FAKE_MUSE_SCENARIO",
+        "META_API_KEY",
+        "AGENT_DEALER_HOME",
+        "MUSE_TERMINAL_GRACE_MS",
+        "MUSE_IDLE_TIMEOUT_MS",
+    ];
+    const prev = Object.fromEntries(keys.map((k) => [k, process.env[k]]));
+    const wt = lingerScratchWorktree();
+    const dealerHome = fs.mkdtempSync(path.join(LINGER_HOME, "home-"));
+    const startedAt = Date.now();
+    try {
+        process.env.MUSE_CLI = FAKE_MUSE;
+        process.env.FAKE_MUSE_SCENARIO = opts.scenario;
+        process.env.META_API_KEY = "mk-test-linger-key";
+        process.env.AGENT_DEALER_HOME = dealerHome;
+        process.env.MUSE_TERMINAL_GRACE_MS = opts.graceMs;
+        process.env.MUSE_IDLE_TIMEOUT_MS = "0";
+        const result = await runMuseDeveloperSession({
+            sessionId: opts.sessionId,
+            runtime: "muse_code",
+            policy: { worktreeWrite: true },
+            model: MUSE_CODE_CONTRIBUTOR_MODEL,
+            deckId: "00000000-0000-4000-a000-000000000099",
+            agentDeckUrl: "http://127.0.0.1:1110/mcp",
+            prompt: "Implement it",
+            cwd: wt,
+            timeoutMs: opts.timeoutMs,
+            logPath: path.join(dealerHome, `muse-${opts.sessionId}.ndjson`),
+        });
+        return {
+            timedOut: result.timedOut,
+            // Assert top-level and muse summary separately — a regression that drops
+            // either field must fail (do not coalesce with ??).
+            lingeredAfterTerminal: result.lingeredAfterTerminal,
+            museLingeredAfterTerminal: result.muse?.lingeredAfterTerminal,
+            failureMessage: result.muse?.failure?.message ?? null,
+            failureKind: result.muse?.failure?.kind ?? null,
+            elapsedMs: Date.now() - startedAt,
+            logPath: result.logPath,
+        };
+    }
+    finally {
+        for (const k of keys) {
+            if (prev[k] === undefined)
+                delete process.env[k];
+            else
+                process.env[k] = prev[k];
+        }
+        fs.rmSync(wt, { recursive: true, force: true });
+        fs.rmSync(dealerHome, { recursive: true, force: true });
+    }
+}
+test("a Muse transport-error that lingers is recorded as a failure, not a timeout", { timeout: 15_000 }, async () => {
+    const out = await runLingeringMuse({
+        scenario: "transport-linger",
+        graceMs: "200",
+        timeoutMs: 20_000,
+        sessionId: "00000000-0000-4000-8000-000000000342",
+    });
+    assert.ok(out.elapsedMs < 5_000, `settled on the grace, took ${out.elapsedMs}ms`);
+    assert.equal(out.timedOut, false);
+    assert.equal(out.lingeredAfterTerminal, true);
+    assert.equal(out.museLingeredAfterTerminal, true);
+    assert.match(out.failureMessage ?? "", /transport error/);
+});
+test("a completed Muse run that lingers is still a completion, not a timeout", { timeout: 15_000 }, async () => {
+    const out = await runLingeringMuse({
+        scenario: "completed-linger",
+        graceMs: "200",
+        timeoutMs: 20_000,
+        sessionId: "00000000-0000-4000-8000-000000000344",
+    });
+    assert.equal(out.timedOut, false);
+    assert.equal(out.lingeredAfterTerminal, true);
+    assert.equal(out.museLingeredAfterTerminal, true);
+    assert.equal(out.failureMessage, null);
+});
+test("MUSE_TERMINAL_GRACE_MS=0 leaves a lingering Muse child to the wall clock", { timeout: 15_000 }, async () => {
+    const out = await runLingeringMuse({
+        scenario: "transport-linger",
+        graceMs: "0",
+        timeoutMs: 500,
+        sessionId: "00000000-0000-4000-8000-000000000343",
+    });
+    assert.equal(out.lingeredAfterTerminal, false);
+    assert.equal(out.museLingeredAfterTerminal, false);
+    assert.equal(out.timedOut, true, "without the grace, the wall clock still kills");
+});
+// NOT-342 repair: a cron run's terminal must not arm the 30s grace and SIGTERM the
+// still-working primary. The child has no primary terminal — only the wall clock kills.
+test("a cron terminal before the primary does not arm terminal grace", { timeout: 15_000 }, async () => {
+    const out = await runLingeringMuse({
+        scenario: "cron-terminal-then-primary-linger",
+        graceMs: "200",
+        timeoutMs: 800,
+        sessionId: "00000000-0000-4000-8000-000000000345",
+    });
+    assert.equal(out.lingeredAfterTerminal, false, "cron terminal must not linger-kill");
+    assert.equal(out.museLingeredAfterTerminal, false);
+    assert.equal(out.timedOut, true, "wall clock still owns the kill when primary never terminals");
+    assert.notEqual(out.failureKind, "malformed_stream");
+});
+test("createMusePrimaryTerminalMatcher is what Muse wires for terminalGrace", () => {
+    // Sanity: the factory exists and matches the shape spawnCli expects.
+    const m = createMusePrimaryTerminalMatcher();
+    assert.equal(typeof m.isTerminalLine, "function");
+    assert.equal(typeof m.sawPrimaryTerminal, "function");
+    assert.equal(m.sawPrimaryTerminal(), false);
+});

package/bundle/server/dist/coordinator/routing.js

@@ -176,6 +176,16 @@ export function routeDeveloperOutcome(outcome, limits) {
             // session ended cleanly with a pushed branch and an open PR. Wait on backoff
             // and re-poll; the deferral path (not this route) enforces the wait ceiling.
             return { next: "defer_work", reason: outcome.reason };
+        case "checks_conflicting":
+            // NOT-354: applyCompletion handles this before routing (it needs the lease to
+            // queue the repair round). Reaching here is a bug — fail safe to a human.
+            return {
+                next: "human_action",
+                actionType: "policy_escalation",
+                reason: outcome.sync.result === "escalate"
+                    ? outcome.sync.reason
+                    : `PR #${outcome.prNumber} conflicts with ${outcome.baseBranch}; CI cannot start.`,
+            };
     }
 }
 function infraFailureReason(outcome) {

package/bundle/server/dist/coordinator/session-timeouts.js

@@ -35,6 +35,28 @@ export function museIdleTimeoutMs() {
     }
     return parsed;
 }
+/**
+ * NOT-342: how long Muse may linger after a `run.terminal` envelope before Dealer
+ * SIGTERMs it. Ships ENABLED at 30 seconds: long enough for a clean self-exit,
+ * short enough that a provider `transport error` is not held until the 1-hour
+ * wall (and then recorded as `timed_out`). `0` disables. A non-numeric or
+ * negative value falls back to the default with a logged warning, matching
+ * `museIdleTimeoutMs`.
+ */
+export const DEFAULT_MUSE_TERMINAL_GRACE_MS = 30_000;
+export function museTerminalGraceMs() {
+    const raw = process.env.MUSE_TERMINAL_GRACE_MS;
+    if (raw === undefined || raw.trim() === "")
+        return DEFAULT_MUSE_TERMINAL_GRACE_MS;
+    const parsed = Number(raw);
+    if (Number.isFinite(parsed) && parsed === 0)
+        return undefined;
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        console.warn(`[dealer] ignoring invalid MUSE_TERMINAL_GRACE_MS=${JSON.stringify(raw)} — using default ${DEFAULT_MUSE_TERMINAL_GRACE_MS}`);
+        return DEFAULT_MUSE_TERMINAL_GRACE_MS;
+    }
+    return parsed;
+}
 export function sessionTimeoutMsFor(role) {
     return role === "reviewer" ? reviewerSessionTimeoutMs() : developerSessionTimeoutMs();
 }

package/bundle/server/dist/runners/muse-code-jsonl.js

@@ -22,6 +22,25 @@ function num(v) {
 function cap(s) {
     return s.length > ERROR_TEXT_MAX ? `${s.slice(0, ERROR_TEXT_MAX)}…` : s;
 }
+/**
+ * NOT-342: true when a stdout line is a Muse `run.terminal.completed` or
+ * `run.terminal.failed` envelope (any run). Prefer
+ * {@link createMusePrimaryTerminalMatcher} for `spawnCli` terminal grace — a
+ * cron run's terminal must not arm the kill. Garbage lines are not terminal
+ * (never throw).
+ */
+export function isMuseTerminalStdoutLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("{"))
+        return false;
+    try {
+        const env = JSON.parse(trimmed);
+        return env.payload_type === "run.terminal.completed" || env.payload_type === "run.terminal.failed";
+    }
+    catch {
+        return false;
+    }
+}
 function firstLine(s) {
     return s.trim().split("\n")[0] ?? "";
 }
@@ -143,6 +162,48 @@ function runIdOf(payload) {
     const rs = asRecord(payload.run_stream);
     return rs?.kind === "run" ? str(rs.id) : undefined;
 }
+/**
+ * NOT-342: stateful predicate for Muse `terminalGrace`. Tracks the first-seen
+ * run id with the same rule as {@link parseMuseRun}, and returns true only when
+ * that primary run's terminal envelope arrives. A cron (or other secondary) run
+ * completing first must not start the grace — otherwise Dealer SIGTERMs the
+ * still-working primary and the session is mis-recorded as `malformed_stream`.
+ */
+export function createMusePrimaryTerminalMatcher() {
+    let primaryRunId = null;
+    let sawPrimary = false;
+    return {
+        sawPrimaryTerminal: () => sawPrimary,
+        isTerminalLine(line) {
+            const trimmed = line.trim();
+            if (!trimmed.startsWith("{"))
+                return false;
+            let parsed;
+            try {
+                parsed = JSON.parse(trimmed);
+            }
+            catch {
+                return false;
+            }
+            const env = toEnvelope(parsed);
+            if (!env)
+                return false;
+            const runId = runIdOf(env.payload);
+            // Same first-run-id rule as parseMuseRun: the first envelope that names a
+            // run wins; envelopes with no run id leave primary unset (any later terminal
+            // with no correlating id is accepted, matching parseMuseRun).
+            if (primaryRunId === null)
+                primaryRunId = runId ?? null;
+            if (env.payloadType !== "run.terminal.completed" && env.payloadType !== "run.terminal.failed") {
+                return false;
+            }
+            if (primaryRunId !== null && runId !== primaryRunId)
+                return false;
+            sawPrimary = true;
+            return true;
+        },
+    };
+}
 function hasRateLimitFacet(payload) {
     const details = asRecord(asRecord(payload.event)?.details);
     const facets = details?.facets;

package/bundle/server/dist/runners/muse-code.test.js

@@ -4,7 +4,7 @@ import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { buildMuseDeveloperInvocation } from "./muse-code-args.js";
-import { parseMuseRun } from "./muse-code-jsonl.js";
+import { parseMuseRun, createMusePrimaryTerminalMatcher } from "./muse-code-jsonl.js";
 import { extractResultText, extractSessionId, extractUsage } from "./stream-json.js";
 // NOT-179: developer argv + JSONL parser, table-driven over the sanitized NOT-177 fixtures.
 const DIR = join(dirname(fileURLToPath(import.meta.url)), "fixtures", "muse-code");
@@ -157,6 +157,18 @@ test("terminals are selected by the primary run id, not by arrival order", () =>
     assert.equal(r.usage.modelDurationMs, 3);
     assert.equal(r.failure, null);
 });
+// NOT-342: terminalGrace must follow the same primary-run rule — a cron terminal
+// arriving first must not arm the kill while the primary is still working.
+test("createMusePrimaryTerminalMatcher ignores a cron terminal before the primary's", () => {
+    const matcher = createMusePrimaryTerminalMatcher();
+    const lines = interleavedStdout.split("\n");
+    assert.equal(matcher.isTerminalLine(lines[0]), false, "primary linked");
+    assert.equal(matcher.isTerminalLine(lines[1]), false, "cron linked");
+    assert.equal(matcher.isTerminalLine(lines[2]), false, "cron terminal must not arm grace");
+    assert.equal(matcher.sawPrimaryTerminal(), false);
+    assert.equal(matcher.isTerminalLine(lines[3]), true, "primary terminal arms grace");
+    assert.equal(matcher.sawPrimaryTerminal(), true);
+});
 test("a cron run's model_completed cannot confirm the primary run's model", () => {
     const log = modelCompletedLine("cron", { usage: { input_tokens: 1 } });
     const r = parseMuseRun({ stdout: interleavedStdout, exitCode: 0, sessionLog: log, expectedModel: MODEL });

package/bundle/server/dist/runners/spawn-cli.js

@@ -54,6 +54,7 @@ export async function spawnCli(runId, cmd, args, cwd, opts) {
             const stderrChunks = [];
             let timedOut = false;
             let settled = false;
+            let lingeredAfterTerminal = false;
             let killEscalation;
             // NOT-307: idle watchdog state. lastActivityMs starts at spawn so a child that
             // never emits anything is killed after exactly idleTimeoutMs. stdout bytes always
@@ -67,6 +68,14 @@ export async function spawnCli(runId, cmd, args, cwd, opts) {
             const idleEnabled = typeof idleMs === "number" && Number.isFinite(idleMs) && idleMs > 0;
             let idleTimer;
             let progressTimer;
+            let terminalGraceTimer;
+            let lingerSettleTimer;
+            let terminalGraceArmed = false;
+            const terminalGraceMs = opts.terminalGrace?.graceMs;
+            const terminalGraceEnabled = typeof terminalGraceMs === "number" &&
+                Number.isFinite(terminalGraceMs) &&
+                terminalGraceMs > 0 &&
+                typeof opts.terminalGrace?.isTerminalLine === "function";
             const clearIdle = () => {
                 if (idleTimer)
                     clearTimeout(idleTimer);
@@ -75,8 +84,16 @@ export async function spawnCli(runId, cmd, args, cwd, opts) {
                 idleTimer = undefined;
                 progressTimer = undefined;
             };
+            const clearTerminalGrace = () => {
+                if (terminalGraceTimer)
+                    clearTimeout(terminalGraceTimer);
+                terminalGraceTimer = undefined;
+                if (lingerSettleTimer)
+                    clearTimeout(lingerSettleTimer);
+                lingerSettleTimer = undefined;
+            };
             const rescheduleIdle = () => {
-                if (!idleEnabled || settled || aborted)
+                if (!idleEnabled || settled || aborted || lingeredAfterTerminal)
                     return;
                 if (idleTimer)
                     clearTimeout(idleTimer);
@@ -99,13 +116,69 @@ export async function spawnCli(runId, cmd, args, cwd, opts) {
             // later) so salvage and infra-retry accounting treat an idle kill as a timeout.
             // Never fires after an abort: a lost lease is not idleness.
             function fireIdle() {
-                if (settled || aborted)
+                if (settled || aborted || lingeredAfterTerminal)
                     return;
                 idleTimedOut = true;
                 timedOut = true;
                 killRunProcess(runId);
                 setTimeout(() => finish(124), 500);
             }
+            // Same polite SIGTERM → SIGKILL backstop the abort path uses: the CLI should
+            // reap its own children on SIGTERM. Does not settle the promise — `close` does.
+            const requestKill = () => {
+                try {
+                    child.kill("SIGTERM");
+                }
+                catch {
+                    // Already exited between the decision and this kill — nothing to signal.
+                }
+                if (killEscalation)
+                    clearTimeout(killEscalation);
+                killEscalation = setTimeout(() => {
+                    try {
+                        child.kill("SIGKILL");
+                    }
+                    catch {
+                        // Same race as above; the 'close' handler still settles the promise.
+                    }
+                }, abortKillGraceMs());
+                killEscalation.unref?.();
+            };
+            function fireTerminalGrace() {
+                if (settled || aborted)
+                    return;
+                lingeredAfterTerminal = true;
+                clearIdle();
+                requestKill();
+                // If a grandchild holds the stdout pipe open after SIGKILL, Node never
+                // emits 'close' — settle as lingered so the spawn slot and lease cannot
+                // leak until the wall clock. Close still wins when it arrives first.
+                if (lingerSettleTimer)
+                    clearTimeout(lingerSettleTimer);
+                lingerSettleTimer = setTimeout(() => {
+                    if (settled || aborted)
+                        return;
+                    finish(1);
+                }, abortKillGraceMs() + 500);
+                lingerSettleTimer.unref?.();
+            }
+            const maybeArmTerminalGrace = (line) => {
+                if (!terminalGraceEnabled || settled || aborted || terminalGraceArmed)
+                    return;
+                let match = false;
+                try {
+                    match = opts.terminalGrace.isTerminalLine(line) === true;
+                }
+                catch (err) {
+                    console.error(`[spawn-cli] terminalGrace.isTerminalLine for ${runId}`, err);
+                    return;
+                }
+                if (!match)
+                    return;
+                terminalGraceArmed = true;
+                terminalGraceTimer = setTimeout(fireTerminalGrace, terminalGraceMs);
+                terminalGraceTimer.unref?.();
+            };
             const logStream = fs.createWriteStream(opts.logPath, { flags: "w" });
             // A WriteStream's 'error' event has no default handler — left unguarded, any
             // stream error (a write after end, ENOSPC, a permissions problem) is an uncaught
@@ -155,21 +228,8 @@ export async function spawnCli(runId, cmd, args, cwd, opts) {
                     return;
                 aborted = true;
                 clearIdle();
-                try {
-                    child.kill("SIGTERM");
-                }
-                catch {
-                    // Already exited between the abort firing and this kill — nothing to signal.
-                }
-                killEscalation = setTimeout(() => {
-                    try {
-                        child.kill("SIGKILL");
-                    }
-                    catch {
-                        // Same race as above; the 'close' handler still settles the promise.
-                    }
-                }, abortKillGraceMs());
-                killEscalation.unref?.();
+                clearTerminalGrace();
+                requestKill();
             };
             // Not cleared on settle alone — `cleanupAbort` also drops the listener, so a
             // long-lived signal (one AbortController per work item, reused across the
@@ -211,6 +271,7 @@ export async function spawnCli(runId, cmd, args, cwd, opts) {
                 }
                 clearTimeout(timer);
                 clearIdle();
+                clearTerminalGrace();
                 cleanupAbort();
                 unregisterChild(runId);
                 // Write any stderr BEFORE ending the stream — writing after end() throws
@@ -238,6 +299,7 @@ export async function spawnCli(runId, cmd, args, cwd, opts) {
                         transcript: stdoutChunks.join(""),
                         timedOut,
                         idleTimedOut,
+                        lingeredAfterTerminal,
                         firstOutputMs,
                         lastActivityAt: new Date(lastActivityMs).toISOString(),
                         idleForMs: idleTimedOut ? Math.max(0, Date.now() - lastActivityMs) : null,
@@ -269,6 +331,14 @@ export async function spawnCli(runId, cmd, args, cwd, opts) {
                 }
             };
             const timer = setTimeout(() => {
+                if (settled)
+                    return;
+                // A terminal-grace kill already requested: settle as lingered (not timedOut)
+                // if 'close' still has not arrived — same backstop role as lingerSettleTimer.
+                if (lingeredAfterTerminal) {
+                    finish(1);
+                    return;
+                }
                 timedOut = true;
                 killRunProcess(runId);
                 setTimeout(() => finish(124), 500);
@@ -283,7 +353,7 @@ export async function spawnCli(runId, cmd, args, cwd, opts) {
                     // that the kill lands near the bound, sparse enough to never matter for I/O.
                     const pollMs = Math.min(Math.max(Math.floor(idleMs / 10), 50), 30_000);
                     progressTimer = setInterval(() => {
-                        if (settled || aborted)
+                        if (settled || aborted || lingeredAfterTerminal)
                             return;
                         let at = null;
                         try {
@@ -306,12 +376,14 @@ export async function spawnCli(runId, cmd, args, cwd, opts) {
                 // NOT-307: any stdout bytes are progress. (stderr deliberately does not count:
                 // the contract defines progress as stdout bytes or the external source.)
                 noteActivity();
-                if (opts.onStdoutLine) {
+                if (opts.onStdoutLine || terminalGraceEnabled) {
                     lineTail += chunk;
                     let idx;
                     while ((idx = lineTail.indexOf("\n")) >= 0) {
-                        emitLine(lineTail.slice(0, idx));
+                        const line = lineTail.slice(0, idx);
                         lineTail = lineTail.slice(idx + 1);
+                        emitLine(line);
+                        maybeArmTerminalGrace(line);
                     }
                 }
             });
@@ -324,6 +396,7 @@ export async function spawnCli(runId, cmd, args, cwd, opts) {
                 settled = true;
                 clearTimeout(timer);
                 clearIdle();
+                clearTerminalGrace();
                 cleanupAbort();
                 unregisterChild(runId);
                 logStream.end();

package/bundle/server/dist/runners/spawn-cli.test.js

@@ -339,4 +339,42 @@ test("spawnCli without idleTimeoutMs times out on the wall clock with idleTimedO
     });
     assert.equal(result.timedOut, true);
     assert.equal(result.idleTimedOut, false);
+    assert.equal(result.lingeredAfterTerminal, false);
+});
+const terminalFailedLine = JSON.stringify({
+    payload_type: "run.terminal.failed",
+    payload: { terminal: "failed", reason: "transport error [net-timeout]: timed out waiting for response data (meta stream)" },
+});
+const isTerminalLine = (line) => line.includes("run.terminal.failed") || line.includes("run.terminal.completed");
+// NOT-342: a child that has already printed its terminal envelope but does not exit
+// is SIGTERM'd after the grace — well before the wall clock — and is not a timeout.
+test("spawnCli kills a lingering child after terminalGrace without timing out", { timeout: 10_000 }, async () => {
+    const logPath = path.join(fs.mkdtempSync(path.join(os.tmpdir(), "dealer-spawn-cli-")), "out.ndjson");
+    const { cmd, args } = nodeChild(`console.log(${JSON.stringify(terminalFailedLine)}); setInterval(() => {}, 1000);`);
+    const startedAt = Date.now();
+    const result = await spawnCli("test-run-terminal-linger", cmd, args, process.cwd(), {
+        logPath,
+        timeoutMs: 30_000,
+        terminalGrace: { isTerminalLine, graceMs: 200 },
+    });
+    const elapsed = Date.now() - startedAt;
+    assert.ok(elapsed < 5_000, `settled on the grace, not the wall clock, took ${elapsed}ms`);
+    assert.equal(result.lingeredAfterTerminal, true);
+    assert.equal(result.timedOut, false);
+    assert.equal(result.idleTimedOut, false);
+    assert.match(result.transcript, /transport error/);
+});
+// NOT-342: exiting on its own inside the grace is the child's own close — no linger kill.
+test("spawnCli does not linger-kill a child that exits inside the terminal grace", async () => {
+    const logPath = path.join(fs.mkdtempSync(path.join(os.tmpdir(), "dealer-spawn-cli-")), "out.ndjson");
+    const { cmd, args } = nodeChild(`console.log(${JSON.stringify(terminalFailedLine)}); process.exit(0);`);
+    const result = await spawnCli("test-run-terminal-exits", cmd, args, process.cwd(), {
+        logPath,
+        timeoutMs: 10_000,
+        terminalGrace: { isTerminalLine, graceMs: 2_000 },
+    });
+    assert.equal(result.lingeredAfterTerminal, false);
+    assert.equal(result.timedOut, false);
+    assert.equal(result.idleTimedOut, false);
+    assert.equal(result.exitCode, 0);
 });

package/bundle/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-dealer/server",
-  "version": "1.2.9",
+  "version": "1.2.10",
   "type": "module",
   "main": "dist/index.js",
   "files": [
@@ -22,7 +22,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@agent-dealer/shared": "1.2.9",
+    "@agent-dealer/shared": "1.2.10",
     "@fastify/cors": "^11.0.1",
     "@fastify/static": "^8.2.0",
     "@modelcontextprotocol/sdk": "^1.29.0",

package/bundle/shared/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-dealer/shared",
-  "version": "1.2.9",
+  "version": "1.2.10",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-dealer",
-  "version": "1.2.9",
+  "version": "1.2.10",
   "description": "Human control plane for agent execution — queue, plan approval, audit",
   "license": "MIT",
   "type": "module",