@davesheffer/hunch 1.39.2 → 1.40.0

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.d.ts

@@ -21,6 +21,25 @@ export declare function hookReportTaskId(root: string, provider: HookProvider, e
  * No raw prompt, host session identifier, or transcript is retained; a repository
  * that opts in (`taskTitles: "prompt"`) keeps only a bounded first-line title. */
 export declare function startHookReport(root: string, provider: HookProvider, event: HunchHookInput): string | null;
+/** The hook already opened the task, so the model needs no start call: the only
+ * thing start used to supply was verification_argv, and the launcher is printed
+ * inline here. Identical in substance for EVERY hook provider that reaches this
+ * function; the one variation is capability-driven, never host-named — where the
+ * host is not PROVEN to close the task it opened (HOST_CLOSES_TASK) nobody but the
+ * next prompt's settle would close it, so finish stays mandatory there. Elsewhere
+ * finish is CONDITIONAL: ~87 start/finish round trips a day mostly returned "No
+ * task-linked delivery observed", and the host's Stop hook closes the task and
+ * shows the evidence either way. FAILS OPEN (con_03a0b94b2e): if the launcher
+ * cannot be computed, fall back to asking for the start call — that path is then
+ * the only source of both the launcher and the finish instruction, so it carries
+ * its own finish sentence. */
+export declare function taskInstruction(task: {
+    task_id: string;
+    title: string;
+}, cwdLiteral: string, provider: HookProvider, launcher?: () => {
+    shell: string;
+    note?: string;
+}): string;
 /** A prompt the host generated to report a background command's completion,
  * not something the user typed. */
 export declare function isNotificationPrompt(prompt: string | undefined): boolean;

package/dist/core/taskReportHook.js

@@ -5,9 +5,10 @@ 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";
+import { verificationLauncher } from "./verifyLauncher.js";
 /** The exact task identity a native host prompt maps to. */
 export function promptTaskId(root, sessionId, promptId, agentId = null, provider = "claude") {
     return `htask_${reportHash([canonicalReportRoot(root), provider, sessionId, promptId, agentId]).slice(7, 31)}`;
@@ -15,6 +16,16 @@ export function promptTaskId(root, sessionId, promptId, agentId = null, provider
 /** Hosts whose hooks deliver a native per-prompt identity (Claude Code's
  * prompt_id, Codex's turn_id). Others get no task from a hook. */
 const NATIVE_PROMPT_HOSTS = new Set(["claude", "codex"]);
+/** Hosts PROVEN to close a task they opened, so its evidence is shown without
+ * the agent's cooperation and the finish call may be made conditional. A host
+ * belongs here only when BOTH hold: (1) `hunch init` wires its stop event, and
+ * (2) its stop payload carries the same native prompt identity the task was
+ * opened under, so `closeHookTask` actually resolves that task and closes it.
+ * (2) is what excludes a host with a stop hook but no native identity: outside
+ * NATIVE_PROMPT_HOSTS `nativeHookCwd` returns null on Stop, so nothing is
+ * closed and a skipped finish would leak an open task. Everywhere else finish
+ * stays mandatory. Adding a host requires proving both, never its name. */
+const HOST_CLOSES_TASK = new Set(["claude", "codex"]);
 const NATIVE_TASK_TITLE = "Assistant task";
 const GENERIC_TASK_TITLES = new Set(["Assistant task", "Claude task"]);
 const TASK_TITLE_MAX = 72;
@@ -85,7 +96,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;
@@ -121,7 +144,7 @@ export function startHookReport(root, provider, event) {
             // this prompt's Stop and hook observations report to that task.
             if (previous && previous.task_id !== id && isNotificationPrompt(event.prompt) && previous.closed_by !== "agent") {
                 aliasReportTask(root, id, previous.task_id);
-                return taskInstruction(previous, cwdLiteral);
+                return taskInstruction(previous, cwdLiteral, provider);
             }
             const continued = previous && previous.task_id !== id ? continuationLinks(previous) : null;
             if (continued)
@@ -142,10 +165,35 @@ export function startHookReport(root, provider, event) {
             throw error;
         task = existing;
     }
-    return taskInstruction(task, cwdLiteral);
+    return taskInstruction(task, cwdLiteral, provider);
 }
-function taskInstruction(task, cwdLiteral) {
-    return `Hunch has opened this prompt's report: ${task.task_id}. Reuse this exact ID for this prompt. Call hunch_task(action: "start", task_id: "${task.task_id}", title: ${JSON.stringify(task.title)}, cwd: ${cwdLiteral}) to obtain verification_argv; do not create another report. Pass this task_id and cwd: ${cwdLiteral} to hunch_context and decision/correction/finding captures, and pass the same cwd when finishing with hunch_task before responding. A host Stop notice will show the evidence even if no task-linked memory was observed.`;
+/** The hook already opened the task, so the model needs no start call: the only
+ * thing start used to supply was verification_argv, and the launcher is printed
+ * inline here. Identical in substance for EVERY hook provider that reaches this
+ * function; the one variation is capability-driven, never host-named — where the
+ * host is not PROVEN to close the task it opened (HOST_CLOSES_TASK) nobody but the
+ * next prompt's settle would close it, so finish stays mandatory there. Elsewhere
+ * finish is CONDITIONAL: ~87 start/finish round trips a day mostly returned "No
+ * task-linked delivery observed", and the host's Stop hook closes the task and
+ * shows the evidence either way. FAILS OPEN (con_03a0b94b2e): if the launcher
+ * cannot be computed, fall back to asking for the start call — that path is then
+ * the only source of both the launcher and the finish instruction, so it carries
+ * its own finish sentence. */
+export function taskInstruction(task, cwdLiteral, provider, launcher = verificationLauncher) {
+    const head = `Hunch has already opened this prompt's report: ${task.task_id}. Reuse this exact ID; never open another report. Pass this task_id and cwd: ${cwdLiteral} to hunch_context and decision/correction/finding captures.`;
+    let verify;
+    try {
+        const l = launcher();
+        verify = ` Never call hunch_task start for it. For checks, run: ${l.shell} task verify ${task.task_id} -- <command> [arguments]${l.note ?? ""}. Default budget 15 min; add --timeout <seconds> before -- for longer suites.`;
+    }
+    catch {
+        return `${head} Call hunch_task(action: "start", task_id: "${task.task_id}", title: ${JSON.stringify(task.title)}, cwd: ${cwdLiteral}) to obtain verification_argv, and finish with hunch_task(action: "finish", task_id, cwd) before responding and show its card.`;
+    }
+    const used = `this task used Hunch (a hunch_* call on this ID, a task verify check, Hunch hook context you acted on, or an application to claim)`;
+    const finish = HOST_CLOSES_TASK.has(provider)
+        ? ` ONLY if ${used}, call hunch_task(action: "finish", task_id, cwd) before responding and show its card; otherwise skip it — this host's stop hook closes the task and shows the evidence.`
+        : ` No stop hook closes this task, so finish it yourself whether or not ${used}: call hunch_task(action: "finish", task_id, cwd) before responding and show its card.`;
+    return `${head}${verify}${finish}`;
 }
 /** The session key a hook event maps to: a hash of (root, provider, session,
  * agent), never the identifier itself. Null without a host session. */

package/dist/core/verifyLauncher.d.ts

@@ -0,0 +1,21 @@
+/** Structured argv is authoritative; the shell hint uses literal quoting, and
+ * `note` disambiguates it where one platform has two incompatible shells. */
+export declare function verificationLauncher(): {
+    argv: string[];
+    shell: string;
+    note: string;
+};
+/** `metaUrl` is the module running (a `.ts` source checkout needs the tsx
+ * loader; a published `.js` build needs nothing) and `resolve` is that
+ * module's `import.meta.resolve`. Callers in sibling directories (src/core,
+ * src/mcp) resolve the same `../cli/index.{ts|js}`, but each must pass ITS OWN
+ * import.meta so the dev/published discrimination stays honest. The loader is
+ * resolved ONLY on the source path: `import.meta.resolve` throws for a package
+ * that is not installed, and `tsx` is a devDependency absent from every
+ * published install (#261). `platform` defaults to the running one and exists so
+ * the Windows quoting branch is testable from any machine. */
+export declare function verificationLauncherFor(metaUrl: string, resolve: (specifier: string) => string, platform?: NodeJS.Platform): {
+    argv: string[];
+    shell: string;
+    note: string;
+};

package/dist/core/verifyLauncher.js

@@ -0,0 +1,37 @@
+/** The launcher that runs `hunch task verify` from THIS installation, not a
+ * potentially stale global binary. Core, not mcp: the prompt hook prints the
+ * command inline (so the model needs no hunch_task start call just to learn it)
+ * and a hook must never pull in the MCP SDK. */
+import { fileURLToPath, pathToFileURL } from "node:url";
+/** Structured argv is authoritative; the shell hint uses literal quoting, and
+ * `note` disambiguates it where one platform has two incompatible shells. */
+export function verificationLauncher() {
+    return verificationLauncherFor(import.meta.url, (specifier) => import.meta.resolve(specifier));
+}
+/** `metaUrl` is the module running (a `.ts` source checkout needs the tsx
+ * loader; a published `.js` build needs nothing) and `resolve` is that
+ * module's `import.meta.resolve`. Callers in sibling directories (src/core,
+ * src/mcp) resolve the same `../cli/index.{ts|js}`, but each must pass ITS OWN
+ * import.meta so the dev/published discrimination stays honest. The loader is
+ * resolved ONLY on the source path: `import.meta.resolve` throws for a package
+ * that is not installed, and `tsx` is a devDependency absent from every
+ * published install (#261). `platform` defaults to the running one and exists so
+ * the Windows quoting branch is testable from any machine. */
+export function verificationLauncherFor(metaUrl, resolve, platform = process.platform) {
+    const dev = metaUrl.endsWith(".ts");
+    const entry = fileURLToPath(new URL(`../cli/index.${dev ? "ts" : "js"}`, metaUrl));
+    // `--import` takes a URL. Converting the resolved loader to a path made Node on
+    // Windows reject it ("Received protocol 'c:'"), so every verification launched
+    // from a source checkout there failed before running and cards showed no check.
+    const loader = dev ? resolve("tsx") : null;
+    const argv = [process.execPath, ...(loader ? ["--import", loader.startsWith("file:") ? loader : pathToFileURL(loader).href] : []), entry];
+    const win = platform === "win32";
+    const quote = (s) => win ? `'${s.replace(/'/g, "''")}'` : `'${s.replace(/'/g, "'\\''")}'`;
+    // Windows hosts run either PowerShell or a POSIX shell (Git Bash), and the
+    // call operator that PowerShell needs is a syntax error in the other. The hint
+    // is quoted for PowerShell and says how to use it in the other; the structured
+    // argv stays the unambiguous form.
+    const note = win ? ` (PowerShell form; in a POSIX shell such as Git Bash drop the leading "& ")` : "";
+    return { argv, shell: `${win ? "& " : ""}${argv.map(quote).join(" ")}`, note };
+}
+//# sourceMappingURL=verifyLauncher.js.map

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 };

package/dist/extractors/git.d.ts

@@ -162,6 +162,11 @@ export declare function isLinkedWorktree(cwd: string): boolean;
 /** Current branch name (e.g. "main", "feat/x"), or "" in detached HEAD / non-repo.
  *  Stamped onto auto-captured decisions so branch-scoped work stays filterable. */
 export declare function currentBranch(cwd: string): string;
+/** Whether HEAD is somewhere a write must not land: mid rebase/merge/cherry-pick/revert/bisect
+ *  ("git-operation-in-progress", which wins when both hold), or detached ("detached-head").
+ *  null when HEAD is a settled branch — and also when git cannot answer at all (not a repo,
+ *  git missing), so a caller keeps its pre-existing behavior rather than failing closed. */
+export declare function gitHeadUnsettled(cwd: string): "git-operation-in-progress" | "detached-head" | null;
 /** Files changed in a single commit. `--root` makes the initial commit (which
  *  has no parent) report its files as additions instead of returning nothing. */
 export declare function commitFiles(sha: string, cwd: string): string[];

package/dist/extractors/git.js

@@ -4,7 +4,7 @@ import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { devNull, tmpdir } from "node:os";
 import { isAbsolute, resolve, join, basename, dirname, relative, sep } from "node:path";
-import { mkdtempSync, openSync, closeSync, readSync, mkdirSync, rmSync, statSync, lstatSync, realpathSync, readFileSync, renameSync, readdirSync } from "node:fs";
+import { mkdtempSync, openSync, closeSync, readSync, mkdirSync, rmSync, statSync, lstatSync, realpathSync, readFileSync, renameSync, readdirSync, existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { MEMLOG_FORMAT } from "../core/memorylog.js";
 import { hunchAttributesAreSafe, hunchTreeAttributesAreSafe, safeOverlayTree } from "../core/overlaySafety.js";
@@ -1686,14 +1686,25 @@ export function syncExistingHunch(hunchDir, protectedRepoRoot, timeoutMs = CAPTU
     }
 }
 const UNKNOWN_LOCK_STALE_MS = 10 * 60_000;
+// An owner-less lock directory is also a NORMAL transient state: the window
+// between the two mkdir calls in createOwnedCommitLock, the release window where
+// recursive cleanup removes owner-<pid> before the outer directory, and a lost
+// reclaim race. This bounds how long a lock may stay owner-less before it is
+// treated as stranded. At ENTRY it is compared with the directory's mtime
+// (creating the directory, or adding/removing a child entry, touches it), so an
+// old stranded lock no-ops instantly. INSIDE the wait loop it is a local
+// continuously-owner-less timer instead, so the wait depends on neither
+// filesystem mtime semantics nor clock agreement between writers.
+const OWNERLESS_LOCK_FRESH_MS = 2_000;
 function createOwnedCommitLock(lock) {
     let created = false;
     try {
         // mkdir is the exclusive atomic operation here. Renaming a staged directory
         // is NOT exclusive on POSIX: it may replace an already-existing empty lock
         // directory, which would steal a fresh legacy/ownerless lock. There is a
-        // harmless ownerless window between these two mkdir calls; contenders treat
-        // it as held until the conservative legacy TTL expires.
+        // harmless ownerless window between these two mkdir calls: it reads as held,
+        // and is reclaimed only after the conservative legacy TTL expires. A capture
+        // waits it out (waitForCommitLockHandoff); other callers just report busy.
         mkdirSync(lock);
         created = true;
         // Empty directories are not Git worktree entries, so owner metadata cannot
@@ -1781,21 +1792,66 @@ function acquireCommitLock(lock) {
     }
     return createOwnedCommitLock(lock) ? { state: "acquired" } : { state: "held-unknown" };
 }
+/** Is an owner-less lock directory recent enough to be a transient window
+ * rather than a stranded one? Only meaningful for the FIRST snapshot, where
+ * there is no local history to measure against. An unreadable directory is not
+ * assumed transient: only ENOENT is, because the owner may have just finished
+ * releasing. `Math.abs` so a clock-skewed far-FUTURE mtime is not read as
+ * recent forever. */
+function ownerlessLockLooksTransient(lock) {
+    try {
+        return Math.abs(Date.now() - statSync(lock).mtimeMs) <= OWNERLESS_LOCK_FRESH_MS;
+    }
+    catch (error) {
+        return error.code === "ENOENT";
+    }
+}
 function waitForCommitLockHandoff(lock, first, timeoutMs) {
-    if (first.state !== "held-live" || first.ownerPid === process.pid)
+    if (first.state === "held-live" && first.ownerPid === process.pid)
+        return false;
+    // An owner-less FIRST snapshot is either a transient window (creation,
+    // release, lost reclaim race) or a stranded/legacy lock. Only the former is
+    // worth waiting for: a stranded lock must not block the capture for the whole
+    // handoff. This is the one place the WAIT POLICY consults the directory's
+    // mtime; acquireCommitLock still stats it for the legacy reclaim TTL.
+    if (first.state === "held-unknown" && !ownerlessLockLooksTransient(lock))
         return false;
     const deadline = Date.now() + timeoutMs;
     const sleeper = new Int32Array(new SharedArrayBuffer(4));
     let attempt = first;
+    // How long the lock has read as held-unknown CONTINUOUSLY, measured locally:
+    // a sighting of a live owner resets it, because a genuine release window lasts
+    // milliseconds. Reading it from this clock keeps the wait independent of the
+    // filesystem's mtime granularity and of other writers' clocks. Besides a truly
+    // owner-less directory this also covers a dead owner whose reclaim another
+    // process has claimed — equally not a handoff this contender can wait for.
+    let ownerlessSince = first.state === "held-unknown" ? Date.now() : null;
+    // "Held" while the directory is not even there means mkdir keeps failing for a
+    // reason that is not contention — a missing, read-only or full store — and no
+    // amount of waiting will hand anything off. Require a short streak so one
+    // sample taken mid-release is not mistaken for it.
+    let vanishedStreak = 0;
     while (Date.now() < deadline) {
         if (attempt.state === "acquired")
             return true;
-        // Once the first snapshot proved a live owner, an owner-less snapshot can be
-        // the normal release window: recursive cleanup removes owner-<pid> before
-        // removing the outer lock directory. Keep the bounded handoff wait through
-        // that transient state instead of reporting a false busy/no-op result.
-        if (attempt.state === "held-live" && attempt.ownerPid === process.pid)
-            return false;
+        if (attempt.state === "held-live") {
+            if (attempt.ownerPid === process.pid)
+                return false;
+            ownerlessSince = null;
+            vanishedStreak = 0;
+        }
+        else if (attempt.state === "held-unknown") {
+            ownerlessSince ??= Date.now();
+            if (Date.now() - ownerlessSince > OWNERLESS_LOCK_FRESH_MS)
+                return false;
+            if (!existsSync(lock)) {
+                vanishedStreak += 1;
+                if (vanishedStreak >= 3)
+                    return false;
+            }
+            else
+                vanishedStreak = 0;
+        }
         Atomics.wait(sleeper, 0, 0, Math.min(25, deadline - Date.now()));
         attempt = acquireCommitLock(lock);
     }
@@ -1877,6 +1933,27 @@ export function currentBranch(cwd) {
     const b = gitSafe(["rev-parse", "--abbrev-ref", "HEAD"], cwd);
     return b === "HEAD" ? "" : b; // detached HEAD reports "HEAD" — treat as no branch
 }
+/** The state files git writes while it is replaying history. `git rev-parse --git-path`
+ *  resolves each against THIS worktree's private git dir (a linked worktree keeps its own
+ *  rebase-merge/MERGE_HEAD), so a rebase in one worktree never reads as one in another. */
+const UNSETTLED_HEAD_PATHS = ["rebase-merge", "rebase-apply", "MERGE_HEAD", "CHERRY_PICK_HEAD", "REVERT_HEAD", "BISECT_LOG"];
+/** Whether HEAD is somewhere a write must not land: mid rebase/merge/cherry-pick/revert/bisect
+ *  ("git-operation-in-progress", which wins when both hold), or detached ("detached-head").
+ *  null when HEAD is a settled branch — and also when git cannot answer at all (not a repo,
+ *  git missing), so a caller keeps its pre-existing behavior rather than failing closed. */
+export function gitHeadUnsettled(cwd) {
+    // One spawn: `git rev-parse --git-path a --git-path b …` prints one line per path.
+    const out = gitSafe(["rev-parse", ...UNSETTLED_HEAD_PATHS.flatMap((p) => ["--git-path", p])], cwd);
+    if (!out)
+        return null; // git could not answer (not a repo) — fail open
+    const paths = out.split("\n").map((p) => p.trim()).filter(Boolean);
+    if (paths.length !== UNSETTLED_HEAD_PATHS.length)
+        return null;
+    if (paths.some((p) => existsSync(isAbsolute(p) ? p : resolve(cwd, p))))
+        return "git-operation-in-progress";
+    // `git symbolic-ref -q HEAD` exits non-zero exactly when HEAD is detached.
+    return gitSafe(["symbolic-ref", "-q", "HEAD"], cwd) ? null : "detached-head";
+}
 /** Files changed in a single commit. `--root` makes the initial commit (which
  *  has no parent) report its files as additions instead of returning nothing. */
 export function commitFiles(sha, cwd) {

package/dist/extractors/indexer.d.ts

@@ -51,5 +51,15 @@ export declare function assertCompleteRepoScan(scan: RepoScan): void;
  * the durable graph merely by inspecting it. Existing public graph records remain
  * inputs for the same churn/component enrichment semantics as a persisted index. */
 export declare function scanRepo(store: HunchStore, root: string, opts?: ScanRepoOptions): RepoScan;
+/** True for an edge this indexer produced: the scan re-derives exactly these on
+ *  every pass, so they — and only they — are safe to replace wholesale. */
+export declare function isExtractorEdge(edge: Edge): boolean;
+/** Merge a fresh scan into the stored edge set. A scan can only re-derive what
+ *  it extracted; `supersedes` edges (written by the store) and human-reviewed
+ *  Landscape relationships have no other source, so replacing the whole index
+ *  with the scan deleted them on every `hunch index` (issue #288). Non-extractor
+ *  edges are carried forward in their stored order and win an id collision:
+ *  a reviewed or store-written fact outranks a re-derivable one. */
+export declare function mergeScannedEdges(stored: Edge[], scanned: Edge[]): Edge[];
 /** Persist one pure scan into the Git-native source of truth. */
 export declare function indexRepo(store: HunchStore, root: string, opts?: IndexRepoOptions): IndexResult;