agent-dealer 0.2.0 → 1.0.0

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

@@ -0,0 +1,351 @@
+// packages/server/src/coordinator/session-progress.ts
+//
+// NOT-109: low-volume mid-session milestones + live intent updates so Issue Detail answers
+// "what happened last?" while a developer/reviewer is running. Timeline events are
+// milestones only — never per-tool-call. During a long agent spawn, a log sampler may
+// refresh `currentIntent` without appending events.
+//
+// NOT-120: deriveLiveProgressFromLog parses the session NDJSON tail into a concrete
+// operator-facing line (assistant sentence and/or tool activity) for the live strip.
+import fs from "node:fs";
+import path from "node:path";
+import { getIssue, transitionIssue } from "../repository/issues.js";
+import { appendWorkflowEvent } from "../repository/workflow-events.js";
+import { parseNdjson } from "../runners/stream-json.js";
+const ROLE_LABEL = {
+    developer: "Developer",
+    reviewer: "Reviewer",
+};
+const LIVE_STATUSES = new Set(["developing", "reviewing", "repairing"]);
+/** Max chars for the strip primary line (one readable line). */
+export const LIVE_PROGRESS_MAX_CHARS = 120;
+/** Ignore Cursor token-stream crumbs and other tiny fragments. */
+const MIN_ASSISTANT_CHARS = 28;
+const ACTIVITY_RULES = [
+    { match: /lens|bugbot|security-review/i, label: "Lens check" },
+    { match: /pytest|npm test|vitest|jest|node --test|flow:verify|typecheck/i, label: "running tests" },
+    { match: /git commit|gh pr|commit/i, label: "committing" },
+    { match: /write|stredit|applypatch|editnotebook|search_replace/i, label: "editing" },
+    { match: /shell|bash|terminal/i, label: "running commands" },
+    { match: /call_service_tool|get_issue|linear/i, label: "fetching ticket brief" },
+    { match: /bind_workspace|get_bound_deck|get_playbook/i, label: "deck bind" },
+    { match: /read|grep|glob|semanticsearch/i, label: "exploring code" },
+];
+/** Short worktree path for timeline payloads — last two path segments when present. */
+export function shortWorktreePath(worktreePath) {
+    if (!worktreePath)
+        return null;
+    const parts = worktreePath.split(/[/\\]/).filter(Boolean);
+    if (parts.length <= 2)
+        return worktreePath;
+    return parts.slice(-2).join("/");
+}
+export function workerSessionPayload(input) {
+    return {
+        runtime: input.runtime ?? null,
+        model: input.model ?? null,
+        sessionId: input.sessionId,
+        ...(input.worktreePath !== undefined
+            ? { worktreePath: shortWorktreePath(input.worktreePath) }
+            : {}),
+    };
+}
+/** Updates currentIntent in place (status self-loop) while a session is live. */
+export function setLiveIntent(issueId, intent) {
+    const issue = getIssue(issueId);
+    if (!issue || !LIVE_STATUSES.has(issue.status))
+        return;
+    if (issue.currentIntent === intent)
+        return;
+    transitionIssue(issueId, issue.status, { currentIntent: intent });
+}
+/**
+ * Append a milestone timeline event and refresh the issue's primary status line.
+ * Callers must keep volume low — setup / checks / push, not every tool use.
+ */
+export function emitSessionMilestone(input) {
+    appendWorkflowEvent({
+        issueId: input.issueId,
+        workflowInstanceId: input.workflowInstanceId,
+        workerSessionId: input.workerSessionId,
+        type: input.type,
+        actorType: input.role,
+        stage: input.stage,
+        round: input.round,
+        payload: input.payload,
+    });
+    setLiveIntent(input.issueId, input.intent);
+}
+function readLogTail(logPath, maxBytes = 64_000) {
+    if (!logPath || !fs.existsSync(logPath))
+        return null;
+    try {
+        const size = fs.statSync(logPath).size;
+        const start = Math.max(0, size - maxBytes);
+        const fd = fs.openSync(logPath, "r");
+        try {
+            const buf = Buffer.alloc(size - start);
+            fs.readSync(fd, buf, 0, buf.length, start);
+            return buf.toString("utf8");
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch {
+        return null;
+    }
+}
+function basenamePath(p) {
+    const base = path.basename(p.replace(/\\/g, "/"));
+    return base || p;
+}
+function truncateOneLine(text, maxChars = LIVE_PROGRESS_MAX_CHARS) {
+    const one = text.replace(/\s+/g, " ").trim();
+    if (one.length <= maxChars)
+        return one;
+    const cut = one.slice(0, Math.max(0, maxChars - 1)).trimEnd();
+    return `${cut}…`;
+}
+function assistantTextFromEvent(e) {
+    if (e.type !== "assistant")
+        return null;
+    const msg = e.message;
+    if (!msg?.content) {
+        if (typeof e.text === "string" && e.text.trim())
+            return e.text;
+        return null;
+    }
+    const text = msg.content
+        .filter((c) => c.type === "text" && typeof c.text === "string")
+        .map((c) => c.text ?? "")
+        .join("");
+    return text.length ? text : null;
+}
+/** Cursor nests tools as `{ readToolCall: { args } }` — no top-level name. */
+function cursorToolEntry(e) {
+    if (e.type !== "tool_call")
+        return null;
+    const nested = e.tool_call;
+    if (!nested || typeof nested !== "object" || Array.isArray(nested))
+        return null;
+    for (const [key, value] of Object.entries(nested)) {
+        if (!key.endsWith("ToolCall") || !value || typeof value !== "object")
+            continue;
+        const args = value.args;
+        return { key, args: args && typeof args === "object" ? args : {} };
+    }
+    return null;
+}
+function toolNameFromEvent(e) {
+    const cursor = cursorToolEntry(e);
+    if (cursor) {
+        // readToolCall → Read, shellToolCall → Shell, mcpToolCall → Mcp
+        const stem = cursor.key.replace(/ToolCall$/, "");
+        return stem.charAt(0).toUpperCase() + stem.slice(1);
+    }
+    if (e.type === "tool_call") {
+        const name = e.name ?? e.tool_name;
+        return typeof name === "string" ? name : null;
+    }
+    if (e.type === "assistant") {
+        const msg = e.message;
+        const tool = msg?.content?.find((c) => c.type === "tool_use" && c.name);
+        return tool?.name ?? null;
+    }
+    if (typeof e.tool_name === "string")
+        return e.tool_name;
+    if (typeof e.name === "string" && (e.type === "tool" || e.type === "function_call"))
+        return e.name;
+    return null;
+}
+function claudeToolInput(e) {
+    if (e.type === "assistant") {
+        const msg = e.message;
+        const tool = msg?.content?.find((c) => c.type === "tool_use");
+        if (tool?.input && typeof tool.input === "object")
+            return tool.input;
+    }
+    if (e.type === "tool_call" && e.input && typeof e.input === "object") {
+        return e.input;
+    }
+    return null;
+}
+function isTestCommand(command) {
+    return /pytest|npm test|npm run test|vitest|jest|node --test|flow:verify|typecheck|poc:integration/i.test(command);
+}
+/** Concrete, human-readable tool activity for the live strip. */
+export function formatToolProgress(e) {
+    const cursor = cursorToolEntry(e);
+    if (cursor) {
+        const { key, args } = cursor;
+        if (key === "readToolCall" && typeof args.path === "string") {
+            return `Reading ${basenamePath(args.path)}`;
+        }
+        if (key === "writeToolCall" || key === "editToolCall" || key === "applyPatchToolCall") {
+            const p = (typeof args.path === "string" && args.path) ||
+                (typeof args.file_path === "string" && args.file_path) ||
+                (typeof args.target_notebook === "string" && args.target_notebook) ||
+                null;
+            return p ? `Editing ${basenamePath(p)}` : "Editing files";
+        }
+        if (key === "shellToolCall" && typeof args.command === "string") {
+            const cmd = args.command.replace(/\s+/g, " ").trim();
+            if (isTestCommand(cmd))
+                return truncateOneLine(`Running tests: ${cmd}`);
+            return truncateOneLine(`Running: ${cmd}`);
+        }
+        if (key === "grepToolCall") {
+            const pattern = typeof args.pattern === "string" ? args.pattern : null;
+            return pattern ? truncateOneLine(`Searching: ${pattern}`) : "Searching code";
+        }
+        if (key === "globToolCall") {
+            const glob = (typeof args.globPattern === "string" && args.globPattern) ||
+                (typeof args.glob_pattern === "string" && args.glob_pattern) ||
+                (typeof args.glob === "string" && args.glob) ||
+                null;
+            return glob ? truncateOneLine(`Finding files: ${glob}`) : "Finding files";
+        }
+        if (key === "mcpToolCall" || key === "getMcpToolsToolCall") {
+            const name = (typeof args.toolName === "string" && args.toolName) ||
+                (typeof args.name === "string" && args.name) ||
+                (typeof args.tool_name === "string" && args.tool_name) ||
+                null;
+            return name ? truncateOneLine(`MCP: ${name}`) : "Calling MCP tool";
+        }
+        if (key === "updateTodosToolCall")
+            return "Updating todos";
+        const stem = key.replace(/ToolCall$/, "");
+        return `Using ${stem.charAt(0).toUpperCase()}${stem.slice(1)}`;
+    }
+    const name = toolNameFromEvent(e);
+    if (!name)
+        return null;
+    const input = claudeToolInput(e) ?? {};
+    const haystack = `${name} ${JSON.stringify(input).slice(0, 500)}`;
+    if (/^(Read|read_file)$/i.test(name) && typeof input.path === "string") {
+        return `Reading ${basenamePath(input.path)}`;
+    }
+    if (/^(Write|StrReplace|Edit|ApplyPatch|search_replace|EditNotebook)$/i.test(name)) {
+        const p = (typeof input.path === "string" && input.path) ||
+            (typeof input.file_path === "string" && input.file_path) ||
+            null;
+        return p ? `Editing ${basenamePath(p)}` : "Editing files";
+    }
+    if (/^(Shell|Bash|Terminal)$/i.test(name) && typeof input.command === "string") {
+        const cmd = input.command.replace(/\s+/g, " ").trim();
+        if (isTestCommand(cmd))
+            return truncateOneLine(`Running tests: ${cmd}`);
+        return truncateOneLine(`Running: ${cmd}`);
+    }
+    if (/^(Grep|rg)$/i.test(name) && typeof input.pattern === "string") {
+        return truncateOneLine(`Searching: ${input.pattern}`);
+    }
+    for (const rule of ACTIVITY_RULES) {
+        if (rule.match.test(haystack)) {
+            // Title-case the coarse label for the strip.
+            const label = rule.label.charAt(0).toUpperCase() + rule.label.slice(1);
+            return label;
+        }
+    }
+    return `Using ${name}`;
+}
+/**
+ * Derive a short operator-facing activity line from the latest tool-ish log events.
+ * Returns null when the log has nothing actionable yet.
+ */
+export function deriveActivityFromLog(logPath) {
+    const progress = deriveLiveProgressFromLog(logPath);
+    if (!progress)
+        return null;
+    // Keep sampler labels short when mapping into currentIntent.
+    return progress;
+}
+/**
+ * Parse the session log tail into a concrete live-progress line for the issue strip.
+ * Prefers a meaningful coalesced assistant sentence when present after the latest tool;
+ * otherwise the latest tool activity. Ignores tiny token-stream fragments.
+ */
+export function deriveLiveProgressFromLog(logPath, maxChars = LIVE_PROGRESS_MAX_CHARS) {
+    const raw = readLogTail(logPath);
+    if (!raw)
+        return null;
+    const events = parseNdjson(raw);
+    if (!events.length)
+        return null;
+    let lastTool = null;
+    let lastToolIsStarted = false;
+    const trailingAssistant = [];
+    let collectingAssistant = true;
+    for (let i = events.length - 1; i >= 0; i--) {
+        const e = events[i];
+        const assistant = assistantTextFromEvent(e);
+        if (assistant !== null) {
+            if (collectingAssistant)
+                trailingAssistant.unshift(assistant);
+            continue;
+        }
+        // Stop coalescing assistant tokens once we hit a non-assistant event.
+        collectingAssistant = false;
+        if (e.type === "tool_call" || toolNameFromEvent(e)) {
+            // Prefer "started" over "completed" for "what is happening now".
+            const subtype = typeof e.subtype === "string" ? e.subtype : "";
+            if (subtype === "completed" && lastTool)
+                continue;
+            const label = formatToolProgress(e);
+            if (!label)
+                continue;
+            if (!lastTool || (subtype === "started" && !lastToolIsStarted)) {
+                lastTool = label;
+                lastToolIsStarted = subtype === "started" || subtype === "";
+            }
+            // Keep scanning for a started call if we only have completed so far.
+            if (lastToolIsStarted)
+                break;
+            continue;
+        }
+        if (lastTool || trailingAssistant.length)
+            break;
+    }
+    const coalesced = trailingAssistant.join("").replace(/\s+/g, " ").trim();
+    if (coalesced.length >= MIN_ASSISTANT_CHARS) {
+        return truncateOneLine(coalesced, maxChars);
+    }
+    if (lastTool)
+        return truncateOneLine(lastTool, maxChars);
+    // No trailing assistant / recent tool — scan the tail for any earlier tool activity.
+    for (let i = events.length - 1; i >= 0; i--) {
+        const label = formatToolProgress(events[i]);
+        if (label)
+            return truncateOneLine(label, maxChars);
+    }
+    return null;
+}
+/**
+ * While an agent CLI is running, periodically refresh currentIntent from the session log
+ * without flooding the timeline. No-ops when the log has no new activity label.
+ */
+export function startActivitySampler(opts) {
+    const prefix = `${ROLE_LABEL[opts.role]} ·`;
+    let lastLabel = null;
+    const tick = () => {
+        const activity = deriveLiveProgressFromLog(opts.logPath);
+        if (!activity || activity === lastLabel)
+            return;
+        lastLabel = activity;
+        setLiveIntent(opts.issueId, `${prefix} ${activity} (round ${opts.round})`);
+    };
+    const handle = setInterval(tick, opts.intervalMs ?? 10_000);
+    // First sample soon so the strip moves off "session running" once tools appear.
+    const first = setTimeout(tick, 2_000);
+    return {
+        stop() {
+            clearInterval(handle);
+            clearTimeout(first);
+        },
+    };
+}
+/** Task/AC are "complete enough" that the agent need not fetch Linear for the brief. */
+export function taskBriefIsComplete(task) {
+    return Boolean(task.description?.trim() && task.acceptanceCriteria?.trim());
+}

package/bundle/server/dist/coordinator/session-progress.test.js

@@ -0,0 +1,190 @@
+// packages/server/src/coordinator/session-progress.test.ts
+import { test, before } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+process.env.AGENT_DEALER_HOME = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-progress-"));
+const { migrate } = await import("../db/index.js");
+const { BUILTIN_AGENT_CLAUDE_ID, BUILTIN_AGENT_CURSOR_ID } = await import("@agent-dealer/shared");
+const { createIssue, getIssue, transitionIssue } = await import("../repository/issues.js");
+const { startWorkflowInstance, listWorkflowEventsForIssue } = await import("../repository/workflow-events.js");
+const { createWorkerSession, startSession } = await import("../repository/worker-sessions.js");
+const { deriveActivityFromLog, deriveLiveProgressFromLog, emitSessionMilestone, shortWorktreePath, taskBriefIsComplete, workerSessionPayload } = await import("./session-progress.js");
+function writeLog(lines) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-progress-log-"));
+    const logPath = path.join(dir, "session.ndjson");
+    fs.writeFileSync(logPath, lines.map((l) => JSON.stringify(l)).join("\n") + "\n");
+    return logPath;
+}
+before(() => migrate());
+test("shortWorktreePath keeps the last two segments", () => {
+    assert.equal(shortWorktreePath("/Users/me/.agent-dealer/worktrees/abc-developer"), "worktrees/abc-developer");
+    assert.equal(shortWorktreePath(null), null);
+});
+test("taskBriefIsComplete requires both description and acceptance criteria", () => {
+    assert.equal(taskBriefIsComplete({ description: "do it", acceptanceCriteria: "done" }), true);
+    assert.equal(taskBriefIsComplete({ description: "do it", acceptanceCriteria: "  " }), false);
+    assert.equal(taskBriefIsComplete({ description: "", acceptanceCriteria: "done" }), false);
+});
+test("workerSessionPayload includes runtime/model/session id", () => {
+    assert.deepEqual(workerSessionPayload({
+        runtime: "cursor_local",
+        model: "composer",
+        sessionId: "11111111-1111-1111-1111-111111111111",
+        worktreePath: "/tmp/wt/issue-1"
+    }), {
+        runtime: "cursor_local",
+        model: "composer",
+        sessionId: "11111111-1111-1111-1111-111111111111",
+        worktreePath: "wt/issue-1"
+    });
+});
+test("deriveActivityFromLog maps recent tool names to operator labels", () => {
+    const logPath = writeLog([
+        { type: "assistant", message: { content: [{ type: "tool_use", name: "Read" }] } },
+        { type: "assistant", message: { content: [{ type: "tool_use", name: "Shell" }] } },
+        {
+            type: "assistant",
+            message: { content: [{ type: "tool_use", name: "Shell", input: { command: "npm test" } }] }
+        },
+    ]);
+    // Last event is a Shell tool with npm test → concrete test progress
+    assert.match(deriveActivityFromLog(logPath), /Running tests:/i);
+});
+test("deriveLiveProgressFromLog returns null for missing or empty logs", () => {
+    assert.equal(deriveLiveProgressFromLog("/no/such/session.ndjson"), null);
+    assert.equal(deriveLiveProgressFromLog(writeLog([{ type: "system", subtype: "init" }])), null);
+});
+test("deriveLiveProgressFromLog surfaces Cursor nested tool_call with file path", () => {
+    const logPath = writeLog([
+        {
+            type: "tool_call",
+            subtype: "started",
+            call_id: "c1",
+            tool_call: { readToolCall: { args: { path: "apps/web/src/pages/IssueDetailPage.tsx" } } }
+        },
+    ]);
+    assert.equal(deriveLiveProgressFromLog(logPath), "Reading IssueDetailPage.tsx");
+});
+test("deriveLiveProgressFromLog surfaces Cursor shell / test commands", () => {
+    const logPath = writeLog([
+        {
+            type: "tool_call",
+            subtype: "started",
+            call_id: "c2",
+            tool_call: {
+                shellToolCall: {
+                    args: { command: "npm test -- packages/server/src/coordinator/failure-reason.test.ts" }
+                }
+            }
+        },
+    ]);
+    const progress = deriveLiveProgressFromLog(logPath);
+    assert.ok(progress);
+    assert.match(progress, /Running tests:/i);
+    assert.match(progress, /failure-reason/);
+});
+test("deriveLiveProgressFromLog prefers recent tool over tiny assistant token fragments", () => {
+    const logPath = writeLog([
+        {
+            type: "tool_call",
+            subtype: "started",
+            call_id: "c1",
+            tool_call: { grepToolCall: { args: { pattern: "liveProgress" } } }
+        },
+        { type: "assistant", message: { content: [{ type: "text", text: "I'll" }] } },
+        { type: "assistant", message: { content: [{ type: "text", text: " fix" }] } },
+    ]);
+    assert.equal(deriveLiveProgressFromLog(logPath), "Searching: liveProgress");
+});
+test("deriveLiveProgressFromLog coalesces a meaningful assistant sentence", () => {
+    const logPath = writeLog([
+        { type: "assistant", message: { content: [{ type: "text", text: "Addressing Lens FIX findings" }] } },
+        { type: "assistant", message: { content: [{ type: "text", text: " and rechecking the flaky test." }] } },
+    ]);
+    assert.equal(deriveLiveProgressFromLog(logPath), "Addressing Lens FIX findings and rechecking the flaky test.");
+});
+test("deriveLiveProgressFromLog truncates long progress to one readable line", () => {
+    const long = "Implementing the live progress strip by parsing the session NDJSON tail for assistant " +
+        "sentences and tool arguments so operators can see concrete work without opening the log file.";
+    const logPath = writeLog([
+        { type: "assistant", message: { content: [{ type: "text", text: long }] } },
+    ]);
+    const progress = deriveLiveProgressFromLog(logPath);
+    assert.ok(progress);
+    assert.ok(progress.length <= 120, `expected <=120 chars, got ${progress.length}`);
+    assert.ok(!progress.includes("\n"));
+    assert.match(progress, /\u2026$|…$/);
+});
+test("deriveLiveProgressFromLog surfaces Cursor editToolCall path", () => {
+    const logPath = writeLog([
+        {
+            type: "tool_call",
+            subtype: "started",
+            tool_call: {
+                editToolCall: { args: { path: "apps/web/src/pages/IssueDetailPage.tsx", streamContent: "…" } }
+            }
+        },
+    ]);
+    assert.equal(deriveLiveProgressFromLog(logPath), "Editing IssueDetailPage.tsx");
+});
+test("deriveLiveProgressFromLog surfaces Cursor globPattern", () => {
+    const logPath = writeLog([
+        {
+            type: "tool_call",
+            subtype: "started",
+            tool_call: { globToolCall: { args: { globPattern: "apps/web/src/pages/*.tsx" } } }
+        },
+    ]);
+    assert.equal(deriveLiveProgressFromLog(logPath), "Finding files: apps/web/src/pages/*.tsx");
+});
+test("deriveLiveProgressFromLog reads the committed Cursor fixture", async () => {
+    const { fileURLToPath } = await import("node:url");
+    const fixture = path.join(path.dirname(fileURLToPath(import.meta.url)), "../runners/fixtures/cursor-success-with-infra-attempt-limit-text.ndjson");
+    const progress = deriveLiveProgressFromLog(fixture);
+    // Fixture ends with result; last concrete signal is the read tool or the assistant sentence.
+    assert.ok(progress);
+    assert.match(progress, /routing\.ts|infra-attempt|Looking at routing/i);
+});
+test("emitSessionMilestone appends a role-attributed event and refreshes currentIntent", () => {
+    const issue = createIssue({
+        title: "Progress",
+        description: "Ship visibility",
+        acceptanceCriteria: "Operators see last progress",
+        repo: "acme/app",
+        developerAgentId: BUILTIN_AGENT_CLAUDE_ID,
+        reviewerAgentId: BUILTIN_AGENT_CURSOR_ID,
+        baseBranch: "main",
+        source: "manual"
+    });
+    const instance = startWorkflowInstance(issue.id, "dev_reviewer_v1");
+    transitionIssue(issue.id, "developing", {
+        currentOwner: "developer",
+        currentIntent: "Developer implementing round 1"
+    });
+    const session = createWorkerSession({
+        issueId: issue.id,
+        role: "developer",
+        round: 1,
+        agentId: BUILTIN_AGENT_CLAUDE_ID,
+        runtime: "cursor_local"
+    });
+    startSession(session.id);
+    emitSessionMilestone({
+        issueId: issue.id,
+        workflowInstanceId: instance.id,
+        workerSessionId: session.id,
+        role: "developer",
+        stage: "developing",
+        round: 1,
+        type: "worktree.ready",
+        intent: "Developer · worktree ready (round 1)",
+        payload: { worktreePath: "wt/x" }
+    });
+    const events = listWorkflowEventsForIssue(issue.id);
+    const milestone = events.find((e) => e.type === "worktree.ready");
+    assert.ok(milestone);
+    assert.equal(milestone.actorType, "developer");
+    assert.equal(getIssue(issue.id).currentIntent, "Developer · worktree ready (round 1)");
+});

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

@@ -0,0 +1,33 @@
+const num = (name, dflt) => Number(process.env[name] ?? dflt);
+export function developerSessionTimeoutMs() {
+    return num("DEVELOPER_TIMEOUT_MS", 60 * 60_000);
+}
+export function reviewerSessionTimeoutMs() {
+    return num("REVIEWER_TIMEOUT_MS", 30 * 60_000);
+}
+export function sessionTimeoutMsFor(role) {
+    return role === "reviewer" ? reviewerSessionTimeoutMs() : developerSessionTimeoutMs();
+}
+/**
+ * The longest recovery will honour an "alive" verdict before reclaiming anyway (NOT-131).
+ *
+ * Making the pid verdict portable across a restart fixes the wrong reclaim, but it opens
+ * the opposite failure: the `spawnCli` timeout that bounds a session is a `setTimeout` in
+ * the process that spawned it, and that process is exactly the one that died. A successor
+ * that honours "alive" unconditionally will extend a hung CLI's lease on every tick,
+ * forever, and the work item never resolves — the permanent stall `process-liveness.ts`
+ * warns about, arriving through the front door instead. So the hold is bounded: past this,
+ * the CLI is killed and the item reclaimed whatever the pid says.
+ *
+ * Measured from `worker_sessions.started_at`, which is stamped *before* worktree setup and
+ * the deck bind, so it precedes the actual spawn by an unbounded amount. Hence the 2x
+ * default rather than the bare timeout: a slow clone must never make this fire on a healthy
+ * session. The guarantee is a hard bound on the stall, not a precise re-enforcement of the
+ * CLI's own deadline.
+ */
+export function maxAliveHoldMsFor(role) {
+    const raw = process.env.COORDINATOR_MAX_ALIVE_HOLD_MS;
+    if (raw !== undefined && raw !== "")
+        return Number(raw);
+    return sessionTimeoutMsFor(role) * 2;
+}