@davesheffer/hunch 1.39.1 → 1.39.3

package/dist/core/procstart.js

@@ -0,0 +1,244 @@
+/**
+ * When is a live PID NOT the process that took a lock?
+ *
+ * Every cross-process lock here trusts a same-host owner while `kill(pid, 0)`
+ * succeeds — age alone cannot tell a slow writer from a dead one, so a live PID
+ * is authoritative (src/serve/writelock.ts, jsonStore's `.rmw-lock`). That trust
+ * has one hole: PIDs are recycled. A container restart routinely hands the new
+ * `hunch serve` the SAME pid on the SAME hostname, so a lock left by the dead
+ * process names its successor's own pid — provably alive, never taken over, and
+ * every write after it refuses forever (issues #287, #293).
+ *
+ * The disambiguator is IDENTITY, compared by STRING EQUALITY: a lock records the
+ * process-instance token of whoever took it, and the current holder of that pid
+ * is the same process only if its token is byte-identical. No arithmetic, no
+ * ordering, no tolerance — a token either matches or it does not.
+ *
+ * WHY NOT CLOCKS. The previous draft compared the lock file's mtime against
+ * start-time arithmetic. Those are two different clocks: mtime comes from the
+ * FILESYSTEM (which on a network or virtualized volume is another machine's),
+ * start times from the HOST's boot-relative accounting. Filesystem/host skew, an
+ * NTP step forward, or a suspend/resume makes a genuinely live owner look as if
+ * it started after its own lock — a false "reused" that STEALS a live lock and
+ * puts two writers inside the mutex. Reproduced by simply `utimes`-ing a held
+ * lock 30 s into the past. Nothing in this file may read a clock.
+ *
+ * REMAINING GAP. Only linux exposes a spawn-free, stable process-instance id
+ * (`/proc/<pid>/stat` field 22 plus the boot id and the pid/time namespaces). On
+ * macOS and Windows a DIFFERENT live process that recycled the owner's pid
+ * therefore stays "not proven" and keeps the lock until the age rule applies —
+ * today's behaviour, and the safe direction. `ps -o lstart` and PowerShell's
+ * `Get-Process ... StartTime` were rejected: both cost a spawn per probe on the
+ * contended path, and both return locale/TZ-dependent strings we would have to
+ * parse back into a comparable identity. Gating such a probe on age does not
+ * rescue them either: the CONTENDER can read the current holder's start time,
+ * but a verdict needs something to compare it WITH — either a start time the
+ * OWNER recorded when it took the lock (which puts that spawn on every writing
+ * process, not just the contended path) or a start-time-vs-mtime comparison,
+ * i.e. exactly the cross-clock arithmetic rejected above.
+ *
+ * UNSUPPORTED TOPOLOGIES. A linux-written token carries its boot id and its pid
+ * and time namespaces, so a lock written under another boot or another namespace
+ * is now reported as "unprobeable" — the recorded pid number means nothing here,
+ * and the age rule governs, exactly as it does for a foreign host. That covers a
+ * reboot, two machines sharing a hostname over a network volume, two containers
+ * sharing hostname + volume, and a restarted container with a fresh namespace.
+ * That "reported as unprobeable" holds only while OUR OWN token is readable: a
+ * null self token on linux means our own /proc proved nothing, and those records
+ * then get main's pid rule instead of the age rule (no regression from main, but
+ * not the age rule either). CRIU checkpoint/restore is NOT supported: a restored
+ * process keeps its pid but gets a new boot id / namespace and a new starttime,
+ * while our own token is memoized from before the checkpoint — so a restored
+ * holder may judge itself against a token that no longer describes it. Tokenless
+ * records (a legacy pre-token hunch, any non-linux writer, an unreadable /proc)
+ * get main's unchanged pid rule — a live same-host pid keeps its lock, a dead one
+ * is stealable — with exactly one exception, the own-pid + foreign-nonce row
+ * described in `judgeSameHostOwner`, which gets the AGE rule instead of main's
+ * "live forever".
+ */
+import { readFileSync, readlinkSync } from "node:fs";
+/** `starttime` in clock ticks since boot, as the exact decimal STRING the kernel
+ *  printed — it is an identity component, never a quantity, so it is never
+ *  converted to a Number (which would lose precision above 2^53 and invite
+ *  arithmetic). `comm` (field 2) may contain spaces and parentheses, so the
+ *  numeric fields are only unambiguous AFTER the last `)`. starttime is overall
+ *  field 22, i.e. index 19 of that remainder (whose [0] is the state field). */
+export function starttimeTicks(stat) {
+    const close = stat.lastIndexOf(")");
+    if (close < 0)
+        return null;
+    const ticks = stat.slice(close + 1).trim().split(/\s+/)[19];
+    return ticks !== undefined && /^\d+$/.test(ticks) ? ticks : null;
+}
+const realProc = {
+    read: (path) => readFileSync(path, "utf8"),
+    readlink: (path) => readlinkSync(path),
+};
+/** The process-instance token `<bootId>:<pidNsInum>:<timeNsInum>:<starttimeTicks>`
+ *  for `pid` ("self" for us), or `null` when any piece is missing or malformed.
+ *  Linux only, and no spawn: every piece is a file read.
+ *
+ *  The pid namespace is ALWAYS the caller's own (`/proc/self/ns/pid`), including
+ *  when tokenizing another pid: a pid we can see in our `/proc` is by definition
+ *  addressed in our namespace, so that is the namespace the token belongs to.
+ *
+ *  The TIME namespace matters because field 22 is rendered relative to the
+ *  READER's time namespace: the same live process yields different ticks to
+ *  readers in different time namespaces, so a token compared across them would
+ *  read "recycled" for a perfectly healthy owner. Kernels before 5.6 have no
+ *  `/proc/self/ns/time` at all — that one missing link is normalized to "0"
+ *  (every process on such a kernel shares the same, only, time namespace).
+ *
+ *  `/proc` itself can be a view from an ANCESTOR pid namespace (a bind-mounted
+ *  or not-remounted /proc inside a container), in which case `/proc/<pid>` names
+ *  a process by the ancestor's numbering while `kill(pid, 0)` uses ours — two
+ *  different pid spaces silently mixed. `readlink /proc/self` returns our pid AS
+ *  /proc numbers it, so requiring it to equal our own `process.pid` is the cheap
+ *  proof that the mount we are reading is our own namespace's. */
+export function linuxStartToken(pid, io = realProc, selfPid = process.pid) {
+    if (pid !== "self" && (!Number.isInteger(pid) || pid <= 0))
+        return null;
+    try {
+        // Validate our /proc VIEW first — it governs every path below, including the
+        // "self" one (a foreign view makes even our own token describe someone else).
+        if (io.readlink("/proc/self").trim() !== String(selfPid))
+            return null;
+        const bootId = io.read("/proc/sys/kernel/random/boot_id").trim();
+        if (!bootId || !/^[0-9a-fA-F-]+$/.test(bootId))
+            return null;
+        // `readlink /proc/self/ns/pid` reads `pid:[4026531836]`.
+        const pidns = /^pid:\[(\d+)\]$/.exec(io.readlink("/proc/self/ns/pid").trim())?.[1];
+        if (pidns === undefined)
+            return null;
+        let timens;
+        try {
+            timens = /^time:\[(\d+)\]$/.exec(io.readlink("/proc/self/ns/time").trim())?.[1] ?? "";
+        }
+        catch {
+            timens = "0"; // kernel < 5.6: no time namespaces exist, so there is only one
+        }
+        if (timens === "")
+            return null; // the link exists but is not the shape we know
+        const ticks = starttimeTicks(io.read(`/proc/${pid === "self" ? "self" : String(pid)}/stat`));
+        if (ticks === null)
+            return null;
+        return `${bootId}:${pidns}:${timens}:${ticks}`;
+    }
+    catch {
+        return null; // no /proc, hidepid, a pid that died mid-read — all unknown
+    }
+}
+let selfToken;
+/** OUR process-instance token, or `null` off linux / when /proc proves nothing.
+ *  Only a NON-NULL token is memoized: a process's own identity never changes,
+ *  but a transient failure to READ it (a momentarily unreadable /proc) must not
+ *  be frozen into a permanent "we have no identity" for the life of the process. */
+export function selfStartToken() {
+    if (selfToken === undefined || selfToken === null) {
+        const token = process.platform === "linux" ? linuxStartToken("self") : null;
+        if (token !== null)
+            selfToken = token;
+        return token;
+    }
+    return selfToken;
+}
+/** The process-instance token of whoever currently holds `pid`, or `null` when
+ *  that cannot be established (not linux, pid gone, /proc hidden). */
+export function startTokenOf(pid) {
+    if (process.platform !== "linux")
+        return null;
+    if (pid === process.pid)
+        return selfStartToken();
+    return linuxStartToken(pid);
+}
+/** The whole verdict, pure and injectable. String comparison only — no clocks. */
+export function ownerInstance(ownerStart, pid, self = selfStartToken(), tokenOf = startTokenOf, platform = process.platform) {
+    // A legacy or non-linux owner recorded no token: today's behaviour, unchanged.
+    if (ownerStart === undefined || !/^[0-9a-fA-F-]+:\d+:\d+:\d+$/.test(ownerStart))
+        return "unknown";
+    if (self === null) {
+        // We cannot speak the owner's language. ON linux that only means our own
+        // /proc proved nothing (hidepid, no mount, a foreign view): the pre-token pid
+        // rule applies unchanged ("unknown"), because handing a live same-host owner
+        // to the AGE rule would steal a slow writer's lock that was never stealable
+        // before. OFF linux a token-bearing record was written by a DIFFERENT OS
+        // instance that merely shares our hostname and volume (a linux container on
+        // this machine), so its pid number means nothing here: age governs.
+        return platform === "linux" ? "unknown" : "unprobeable";
+    }
+    // Written under another kernel boot or another pid/time namespace: the recorded
+    // pid NUMBER means nothing in ours — a live pid here is a stranger, a dead one
+    // is no evidence of the owner's death. Age governs instead.
+    const prefix = (token) => token.slice(0, token.lastIndexOf(":"));
+    if (prefix(ownerStart) !== prefix(self))
+        return "unprobeable";
+    const now = tokenOf(pid);
+    if (now === null)
+        return "unknown"; // died between probes, or /proc hidden for it
+    return now === ownerStart ? "same" : "recycled";
+}
+/** Nonces of the locks THIS process currently holds.
+ *
+ *  The own-pid fallback for platforms without tokens: when the token path says
+ *  "unknown" and the lock names OUR OWN pid, a nonce we do not hold means the
+ *  lock is not one WE took — most likely a PREDECESSOR that happened to have this
+ *  pid (the container-restart shape) — so the record falls to the age rule
+ *  instead of our own liveness vouching for a corpse forever.
+ *
+ *  This is module state, i.e. per THREAD. `src/` has no `worker_threads` users
+ *  (verified by grep), so every holder in a process shares this set; if a worker
+ *  ever takes these locks, this fallback must be revisited. It is also per MODULE
+ *  INSTANCE: were this module ever loaded twice in one process (a cache-busting
+ *  import, a duplicated dependency), one copy would not recognise the other's
+ *  held nonce and could age-steal its live lock. */
+export const heldLockNonces = new Set();
+/**
+ * THE decision table, shared by `src/serve/writelock.ts` and jsonStore's
+ * `.rmw-lock` so the two locks can never drift apart. Pure: no clock, no fs, no
+ * process state beyond what `env` hands it.
+ */
+export function judgeSameHostOwner(owner, env) {
+    // 1. A lock THIS process holds is never stolen — not by a recycled-pid guess,
+    //    not by age. Our own held nonce outranks every other signal.
+    if (owner.nonce !== undefined && env.heldNonces.has(owner.nonce))
+        return "live";
+    const verdict = ownerInstance(owner.start, owner.pid, env.self, env.tokenOf, env.platform);
+    // 2. The pid number means nothing under this boot/namespace: neither its life
+    //    nor its death is evidence. The caller's age rule governs, as for a
+    //    foreign host.
+    if (verdict === "unprobeable")
+        return "age";
+    // 3. A dead pid whose number IS meaningful here: the owner is gone.
+    if (!env.alive(owner.pid))
+        return "stale";
+    // 4. Alive, but a different process instance holds that pid (the recycled-pid
+    //    hole, proven by string equality).
+    if (verdict === "recycled")
+        return "stale";
+    // 5. Alive and byte-identical: the genuine owner, however old the file looks.
+    if (verdict === "same")
+        return "live";
+    // 6. "unknown": no token on one side or the other. A live pid is never stolen
+    //    on a guess, with one exception — a record naming OUR OWN pid whose nonce
+    //    we do NOT hold (row 1 already returned for one we do). That is the
+    //    container-restart shape: a predecessor with this pid left the lock, we
+    //    are alive, and nobody would ever take it over.
+    //
+    //    WHY "age" AND NOT AN IMMEDIATE STEAL, ON EVERY PLATFORM. A nonce we do
+    //    not hold proves only that the record is not THIS process's lock — NOT
+    //    that whoever wrote it is dead. "Our pid" can be a LIVE NEIGHBOUR's in
+    //    another pid space that happens to share our hostname and our volume: on
+    //    linux, two containers sharing hostname + volume but not the pid namespace
+    //    (k8s sidecars, `--net=host`); off linux, a linux GUEST of this machine
+    //    (WSL2 shares the Windows hostname and /mnt/c by default; Docker Desktop
+    //    bind mounts do the same). main never stole this shape at all — that is
+    //    issue #287's forever-deadlock — so the age rule is what ends the deadlock,
+    //    within the caller's own stale window, without ever stealing a FRESH lock
+    //    that a live writer may still hold.
+    if (owner.pid === env.selfPid && owner.nonce !== undefined)
+        return "age";
+    // A nonce-less own-pid record stays live: there is nothing to compare, and a
+    // live pid is never stolen on a guess.
+    return "live";
+}
+//# sourceMappingURL=procstart.js.map

