@davesheffer/hunch 1.39.2 → 1.39.3

package/dist/core/procstart.d.ts

@@ -0,0 +1,94 @@
+/** `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 declare function starttimeTicks(stat: string): string | null;
+/** Reader seam so the pure token logic is testable off linux. */
+interface ProcReader {
+    read: (path: string) => string;
+    readlink: (path: string) => string;
+}
+/** 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 declare function linuxStartToken(pid: number | "self", io?: ProcReader, selfPid?: number): string | null;
+/** 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 declare function selfStartToken(): string | null;
+/** The process-instance token of whoever currently holds `pid`, or `null` when
+ *  that cannot be established (not linux, pid gone, /proc hidden). */
+export declare function startTokenOf(pid: number): string | null;
+/** What the recorded owner is, relative to whoever holds its pid NOW.
+ *  - `same`        — byte-identical token: the genuine owner, still running.
+ *  - `recycled`    — the pid is held by a DIFFERENT process instance.
+ *  - `unprobeable` — the pid number carries no meaning here (another boot, another
+ *                    namespace, or a token read on a platform that has none), so
+ *                    neither "alive" nor "dead" is evidence.
+ *  - `unknown`     — no token recorded, or none readable now: not proven either way. */
+export type InstanceVerdict = "same" | "recycled" | "unprobeable" | "unknown";
+/** The whole verdict, pure and injectable. String comparison only — no clocks. */
+export declare function ownerInstance(ownerStart: string | undefined, pid: number, self?: string | null, tokenOf?: (pid: number) => string | null, platform?: NodeJS.Platform): InstanceVerdict;
+/** 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 declare const heldLockNonces: Set<string>;
+/** What a contender should do about a SAME-HOST lock owner.
+ *  - `stale` — provably not the owner's process any more: take it over.
+ *  - `live`  — authoritative, however old the file looks: never steal it.
+ *  - `age`   — nothing is proven; fall back to the caller's own age rule. */
+export type SameHostVerdict = "stale" | "live" | "age";
+/** The parts of a lock record this decision reads. Both lock formats supply it. */
+export interface SameHostOwner {
+    pid: number;
+    start?: string;
+    nonce?: string;
+}
+/** Everything the decision consults, injected so every row is unit-testable. */
+export interface SameHostEnv {
+    alive: (pid: number) => boolean;
+    self: string | null;
+    tokenOf: (pid: number) => string | null;
+    platform: NodeJS.Platform;
+    selfPid: number;
+    heldNonces: ReadonlySet<string>;
+}
+/**
+ * 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 declare function judgeSameHostOwner(owner: SameHostOwner, env: SameHostEnv): SameHostVerdict;
+export {};

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/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/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 = {}) {
@@ -242,7 +244,7 @@ export async function runReportCheck(root, taskId, command, label, timeoutMs = D
         }
         const child = started;
         let timedOut = false, cancelled = false, settled = false;
-        let cleanupTimer;
+        let cleanupTimer, drainTimer;
         const settle = (code) => {
             if (settled)
                 return;
@@ -251,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") }) });
@@ -296,6 +300,18 @@ export async function runReportCheck(root, taskId, command, label, timeoutMs = D
             }
             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)

package/dist/core/taskReportHook.js

@@ -5,7 +5,7 @@ import { join } from "node:path";
 import { findRoot } from "./paths.js";
 import { canonicalReportRoot } from "./taskReportPaths.js";
 import { isCredentialFreeText } from "./types.js";
-import { aliasReportTask, continuationLinks, finishReportTask, isEmptyTaskReport, latestSessionTask, readTaskReport, recordReportRefusal, reportHash, reportPresentationEnabled, resolveReportTask, settleSessionTasks, startReportTask } from "./taskReport.js";
+import { aliasReportTask, continuationLinks, finishReportTask, isEmptyTaskReport, latestSessionTask, readTaskReport, recordReportRefusal, reportHash, reportPresentationEnabled, reportTaskExists, resolveReportTask, settleSessionTasks, startReportTask } from "./taskReport.js";
 import { reportSourceSnapshot } from "./taskReportEvidence.js";
 import { renderTaskReport } from "./taskReportRender.js";
 /** The exact task identity a native host prompt maps to. */
