@davesheffer/hunch 1.39.2 → 1.40.0

package/dist/integrations/providers.js

@@ -21,6 +21,7 @@ import { readFileSync, existsSync, mkdirSync } from "node:fs";
 import { writeFileAtomic } from "../core/io.js";
 import { homedir } from "node:os";
 import { join, dirname } from "node:path";
+import { isHunchHookCommand } from "./hookmatch.js";
 import { renderHunchSection, stripManagedSection, upsertSection, updateClaudeMd } from "./claudemd.js";
 import { headFileContent, isGitCleanPath } from "../extractors/git.js";
 import { parseJsonc } from "../core/jsonc.js";
@@ -106,23 +107,7 @@ function isHunchProviderHook(entry) {
     // whose every nested hook is ours is ours; a mixed entry stays foreign.
     if (e && Array.isArray(e.hooks) && e.hooks.length && typeof e.command !== "string")
         return e.hooks.every(isHunchProviderHook);
-    const command = typeof e?.command === "string" ? e.command : "";
-    // Anchored to the shapes hookCommand() writes — a Hunch launcher (the pinned
-    // npm package spec, or a …/index.js|ts path for source installs) plus a tail
-    // of `hook --provider <name>`, tokens quoted or bare. The old unanchored
-    // /index\.(js|ts)/ + /\bhook\b/ pair classified FOREIGN entries like
-    // `node ./hook/index.js` as ours and silently deleted them, violating the
-    // leave-every-foreign-hook-in-place contract (con_8460b6770f, issue #41), so
-    // the bare tail must still carry --provider to match; only the LEGACY
-    // fully-quoted form (written before this quoting fix, and by hunch versions
-    // that predate --provider) may omit it, and its quotes keep it unambiguous.
-    // Source-checkout invocations generated by resolveInvocation point at the
-    // CLI entry specifically. A generic `other-tool/index.js hook` is foreign
-    // even when it happens to use Hunch's old command tail.
-    const launcher = /@davesheffer\/hunch|(?:dist|src)[\\/]+cli[\\/]+index\.(?:js|ts)(?=["\s]|$)/.test(command);
-    const legacyTail = /\s"hook"(?:\s+"--provider"\s+"[a-z]+")?\s*$/.test(command);
-    const tail = /\s"?hook"?\s+"?--provider"?\s+"?[a-z]+"?\s*$/.test(command);
-    return launcher && (legacyTail || tail);
+    return isHunchHookCommand(typeof e?.command === "string" ? e.command : "", true);
 }
 /** Merge our command entries into a standard `{ hooks: { Event: [] } }` file.
  * We replace only old Hunch commands and leave every foreign hook in place. */

package/dist/integrations/scaffold.d.ts

@@ -19,7 +19,7 @@ export interface ClaudeHookInstall {
  *   - UserPromptSubmit → remind the agent to consult Hunch.
  * Both invoke `hunch hook`, which reads the firmness level from .hunch/config.json
  * at run time — so changing firmness needs no settings.json edit. We own only our
- * entries (matched by isHunchHook): other hooks and settings are preserved, and a
+ * commands (matched by isHunchHookCommand): other hooks and settings are preserved, and a
  * non-empty file we cannot parse THROWS rather than clobbering the user's config.
  */
 export declare function installClaudeHooks(root: string, hookCmd: string): ClaudeHookInstall;

package/dist/integrations/scaffold.js

@@ -6,6 +6,7 @@
 import { readFileSync, existsSync, mkdirSync } from "node:fs";
 import { writeFileAtomic } from "../core/io.js";
 import { join, dirname } from "node:path";
+import { isHunchHookCommand } from "./hookmatch.js";
 /** Merge a `hunch` server entry into .mcp.json, preserving other servers.
  *  A non-empty file we cannot parse THROWS instead of being silently replaced
  *  (con_8460b6770f — it may hold the user's other MCP servers); the caller
@@ -115,25 +116,27 @@ Reconcile decision-grounding drift for **$ARGUMENTS** (or the whole repo).
 3. Only if I explicitly say "the DECISION is stale, not the doc" (Heal B): run /capture to record a superseding decision, then return to step 2 — the prose re-derives from the new decision as a separate confirm.
 4. Report: healed (Heal A), superseded (Heal B), skipped. Never touch the graph except via an explicit Heal B capture.
 `;
-/** A settings.json hook entry is Hunch's if any of its commands is either the
- *  native/source CLI entry (`…/index.js hook`) or the exact published-package
- *  launcher written by older Hunch versions (`npx --package=…@davesheffer/hunch…
- *  hunch hook`). Matching both generations makes an upgrade idempotent instead
- *  of leaving the portable old hook alongside the new native invocation. The
- *  source form still requires `index` to be a full path segment, and the npx form
- *  requires both the scoped package and the `hunch hook` tail, so foreign hooks
- *  are preserved. */
-function isHunchHook(entry) {
-    return !!entry.hooks?.some((h) => {
-        if (typeof h.command !== "string")
-            return false;
-        const command = h.command;
-        const nativeOrSource = /(?:dist|src)[\\/]+cli[\\/]+index\.(js|ts)"?\s+hook\s*$/.test(command);
-        const publishedNpx = /^\s*"?npx(?:\.cmd)?"?\s+/i.test(command)
-            && /--package=(?:hunch-exact@npm:)?@davesheffer\/hunch(?:@[^"\s]+)?/.test(command)
-            && /\s"?hunch"?\s+"?hook"?\s*$/.test(command);
-        return nativeOrSource || publishedNpx;
-    });
+/** Strip Hunch's own commands out of one settings.json hook entry, matching with
+ *  the SAME anchored rule the provider writers use (isHunchHookCommand, issue
+ *  #41) so an unrelated tool that merely shares our layout — `node
+ *  tools/lint/dist/cli/index.js hook` — is never classified as ours. Claude
+ *  Code's hooks carry no `--provider`, hence the bare-tail variant.
+ *
+ *  Filtering per COMMAND rather than per entry is what keeps a MIXED entry (our
+ *  hook and the user's own command side by side) intact: the entry survives with
+ *  its matcher and the user's remaining commands in order, and is dropped only
+ *  when nothing of the user's is left. Dropping the whole entry deleted user
+ *  hooks (con_8460b6770f, issue #310). */
+function withoutHunchCommands(entry, hookCmd) {
+    const hooks = entry.hooks;
+    if (!Array.isArray(hooks))
+        return entry;
+    // The command being installed is ours by definition, whatever shape a future
+    // launcher takes — so a re-run stays idempotent even if the matcher lags it.
+    const kept = hooks.filter((h) => !(typeof h?.command === "string" && (h.command === hookCmd || isHunchHookCommand(h.command, false))));
+    if (kept.length === hooks.length)
+        return entry;
+    return kept.length ? { ...entry, hooks: kept } : null;
 }
 /**
  * Install the Claude Code AGENT hooks into `.claude/settings.json` so the agent
@@ -143,7 +146,7 @@ function isHunchHook(entry) {
  *   - UserPromptSubmit → remind the agent to consult Hunch.
  * Both invoke `hunch hook`, which reads the firmness level from .hunch/config.json
  * at run time — so changing firmness needs no settings.json edit. We own only our
- * entries (matched by isHunchHook): other hooks and settings are preserved, and a
+ * commands (matched by isHunchHookCommand): other hooks and settings are preserved, and a
  * non-empty file we cannot parse THROWS rather than clobbering the user's config.
  */
 export function installClaudeHooks(root, hookCmd) {
@@ -176,7 +179,7 @@ export function installClaudeHooks(root, hookCmd) {
             throw new Error(`refusing to edit ${file}: hooks.${event} must be an array when present; fix it, then re-run.`);
         }
     }
-    const keep = (arr) => (Array.isArray(arr) ? arr.filter((e) => !isHunchHook(e)) : []);
+    const keep = (arr) => (Array.isArray(arr) ? arr.map((entry) => withoutHunchCommands(entry, hookCmd)).filter((e) => e !== null) : []);
     json.hooks.PreToolUse = [
         ...keep(json.hooks.PreToolUse),
         { matcher: "Edit|Write|MultiEdit", hooks: [{ type: "command", command: hookCmd }] },

package/dist/integrations/workspaceLedger.d.ts

@@ -33,6 +33,16 @@ export type SnapshotOutcome = {
     status: "collision";
     record: Workspace;
     reason: string;
+}
+/** A PUBLIC-home snapshot is a commit on the checked-out code branch. While git is replaying
+ *  history (rebase / merge / cherry-pick / revert / bisect) or HEAD is detached, that write
+ *  would land in the middle of the operation — an untracked `ws_*.json` that makes
+ *  `git rebase --continue` abort, or a commit no branch owns. Nothing is lost: the next
+ *  branch checkout or ledger read records this machine. */
+ | {
+    status: "deferred";
+    record: Workspace;
+    reason: "git-operation-in-progress" | "detached-head";
 } | {
     status: "written";
     record: Workspace;

package/dist/integrations/workspaceLedger.js

@@ -11,7 +11,7 @@
  */
 import { execFileSync, spawnSync } from "node:child_process";
 import { createInterface } from "node:readline";
-import { foreignRepoEnv, mainWorktreeRoot } from "../extractors/git.js";
+import { foreignRepoEnv, gitHeadUnsettled, mainWorktreeRoot } from "../extractors/git.js";
 import { hunchPaths } from "../core/paths.js";
 import { readConfig, workspacesConfig } from "../core/config.js";
 import { loadOrCreateMachine } from "../core/machine.js";
@@ -47,6 +47,14 @@ export function recordWorkspaceSnapshot(store, root, opts = {}) {
     if (previous && Date.now() - Date.parse(previous.observed_at) < 86_400_000 && sameWorkspaceContent(previous, record)) {
         return { status: "unchanged", record, previous };
     }
+    // Checked as late as possible (the live snapshot above takes time, and a rebase can start or
+    // finish while it runs). A private overlay is its own repository, whose commits never touch
+    // the code branch, so only a PUBLIC home defers.
+    if (!isPrivate) {
+        const unsettled = gitHeadUnsettled(root);
+        if (unsettled)
+            return { status: "deferred", record, reason: unsettled };
+    }
     try {
         store.putCapture("workspaces", record, isPrivate);
     }

package/dist/mcp/server.d.ts

@@ -7,7 +7,17 @@
  * diagnostics go to stderr.
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { HunchStore } from "../store/hunchStore.js";
+import type { Symbol } from "../core/types.js";
 export declare const publicationVocabulary: (hunchDir: string) => RegExp[];
+/** Resolve a free-form target (symbol id / name / file path) to symbol records.
+ *  Tiered exact-id > exact-name > exact-file > segment-anchored-suffix matching,
+ *  shared with `HunchStore.why()` via `matchSymbolsTiered` so the two don't drift
+ *  apart on the same question. */
+export declare function resolveSymbols(store: HunchStore, target: string): Symbol[];
+/** Resolve a target to canonical indexed file path(s) (for file-granular blast
+ *  radius). Falls back to the literal target so direct-scope checks still run. */
+export declare function resolveFiles(store: HunchStore, target: string): string[];
 export type RootControlledServer = {
     server: McpServer;
     getRoot: () => string;

package/dist/mcp/server.js

@@ -12,7 +12,8 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { RootsListChangedNotificationSchema } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
-import { hunchPaths, findRoot, toPosixTarget } from "../core/paths.js";
+import { hunchPaths, findRoot, toPosixTarget, repoRelativeTarget } from "../core/paths.js";
+import { matchSymbolsTiered } from "../core/glob.js";
 import { resolveMcpToolset } from "./toolset.js";
 import { readConfig } from "../core/config.js";
 import { canonicalRootPath, resolveActiveRoot } from "./roots.js";
@@ -454,23 +455,33 @@ function qualityNudge(rec) {
     }
     return "";
 }
-/** Resolve a free-form target (symbol id / name / file path) to symbol records. */
-function resolveSymbols(store, target) {
-    target = toPosixTarget(target);
+/** Resolve a free-form target (symbol id / name / file path) to symbol records.
+ *  Tiered exact-id > exact-name > exact-file > segment-anchored-suffix matching,
+ *  shared with `HunchStore.why()` via `matchSymbolsTiered` so the two don't drift
+ *  apart on the same question. */
+export function resolveSymbols(store, target) {
+    // An absolute target (an agent's edit-payload path, verbatim) never matched
+    // the repo-relative stored file paths below (issue #296).
+    target = repoRelativeTarget(target, store.publicRoot);
     const syms = store.json.loadAll("symbols");
-    const byId = syms.find((s) => s.id === target);
-    if (byId)
-        return [byId];
-    const byName = syms.filter((s) => s.name === target);
-    if (byName.length)
-        return byName;
-    return syms.filter((s) => s.file === target || s.file.endsWith(target));
+    const components = store.json.loadAll("components");
+    // A target that IS a real path (has a symbol, is covered by an indexed
+    // component even with zero symbols — README.md, package.json, ... — or, last
+    // resort, is a real working-tree file the index cannot see at all, issue
+    // #334) never falls through to the suffix tier: bare `endsWith` matched
+    // unrelated files that merely end in the same characters — "db.ts" matched
+    // "mongodb.ts" (issue #300), and a same-basename file in another directory
+    // leaked its rules onto a real target with no symbols of its own (issue
+    // #299). `store.isKnownPath` is the one definition of that question; it is
+    // asked here over the PUBLIC graph only, matching the records resolved below.
+    const indexed = store.isKnownPath(target, { symbols: syms, components });
+    return matchSymbolsTiered(target, syms, indexed);
 }
 /** Resolve a target to canonical indexed file path(s) (for file-granular blast
  *  radius). Falls back to the literal target so direct-scope checks still run. */
-function resolveFiles(store, target) {
+export function resolveFiles(store, target) {
     const files = new Set(resolveSymbols(store, target).map((s) => s.file));
-    return files.size ? [...files] : [toPosixTarget(target)];
+    return files.size ? [...files] : [repoRelativeTarget(target, store.publicRoot)];
 }
 function pullBackoff(status, finishedAt, failures) {
     if (status === "updated" || status === "current") {
@@ -575,7 +586,7 @@ function prepareRoot(root, explicitOverlay, requireIndex) {
  * per-host prose (CLAUDE.md, AGENTS.md) and hooks add to it, never replace it. */
 export const MCP_INSTRUCTIONS = [
     "Hunch is this repository's engineering memory: decisions, bug history, invariants, components, with provenance.",
-    "Per user task: (1) hunch_task(action:\"start\", title) once — unless the host's prompt hook already printed a task_id, then reuse it; (2) hunch_context(target, task_id) FIRST, before reading or editing, for the file, symbol, or task phrase; (3) hunch_check_constraints(scope) before editing shared code; (4) hunch_task(action:\"finish\", task_id) before the final response and show its contribution card.",
+    "Per user task: (1) hunch_task(action:\"start\", title) once — skip it when the host's prompt hook already opened the task and printed its verify command, and reuse that task_id; (2) hunch_context(target, task_id) FIRST, before reading or editing, for the file, symbol, or task phrase; (3) hunch_check_constraints(scope) before editing shared code; (4) hunch_task(action:\"finish\", task_id) before the final response, showing its contribution card — required, with one exception: the host's prompt hook opened the task AND its instruction said that host closes the task AND the task used no Hunch (no hunch_* call on this task_id, no task verify check, no hook context you acted on, nothing to claim). A task you started with hunch_task is always finished by you.",
     "Then by moment: hunch_why(target) for rationale and rejected alternatives, hunch_bug_lineage before fixing a failure, hunch_record_decision after a non-trivial choice, hunch_record_correction when a human corrects you.",
     "Hosts without lifecycle hooks (Windsurf, Cursor, or Codex before its hooks are trusted) receive no automatic grounding: call these tools yourself.",
 ].join("\n");
@@ -924,8 +935,13 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                 if (!all.has(d.id))
                     all.set(d.id, d);
         const deps = [...all.values()].sort((a, b) => a.depth - b.depth);
-        if (!deps.length)
-            return ok(`Nothing depends on "${symbol}" (leaf node, or not indexed).`);
+        // A real path the index has no symbols for reaches here too (resolveSymbols
+        // correctly refuses to suffix-resolve it, #334) — don't tell the caller a
+        // path we can confirm is real "isn't indexed".
+        if (!deps.length) {
+            const known = store.isKnownPath(repoRelativeTarget(symbol, store.publicRoot));
+            return ok(`Nothing depends on "${symbol}" (${known ? "leaf node, or no indexed symbols for it" : "leaf node, or not indexed"}).`);
+        }
         // Nearest dependents first (sorted by depth); cap the tail so a high-fan-in
         // symbol can't flood the session context.
         const lines = deps.slice(0, DEP_CAP).map((d) => `  • [depth ${d.depth}] ${d.via} (${d.id})`);

package/dist/mcp/taskReportTools.d.ts

@@ -1,4 +1,5 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { verificationLauncherFor } from "../core/verifyLauncher.js";
 import { readTaskReport } from "../core/taskReport.js";
 import type { HunchStore } from "../store/hunchStore.js";
 /** A tool result must fit the host's round-trip. The full report (every
@@ -193,13 +194,8 @@ export declare function boundedTaskReportForHost(report: ReturnType<typeof readT
     };
     full_report: 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`. 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). */
-export declare function verificationLauncherFor(metaUrl: string, resolve: (specifier: string) => string): {
-    argv: string[];
-    shell: string;
-};
+/** Re-exported so existing imports keep working; the implementation lives in
+ * src/core/verifyLauncher.ts because the prompt hook needs it too and a hook
+ * must not pull in the MCP SDK. */
+export { verificationLauncherFor };
 export declare function registerTaskReportTools(server: McpServer, getRoot: () => string, getStore: () => HunchStore): void;

package/dist/mcp/taskReportTools.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import { verificationLauncherFor } from "../core/verifyLauncher.js";
 import { TaskIdSchema, ReportClaimSchema, LessonReferenceSchema, finishReportTask, listReportTasks, readTaskReport, readLessonHistory, recordReportClaim, reportPresentationEnabled, startReportTask } from "../core/taskReport.js";
 import { persistTaskRecord } from "../core/taskRecord.js";
 import { reportSourceSnapshot, runReportConformance } from "../core/taskReportEvidence.js";
@@ -49,30 +49,19 @@ export function boundedTaskReportForHost(report) {
     return { ...minimal, deliveries: [], omitted: { ...minimal.omitted, deliveries: report.deliveries.length } };
 }
 /** Reuse the MCP server's installation, not a potentially stale global binary.
- * Structured argv is authoritative; the shell hint uses literal quoting. */
+ * `src/core/` and `src/mcp/` are siblings, so the relative entry URL is the
+ * same from either — but each caller passes ITS OWN import.meta. */
 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`. 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). */
-export function verificationLauncherFor(metaUrl, resolve) {
-    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 quote = (s) => process.platform === "win32" ? `'${s.replace(/'/g, "''")}'` : `'${s.replace(/'/g, "'\\''")}'`;
-    return { argv, shell: `${process.platform === "win32" ? "& " : ""}${argv.map(quote).join(" ")}` };
-}
+/** Re-exported so existing imports keep working; the implementation lives in
+ * src/core/verifyLauncher.ts because the prompt hook needs it too and a hook
+ * must not pull in the MCP SDK. */
+export { verificationLauncherFor };
 export function registerTaskReportTools(server, getRoot, getStore) {
     server.registerTool("hunch_task", {
         title: "Start or finish a task's contribution report",
-        description: "Start once per user task; pass the returned task_id to hunch_context. Finish before your final response and include the returned concise contribution card, without asking the user. Applications are explicitly agent-reported and must name an exact delivered occurrence and record hash. Completion never implies successful verification. Not for storing decisions or claiming tests passed; use the CLI task verify wrapper for observed command results.",
+        description: "Start once per user task, unless the host's prompt hook already opened the task and printed its verify command — then reuse that task_id and do not start. Pass the task_id to hunch_context. Finish before your final response and include the returned concise contribution card, without asking the user; skip finish only when the prompt hook's own instruction said this host closes the task and the task used no Hunch (no hunch_* call on this task_id, no verified check, no hook context you acted on, nothing to claim), and a task you started with this tool must always be finished. Applications are explicitly agent-reported and must name an exact delivered occurrence and record hash. Completion never implies successful verification. Not for storing decisions or claiming tests passed; use the CLI task verify wrapper for observed command results.",
         inputSchema: {
             action: z.enum(["start", "finish"]), task_id: TaskIdSchema.optional(),
             title: z.string().min(1).max(200).optional(),
@@ -99,7 +88,7 @@ export function registerTaskReportTools(server, getRoot, getStore) {
                     task = readTaskReport(root, task_id, reportSourceSnapshot(root).hash).task;
                 }
                 const launcher = verificationLauncher();
-                return { content: [{ type: "text", text: `Task ${task.task_id} · ${task.state}. Pass task_id to every hunch_context and decision/correction/finding capture call. Before the final response, finish with hunch_task and include its contribution card. For checks use this exact installation (the global hunch binary may be stale): ${launcher.shell} task verify ${task.task_id} -- <command> [arguments]. The default budget is 15 minutes; add --timeout <seconds> before -- for a longer suite.` }], structuredContent: { task, verification_argv: [...launcher.argv, "task", "verify", task.task_id, "--"] } };
+                return { content: [{ type: "text", text: `Task ${task.task_id} · ${task.state}. Pass task_id to every hunch_context and decision/correction/finding capture call. Before the final response, finish with hunch_task and include its contribution card. For checks use this exact installation (the global hunch binary may be stale): ${launcher.shell} task verify ${task.task_id} -- <command> [arguments]${launcher.note}. The default budget is 15 minutes; add --timeout <seconds> before -- for a longer suite.` }], structuredContent: { task, verification_argv: [...launcher.argv, "task", "verify", task.task_id, "--"] } };
             }
             if (!task_id)
                 throw new Error("finish requires the exact task_id");

package/dist/serve/writelock.d.ts

@@ -3,11 +3,25 @@
 export declare const STALE_AFTER_MS = 60000;
 /** Longest a writer waits before giving up and telling the caller. */
 export declare const ACQUIRE_TIMEOUT_MS = 10000;
+/** Longest a takeover claim may sit before another contender may clear it. The
+ *  claimed section is a few syscalls, so anything this old means its claimer
+ *  crashed inside it. */
+export declare const CLAIM_STALE_MS = 10000;
 export interface LockOwner {
     pid: number;
     host: string;
     nonce: string;
     at: string;
+    start?: string;
+}
+/** Token seam: the caller's own process-instance token and a probe for another
+ *  pid's, plus the platform the decision table should reason about (the own-pid
+ *  fallback differs on linux, where pid namespaces exist). Injected by tests so
+ *  the identity paths are exercised off linux. */
+export interface StartTokenProbe {
+    self: string | null;
+    of: (pid: number) => string | null;
+    platform?: NodeJS.Platform;
 }
 export declare class WriteLockTimeout extends Error {
     readonly path: string;
@@ -16,7 +30,13 @@ export declare class WriteLockTimeout extends Error {
     constructor(path: string, heldBy: LockOwner | undefined, waitedMs: number);
 }
 export declare function writeLockPath(hunchDir: string): string;
-/** Hold the partition's lock across `fn` (sync or async); released even if it throws. */
+/** Hold the partition's lock across `fn` (sync or async); released even if it throws.
+ *
+ *  `opts.startToken` is an INTERNAL TEST SEAM, not API: it lets the test suite
+ *  drive the process-identity rows of the decision table on a platform that has
+ *  no such identity. Callers outside this repo must leave it unset — the real
+ *  probe (`selfStartToken`/`startTokenOf`) is the only sound one. */
 export declare function withWriteLock<T>(hunchDir: string, fn: () => T | Promise<T>, opts?: {
     timeoutMs?: number;
+    startToken?: StartTokenProbe;
 }): Promise<T>;

package/dist/serve/writelock.js

@@ -7,18 +7,28 @@
  * processes can both complete the read before either writes. An in-process mutex
  * does not span processes, so the lock is a file created with `open(path, "wx")` —
  * atomic on POSIX and Windows. A holder that dies leaves the file behind; a lock is
- * stealable once its owner is provably gone (pid dead on the same host) or older
- * than any plausible write.
+ * stealable once its owner is provably gone (pid dead — or RECYCLED — on the same
+ * host) or older than any plausible write. "Recycled" is decided by comparing the
+ * owner's recorded process-instance token with the current holder's, by string
+ * equality and never by clock arithmetic (see core/procstart.ts). Removing a stale
+ * lock is itself serialized behind an exclusive `.reclaim` claim directory, because
+ * judging and removing are two steps and two contenders can otherwise both "win"
+ * (see `takeOver`).
  */
 import { hostname } from "node:os";
 import { randomBytes } from "node:crypto";
-import { closeSync, openSync, readFileSync, rmSync, statSync, writeSync } from "node:fs";
+import { closeSync, mkdirSync, openSync, readFileSync, rmSync, rmdirSync, statSync, writeSync } from "node:fs";
 import { join } from "node:path";
+import { heldLockNonces, judgeSameHostOwner, selfStartToken, startTokenOf } from "../core/procstart.js";
 /** Longest a write may hold the lock before another process may steal it: a put plus a
  *  git commit and push — seconds, not minutes. */
 export const STALE_AFTER_MS = 60_000;
 /** Longest a writer waits before giving up and telling the caller. */
 export const ACQUIRE_TIMEOUT_MS = 10_000;
+/** Longest a takeover claim may sit before another contender may clear it. The
+ *  claimed section is a few syscalls, so anything this old means its claimer
+ *  crashed inside it. */
+export const CLAIM_STALE_MS = 10_000;
 const POLL_MS = 25;
 export class WriteLockTimeout extends Error {
     path;
@@ -42,7 +52,13 @@ function readOwner(path) {
         const parsed = JSON.parse(readFileSync(path, "utf8"));
         if (typeof parsed.pid !== "number" || typeof parsed.nonce !== "string")
             return undefined;
-        return { pid: parsed.pid, host: typeof parsed.host === "string" ? parsed.host : "", nonce: parsed.nonce, at: typeof parsed.at === "string" ? parsed.at : "" };
+        return {
+            pid: parsed.pid,
+            host: typeof parsed.host === "string" ? parsed.host : "",
+            nonce: parsed.nonce,
+            at: typeof parsed.at === "string" ? parsed.at : "",
+            ...(typeof parsed.start === "string" ? { start: parsed.start } : {}),
+        };
     }
     catch {
         return undefined; // released between our open and this read, or truncated by a crash — age decides
@@ -57,7 +73,7 @@ function pidAlive(pid) {
         return error.code === "EPERM"; // exists, another user — alive for our purposes
     }
 }
-function stealable(path, owner, now) {
+function stealable(path, owner, now, token) {
     let ageMs;
     try {
         ageMs = now - statSync(path).mtimeMs;
@@ -71,15 +87,124 @@ function stealable(path, owner, now) {
     // their record and ledger updates. The age fallback is only safe when the
     // owner is from another host (whose PID we cannot probe) or its metadata is
     // unreadable.
-    if (owner && owner.host === hostname())
-        return !pidAlive(owner.pid);
+    //
+    // The one exception is a PID that is alive but is no longer the OWNER: PIDs
+    // are recycled, and a container restart routinely gives the new writer the
+    // dead one's exact pid and hostname, so the orphaned lock names the contender
+    // itself and is never taken over again (issue #287). The owner's recorded
+    // process-instance token settles it by plain string equality — no clock is
+    // read, because the lock's mtime and a start time come from different clocks
+    // and any skew between them would "prove" a live owner recycled and steal its
+    // lock. Anything the token cannot settle stays "not proven".
+    //
+    // The whole table lives in core/procstart.ts so this lock and jsonStore's
+    // `.rmw-lock` can never drift apart; "age" means it proved nothing and the
+    // fallback below governs, exactly as for a foreign host.
+    if (owner && owner.host === hostname()) {
+        const verdict = judgeSameHostOwner(owner, {
+            alive: pidAlive,
+            self: token.self,
+            tokenOf: token.of,
+            platform: token.platform ?? process.platform,
+            selfPid: process.pid,
+            heldNonces: heldLockNonces,
+        });
+        if (verdict !== "age")
+            return verdict === "stale";
+    }
     return ageMs > STALE_AFTER_MS;
 }
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-/** Hold the partition's lock across `fn` (sync or async); released even if it throws. */
+/** The claim a contender must hold to REMOVE a stale lock. A sibling directory,
+ *  created with the same exclusive `mkdir` the commit lock uses
+ *  (src/extractors/git.ts `acquireCommitLock`) — a directory because an empty one
+ *  is invisible to git and can never be staged. */
+function claimPath(lockPath) {
+    return `${lockPath}.reclaim`;
+}
+/**
+ * Remove a stale lock under an exclusive claim, and report whether the path may
+ * now be free. "judge stale → rm → create" is NOT atomic: two contenders can
+ * both judge the same corpse stale, the first removes it and creates its own,
+ * and the second then removes that FRESH lock and creates a second holder
+ * (issue #287). Serializing the removal behind one claim closes it.
+ *
+ * INVARIANT: a stale lock's path can only be vacated by a claim holder (its
+ * owner is dead and will never release), and only one contender holds the claim
+ * at a time — so between the re-judge below and the `rm` nothing can replace the
+ * lock. A contender that judged stale a moment earlier re-judges under the
+ * claim, sees the winner's fresh live lock, and removes nothing.
+ *
+ * Residuals accepted:
+ *  (i) an AGE-judged lock (foreign host, unprobeable owner, or unreadable owner
+ *      metadata) whose owner is actually alive and releases inside the
+ *      re-judge→rm window — the same class as the already-accepted "stolen after
+ *      STALE_AFTER_MS";
+ *  (ii) two contenders racing to clear a STRANDED claim. A claim's staleness is
+ *      judged by ITS MTIME against OUR clock — the one clock comparison left in
+ *      the takeover path — and there is no claim-nonce file to fall back on. So
+ *      with filesystem/host clock skew beyond CLAIM_STALE_MS every LIVE claim
+ *      looks stranded, and with three or more simultaneous contenders exclusion
+ *      degrades to the pre-fix race. Without such skew it needs a claim section
+ *      that is stranded plus simultaneous removers — and "stranded" is NOT only a
+ *      crash: a STALL longer than CLAIM_STALE_MS between the re-judge and the
+ *      `rm` (SIGSTOP, a VM pause or live migration, a laptop sleep) does it too.
+ *      One other contender is then enough: it clears the "stranded" claim, takes
+ *      over and publishes a LIVE lock, and the resumed claimer's `rm` removes
+ *      that live lock; the unconditional `rmdirSync(claim)` in the `finally` can
+ *      likewise remove a SUCCESSOR's claim. Same probability class as the age
+ *      steal we already accept — a process stalled past the stale window while
+ *      another writes — which is why it is accepted here too;
+ *  (iii) a stranded claim blocks any takeover for up to CLAIM_STALE_MS —
+ *      bounded, needing the same crash OR over-CLAIM_STALE_MS stall; a filesystem
+ *      clock AHEAD of this host extends that block by the amount of the skew;
+ *  (iv) MIXED VERSIONS: a pre-fix `hunch` ignores `.reclaim` entirely, so the
+ *      takeover race persists until every writer on the store is upgraded.
+ */
+function takeOver(path, token) {
+    const claim = claimPath(path);
+    try {
+        mkdirSync(claim);
+    }
+    catch (error) {
+        if (error.code === "EEXIST") {
+            // Someone else is mid-takeover — or crashed inside one. Clear only a
+            // provably stranded claim; either way, do not take over this round (the
+            // caller falls through to its deadline check and sleep, never a hot spin).
+            try {
+                if (Date.now() - statSync(claim).mtimeMs > CLAIM_STALE_MS)
+                    rmdirSync(claim);
+            }
+            catch { /* vanished, or another contender cleared it first */ }
+        }
+        return false;
+    }
+    try {
+        // RE-JUDGE from scratch under the claim: the lock we judged stale may already
+        // have been replaced by the winner's live one.
+        const current = readOwner(path);
+        if (!stealable(path, current, Date.now(), token))
+            return false;
+        rmSync(path, { force: true });
+        return true;
+    }
+    finally {
+        try {
+            rmdirSync(claim);
+        }
+        catch { /* best effort; a stranded claim is cleared by age */ }
+    }
+}
+/** Hold the partition's lock across `fn` (sync or async); released even if it throws.
+ *
+ *  `opts.startToken` is an INTERNAL TEST SEAM, not API: it lets the test suite
+ *  drive the process-identity rows of the decision table on a platform that has
+ *  no such identity. Callers outside this repo must leave it unset — the real
+ *  probe (`selfStartToken`/`startTokenOf`) is the only sound one. */
 export async function withWriteLock(hunchDir, fn, opts = {}) {
     const path = writeLockPath(hunchDir);
     const timeoutMs = opts.timeoutMs ?? ACQUIRE_TIMEOUT_MS;
+    const token = opts.startToken ?? { self: selfStartToken(), of: startTokenOf };
     const nonce = randomBytes(8).toString("hex");
     const started = Date.now();
     let fd;
@@ -87,22 +212,31 @@ export async function withWriteLock(hunchDir, fn, opts = {}) {
     for (;;) {
         try {
             fd = openSync(path, "wx");
+            // Synchronously adjacent to the successful create, before any await: from
+            // here on this nonce is one WE hold, so our own later calls do not mistake
+            // it for a predecessor's (and adding it before the open would make a mere
+            // waiter look like a holder).
+            heldLockNonces.add(nonce);
             break;
         }
         catch (error) {
             if (error.code !== "EEXIST")
                 throw error;
             lastOwner = readOwner(path);
-            if (stealable(path, lastOwner, Date.now())) {
-                rmSync(path, { force: true });
+            if (stealable(path, lastOwner, Date.now(), token) && takeOver(path, token))
                 continue;
-            }
             if (Date.now() - started >= timeoutMs)
                 throw new WriteLockTimeout(path, lastOwner, Date.now() - started);
             await sleep(POLL_MS);
         }
     }
-    const owner = { pid: process.pid, host: hostname(), nonce, at: new Date().toISOString() };
+    const owner = {
+        pid: process.pid,
+        host: hostname(),
+        nonce,
+        at: new Date().toISOString(),
+        ...(token.self !== null ? { start: token.self } : {}),
+    };
     try {
         writeSync(fd, JSON.stringify(owner));
     }
@@ -113,10 +247,17 @@ export async function withWriteLock(hunchDir, fn, opts = {}) {
     }
     finally {
         // Only remove a lock that is still ours: if we overran STALE_AFTER_MS and were stolen
-        // from, the file now protects another writer.
-        const current = readOwner(path);
-        if (!current || current.nonce === nonce)
-            rmSync(path, { force: true });
+        // from, the file now protects another writer. The nonce is dropped in a
+        // `finally` of its own, so a throw from the conditional remove can never
+        // leave us vouching for a lock we no longer hold.
+        try {
+            const current = readOwner(path);
+            if (!current || current.nonce === nonce)
+                rmSync(path, { force: true });
+        }
+        finally {
+            heldLockNonces.delete(nonce);
+        }
     }
 }
 //# sourceMappingURL=writelock.js.map