package/dist/core/reviewqueue.js

@@ -33,7 +33,12 @@ export const READY_MIN_GROUNDED = 0.7;
  *  explicit roadmap/intent entry a human hasn't confirmed — counts as a review draft.
  *  (Enforcement authority is granted INLINE, not by draining a background queue.) */
 export function isReviewDraft(d) {
-    return d.status === "proposed" && !d.provenance.source.includes("human_confirmed");
+    // Agent testimony (agent_recorded) is deliberate intent, not a machine draft: it shows
+    // on the roadmap marked unconfirmed, and a human confirms it with `hunch review
+    // --confirm`. Keeping it out of the draft queue keeps `adopt-drafts` / `auto-review`
+    // from accepting or rejecting it in bulk.
+    return d.status === "proposed" && !d.provenance.source.includes("human_confirmed")
+        && !d.provenance.source.split("+").includes("agent_recorded");
 }
 /** A draft is "ready to confirm" only when the Critic actually audited it (source
  *  includes "verified") AND judged it well-grounded. A high confidence number alone

package/dist/core/served.d.ts

@@ -47,9 +47,12 @@ export interface ServedSummary {
     rows: ServedRow[];
     recent: ServedReceipt[];
 }
-/** Shared observation ledger. Explicit report operations surface failures; only
- * passive delivery/hook callers may degrade to best-effort recording. */
-export declare function withServedDatabase<T>(root: string, run: (db: DatabaseSync) => T): T;
+/** Shared observation ledger. Explicit report operations surface failures and may
+ * pass a longer wait for a competing writer; passive delivery/hook callers keep the
+ * 100 ms default and may degrade to best-effort recording. */
+export declare function withServedDatabase<T>(root: string, run: (db: DatabaseSync) => T, options?: {
+    busyTimeoutMs?: number;
+}): T;
 /** Append delivery receipts. Never throws — a receipt must never cost a delivery. */
 export declare function recordServed(root: string, entries: readonly ServedEntry[]): void;
 /** The ledger, aggregated per record. Never throws; an unreadable ledger reads as empty. */

