agent-dealer 1.2.7 → 1.2.8

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

@@ -7,7 +7,7 @@
 // duplicate delivery is a no-op. The effect *work* itself runs elsewhere, through a leased
 // worker whose structured result comes back into applyCompletion.
 import fs from "node:fs";
-import { canTransitionIssue } from "@agent-dealer/shared";
+import { canTransitionIssue, tryCompileContract } from "@agent-dealer/shared";
 import { getDb } from "../db/index.js";
 import { getIssue, incrementIssueRound, incrementIssueInfraAttempts, resetIssueInfraAttempts, grantReviewRetry, transitionIssue, } from "../repository/issues.js";
 import { appendWorkflowEvent, completeWorkflowInstance, getActiveWorkflowInstance, getWorkflowInstance, listWorkflowEventsForIssue, startWorkflowInstance, WorkflowAlreadyActiveError, } from "../repository/workflow-events.js";
@@ -17,7 +17,8 @@ import { ensureIssueRepoCheckout } from "../adapters/managed-repo.js";
 import { reconcileFinding, resolveFindingsAbsentFromRound } from "../repository/findings.js";
 import { normalizeReviewerResult } from "./reviewer-result.js";
 import { getAgent } from "../repository/agents.js";
-import { githubIssuesSync } from "../adapters/agent-health.js";
+import { githubIssuesSync, invalidateMuseHealthCache } from "../adapters/agent-health.js";
+import { recordMuseCapabilityOverride } from "../adapters/muse-capability.js";
 import { createIssueArtifact, latestIssueArtifact } from "../repository/artifacts.js";
 import { cancelWorkItem, enqueueWorkItem, finishWorkItem, getWorkItem, listWorkItemsForIssue, } from "../repository/work-items.js";
 import { completeSession, getWorkerSession, listWorkerSessionsForIssue } from "../repository/worker-sessions.js";
