@isaacriehm/cairn-core 0.13.2 → 0.14.0

package/dist/hooks/runners/stop.js

@@ -13,7 +13,7 @@
  * When nothing: emits `{ continue: true }` and Claude stops normally.
  */
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync, } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
 import { dirname, join } from "node:path";
 import { readActiveTaskSummary } from "../../context/index.js";
 import { eventsSince, } from "../../events/index.js";
@@ -22,7 +22,7 @@ import { isDeferActive, readDeferState } from "../defer.js";
 import { resolveRepoRoot } from "../../session-start/index.js";
 import { readEventsMarker, stampEventsPoll, } from "../../session/index.js";
 import { writeStatusJson } from "../../status-line/index.js";
-import { completeTask, findCurrentActiveTask, readTaskAttestationState, transitionTaskPhase, } from "../../tasks/index.js";
+import { completeTask, findCurrentActiveTask, readTaskAttestationState, } from "../../tasks/index.js";
 import { effectivePhaseExitGate, findActiveMission, readMissionState, readRoadmap, } from "@isaacriehm/cairn-state";
 import { checkContextThreshold, renderContextThresholdHint, } from "./context-threshold.js";
 import { writePhaseReadyPending, } from "./phase-ready-surface.js";
@@ -66,7 +66,7 @@ const MAX_REASON_CHARS = 4_000;
  * CC convention, not a failure signal. One short line keeps the chat
  * tidy without dropping the cue entirely.
  */
-const REASON_PREAMBLE = "↳ Cairn cue — render any choice via `AskUserQuestion`.\n\n";
+const REASON_PREAMBLE = "↳ Cairn hint — surface to operator at a natural stopping point. Don't interrupt productive work; quote / `AskUserQuestion` only when there's no obvious continuation.\n\n";
 function clampReason(body) {
     if (body.length === 0)
         return body;
@@ -85,6 +85,96 @@ function clampReason(body) {
  * the window or whenever the payload hash changes.
  */
 const CUE_DEBOUNCE_WINDOW_MS = 60 * 60 * 1000;
+/**
+ * Bug-mine 0.13.8 — Phase 5 stall-cue tuning.
+ *
+ * `SESSION_ACTIVITY_WINDOW_MS` — when the transcript records any
+ * `tool_use` within this window, the AI is actively working; suppress
+ * the stalled-task surface so the cue doesn't interrupt productive
+ * flow. Mining showed stall cues firing while an Agent subagent was
+ * mid-dispatch and a research run was committing.
+ *
+ * `SESSION_STALLED_CUE_WINDOW_MS` — at most one stalled cue per
+ * session per hour, total (not per-task). Per-task throttle
+ * (`STALLED_FIRE_WINDOW_MS`) remains as a floor on top.
+ */
+const SESSION_ACTIVITY_WINDOW_MS = 5 * 60 * 1000;
+const SESSION_STALLED_CUE_WINDOW_MS = 60 * 60 * 1000;
+/**
+ * Walk the transcript tail and return the millisecond age of the most
+ * recent `tool_use` entry whose timestamp parses, or `null` when no
+ * such entry is found. Best-effort — any read / parse failure returns
+ * `null` and the caller falls through to the threshold check.
+ *
+ * Claude Code transcript entries are JSONL; assistant messages with
+ * tool calls carry `type: "tool_use"` on a content block. We scan
+ * backwards from the tail and stop at the first matching line.
+ */
+function lastToolUseAgeMs(transcriptPath, nowMs) {
+    if (transcriptPath === null || transcriptPath.length === 0)
+        return null;
+    if (!existsSync(transcriptPath))
+        return null;
+    let raw;
+    try {
+        raw = readFileSync(transcriptPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    const lines = raw.split("\n");
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i];
+        if (line === undefined || line.length === 0)
+            continue;
+        if (!line.includes('"tool_use"'))
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (entry === null || typeof entry !== "object")
+            continue;
+        const ts = entry["timestamp"]
+            ?? entry["ts"];
+        if (typeof ts !== "string")
+            continue;
+        const parsed = Date.parse(ts);
+        if (Number.isNaN(parsed))
+            continue;
+        return nowMs - parsed;
+    }
+    return null;
+}
+function lastSessionStalledCuePath(repoRoot, sessionId) {
+    return join(repoRoot, ".cairn", "sessions", sessionId, "last-stalled-cue.iso");
+}
+function lastSessionStalledCueMs(repoRoot, sessionId) {
+    const path = lastSessionStalledCuePath(repoRoot, sessionId);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, "utf8").trim();
+        const ms = Date.parse(raw);
+        return Number.isNaN(ms) ? null : ms;
+    }
+    catch {
+        return null;
+    }
+}
+function stampSessionStalledCue(repoRoot, sessionId) {
+    const path = lastSessionStalledCuePath(repoRoot, sessionId);
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, new Date().toISOString(), "utf8");
+    }
+    catch {
+        // best-effort
+    }
+}
 function priorCuePath(repoRoot, sessionId) {
     return join(repoRoot, ".cairn", "sessions", sessionId, "last-stop-cue.json");
 }