package/dist/core/served.js

@@ -67,12 +67,15 @@ function ensureReceiptColumns(db) {
         existing.add(name);
     }
 }
-function openServedDb(root) {
+function openServedDb(root, busyTimeoutMs = 100) {
     sqlite ??= loadSqlite();
     const dir = join(root, ".hunch-cache");
     mkdirSync(dir, { recursive: true });
     const db = new sqlite.DatabaseSync(join(dir, "served.db"));
-    db.exec("PRAGMA busy_timeout = 100");
+    // Rollback-journal mode is deliberate: WAL would create and delete -wal/-shm
+    // siblings on every open, which file watchers on `.hunch-cache/served.db*` see
+    // as ledger changes.
+    db.exec(`PRAGMA busy_timeout = ${Math.max(0, Math.trunc(busyTimeoutMs))}`);
     db.exec(`CREATE TABLE IF NOT EXISTS served (
     at TEXT NOT NULL,
     session TEXT,
@@ -85,11 +88,12 @@ function openServedDb(root) {
     ensureReceiptColumns(db);
     return db;
 }
-/** Shared observation ledger. Explicit report operations surface failures; only
- * passive delivery/hook callers may degrade to best-effort recording. */
-export function withServedDatabase(root, run) {
+/** Shared observation ledger. Explicit report operations surface failures and may
+ * pass a longer wait for a competing writer; passive delivery/hook callers keep the
+ * 100 ms default and may degrade to best-effort recording. */
+export function withServedDatabase(root, run, options = {}) {
     assertReportPath(root, ".hunch-cache", "served.db");
-    const db = openServedDb(root);
+    const db = openServedDb(root, options.busyTimeoutMs);
     try {
         return run(db);
     }

package/dist/core/spawnCommand.js

@@ -9,16 +9,48 @@
  * npm/npx launchers run as plain Node scripts (no shell at all). */
 import { existsSync } from "node:fs";
 import { posix, win32 } from "node:path";
-/** cmd.exe quoting for one argument: wrap when it has whitespace or shell
- * metacharacters; double embedded quotes. Good for test/build commands; a
- * deliberately hostile argument still cannot escape because the whole line is
- * passed as one `/s /c "..."` token. */
+/** Quote one argument for a `cmd.exe /d /v:off /s /c "<line>"` launch of a
+ * batch file whose target program parses its command line with the MSVCRT
+ * rules (Node, Python, most native tools).
+ *
+ * Two parsers read the line, and a batch shim that forwards `%*` makes cmd.exe
+ * read it again, so the quoting must mean the same thing to both on every pass:
+ *
+ * - Every non-trivial argument is wrapped in quotes. An embedded quote becomes
+ *   `""` (not `\"`): MSVCRT reads `""` inside a quoted argument as one literal
+ *   quote, and cmd.exe sees two toggles, so its quote state never drifts from
+ *   the argument boundaries and `& | < > ( ) ^` always stay inside quotes.
+ *   A `\"` would look escaped to MSVCRT but end the quoted region for cmd.exe.
+ * - Backslashes are literal except before a quote, so a run of backslashes that
+ *   precedes an embedded or closing quote is doubled.
+ * - `%` expands even inside quotes. It is emitted as `"^%"`: the quote closes,
+ *   the caret escapes the percent outside quotes (cmd.exe removes the caret),
+ *   and the quote reopens. MSVCRT joins the pieces back into one argument.
+ *   Expansion of a forwarded `%*` is not rescanned, so a shim pass is safe too.
+ *
+ * A line break cannot be carried: cmd.exe ends the command at it and silently
+ * drops the rest, so such an argument is refused rather than truncated. */
 function quoteForCmd(arg) {
-    if (arg === "")
-        return '""';
-    if (!/[\s"&|<>^()%!]/.test(arg))
+    if (/[\r\n]/.test(arg))
+        throw new Error("a .cmd/.bat launcher cannot receive an argument containing a line break");
+    if (arg !== "" && /^[A-Za-z0-9_\-.:/\\@+]+$/.test(arg))
         return arg;
-    return `"${arg.replace(/"/g, '""')}"`;
+    let out = '"';
+    let backslashes = 0;
+    for (const ch of arg) {
+        if (ch === "\\") {
+            backslashes++;
+            continue;
+        }
+        if (ch === '"')
+            out += "\\".repeat(backslashes * 2) + '""';
+        else if (ch === "%")
+            out += "\\".repeat(backslashes * 2) + '"^%"';
+        else
+            out += "\\".repeat(backslashes) + ch;
+        backslashes = 0;
+    }
+    return out + "\\".repeat(backslashes * 2) + '"';
 }
 export function resolveSpawnCommand(command, options = {}) {
     const platform = options.platform ?? process.platform;
@@ -49,7 +81,7 @@ export function resolveSpawnCommand(command, options = {}) {
                 continue;
             if (/\.(cmd|bat)$/i.test(candidate)) {
                 const line = [candidate, ...args].map(quoteForCmd).join(" ");
-                return { file: env.ComSpec ?? "cmd.exe", args: ["/d", "/s", "/c", `"${line}"`], windowsVerbatimArguments: true, how: "cmd-shim" };
+                return { file: env.ComSpec ?? "cmd.exe", args: ["/d", "/v:off", "/s", "/c", `"${line}"`], windowsVerbatimArguments: true, how: "cmd-shim" };
             }
             if (ext === "" && !/\.(exe|com)$/i.test(candidate))
                 continue; // an extensionless file is not runnable on Windows

package/dist/core/stateHttp.d.ts

@@ -40,7 +40,7 @@ export declare const HttpHealthSchema: z.ZodObject<{
     ok: z.ZodBoolean;
     version: z.ZodString;
     protocol: z.ZodLiteral<"nuryel.state/1">;
-    partitions: z.ZodArray<z.ZodString>;
+    partitions: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;
 export declare const HttpReadResponseSchema: z.ZodObject<{
     conventions: z.ZodOptional<z.ZodObject<{

package/dist/core/stateHttp.js

@@ -6,7 +6,9 @@ export const HttpCapabilitiesSchema = CapabilityNegotiationSchema.extend({
     principal: PrincipalSchema.pick({ id: true, kind: true, grants: true }),
 }).strict();
 export const HttpHealthSchema = z.object({
-    ok: z.boolean(), version: z.string(), protocol: z.literal(STATE_CONTRACT_VERSION), partitions: z.array(z.string()),
+    ok: z.boolean(), version: z.string(), protocol: z.literal(STATE_CONTRACT_VERSION),
+    // Present only when the request carried a valid credential.
+    partitions: z.array(z.string()).optional(),
 }).strict();
 // Delivery has its own richer assertion and receipt checks in delivery.ts.
 export const HttpReadResponseSchema = ReadResponseSchema.extend({ envelope: z.record(z.string(), z.unknown()) });

package/dist/core/taskReport.d.ts

@@ -206,6 +206,8 @@ export interface LessonHistory {
 export declare function aliasReportTask(root: string, aliasId: string, taskId: string): void;
 /** The task an aliased prompt identity reports to, or the identity itself. */
 export declare function resolveReportTask(root: string, id: string): string;
+/** Whether a task id names a real task of THIS repository/worktree. */
+export declare function reportTaskExists(root: string, id: string): boolean;
 /** The lookup is derived, never evidence. Backfill at most 64 events and
  * 512 KB per read. Parse outside the writer transaction so a history view cannot
  * hold the writer lock while validating a large legacy ledger. */

package/dist/core/taskReport.js

@@ -99,7 +99,10 @@ const TaskSchema = z.object({
 export const LessonReferenceSchema = z.object({
     kind: safeText(64), record_id: safeText(512), content_hash: hashSchema.optional(),
 }).strict();
-function taskDb(root, run) {
+/** Explicit report operations wait out a competing writer; hook/delivery paths keep
+ * the ledger's 100 ms default so a receipt never costs a delivery. */
+const PATIENT_BUSY_MS = 5_000;
+function taskDb(root, run, patient = false) {
     return withServedDatabase(root, (db) => {
         db.exec(`CREATE TABLE IF NOT EXISTS report_tasks (
       task_id TEXT PRIMARY KEY, scope TEXT NOT NULL, body TEXT NOT NULL
@@ -115,10 +118,13 @@ function taskDb(root, run) {
     );
     CREATE INDEX IF NOT EXISTS report_record_lookup ON report_record_links(kind, record_id, content_hash);
     CREATE TABLE IF NOT EXISTS report_history_progress (id INTEGER PRIMARY KEY CHECK(id = 1), through_rowid INTEGER NOT NULL);
-    INSERT OR IGNORE INTO report_history_progress VALUES (1, 0);
     CREATE TABLE IF NOT EXISTS report_task_aliases (alias_id TEXT PRIMARY KEY, task_id TEXT NOT NULL);`);
+        // Seed only when the row is missing: an unconditional INSERT made every pure
+        // read take the writer lock. INSERT OR IGNORE still settles the race.
+        if (!db.prepare("SELECT 1 FROM report_history_progress WHERE id = 1").get())
+            db.exec("INSERT OR IGNORE INTO report_history_progress VALUES (1, 0)");
         return run(db);
-    });
+    }, patient ? { busyTimeoutMs: PATIENT_BUSY_MS } : {});
 }
 /** A prompt identity that reports to another prompt's task: a host notification
  * turn continues the session's latest task instead of opening a row. Explicit,
@@ -134,6 +140,11 @@ export function aliasReportTask(root, aliasId, taskId) {
 export function resolveReportTask(root, id) {
     return taskDb(root, db => db.prepare("SELECT task_id FROM report_task_aliases WHERE alias_id = ?").get(id)?.task_id ?? id);
 }
+/** Whether a task id names a real task of THIS repository/worktree. */
+export function reportTaskExists(root, id) {
+    TaskIdSchema.parse(id);
+    return taskDb(root, db => !!db.prepare("SELECT 1 FROM report_tasks WHERE task_id = ? AND scope IN (?, ?, ?)").get(id, ...scopePair(root)));
+}
 function deliveryRecords(kind, body) {
     if (kind === "save")
         return [ReportSaveSchema.parse(body).record];
@@ -298,10 +309,12 @@ function newestSessionTask(db, root, sessionKey) {
 export function latestSessionTask(root, sessionKey) {
     return taskDb(root, db => newestSessionTask(db, root, sessionKey));
 }
-/** Check-starts still inside their own timeout plus the grace window, minus the
- * results that arrived: while positive, a runner may still deliver a result. */
+/** Check-starts still inside their own timeout plus the grace window whose own
+ * result has not arrived: while positive, a runner may still deliver a result.
+ * A result clears the start it names (its `check_id`) and nothing else — netting
+ * results against starts let a finished old check hide a running new one. */
 function pendingChecks(db, taskId) {
-    const { pending } = db.prepare(`SELECT SUM(CASE WHEN kind = 'check-start' AND (julianday('now') - julianday(at)) * 86400000 < COALESCE(json_extract(body, '$.timeout_ms'), ${MAX_PENDING_CHECK_MS}) + ${CHECK_RESULT_GRACE_MS} THEN 1 WHEN kind = 'check' AND json_extract(body, '$.check_id') IS NOT NULL THEN -1 ELSE 0 END) AS pending FROM report_events WHERE task_id = ?`).get(taskId);
+    const { pending } = db.prepare(`SELECT COUNT(*) AS pending FROM report_events s WHERE s.task_id = ? AND s.kind = 'check-start' AND (julianday('now') - julianday(s.at)) * 86400000 < COALESCE(json_extract(s.body, '$.timeout_ms'), ${MAX_PENDING_CHECK_MS}) + ${CHECK_RESULT_GRACE_MS} AND NOT EXISTS (SELECT 1 FROM report_events c WHERE c.task_id = s.task_id AND c.kind = 'check' AND json_extract(c.body, '$.check_id') = s.event_id)`).get(taskId);
     return pending ?? 0;
 }
 /** Tasks of a session that an earlier prompt left open are over once the
@@ -353,6 +366,9 @@ function appendEvent(root, taskId, kind, body, eventId) {
     if (!/^(hev|hocc)_[a-f0-9]{24}$/.test(id))
         throw new Error("invalid report event identity");
     const contentHash = reportHash(body);
+    // Explicit CLI/agent operations; passive observers (delivery, save, refusal,
+    // conformance) keep the default so an observation never costs a delivery.
+    const patient = kind === "check-start" || kind === "check" || kind === "claim";
     return taskDb(root, db => transaction(db, () => {
         const task = readTask(db, root, taskId);
         const prior = db.prepare("SELECT task_id, kind, content_hash FROM report_events WHERE event_id = ?").get(id);
@@ -408,7 +424,7 @@ function appendEvent(root, taskId, kind, body, eventId) {
         const seq = Number(inserted.lastInsertRowid);
         db.prepare("UPDATE report_history_progress SET through_rowid = ? WHERE id = 1 AND through_rowid = ?").run(seq, seq - 1);
         return id;
-    }));
+    }), patient);
 }
 /** The record revisions among `records` that this task has not received before.
  * Powers the one-line "Hunch recalled …" indication on a lesson's FIRST delivery
@@ -472,12 +488,32 @@ export function recordReportConformance(root, taskId, conformance) {
         throw new Error("rule evaluation does not name a record revision delivered in this task");
     return appendEvent(root, taskId, "conformance", value);
 }
+/** SQLITE_BUSY (5) / SQLITE_LOCKED (6); node:sqlite carries the extended code. */
+function isBusyError(error) {
+    const code = error.errcode;
+    if (typeof code === "number")
+        return (code & 0xff) === 5 || (code & 0xff) === 6;
+    return /database is locked/i.test(error?.message ?? "");
+}
 /** Only the local runner calls this. MCP never accepts a claimed successful check. */
 export function recordReportCheck(root, taskId, check) {
     const value = ReportCheckSchema.parse(check);
     if (!value.check_id)
         throw new Error("verification result requires a reserved check identity");
-    return appendEvent(root, taskId, "check", value, `hev_${reportHash({ taskId, check: value.check_id }).slice(7, 31)}`);
+    const id = `hev_${reportHash({ taskId, check: value.check_id }).slice(7, 31)}`;
+    // A result that took minutes to produce must not be lost to a busy ledger. The
+    // write is idempotent (deterministic id; appendEvent returns the existing id for
+    // identical content), so a retry is safe. Each attempt already waits out
+    // PATIENT_BUSY_MS in BEGIN IMMEDIATE; no sleep between them.
+    for (let attempt = 1;; attempt++) {
+        try {
+            return appendEvent(root, taskId, "check", value, id);
+        }
+        catch (error) {
+            if (attempt >= 3 || !isBusyError(error))
+                throw error;
+        }
+    }
 }
 /** A start without a result blocks completion only while the runner could still
  * deliver one: its own timeout plus a minute of grace. After that the runner is
@@ -509,14 +545,13 @@ export function finishReportTask(root, taskId, state = "completed", options = {}
             return task;
         }
         if (state === "completed") {
-            const { pending } = db.prepare(`SELECT SUM(CASE WHEN kind = 'check-start' AND (julianday('now') - julianday(at)) * 86400000 < COALESCE(json_extract(body, '$.timeout_ms'), ${MAX_PENDING_CHECK_MS}) + ${CHECK_RESULT_GRACE_MS} THEN 1 WHEN kind = 'check' AND json_extract(body, '$.check_id') IS NOT NULL THEN -1 ELSE 0 END) AS pending FROM report_events WHERE task_id = ?`).get(taskId);
-            if ((pending ?? 0) > 0)
+            if (pendingChecks(db, taskId) > 0)
                 throw new Error("verification is still running or was interrupted; wait for its result or close the task as interrupted");
         }
         const finished = TaskSchema.parse({ ...task, state, finished_at: new Date().toISOString(), closed_by: by });
         db.prepare("UPDATE report_tasks SET body = ? WHERE task_id = ?").run(JSON.stringify(finished), taskId);
         return finished;
-    }));
+    }), by === "agent");
 }
 /** A report with no observation of any kind. Presentation surfaces may stay
  * silent for it; the task row itself is retained so "never touched Hunch" is

package/dist/core/taskReportEvidence.js

@@ -197,6 +197,8 @@ export function runReportConformance(root, store, taskId) {
  * not a verdict. */
 export const DEFAULT_CHECK_TIMEOUT_MS = 15 * 60_000;
 export const MAX_CHECK_TIMEOUT_MS = 6 * 60 * 60_000;
+/** After the command itself exits, everything it wrote is already in the pipe; the window only lets those buffered chunks be read before settling. */
+const EXIT_DRAIN_MS = 500;
 /** A deliberately explicit command wrapper. The caller chooses the command;
  * reports never execute commands automatically to validate submitted claims. */
 export async function runReportCheck(root, taskId, command, label, timeoutMs = DEFAULT_CHECK_TIMEOUT_MS, options = {}) {
@@ -216,11 +218,33 @@ export async function runReportCheck(root, taskId, command, label, timeoutMs = D
         // Windows launchers (npx.cmd, npm.cmd, other .cmd/.bat shims) cannot be spawned
         // without a shell; resolve them first so a check actually runs instead of
         // silently recording exit_code null (fnd: every Windows card said "no result").
-        const resolved = resolveSpawnCommand(command);
-        const child = spawn(resolved.file, resolved.args, { cwd: root, shell: false, stdio: ["ignore", "pipe", "pipe"], windowsHide: true, detached: process.platform !== "win32", windowsVerbatimArguments: resolved.windowsVerbatimArguments === true });
         const stdout = createHash("sha256"), stderr = createHash("sha256");
+        const launchFailure = (error) => {
+            // A launch failure is a result the user must see (ENOENT is the common
+            // one); it is hashed like any other stderr and streamed to the caller.
+            const text = error instanceof Error ? error.message : String(error);
+            return Buffer.from(`hunch: could not start ${JSON.stringify(command[0])}: ${text}\n`);
+        };
+        const started = (() => {
+            try {
+                const resolved = resolveSpawnCommand(command);
+                return spawn(resolved.file, resolved.args, { cwd: root, shell: false, stdio: ["ignore", "pipe", "pipe"], windowsHide: true, detached: process.platform !== "win32", windowsVerbatimArguments: resolved.windowsVerbatimArguments === true });
+            }
+            catch (error) {
+                // An argument the launcher cannot carry, or a synchronous spawn refusal
+                // (EINVAL for a batch file), is the same visible failure as ENOENT.
+                return launchFailure(error);
+            }
+        })();
+        if (Buffer.isBuffer(started)) {
+            stderr.update(started);
+            options.onStderr?.(started);
+            resolveResult({ code: null, timedOut: false, cancelled: false, hash: reportHash({ stdout: stdout.digest("hex"), stderr: stderr.digest("hex") }) });
+            return;
+        }
+        const child = started;
         let timedOut = false, cancelled = false, settled = false;
-        let cleanupTimer;
+        let cleanupTimer, drainTimer;
         const settle = (code) => {
             if (settled)
                 return;
@@ -229,6 +253,8 @@ export async function runReportCheck(root, taskId, command, label, timeoutMs = D
             options.signal?.removeEventListener("abort", cancel);
             if (cleanupTimer)
                 clearTimeout(cleanupTimer);
+            if (drainTimer)
+                clearTimeout(drainTimer);
             child.stdout.destroy();
             child.stderr.destroy();
             resolveResult({ code, timedOut, cancelled, hash: reportHash({ stdout: stdout.digest("hex"), stderr: stderr.digest("hex") }) });
@@ -267,15 +293,25 @@ export async function runReportCheck(root, taskId, command, label, timeoutMs = D
             options.onStderr?.(chunk);
         } });
         child.once("error", (error) => {
-            // A launch failure is a result the user must see (ENOENT is the common
-            // one); it is hashed like any other stderr and streamed to the caller.
-            const message = Buffer.from(`hunch: could not start ${JSON.stringify(command[0])}: ${error.message}\n`);
+            const message = launchFailure(error);
             if (!settled) {
                 stderr.update(message);
                 options.onStderr?.(message);
             }
             settle(null);
         });
+        // `close` waits for EVERY holder of the stdio pipes; a command that leaves a
+        // helper inheriting stdout (dev server, watcher) and exits 0 would otherwise
+        // burn the whole budget and be recorded as a timeout (#304). The command's own
+        // `exit` is the result; settle on it after a short drain of the buffered output.
+        child.once("exit", code => {
+            if (settled)
+                return;
+            // The command finished inside its budget; the drain window is not part of it.
+            if (code !== null && !timedOut)
+                clearTimeout(timer);
+            drainTimer = setTimeout(() => settle(code), EXIT_DRAIN_MS);
+        });
         child.once("close", code => settle(code));
         options.signal?.addEventListener("abort", cancel, { once: true });
         if (options.signal?.aborted)