@@ -53,7 +54,13 @@ export function getTaskSnapshot(issue) {
     const artifact = latestIssueArtifact(issue.id, TASK_SNAPSHOT_ARTIFACT_KIND);
     if (artifact?.contentJson) {
         try {
-            return JSON.parse(artifact.contentJson);
+            const parsed = JSON.parse(artifact.contentJson);
+            // Snapshots frozen before NOT-306 carry no contract — derive it from the
+            // frozen source description so old workflows still render what they ran.
+            if (parsed.executionContract === undefined) {
+                return { ...parsed, executionContract: tryCompileContract(parsed.description) };
+            }
+            return parsed;
         }
         catch {
             // fall through to the live-field fallback below
@@ -66,6 +73,7 @@ export function getTaskSnapshot(issue) {
         repo: issue.repo,
         baseBranch: issue.baseBranch,
         workflowVersion: WORKFLOW_VERSION,
+        executionContract: tryCompileContract(issue.description),
     };
 }
 /**
@@ -83,9 +91,15 @@ export function canEditParkedIssue(issue) {
         return false;
     return !listWorkItemsForIssue(issue.id).some((w) => w.status === "pending" || w.status === "leased");
 }
-/** Re-freezes the snapshot when the operator edited title/description/criteria; returns the changed fields (empty = no-op). */
+/**
+ * Re-freezes the snapshot when the operator edited title/description/criteria
+ * (or the contract compiled from the description); returns the changed fields
+ * (empty = no-op). Source and compiled contract always re-freeze atomically —
+ * one artifact write carries both, so they can never diverge.
+ */
 function refreshTaskSnapshotIfEdited(issue) {
     const frozen = getTaskSnapshot(issue);
+    const liveContract = tryCompileContract(issue.description);
     const changed = [];
     if (frozen.title !== issue.title)
         changed.push("title");
@@ -93,6 +107,9 @@ function refreshTaskSnapshotIfEdited(issue) {
         changed.push("description");
     if (frozen.acceptanceCriteria !== (issue.acceptanceCriteria ?? ""))
         changed.push("acceptanceCriteria");
+    if (JSON.stringify(frozen.executionContract ?? null) !== JSON.stringify(liveContract ?? null)) {
+        changed.push("executionContract");
+    }
     if (changed.length > 0)
         freezeTaskSnapshot(issue);
     return changed;
@@ -109,6 +126,7 @@ function freezeTaskSnapshot(issue) {
             repo: issue.repo,
             baseBranch: issue.baseBranch,
             workflowVersion: WORKFLOW_VERSION,
+            executionContract: tryCompileContract(issue.description),
         },
     });
 }
@@ -973,6 +991,11 @@ function questionFor(actionType, reason, resumeAsReviewer = false, mergeFailure
             // Run-scoped action type directly with its own question text (NOT-95). Case exists
             // only so this function stays total over HumanActionType.
             throw new Error("outbound_delivery_interaction_required is not raised through applyEffect");
+        case "muse_capability":
+            // Never raised through applyEffect — muse-capability.ts creates this action
+            // directly with its own question text (NOT-308). Case exists only so this
+            // function stays total over HumanActionType.
+            throw new Error("muse_capability is not raised through applyEffect");
     }
 }
 /** Exported for db/migrate-to-issues.ts, which must populate the same response options on
@@ -1014,6 +1037,11 @@ export function responseOptionsFor(actionType, resumeAsReviewer = false, opts =
         case "outbound_delivery_interaction_required":
             // Never actually raised through applyEffect — see questionFor's identical case.
             throw new Error("outbound_delivery_interaction_required is not raised through applyEffect");
+        case "muse_capability":
+            // NOT-308: created with its own stored options (muse-capability.ts) — acknowledge
+            // admits on that Muse version (missing) or dismisses (unverified). Never raised
+            // through applyEffect; case exists only so this function stays total.
+            return [{ choice: "acknowledge", label: "Acknowledge" }];
     }
 }
 function parseContinuationPreview(json) {
@@ -1052,6 +1080,61 @@ export function resolveHumanActionAndAdvance(actionId, resolvedBy, choice, opts)
     const normalizedNote = normalizeResolutionNote(opts?.note);
     if (!normalizedNote.ok)
         return { ok: false, code: 400, error: normalizedNote.error };
+    // NOT-308: a Muse capability escalation resolves without touching the workflow — it
+    // has no round to spend and no merge to park, and parseHumanResolution (below)
+    // deliberately rejects it since there is no workflow outcome to map. Acknowledging a
+    // `missing` verdict records a per-version override so the admission gate stops
+    // blocking that version; acknowledging `unverified` just dismisses. Works with or
+    // without an active instance (a blocked admission never has one).
+    if (action.actionType === "muse_capability") {
+        if (choice !== "acknowledge") {
+            return { ok: false, code: 400, error: `Invalid choice "${choice}" for muse_capability` };
+        }
+        if (!action.issueId)
+            return { ok: false, code: 500, error: "Human action has no issue" };
+        const museIssue = getIssue(action.issueId);
+        if (!museIssue)
+            return { ok: false, code: 404, error: "Issue not found" };
+        const museInstance = getActiveWorkflowInstance(action.issueId);
+        let evidence = null;
+        try {
+            evidence = action.evidenceJson
+                ? JSON.parse(action.evidenceJson)
+                : null;
+        }
+        catch {
+            evidence = null;
+        }
+        // File first, then the row: if the resolve below fails the action stays open and
+        // the operator retries idempotently; the reverse order could leave a resolved
+        // action whose version still blocks with no way to re-acknowledge.
+        if (evidence?.kind === "missing" && typeof evidence.version === "string" && evidence.version) {
+            recordMuseCapabilityOverride(evidence.version);
+        }
+        // The lifted block must be visible on the next health read, not after the cache TTL.
+        invalidateMuseHealthCache();
+        return getDb().transaction(() => {
+            resolveHumanAction(actionId, resolvedBy, { choice });
+            appendWorkflowEvent({
+                issueId: museIssue.id,
+                ...(museInstance ? { workflowInstanceId: museInstance.id } : {}),
+                type: "human_action.resolved",
+                actorType: "human",
+                actorRef: resolvedBy,
+                stage: museIssue.status,
+                round: museIssue.currentRound,
+                payload: { actionType: action.actionType, choice },
+            });
+            return {
+                ok: true,
+                issueStatus: museIssue.status,
+                nextWorkItemId: null,
+                instanceCompleted: false,
+                restarted: false,
+                triggerReflect: false,
+            };
+        })();
+    }
     const resolution = parseHumanResolution(action.actionType, choice, normalizedNote.note);
     if (!resolution) {
         return { ok: false, code: 400, error: `Invalid choice "${choice}" for ${action.actionType}` };
@@ -1446,7 +1529,9 @@ export async function resolveHumanActionAndAdvanceAsync(actionId, resolvedBy, ch
     return {
         ok: true,
         issueStatus: merged.issueStatus,
-        nextWorkItemId: null,
+        // NOT-310: a retry_merge that hit a textual conflict queues a repair round —
+        // report it like any other queued round instead of dropping it.
+        nextWorkItemId: merged.nextWorkItemId,
         instanceCompleted: merged.instanceCompleted,
         restarted: false,
         triggerReflect: merged.triggerReflect,

package/bundle/server/dist/coordinator/deck-outage.integration.test.js

@@ -31,15 +31,17 @@ const { deckOutageBackoffMs } = await import("./deck-outage-config.js");
 const UNREACHABLE = "Agent Deck is unreachable — fetch failed";
 before(() => migrate());
 beforeEach(() => {
+    // NOT-305: session-linked playbook_use_receipt artifacts reference worker_sessions,
+    // so child rows (artifacts, usage_events) go before their parents.
     getDb().exec(`
     DELETE FROM review_publications;
+    DELETE FROM artifacts;
     DELETE FROM work_items;
     DELETE FROM human_actions;
     DELETE FROM workflow_events;
     DELETE FROM findings;
-    DELETE FROM worker_sessions;
-    DELETE FROM artifacts;
     DELETE FROM usage_events;
+    DELETE FROM worker_sessions;
     DELETE FROM workflow_instances;
     DELETE FROM issues;
     DELETE FROM runtime_availability;

package/bundle/server/dist/coordinator/developer-effect.js

@@ -27,7 +27,10 @@ import { ensureIssueRepoCheckout, roleWorktreePathForResolution, resolveCheckout
 import { baseRefCandidates, inspectBranchProgress } from "./branch-progress.js";
 import { prepareWorkerDeckConnection, releaseWorkerDeckConnection, verifyWorkerDeckConnection } from "../adapters/agent-deck-bind.js";
 import { realGithubAdapter, pollPrChecks } from "../adapters/github.js";
-import { getWorkerSession, patchRunningSession, recordSessionProcess, setSessionInputSha } from "../repository/worker-sessions.js";
+import { museCapabilitySafetyNetAfterSession } from "../adapters/muse-capability.js";
+import { getOrAssignSessionCorrelationId, getWorkerSession, mergeSessionMetadata, patchRunningSession, recordSessionProcess, setSessionInputSha } from "../repository/worker-sessions.js";
+import { museIdleMinutes, museStallMetadata } from "./muse-spawn.js";
+import { museIdleTimeoutMs } from "./session-timeouts.js";
 import { COORDINATOR_PROCESS_OWNER, readProcessStartTime } from "./process-liveness.js";
 import { checkDeveloperWorktreeOwnerLiveness } from "./worktree-owner-liveness.js";
 import { developerSessionTimeoutMs } from "./session-timeouts.js";
@@ -87,6 +90,23 @@ async function crashOrTimeoutOutcome(opts) {
         ...(opts.logPath ? { logPath: opts.logPath } : {}),
     };
 }
+/**
+ * NOT-307: idle-kill description for the timeout reason, or null for anything else
+ * (wall-clock timeout, crash, success). Minutes prefer the measured last-activity
+ * time and fall back to the configured bound; the last tool name rides along so the
+ * recorded reason — and the `muse_no_progress` classifier — names the stall point.
+ */
+function idleCrashInfoFor(spawned) {
+    if (!spawned.idleTimedOut)
+        return null;
+    return {
+        minutes: museIdleMinutes({
+            lastActivityAt: spawned.muse?.lastActivityAt ?? null,
+            idleTimeoutMs: museIdleTimeoutMs(),
+        }),
+        lastToolName: spawned.muse?.lastToolName ?? null,
+    };
+}
 export const developerEffectConfig = {
     get sessionTimeoutMs() {
         return developerSessionTimeoutMs();
@@ -601,6 +621,9 @@ export async function runDeveloperEffect(ctx, deps = defaultDeps) {
     }
     const session = getWorkerSession(sessionId);
     const snapshot = parseProfileSnapshot(session?.profileSnapshotJson);
+    // NOT-305: opaque per-session Deck correlation UUID, persisted before spawn and
+    // carried as observability metadata in every runtime launch config below.
+    const deckCorrelationId = session?.deckCorrelationId ?? getOrAssignSessionCorrelationId(sessionId);
     let taskSnapshot = getTaskSnapshot(issue);
     const runtime = snapshot?.runtime ?? "claude_code";
     const round = workItem.round;
@@ -807,6 +830,7 @@ export async function runDeveloperEffect(ctx, deps = defaultDeps) {
                 worktreePath,
                 runtime,
                 policy,
+                correlationId: deckCorrelationId,
                 verifyCallTool: deps.deckCallTool,
             });
             if (!prepared.ok) {
@@ -862,6 +886,22 @@ export async function runDeveloperEffect(ctx, deps = defaultDeps) {
         const scopeDecisionNote = typeof payload.scopeDecisionNote === "string" && payload.scopeDecisionNote.trim()
             ? payload.scopeDecisionNote.trim()
             : undefined;
+        // NOT-310: the conflict directive rides only the work item queued by the merge
+        // path — exactly this round reads it; nothing is re-read from the DB. Shaped
+        // defensively: a malformed directive renders nothing rather than breaking the
+        // prompt (conflictRepairSection also guards on empty base/branch).
+        const conflictRepair = payload.conflictRepair &&
+            typeof payload.conflictRepair === "object" &&
+            typeof payload.conflictRepair.baseBranch === "string" &&
+            typeof payload.conflictRepair.branch === "string"
+            ? {
+                baseBranch: payload.conflictRepair.baseBranch,
+                branch: payload.conflictRepair.branch,
+                files: Array.isArray(payload.conflictRepair.files)
+                    ? payload.conflictRepair.files.filter((f) => typeof f === "string")
+                    : [],
+            }
+            : undefined;
         let priorConclusion;
         let priorVerificationReceipt;
         if (retryReason) {
@@ -897,6 +937,7 @@ export async function runDeveloperEffect(ctx, deps = defaultDeps) {
             museDeveloper: isMuse,
             guidance: guidance.length ? guidance : undefined,
             scopeDecisionNote,
+            conflictRepair,
         });
         // NOT-83 review finding: the session is marked `running` (worker-loop.ts) before this
         // handler ever runs, so an abort landing during worktree setup/deck-bind above already
@@ -998,6 +1039,9 @@ export async function runDeveloperEffect(ctx, deps = defaultDeps) {
                 // NOT-278: frozen profile deck → the Muse exec attempt (deck headers + pre-spawn
                 // verify). Other runtimes carry their deck via mcpConfigPath/mcpEnv and ignore this.
                 deckId: snapshot?.deckId ?? null,
+                // NOT-305: opaque per-session Deck correlation UUID → the Muse settings
+                // `x-agent-deck-correlation-id` observability header.
+                deckCorrelationId,
                 prompt,
                 cwd: worktreePath,
                 timeoutMs: developerEffectConfig.sessionTimeoutMs,
@@ -1069,6 +1113,18 @@ export async function runDeveloperEffect(ctx, deps = defaultDeps) {
         // here on (usage, receipt, push, PR verify, checks poll) is post-spawn and must
         // not be mislabeled as a session that could not start.
         sessionStarted = true;
+        // NOT-307: stall evidence for every Muse session (timed out or not) — merged
+        // into metadata_json while the row is still running, so the classifier and the
+        // operator can read last-activity evidence whatever the outcome. Best-effort:
+        // evidence must never fail the attempt it describes.
+        if (spawned.muse) {
+            try {
+                mergeSessionMetadata(sessionId, museStallMetadata(spawned.muse));
+            }
+            catch {
+                // ignore
+            }
+        }
         // NOT-169: exactly one agent.completed per spawned process, at child exit and before
         // any receipt mining, usage extraction, or validation. Raw outcome only — no
         // failure classification.
@@ -1094,6 +1150,26 @@ export async function runDeveloperEffect(ctx, deps = defaultDeps) {
                 // ignore
             }
         }
+        // NOT-308 safety net: a Muse session that left the worktree dirty without a
+        // single shell tool call is what a shell-less build looks like from the outside —
+        // when the running version is not yet the confirmed baseline, re-verify it in the
+        // background immediately (bypassing the error backoff) and escalate a `missing`
+        // verdict on this issue. Fire-and-forget: never throws, never changes this outcome.
+        // Dirtiness is read here, before salvage/commit handling below can clean the tree.
+        if (runtime === "muse_code") {
+            try {
+                const dirtyAtSessionEnd = !(await isWorktreeClean(worktreePath).catch(() => true));
+                museCapabilitySafetyNetAfterSession({
+                    issueId: issue.id,
+                    runtime,
+                    logPath: spawned.logPath,
+                    dirty: dirtyAtSessionEnd,
+                });
+            }
+            catch {
+                // Observational only — the session outcome stands on its own.
+            }
+        }
         // NOT-130: record suite evidence even when the session later fails/times out — an
         // interrupted-but-verified tip must carry the receipt into the retry prompt.
         const verificationReceipt = await persistVerificationReceiptIfAny({
@@ -1287,6 +1363,7 @@ export async function runDeveloperEffect(ctx, deps = defaultDeps) {
                         timedOut: Boolean(spawned.timedOut),
                         logPath: spawned.logPath,
                         runtime,
+                        idle: idleCrashInfoFor(spawned),
                     });
                     const salvageNote = `Salvaged uncommitted work as ${salvaged.message} (${salvaged.commitSha.slice(0, 7)}).`;
                     const crashOutcome = await crashOrTimeoutOutcome({
@@ -1341,6 +1418,7 @@ export async function runDeveloperEffect(ctx, deps = defaultDeps) {
                     timedOut: Boolean(spawned.timedOut),
                     logPath: spawned.logPath,
                     runtime,
+                    idle: idleCrashInfoFor(spawned),
                 }),
                 worktreePath,
                 logPath: spawned.logPath,

package/bundle/server/dist/coordinator/execution-report.js

@@ -151,6 +151,12 @@ export function classifyFailureReason(reason) {
     const text = (reason ?? "").trim();
     if (!text)
         return { code: "unknown", domain: "unknown", confidence: "low" };
+    // NOT-307: an idle-watchdog kill names itself ("made no progress … idle timeout").
+    // Checked before the timeout rules: the reason contains both "timeout" and "tool"
+    // ("last tool: …"), which would otherwise misread as tool_test_timeout.
+    if (/made no progress|killed on the idle timeout/i.test(text)) {
+        return { code: "muse_no_progress", domain: "infrastructure", confidence: "high" };
+    }
     // A bare timeout with no tool/test in flight is unknown by rule — do not guess.
     if (/timed? ?out|deadline/i.test(text) && !/tool|test|jest|vitest|pytest|subprocess|command/i.test(text)) {
         return { code: "unknown", domain: "unknown", confidence: "low" };

package/bundle/server/dist/coordinator/execution-report.test.js

@@ -88,6 +88,13 @@ test("classifier keeps ambiguous timeouts unknown", () => {
     assert.equal(classifyFailureReason(null).code, "unknown");
     assert.equal(classifyFailureReason("").code, "unknown");
 });
+test("NOT-307: classifier reads an idle-watchdog kill as muse_no_progress", () => {
+    const reason = "Developer session made no progress for 20 minutes. (last tool: npm_test) Killed on the idle timeout.";
+    const got = classifyFailureReason(reason);
+    assert.equal(got.code, "muse_no_progress");
+    assert.equal(got.domain, "infrastructure");
+    assert.equal(got.confidence, "high");
+});
 test("classifier anchors keep author/release/unrelated spawn out of buckets", () => {
     // `auth` must not match "author"; `lease` must not match "release"/"please".
     assert.equal(classifyFailureReason("the author released a fix").code, "unknown");

package/bundle/server/dist/coordinator/failure-cause.js

@@ -329,6 +329,27 @@ export function classifyAttemptFailure(input) {
             rawReason: rawReason || "Agent Deck failure.",
         });
     }
+    // NOT-307: an idle-watchdog kill is a specific, high-confidence infrastructure
+    // cause — never `unknown`. It sorts after log evidence (an auth/429 already on
+    // record names an earlier, more specific root cause for the same stall) but
+    // before the outcome-level timeout guess, so a hung tool/test in flight does not
+    // demote the stall to `tool_test_timeout`. The raw reason carries the idle
+    // minutes and the last tool name, reusing the recorded reason when it already
+    // names them (reasonForSessionCrash writes them at kill time).
+    if (input.idleTimedOut) {
+        const minutes = typeof input.idleForMs === "number" && Number.isFinite(input.idleForMs) && input.idleForMs >= 0
+            ? Math.max(1, Math.round(input.idleForMs / 60_000))
+            : null;
+        const alreadySpecific = /made no progress/i.test(rawReason);
+        signals.push({
+            code: "muse_no_progress",
+            confidence: "high",
+            evidenceSource: "outcome_kind",
+            rawReason: alreadySpecific
+                ? rawReason
+                : `Muse developer session made no progress${minutes !== null ? ` for ${minutes} minute${minutes === 1 ? "" : "s"}` : ""} (last tool: ${input.lastToolName ?? "none"}).${rawReason ? ` ${rawReason}` : ""}`,
+        });
+    }
     const outcomeSignal = detectOutcomeSignal(outcomeKind, rawReason, {
         timedOut,
         toolInFlight,
@@ -413,6 +434,36 @@ function agentCompletedEvidence(workerSessionId) {
     }
     return out;
 }
+/**
+ * NOT-307: idle-watchdog evidence read back out of `worker_sessions.metadata_json`
+ * (written by the developer effect for every Muse session). Silence duration is
+ * measured against `occurredAtMs` — the kill/completion time — from the recorded
+ * `lastActivityAt`. Anything unparseable reads as no idle evidence, never a throw.
+ */
+export function museStallFromMetadata(metadataJson, occurredAtMs) {
+    const none = { idleTimedOut: false, idleForMs: null, lastToolName: null };
+    if (!metadataJson)
+        return none;
+    try {
+        const parsed = JSON.parse(metadataJson);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return none;
+        const rec = parsed;
+        if (rec.idleTimedOut !== true)
+            return none;
+        const lastToolName = typeof rec.lastToolName === "string" ? rec.lastToolName : null;
+        let idleForMs = null;
+        if (occurredAtMs !== null && Number.isFinite(occurredAtMs) && typeof rec.lastActivityAt === "string") {
+            const at = Date.parse(rec.lastActivityAt);
+            if (Number.isFinite(at) && occurredAtMs >= at)
+                idleForMs = occurredAtMs - at;
+        }
+        return { idleTimedOut: true, idleForMs, lastToolName };
+    }
+    catch {
+        return none;
+    }
+}
 /**
  * Backfill-on-read for legacy rows: classify from existing session error/log
  * evidence without mutating any append-only event. Always quality "inferred" —
@@ -421,6 +472,9 @@ function agentCompletedEvidence(workerSessionId) {
 export function backfillCausesForSession(session, opts) {
     const agent = agentCompletedEvidence(session.id);
     const outcomeKind = opts?.outcomeKind ?? null;
+    const occurredAt = opts?.occurredAt ?? session.completedAt ?? session.updatedAt;
+    const occurredAtMs = occurredAt ? Date.parse(occurredAt) : NaN;
+    const stall = museStallFromMetadata(session.metadataJson ?? null, Number.isFinite(occurredAtMs) ? occurredAtMs : null);
     return classifyAttemptFailure({
         outcomeKind,
         sessionErrorJson: session.errorJson,
@@ -428,8 +482,11 @@ export function backfillCausesForSession(session, opts) {
         runtime: session.runtime,
         exitCode: session.exitCode ?? agent.exitCode,
         timedOut: outcomeKind === "timed_out" || agent.timedOut,
+        idleTimedOut: stall.idleTimedOut || undefined,
+        idleForMs: stall.idleForMs,
+        lastToolName: stall.lastToolName,
         hostSuspended: agent.hostSuspended,
-        occurredAt: opts?.occurredAt ?? session.completedAt ?? session.updatedAt,
+        occurredAt,
         eventCursor: opts?.eventCursor ?? null,
         sessionId: session.id,
         eventId: opts?.eventId ?? null,
@@ -449,6 +506,9 @@ export function recordCausesForWorkerFailedEvent(opts) {
         const session = opts.event.workerSessionId ? getWorkerSession(opts.event.workerSessionId) : null;
         const agent = agentCompletedEvidence(opts.event.workerSessionId);
         const outcomeTimedOut = opts.outcomeKind === "timed_out";
+        const occurredAtMs = Date.parse(opts.event.ts);
+        // NOT-307: an idle kill's stall evidence rides on the session row's metadata.
+        const stall = museStallFromMetadata(session?.metadataJson ?? null, Number.isFinite(occurredAtMs) ? occurredAtMs : null);
         const causes = classifyAttemptFailure({
             outcomeKind: opts.outcomeKind,
             outcomeReason: opts.outcomeReason,
@@ -458,6 +518,9 @@ export function recordCausesForWorkerFailedEvent(opts) {
             runtime: session?.runtime ?? undefined,
             exitCode: session?.exitCode ?? agent.exitCode,
             timedOut: outcomeTimedOut || agent.timedOut,
+            idleTimedOut: stall.idleTimedOut || undefined,
+            idleForMs: stall.idleForMs,
+            lastToolName: stall.lastToolName,
             hostSuspended: agent.hostSuspended,
             recovery: opts.recovery,
             occurredAt: opts.event.ts,

package/bundle/server/dist/coordinator/failure-cause.test.js

@@ -8,7 +8,7 @@ import assert from "node:assert/strict";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { classifyAttemptFailure, orderAttemptCauses, } from "./failure-cause.js";
+import { backfillCausesForSession, classifyAttemptFailure, museStallFromMetadata, orderAttemptCauses, } from "./failure-cause.js";
 import { PRESUMED_DEAD_REASON } from "./failure-reason.js";
 function writeLog(body) {
     const dir = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-failure-cause-"));
@@ -274,6 +274,97 @@ test("reclaimed session with provider/auth log evidence keeps it primary", () =>
     assert.equal(reclaimedAuth[0].primary, true);
     assert.equal(reclaimedAuth.find((c) => c.code === "coordinator_crash")?.primary, false);
 });
+// NOT-307: an idle-watchdog kill classifies as muse_no_progress (infrastructure,
+// high confidence) instead of unknown — with the idle minutes and last tool name
+// in the raw reason — even when a tool was in flight (a hung tool is still a stall).
+test("idle-watchdog kill classifies as muse_no_progress, not unknown", () => {
+    const idle = primary(classifyAttemptFailure({
+        outcomeKind: "timed_out",
+        outcomeReason: "Developer session made no progress for 20 minutes. (last tool: npm_test) Killed on the idle timeout.",
+        timedOut: true,
+        idleTimedOut: true,
+        idleForMs: 20 * 60_000,
+        lastToolName: "npm_test",
+    }));
+    assert.equal(idle.code, "muse_no_progress");
+    assert.equal(idle.domain, "infrastructure");
+    assert.equal(idle.confidence, "high");
+    assert.match(idle.rawReason, /20 minutes/);
+    assert.match(idle.rawReason, /npm_test/);
+});
+test("idle kill beats the tool_test_timeout guess and the unknown fallback", () => {
+    // A hung test in flight plus an idle kill: still the stall, not the tool timeout.
+    const hungTool = primary(classifyAttemptFailure({
+        outcomeKind: "timed_out",
+        outcomeReason: "vitest run timed out after 30000ms",
+        timedOut: true,
+        toolInFlight: true,
+        idleTimedOut: true,
+        idleForMs: 21 * 60_000,
+        lastToolName: "vitest",
+    }));
+    assert.equal(hungTool.code, "muse_no_progress");
+    // A bare timed_out with no idle evidence still classifies as before (unknown here).
+    const plain = primary(classifyAttemptFailure({ outcomeKind: "timed_out", timedOut: true }));
+    assert.equal(plain.code, "unknown");
+});
+test("idle kill composes the reason when the recorded text lacks minutes and tool", () => {
+    const composed = primary(classifyAttemptFailure({
+        outcomeKind: "timed_out",
+        outcomeReason: "Developer session timed out.",
+        timedOut: true,
+        idleTimedOut: true,
+        idleForMs: 22 * 60_000,
+        lastToolName: null,
+    }));
+    assert.equal(composed.code, "muse_no_progress");
+    assert.match(composed.rawReason, /22 minutes/);
+    assert.match(composed.rawReason, /last tool: none/);
+    assert.match(composed.rawReason, /Developer session timed out\./);
+});
+// NOT-307: stall evidence round-trips through worker_sessions.metadata_json —
+// the record/backfill paths read the same five fields the developer effect wrote.
+test("museStallFromMetadata reads idle evidence, and ignores anything else", () => {
+    const at = Date.parse("2026-10-01T19:40:00.000Z");
+    const stall = museStallFromMetadata(JSON.stringify({
+        lastActivityAt: "2026-10-01T19:20:00.000Z",
+        toolCallCount: 24,
+        lastToolName: "npm_test",
+        firstOutputMs: 900,
+        idleTimedOut: true,
+    }), at);
+    assert.equal(stall.idleTimedOut, true);
+    assert.equal(stall.idleForMs, 20 * 60_000);
+    assert.equal(stall.lastToolName, "npm_test");
+    assert.deepEqual(museStallFromMetadata(null, at).idleTimedOut, false);
+    assert.deepEqual(museStallFromMetadata("not-json{", at).idleTimedOut, false);
+    assert.deepEqual(museStallFromMetadata(JSON.stringify({ idleTimedOut: false }), at).idleTimedOut, false, "a clean session's metadata is not idle evidence");
+    assert.deepEqual(museStallFromMetadata(JSON.stringify({ idleTimedOut: true }), null).idleForMs, null, "no kill time means no measured silence");
+});
+test("backfill over an idle-kill row classifies muse_no_progress", () => {
+    const causes = backfillCausesForSession({
+        id: "s-idle-backfill",
+        errorJson: JSON.stringify({
+            reason: "Developer session made no progress for 20 minutes. (last tool: npm_test) Killed on the idle timeout.",
+        }),
+        logPath: null,
+        runtime: "muse_code",
+        exitCode: 124,
+        completedAt: "2026-10-01T19:40:00.000Z",
+        updatedAt: "2026-10-01T19:40:00.000Z",
+        metadataJson: JSON.stringify({
+            lastActivityAt: "2026-10-01T19:20:00.000Z",
+            toolCallCount: 24,
+            lastToolName: "npm_test",
+            firstOutputMs: 900,
+            idleTimedOut: true,
+        }),
+    }, { outcomeKind: "timed_out" });
+    const found = primary(causes);
+    assert.equal(found.code, "muse_no_progress");
+    assert.equal(found.quality, "inferred");
+    assert.match(found.rawReason, /20 minutes/);
+});
 test("usage-capped and tool-timeout evidence map to capacity/task", () => {
     const capped = primary(classifyAttemptFailure({ outcomeKind: "usage_capped", outcomeReason: "claude_code usage capped — plan limit rejected" }));
     assert.equal(capped.code, "provider_capacity_rate_limit");

package/bundle/server/dist/coordinator/failure-reason.js

@@ -184,6 +184,13 @@ export function reasonForSessionCrash(opts) {
     const classified = classifyRunnerLogFailure(opts.logPath, opts.runtime);
     if (classified)
         return classified;
+    if (opts.timedOut && opts.idle) {
+        const mins = typeof opts.idle.minutes === "number" && Number.isFinite(opts.idle.minutes)
+            ? ` for ${opts.idle.minutes} minute${opts.idle.minutes === 1 ? "" : "s"}`
+            : "";
+        const tool = opts.idle.lastToolName ? ` (last tool: ${opts.idle.lastToolName})` : " (no tool call seen)";
+        return `Developer session made no progress${mins}.${tool} Killed on the idle timeout.`;
+    }
     return opts.timedOut ? "Developer session timed out." : "Developer session failed or crashed.";
 }
 function outcomeExplicitReason(outcome) {

package/bundle/server/dist/coordinator/failure-reason.test.js

@@ -206,6 +206,20 @@ test("NOT-133: a worker.failed event for an auth death carries the auth reason",
 test("reasonForSessionCrash falls back when log is clean", () => {
     assert.equal(reasonForSessionCrash({ timedOut: false, logPath: writeLog('{"type":"result"}\n') }), "Developer session failed or crashed.");
 });
+test("NOT-307: reasonForSessionCrash names the idle minutes and last tool on an idle kill", () => {
+    assert.equal(reasonForSessionCrash({
+        timedOut: true,
+        logPath: writeLog('{"type":"result"}\n'),
+        idle: { minutes: 20, lastToolName: "npm_test" },
+    }), "Developer session made no progress for 20 minutes. (last tool: npm_test) Killed on the idle timeout.");
+    assert.equal(reasonForSessionCrash({
+        timedOut: true,
+        logPath: writeLog('{"type":"result"}\n'),
+        idle: { minutes: null, lastToolName: null },
+    }), "Developer session made no progress. (no tool call seen) Killed on the idle timeout.");
+    // Wall-clock timeouts read exactly as before when no idle info is given.
+    assert.equal(reasonForSessionCrash({ timedOut: true, logPath: writeLog('{"type":"result"}\n') }), "Developer session timed out.");
+});
 test("parseErrorJsonReason reads recovery presumed-dead shape", () => {
     assert.equal(parseErrorJsonReason(JSON.stringify({ reason: PRESUMED_DEAD_REASON })), PRESUMED_DEAD_REASON);
 });