@@ -121,6 +211,7 @@ export async function runStopHook() {
     const payload = parseHookPayload(raw);
     const sessionId = typeof payload.session_id === "string" ? payload.session_id : null;
     const cwdInput = typeof payload.cwd === "string" ? payload.cwd : process.cwd();
+    const transcriptPath = typeof payload.transcript_path === "string" ? payload.transcript_path : null;
     const repoRoot = resolveRepoRoot(cwdInput);
     const warnings = [];
     let drained = [];
@@ -176,9 +267,6 @@ export async function runStopHook() {
                     const hint = `## Cairn — ${grad.completed.length} ${noun} graduated\n\n✓ ${ids} → done. Final attestation written.`;
                     reason = reason.length > 0 ? `${reason}\n\n${hint}` : hint;
                 }
-                if (grad.transitioned.length > 0) {
-                    warnings.push(`auto_graduated_review_ready:${grad.transitioned.length}`);
-                }
             }
             catch (err) {
                 warnings.push(`auto_graduate_failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -204,42 +292,73 @@ export async function runStopHook() {
                 warnings.push(`pending_review_scan_failed: ${err instanceof Error ? err.message : String(err)}`);
             }
             // Stalled-task scanner — surfaces tasks stuck in phase=running
-            // with no attestation for 30min+. Catches the failure mode where
-            // the autonomous flow finished the work but skipped spawning the
-            // reviewer subagent (no attestation → auto-graduator never fires
-            // → task accumulates as orphaned). Only fires when no other
-            // higher-priority surface (reviewer hint, ctx threshold) already
-            // owns the reason channel — stalled-task triage is informational
-            // catch-up, not blocking.
+            // with no attestation for 2h+ (raised from 30 min in bug-mine
+            // 0.13.8 / Phase 5 — see CONTEXT.md §2.4 for false-fire mining).
+            // Catches the failure mode where the autonomous flow finished
+            // the work but skipped spawning the reviewer subagent (no
+            // attestation → auto-graduator never fires → task accumulates
+            // as orphaned). Only fires when no other higher-priority surface
+            // (reviewer hint, ctx threshold) already owns the reason channel
+            // — stalled-task triage is informational catch-up, not blocking.
+            //
+            // Three additional gates layered on top of the per-task window:
             //
-            // Per-task suppression window: once a stalled hint fires for a
-            // given task id, suppress re-fires on the same id for 60 min so
-            // the operator isn't asked the same triage question every Stop
-            // tick (bug-mine report #9 — same task flagged 3× in 90s).
+            //   1. Session-activity gate — when the transcript carries a
+            //      `tool_use` event within the last 5 minutes, the AI is
+            //      actively working; suppress entirely.
+            //   2. Per-session rate limit — at most one stalled cue per
+            //      session per hour, total (not per-task). Bug-mine showed
+            //      three active tasks idle = three prompts per hour without
+            //      a global cap.
+            //   3. Per-task throttle — 60 minute suppression window per
+            //      task id so the operator isn't asked the same triage
+            //      question every Stop tick (bug-mine report #9 — same
+            //      task flagged 3× in 90s).
             if (reason.length === 0 && !isFirstTurnWarmup) {
                 try {
-                    const stalled = scanStalledRunningTasks(repoRoot);
-                    const surfaced = stalled.filter((t) => !isStalledFireSuppressed(repoRoot, t.task_id));
-                    if (surfaced.length > 0) {
-                        const reviewDefer = readDeferState(repoRoot, "review");
-                        const suppressed = reviewDefer !== null &&
-                            isDeferActive(reviewDefer, new Date(), {
-                                kind: "task_ids",
-                                values: surfaced.map((t) => t.task_id),
-                            });
-                        if (suppressed) {
-                            warnings.push(`stalled_suppressed_until:${reviewDefer.deferred_at}`);
+                    gcStalledWarnedMarkers(repoRoot);
+                    const lastSessionCue = sessionId !== null
+                        ? lastSessionStalledCueMs(repoRoot, sessionId)
+                        : null;
+                    if (lastSessionCue !== null &&
+                        Date.now() - lastSessionCue < SESSION_STALLED_CUE_WINDOW_MS) {
+                        warnings.push(`stalled_session_rate_limited:${new Date(lastSessionCue).toISOString()}`);
+                    }
+                    else {
+                        const recentToolUseAge = lastToolUseAgeMs(transcriptPath, Date.now());
+                        const sessionActive = recentToolUseAge !== null && recentToolUseAge < SESSION_ACTIVITY_WINDOW_MS;
+                        if (sessionActive) {
+                            warnings.push(`stalled_session_active:${recentToolUseAge}`);
                         }
                         else {
-                            reason = renderStalledTasksHint(surfaced);
-                            for (const t of surfaced)
-                                stampStalledFire(repoRoot, t.task_id);
-                            warnings.push(`stalled_running_tasks:${surfaced.length}`);
+                            const stalled = scanStalledRunningTasks(repoRoot, Date.now(), {
+                                currentSessionId: sessionId,
+                            });
+                            const surfaced = stalled.filter((t) => !isStalledFireSuppressed(repoRoot, t.task_id));
+                            if (surfaced.length > 0) {
+                                const reviewDefer = readDeferState(repoRoot, "review");
+                                const suppressed = reviewDefer !== null &&
+                                    isDeferActive(reviewDefer, new Date(), {
+                                        kind: "task_ids",
+                                        values: surfaced.map((t) => t.task_id),
+                                    });
+                                if (suppressed) {
+                                    warnings.push(`stalled_suppressed_until:${reviewDefer.deferred_at}`);
+                                }
+                                else {
+                                    reason = renderStalledTasksHint(surfaced);
+                                    for (const t of surfaced)
+                                        stampStalledFire(repoRoot, t.task_id);
+                                    if (sessionId !== null)
+                                        stampSessionStalledCue(repoRoot, sessionId);
+                                    warnings.push(`stalled_running_tasks:${surfaced.length}`);
+                                }
+                            }
+                            else if (stalled.length > 0) {
+                                warnings.push(`stalled_window_suppressed:${stalled.length}`);
+                            }
                         }
                     }
-                    else if (stalled.length > 0) {
-                        warnings.push(`stalled_window_suppressed:${stalled.length}`);
-                    }
                 }
                 catch (err) {
                     warnings.push(`stalled_scan_failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -452,22 +571,6 @@ function readTaskPhase(taskDir) {
     }
     return null;
 }
-function checkNeedsReview(specPath) {
-    try {
-        const raw = readFileSync(specPath, "utf8");
-        const fmMatch = raw.match(/^---\r?\n([\s\S]*?)\n---/);
-        if (!fmMatch)
-            return true;
-        const fm = fmMatch[1] ?? "";
-        const m = fm.match(/^needs_review:\s*(true|false)/m);
-        if (m && m[1] === "false")
-            return false;
-        return true;
-    }
-    catch {
-        return true;
-    }
-}
 function scanPendingReviews(repoRoot) {
     const activeDir = join(repoRoot, ".cairn", "tasks", "active");
     if (!existsSync(activeDir))
@@ -492,10 +595,10 @@ function scanPendingReviews(repoRoot) {
         const attestation = join(taskDir, "attestation.yaml");
         if (existsSync(attestation))
             continue;
-        // Finding 4: Opt-in reviewer. Default to true, skip if explicitly false.
-        if (!checkNeedsReview(tightenedSpec))
-            continue;
         // Phase gate — `running` / `tightening` / etc. are not review-ready.
+        // Reviewer is now opt-in (bug-mine 0.13.5); this surface only fires
+        // when an explicit reviewer subagent set phase=ready_for_review and
+        // ended its turn before writing attestation.yaml.
         const phase = readTaskPhase(taskDir);
         if (phase !== null && !REVIEW_READY_PHASES.has(phase))
             continue;
@@ -551,36 +654,51 @@ function stampStalledFire(repoRoot, taskId) {
     }
 }
 /**
- * Scan `tasks/active/` for tasks stuck in `phase: running` with no
- * attestation and no recent activity. The auto-graduator only fires
- * when a reviewer subagent has written attestation.yaml; tasks that
- * were committed manually (or where the autonomous flow skipped the
- * reviewer-spawn step) never graduate. They accumulate silently and
- * resurface only on a fresh session as "wait, why are these still
- * open?".
- *
- * Definition of stalled:
- *   - phase = "running"
- *   - tightened spec exists
- *   - no `attestation.yaml`
- *   - no `subagents/<id>/attestation.yaml` either (else the regular
- *     auto-graduator path will transition it)
- *   - `status.yaml` mtime > 30min ago (recent enough activity stays
- *     under the radar to avoid spamming during in-flight work)
- *   - upper bound 7d so we don't surface long-archived noise that
- *     the operator already mentally retired
- *
- * Returned list drives the Stop-hook hint that asks the operator to
- * triage stalled tasks — close, abort, or keep open while spawning
- * a reviewer.
+ * Drop `.stalled-warned/<task-id>.iso` files for tasks that have since
+ * graduated (now under `tasks/done/`) or vanished entirely. Without
+ * this, GC residue accumulates and the marker count looks alarming
+ * even though every referenced task already shipped. Best-effort —
+ * called on every Stop tick.
  */
-function scanStalledRunningTasks(repoRoot, nowMs = Date.now()) {
+function gcStalledWarnedMarkers(repoRoot) {
+    const dir = join(repoRoot, ".cairn", ".stalled-warned");
+    if (!existsSync(dir))
+        return;
+    const activeDir = join(repoRoot, ".cairn", "tasks", "active");
+    let entries = [];
+    try {
+        entries = readdirSync(dir, { withFileTypes: true, encoding: "utf8" });
+    }
+    catch {
+        return;
+    }
+    for (const e of entries) {
+        if (!e.isFile() || !e.name.endsWith(".iso"))
+            continue;
+        const taskId = e.name.replace(/\.iso$/, "");
+        if (existsSync(join(activeDir, taskId)))
+            continue;
+        try {
+            unlinkSync(join(dir, e.name));
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+}
+function scanStalledRunningTasks(repoRoot, nowMs = Date.now(), opts = { currentSessionId: null }) {
     const activeDir = join(repoRoot, ".cairn", "tasks", "active");
     if (!existsSync(activeDir))
         return [];
     const out = [];
-    const idleThresholdMs = 30 * 60 * 1000;
+    const idleThresholdMs = 2 * 60 * 60 * 1000;
     const upperBoundMs = 7 * 24 * 60 * 60 * 1000;
+    // When a task's last journal write came from a DIFFERENT live session
+    // within this window, treat it as "owned by that session" and don't
+    // surface the stall in the current session. Matches the case where
+    // an operator runs two concurrent Claude Code windows on a single
+    // checkout, each with its own active task.
+    const crossSessionTakeoverMs = 90 * 60 * 1000;
     let entries;
     try {
         entries = readdirSync(activeDir, { withFileTypes: true, encoding: "utf8" });
@@ -652,6 +770,8 @@ function scanStalledRunningTasks(repoRoot, nowMs = Date.now()) {
             continue;
         let title = taskId;
         let module = null;
+        let lastJournalSession = null;
+        let blockedOnOperator = false;
         try {
             const raw = readFileSync(statusPath, "utf8");
             for (const line of raw.split(/\r?\n/)) {
@@ -661,11 +781,36 @@ function scanStalledRunningTasks(repoRoot, nowMs = Date.now()) {
                 const m = line.match(/^module:\s*(.+)$/);
                 if (m && m[1] !== undefined)
                     module = m[1].trim().replace(/^['"]|['"]$/g, "");
+                const ljs = line.match(/^last_journal_session:\s*(.+)$/);
+                if (ljs && ljs[1] !== undefined) {
+                    lastJournalSession = ljs[1].trim().replace(/^['"]|['"]$/g, "");
+                }
+                const bo = line.match(/^blocked_on:\s*(.+)$/);
+                if (bo && bo[1] !== undefined) {
+                    const v = bo[1].trim().replace(/^['"]|['"]$/g, "").toLowerCase();
+                    if (v === "operator")
+                        blockedOnOperator = true;
+                }
             }
         }
         catch {
             // fall through with id-as-title
         }
+        // Session-affinity filter: another session journaled this task
+        // recently — they own it. Skip surfacing in the current session.
+        if (opts.currentSessionId !== null &&
+            opts.currentSessionId.length > 0 &&
+            lastJournalSession !== null &&
+            lastJournalSession !== opts.currentSessionId &&
+            idleMs < crossSessionTakeoverMs) {
+            continue;
+        }
+        // Operator-blocked task: the work itself can't progress without an
+        // external action (e.g. browser repro, manual config). Surfacing
+        // "stalled" interrupts the operator with a triage prompt for a
+        // task they already know is paused.
+        if (blockedOnOperator)
+            continue;
         out.push({
             task_id: taskId,
             title,
@@ -682,9 +827,9 @@ function renderStalledTasksHint(stalled) {
     const lines = [
         `## Cairn — ${stalled.length} stalled ${noun}`,
         ``,
-        `${stalled.length} active ${noun} idle 30min+ with no attestation. ` +
+        `${stalled.length} active ${noun} idle 2h+ with no attestation. ` +
             `Either the autonomous flow skipped the reviewer-spawn step, or the ` +
-            `session was interrupted mid-task. Triage before continuing:`,
+            `session was interrupted mid-task.`,
         ``,
     ];
     for (const t of stalled) {
@@ -692,7 +837,7 @@ function renderStalledTasksHint(stalled) {
         lines.push(`- \`${t.task_id}\` — ${t.title}${mod} (idle ${t.idle_minutes}m)`);
     }
     lines.push("");
-    lines.push("Render this question via `AskUserQuestion` — do not skip:");
+    lines.push("If you reach a stopping point with no obvious continuation, surface to operator (e.g. via `AskUserQuestion`):");
     lines.push("");
     lines.push(`> ${stalled.length} stalled ${noun}. Pick once for all (or address one at a time after):`);
     lines.push(`>`);
@@ -702,26 +847,30 @@ function renderStalledTasksHint(stalled) {
     lines.push(``);
     lines.push("On [a], call `cairn_task_complete({task_id, outcome: \"succeeded\", summary: \"closing stalled task — work landed via prior session\"})` for each id above.");
     lines.push("On [b], dispatch the `reviewer` subagent for each task in turn (one task brief per Task call).");
-    lines.push("On [c], end the turn — the prompt re-fires only when status.yaml stays idle past the next 30min mark.");
+    lines.push("On [c], end the turn — the prompt re-fires only when status.yaml stays idle past the next 2h mark.");
+    lines.push("");
+    lines.push("If you're actively working (Agent dispatch in flight, edits queued), ignore this hint and keep going — it will re-evaluate on the next Stop tick.");
     return lines.join("\n");
 }
 /**
  * Auto-graduate active tasks based on attestation presence.
  *
+ * Self-attest is the default path (bug-mine 0.13.5): the AI calls
+ * `cairn_task_complete({outcome, summary})` and the tool moves the
+ * directory itself. This auto-graduator is the fallback for the rare
+ * case where an opt-in reviewer subagent wrote attestation.yaml but
+ * ended its turn before the explicit close call.
+ *
  * Rules (only acts on tasks with phase=running):
- *   1. Task-root `attestation.yaml` exists                     → succeeded → tasks/done/
- *      (reviewer subagent attested; nothing more to do)
- *   2. ≥1 subagents/<id>/attestation.yaml AND needs_review=false → succeeded → tasks/done/
- *      (trivial task, no reviewer scheduled)
- *   3. ≥1 subagents/<id>/attestation.yaml AND needs_review=true  → ready_for_review
- *      (reviewer hasn't run yet — `scanPendingReviews` will surface a hint)
+ *   1. Task-root `attestation.yaml` exists       → succeeded → tasks/done/
+ *   2. ≥1 subagents/<id>/attestation.yaml        → succeeded → tasks/done/
  *
  * Tasks with no attestation activity stay `running` — they're either
- * still in flight or stalled (Q4 surfaces stall detection separately).
+ * still in flight or stalled (stall detection runs separately).
  */
 function autoGraduateTasks(repoRoot) {
     const activeDir = join(repoRoot, ".cairn", "tasks", "active");
-    const result = { completed: [], transitioned: [] };
+    const result = { completed: [] };
     if (!existsSync(activeDir))
         return result;
     let entries;
@@ -740,7 +889,7 @@ function autoGraduateTasks(repoRoot) {
             continue;
         if (state.phase !== "running")
             continue;
-        if (state.rootAttestation) {
+        if (state.rootAttestation || state.subagentAttestations > 0) {
             const r = completeTask({
                 repoRoot,
                 taskId,
@@ -749,27 +898,6 @@ function autoGraduateTasks(repoRoot) {
             });
             if (r.ok)
                 result.completed.push(taskId);
-            continue;
-        }
-        if (state.subagentAttestations > 0) {
-            if (!state.needsReview) {
-                const r = completeTask({
-                    repoRoot,
-                    taskId,
-                    outcome: "succeeded",
-                    source: "cairn_stop_auto_graduate",
-                });
-                if (r.ok)
-                    result.completed.push(taskId);
-                continue;
-            }
-            const ok = transitionTaskPhase({
-                repoRoot,
-                taskId,
-                newPhase: "ready_for_review",
-            });
-            if (ok)
-                result.transitioned.push(taskId);
         }
     }
     return result;
@@ -841,10 +969,27 @@ function isMissionPhaseDeferActive(repoRoot, missionId, phaseId) {
     if (typeof parsed !== "object" || parsed === null)
         return false;
     const o = parsed;
-    if (o["mission_id"] !== missionId || o["phase_id"] !== phaseId)
-        return false;
+    // Lazy clean: if the marker is for a different mission/phase or its
+    // until-timestamp already passed, unlink it on the read path so we
+    // don't keep evaluating a stale file every Stop tick. Write-side
+    // unlink happens on phase-advance + mission-close; this is the
+    // belt-and-suspenders fallback for projects with markers stranded
+    // pre-fix.
     const until = typeof o["deferred_until"] === "string" ? Date.parse(o["deferred_until"]) : NaN;
-    if (Number.isNaN(until))
+    const expired = Number.isFinite(until) && Date.now() >= until;
+    const mismatch = o["mission_id"] !== missionId || o["phase_id"] !== phaseId;
+    if (expired || (mismatch && Number.isFinite(until) && Date.now() >= until)) {
+        try {
+            unlinkSync(path);
+        }
+        catch {
+            /* best-effort */
+        }
+        return false;
+    }
+    if (mismatch)
+        return false;
+    if (!Number.isFinite(until))
         return false;
     return Date.now() < until;
 }