@@ -85,7 +85,19 @@ function identity(root, provider, event) {
 export function hookReportTaskId(root, provider, event) {
     try {
         const id = identity(root, provider, event);
-        return id === "legacy" ? null : id;
+        if (!id || id === "legacy")
+            return null;
+        // A subagent's tool call carries the prompt's session and prompt identity
+        // plus its own agent_id, and no prompt ever opens a task under that
+        // identity (subagents never fire UserPromptSubmit): its deliveries and
+        // denials belong to the prompt's task. An agent-scoped task that DOES
+        // exist keeps its own evidence, and without a prompt task nothing is guessed.
+        if (event.agent_id && event.session_id && event.prompt_id && !reportTaskExists(root, id)) {
+            const parent = resolveReportTask(root, promptTaskId(root, event.session_id, event.prompt_id, null, provider));
+            if (reportTaskExists(root, parent))
+                return parent;
+        }
+        return id;
     }
     catch {
         return null;

package/dist/core/workspace.d.ts

@@ -253,4 +253,13 @@ export interface PrunePlan {
 /** Why a branch must not be pruned, or null when it may. The rules are the documented ones:
  *  proven merged, not the default branch, worktree (if any) clean, unlocked and present. */
 export declare function pruneRefusal(b: WorkspaceBranch, wt: WorkspaceWorktree | undefined): string | null;
+/** The repo-relative path of a workspace record committed into the PUBLIC `.hunch/`. */
+export declare function publicWorkspaceRecordPath(id: string): string;
+/** The manual recipe for removing a workspace record that lives in the repo-tracked
+ *  `.hunch/`. Hunch's own publication pump is deliberately ADDITIVE — it refuses to stage
+ *  a tracked deletion so a stale clone can never erase team history (the same stance
+ *  `compact --apply` takes) — so deleting such a record here would strand `D .hunch/…` in
+ *  the working tree and wedge every later auto-commit. The removal is a normal, reviewable
+ *  git change the human makes instead. */
+export declare function publicWorkspaceRemovalRecipe(id: string, machine: string): string;
 export declare function planPrune(live: Workspace, others: readonly Workspace[]): PrunePlan;

package/dist/core/workspace.js

@@ -346,6 +346,21 @@ export function pruneRefusal(b, wt) {
         return wt.dirty === null ? "worktree state could not be read" : "worktree has uncommitted or untracked changes";
     return null;
 }
+/** The repo-relative path of a workspace record committed into the PUBLIC `.hunch/`. */
+export function publicWorkspaceRecordPath(id) {
+    return `.hunch/workspaces/${id}.json`;
+}
+/** The manual recipe for removing a workspace record that lives in the repo-tracked
+ *  `.hunch/`. Hunch's own publication pump is deliberately ADDITIVE — it refuses to stage
+ *  a tracked deletion so a stale clone can never erase team history (the same stance
+ *  `compact --apply` takes) — so deleting such a record here would strand `D .hunch/…` in
+ *  the working tree and wedge every later auto-commit. The removal is a normal, reviewable
+ *  git change the human makes instead. */
+export function publicWorkspaceRemovalRecipe(id, machine) {
+    const path = publicWorkspaceRecordPath(id);
+    return `  · git rm ${path}   (never committed? delete the file instead)\n`
+        + `  · git commit -m "hunch: forget workspace ${machine}"`;
+}
 export function planPrune(live, others) {
     const mine = pruneStepsFor(live, { skip: pruneRefusal });
     const plan = { local: mine.steps, others: {}, skipped: mine.skipped };