@davesheffer/hunch 1.39.1 → 1.39.3

package/dist/core/correction.d.ts

@@ -25,12 +25,18 @@ export interface CorrectionInput {
      *  consumer matches repo-relative paths — so without this an absolute hint mints a
      *  scope that can never match. */
     root?: string;
-    /** True when a capture token was CONSUMED for this write — proof a grilling interview
-     *  preceded it. Determines the TIER, never whether the write lands: an un-vouched
-     *  correction still records immediately and still surfaces at edit time and in CI.
-     *  Only the authority to DENY waits for a countersign. */
+    /** True only when a HUMAN confirmed this write outside the agent's channel (an MCP
+     *  elicitation answered in the client UI). A consumed capture token alone is NOT
+     *  enough — any agent can mint and consume one. Determines the TIER, never whether
+     *  the write lands: an un-vouched correction still records immediately and still
+     *  surfaces at edit time and in CI. Only the authority to DENY waits for a countersign
+     *  (`hunch review --confirm <id>`). */
     vouched?: boolean;
 }
+/** Default rationales, exported so a later human countersign can replace the testimony
+ *  wording without touching a rationale a person actually wrote. */
+export declare const VOUCHED_CORRECTION_RATIONALE = "Captured from a human correction of the agent (Never Twice).";
+export declare const TESTIMONY_CORRECTION_RATIONALE = "Recorded by the agent as a correction, without a human confirmation \u2014 advisory testimony until a human countersigns it (`hunch review --confirm`) (Never Twice).";
 /**
  * Build the Constraint a correction mints. Pure (caller passes `now`), so the
  * scope/severity policy is testable in isolation. Key safety rule (research

package/dist/core/correction.js

@@ -8,9 +8,9 @@
  *   - buildCorrectionConstraint(): mint the Constraint record (human-confirmed,
  *     scoped conservatively) that the pre-edit hook + CI guard then enforce.
  */
-import { isAbsolute, relative } from "node:path";
+import { isAbsolute } from "node:path";
 import { constraintId } from "./ids.js";
-import { toPosixTarget } from "./paths.js";
+import { toPosixTarget, repoRelativeTarget } from "./paths.js";
 import { deriveForbids } from "./constraintmatch.js";
 /** Correction cues. Deliberately conservative — anchored to imperative/rebuke
  *  phrasing, not bare "no", so ordinary conversational negation ("no idea",
@@ -41,6 +41,10 @@ export const CORRECTION_NUDGE = "This looks like a correction. If it's a rule th
     "call hunch_record_correction({ rule, scope_hint_file, severity, applies_to_all }) so it " +
     "becomes an enforced, scoped constraint (held at edit-time and in CI) — not a one-off the next session forgets. " +
     "Use severity:\"blocking\" only when the human said never/must; set applies_to_all:true only if the rule is genuinely repo-wide.";
+/** Default rationales, exported so a later human countersign can replace the testimony
+ *  wording without touching a rationale a person actually wrote. */
+export const VOUCHED_CORRECTION_RATIONALE = "Captured from a human correction of the agent (Never Twice).";
+export const TESTIMONY_CORRECTION_RATIONALE = "Recorded by the agent as a correction, without a human confirmation — advisory testimony until a human countersigns it (`hunch review --confirm`) (Never Twice).";
 /** Normalize a scope hint to a repo-relative POSIX path.
  *
  *  An ABSOLUTE hint is the shape an agent naturally sends, but `checkConstraints`
@@ -53,7 +57,13 @@ export const CORRECTION_NUDGE = "This looks like a correction. If it's a rule th
  *  Returns "" when the hint cannot be made repo-relative (no root, or a path outside the
  *  repo). The caller then falls back to "**", where the existing severity guard
  *  down-ranks a non-explicit blocking rule to a warning — fail-safe and honest, rather
- *  than a blocking rule enforced nowhere. */
+ *  than a blocking rule enforced nowhere.
+ *
+ *  Thin adapter over the shared `repoRelativeTarget` (core/paths.ts): that function
+ *  passes an unresolvable absolute hint through UNCHANGED (still absolute) rather
+ *  than signaling failure directly, since other callers (checkConstraints, why())
+ *  want the original target back to fail their own match safely. This adapter
+ *  converts that "still absolute" signal to "" — the fail-safe this caller needs. */
 function repoRelativeHint(rawHint, root) {
     if (!rawHint)
         return "";
@@ -62,10 +72,9 @@ function repoRelativeHint(rawHint, root) {
         return rawHint;
     if (!root)
         return "";
-    const rel = toPosixTarget(relative(root, rawHint));
-    if (!rel || rel === ".." || rel.startsWith("../") || isAbsolute(rel) || /^[a-zA-Z]:/.test(rel))
-        return "";
-    return rel;
+    const rewritten = repoRelativeTarget(rawHint, root);
+    const stillAbsolute = isAbsolute(rewritten) || /^[a-zA-Z]:/.test(rewritten);
+    return stillAbsolute ? "" : rewritten;
 }
 /**
  * Build the Constraint a correction mints. Pure (caller passes `now`), so the
@@ -94,7 +103,8 @@ export function buildCorrectionConstraint(input, now) {
     // the highest-authority write path the least gated one, and strictly worse than
     // hunch_record_decision, which only ever produced advisory memory and is now tiered.
     //
-    // The token sets the TIER, never whether the write lands. An un-vouched correction is
+    // A HUMAN confirmation sets the TIER (a capture token alone is not one — any agent can
+    // mint and consume a token), never whether the write lands. An un-vouched correction is
     // still recorded immediately and still held against every assistant at edit time and
     // in CI — Never Twice keeps its promise. What waits for a countersign is only the
     // authority to DENY.
@@ -114,9 +124,7 @@ export function buildCorrectionConstraint(input, now) {
         // rule that goes stale. Validated against the repo's real deps when supplied → never mints a
         // never-firing rule for a non-dependency. null when nothing derivable → falls back to scope.
         forbids: deriveForbids(rule, input.knownDeps),
-        rationale: input.rationale ?? (vouched
-            ? "Captured from a human correction of the agent (Never Twice)."
-            : "Recorded by the agent as a correction, WITHOUT a capture interview — advisory testimony until a human countersigns it via /capture (Never Twice)."),
+        rationale: input.rationale ?? (vouched ? VOUCHED_CORRECTION_RATIONALE : TESTIMONY_CORRECTION_RATIONALE),
         source_decision: input.source_decision ?? null,
         violations: [],
         status: "active",

package/dist/core/countersign.d.ts

@@ -0,0 +1,28 @@
+/** Human countersign: turn agent testimony into a human-confirmed record.
+ *
+ *  A capture token proves an interview protocol was issued, not that a human answered
+ *  (see capturetoken.ts), so agent-written decisions and corrections land as
+ *  `agent_recorded` testimony. This is the pure record transform behind the human act
+ *  that upgrades them — `hunch review --confirm <id>` (and, for a correction, the
+ *  severity the human grants). It never changes a record's content or status: confirming
+ *  a proposed decision is not shipping it. Pure (caller passes `now`) so it is testable. */
+import type { Constraint, Decision } from "./types.js";
+/** Is this record agent testimony awaiting a human countersign? Token-aware ("+"-joined
+ *  sources), and a record carrying a human signature is never testimony. */
+export declare function isAgentTestimony(source: string | undefined): boolean;
+/** The exact command a HUMAN runs to countersign agent testimony (outside the agent
+ *  channel). `private` targets the overlay home; `severity` grants a correction's authority. */
+export declare function confirmCommand(id: string, opts?: {
+    private?: boolean;
+    severity?: string;
+}): string;
+/** Replace the agent testimony tier with the human signature, keeping every other
+ *  "+"-joined source token ("llm_draft+agent_recorded" → "llm_draft+human_confirmed"). */
+export declare function withHumanSignature(source: string): string;
+/** Countersign a decision. Same tier + confidence the capture path grants a human-confirmed
+ *  write; status, content, and tripwires are untouched (`hunch review --accept` is the path
+ *  that ships a draft and arms its tripwires). */
+export declare function countersignDecision(d: Decision, now: string): Decision;
+/** Countersign a correction. `severity`, when given, is the authority the human grants
+ *  (an unconfirmed "blocking" request was capped to "warning"); otherwise it is kept. */
+export declare function countersignConstraint(c: Constraint, now: string, severity?: Constraint["severity"]): Constraint;

package/dist/core/countersign.js

@@ -0,0 +1,50 @@
+import { TESTIMONY_CORRECTION_RATIONALE, VOUCHED_CORRECTION_RATIONALE } from "./correction.js";
+/** Is this record agent testimony awaiting a human countersign? Token-aware ("+"-joined
+ *  sources), and a record carrying a human signature is never testimony. */
+export function isAgentTestimony(source) {
+    const tokens = (source ?? "").split("+");
+    return tokens.includes("agent_recorded") && !tokens.includes("human_confirmed");
+}
+/** The exact command a HUMAN runs to countersign agent testimony (outside the agent
+ *  channel). `private` targets the overlay home; `severity` grants a correction's authority. */
+export function confirmCommand(id, opts = {}) {
+    return `hunch review --confirm ${id}${opts.severity ? ` --severity ${opts.severity}` : ""}${opts.private ? " --private" : ""}`;
+}
+/** Replace the agent testimony tier with the human signature, keeping every other
+ *  "+"-joined source token ("llm_draft+agent_recorded" → "llm_draft+human_confirmed"). */
+export function withHumanSignature(source) {
+    const tokens = source.split("+").filter((t) => t && t !== "agent_recorded");
+    if (!tokens.includes("human_confirmed"))
+        tokens.push("human_confirmed");
+    return tokens.join("+");
+}
+/** Countersign a decision. Same tier + confidence the capture path grants a human-confirmed
+ *  write; status, content, and tripwires are untouched (`hunch review --accept` is the path
+ *  that ships a draft and arms its tripwires). */
+export function countersignDecision(d, now) {
+    return {
+        ...d,
+        provenance: {
+            ...d.provenance,
+            source: withHumanSignature(d.provenance.source),
+            confidence: Math.max(d.provenance.confidence ?? 0, 0.95),
+            last_verified: now,
+        },
+    };
+}
+/** Countersign a correction. `severity`, when given, is the authority the human grants
+ *  (an unconfirmed "blocking" request was capped to "warning"); otherwise it is kept. */
+export function countersignConstraint(c, now, severity) {
+    return {
+        ...c,
+        severity: severity ?? c.severity,
+        rationale: c.rationale === TESTIMONY_CORRECTION_RATIONALE ? VOUCHED_CORRECTION_RATIONALE : c.rationale,
+        provenance: {
+            ...c.provenance,
+            source: withHumanSignature(c.provenance.source),
+            confidence: 1,
+            last_verified: now,
+        },
+    };
+}
+//# sourceMappingURL=countersign.js.map

package/dist/core/docanchors.js

@@ -4,7 +4,9 @@ const MARKER = /<!--\s*hunch:topic\s+([A-Za-z0-9._/-]+)(?:\s+(dec_[A-Za-z0-9]+))
  *  documentation EXAMPLE of a marker never registers as a live anchor.
  *  CommonMark-lite: a fence of N chars (≤3 leading spaces) closes only on a
  *  line of ≥N of the same char and nothing else; an unclosed fence runs to
- *  EOF; a backtick fence's info string may not itself contain a backtick. */
+ *  EOF; a backtick fence's info string may not itself contain a backtick.
+ *  Expects LF-normalized text — see parseDocAnchors's normalization; a
+ *  caller that skips it re-opens the CRLF fence-detection bug. */
 function fencedRanges(text) {
     const ranges = [];
     let open = null;
@@ -31,7 +33,11 @@ function fencedRanges(text) {
 /** Character ranges covered by inline code spans (`…`), same rationale as
  *  fencedRanges: prose quoting a marker in backticks is showing an example.
  *  CommonMark-lite: an opener run pairs with the next run of the SAME length
- *  on the same line; unpaired runs never open a span. */
+ *  on the same line; unpaired runs never open a span.
+ *  Expects LF-normalized text — see parseDocAnchors's normalization.
+ *  `split("\n")` does not split a bare CR, so on CR-only input the whole
+ *  document reads as one line and stray backticks on different lines
+ *  falsely pair. */
 function inlineSpanRanges(text) {
     const ranges = [];
     let offset = 0;
@@ -55,6 +61,14 @@ function inlineSpanRanges(text) {
  *  fenced code blocks or inline code spans are examples, not declarations,
  *  and are skipped. */
 export function parseDocAnchors(text) {
+    // fencedRanges is CRLF-sensitive (its fence-line regex's `.` excludes \r, so
+    // "```\r" never matched at all on a CRLF checkout); inlineSpanRanges is
+    // lone-CR-sensitive (split("\n") doesn't split a bare CR — see its
+    // docblock). Either way an example marker inside a fence/span registered as
+    // a live, pinned anchor. Normalizing both CRLF and lone CR once here keeps
+    // fencedRanges/inlineSpanRanges/MARKER offsets consistent with each other
+    // and with the line numbers reported below.
+    text = text.replace(/\r\n?/g, "\n");
     const out = [];
     const skip = [...fencedRanges(text), ...inlineSpanRanges(text)];
     MARKER.lastIndex = 0;

package/dist/core/glob.d.ts

@@ -7,3 +7,22 @@ export declare function pathMatchesGlob(path: string, glob: string): boolean;
 /** Do two concrete repo paths identify the same path at different prefix depth?
  * Segment-anchored: `x/scenario.ts` relates to `scenario.ts`, never `io.ts`. */
 export declare function pathsRelated(left: string, right: string): boolean;
+/** True when `target` is a path Hunch's index already knows about: an indexed
+ *  symbol's exact file, or a path an indexed component's `paths` glob(s) cover.
+ *  The latter catches a symbol-less-but-indexed file (README.md, package.json,
+ *  Dockerfile, ...) that has zero tree-sitter symbols but is still a real,
+ *  known file. Derived entirely from already-loaded graph data — never the
+ *  filesystem — so the answer doesn't depend on untracked working-tree state
+ *  (a deleted-but-still-indexed path stays "real"; issue #299). */
+export declare function isIndexedPath(target: string, symbolFiles: Iterable<string>, componentPaths: Iterable<readonly string[]>): boolean;
+/** Resolve symbols matching `target`, tiered: exact id > exact name > exact file >
+ *  (only when `target` is NOT a path already known to the index) segment-anchored
+ *  suffix. A real indexed file with zero symbols must return [] rather than fall
+ *  through to the suffix tier, which would leak an unrelated same-basename file's
+ *  records (issue #299) — callers compute `indexed` via `isIndexedPath` first so
+ *  the "is this a real path" question is answered identically everywhere. */
+export declare function matchSymbolsTiered<S extends {
+    id: string;
+    file: string;
+    name: string;
+}>(target: string, symbols: readonly S[], indexed: boolean): S[];

package/dist/core/glob.js

@@ -66,4 +66,41 @@ export function pathsRelated(left, right) {
     const b = norm(right);
     return a === b || a.endsWith(`/${b}`) || b.endsWith(`/${a}`);
 }
+/** True when `target` is a path Hunch's index already knows about: an indexed
+ *  symbol's exact file, or a path an indexed component's `paths` glob(s) cover.
+ *  The latter catches a symbol-less-but-indexed file (README.md, package.json,
+ *  Dockerfile, ...) that has zero tree-sitter symbols but is still a real,
+ *  known file. Derived entirely from already-loaded graph data — never the
+ *  filesystem — so the answer doesn't depend on untracked working-tree state
+ *  (a deleted-but-still-indexed path stays "real"; issue #299). */
+export function isIndexedPath(target, symbolFiles, componentPaths) {
+    for (const f of symbolFiles)
+        if (f === target)
+            return true;
+    for (const globs of componentPaths)
+        for (const g of globs)
+            if (pathMatchesGlob(target, g))
+                return true;
+    return false;
+}
+/** Resolve symbols matching `target`, tiered: exact id > exact name > exact file >
+ *  (only when `target` is NOT a path already known to the index) segment-anchored
+ *  suffix. A real indexed file with zero symbols must return [] rather than fall
+ *  through to the suffix tier, which would leak an unrelated same-basename file's
+ *  records (issue #299) — callers compute `indexed` via `isIndexedPath` first so
+ *  the "is this a real path" question is answered identically everywhere. */
+export function matchSymbolsTiered(target, symbols, indexed) {
+    const byId = symbols.find((s) => s.id === target);
+    if (byId)
+        return [byId];
+    const byName = symbols.filter((s) => s.name === target);
+    if (byName.length)
+        return byName;
+    const exact = symbols.filter((s) => s.file === target);
+    if (exact.length)
+        return exact;
+    if (indexed)
+        return [];
+    return symbols.filter((s) => pathsRelated(s.file, target));
+}
 //# sourceMappingURL=glob.js.map

package/dist/core/paths.d.ts

@@ -1,10 +1,32 @@
 export declare const HUNCH_DIR = ".hunch";
-/** Canonicalize a free-form path/target to repo-relative POSIX form. Hunch stores
- *  every path with forward slashes (git emits "/" on all OSes), so any user- or
- *  agent-supplied target must be normalized before comparison — otherwise a
- *  Windows caller passing `src\auth\session.ts` never matches the stored
- *  `src/auth/session.ts`. Safe on symbol names too: they contain no backslashes. */
+/** Canonicalize a free-form path/target to forward-slash form (Hunch stores every
+ *  path with "/" — git emits it on all OSes — so any user- or agent-supplied
+ *  target must be normalized before comparison, otherwise a Windows caller passing
+ *  `src\auth\session.ts` never matches the stored `src/auth/session.ts`). Safe on
+ *  symbol names too: they contain no backslashes. This does NOT make a path
+ *  repo-relative — an absolute path passes through with its separators flipped,
+ *  unchanged otherwise; use `repoRelativeTarget` for that. */
 export declare function toPosixTarget(target: string): string;
+/** realpath a path even if it doesn't exist yet (e.g. a new file an agent is about
+ *  to Write, or a glob whose concrete segments aren't literal): resolve the longest
+ *  existing ancestor, then re-append the missing tail. Idempotent on an
+ *  already-resolved path. */
+export declare function realpathNorm(p: string): string;
+/** Rewrite an ABSOLUTE target to repo-relative POSIX form when it falls inside
+ *  `root`. Hunch's stored paths (symbols, constraint scopes, ...) are always
+ *  repo-relative, so a caller that hands over an absolute edit-payload path
+ *  matched nothing (issue #296: hunch_check_constraints / hunch_blast_radius
+ *  returned empty for an absolute target that plainly had a matching rule). A
+ *  relative target, a glob, or an absolute path outside `root` passes through
+ *  unchanged (toPosixTarget'd) — there is nothing safe to rewrite it to.
+ *
+ *  BOTH ends are realpath-normalized before the relative-path computation: on
+ *  macOS `process.cwd()` (hence `findRoot`) resolves /var → /private/var, but a
+ *  hook event's `file_path` arrives UN-resolved, so a naive `relative()` yields a
+ *  bogus "../" path under a symlinked root (/var, /tmp, symlinked $HOME) and the
+ *  caller treats the file as outside the repo, silently dropping all context
+ *  (dec_e0a36efbf5). */
+export declare function repoRelativeTarget(target: string, root: string): string;
 export interface HunchPaths {
     /** Repo root (where .hunch/ lives). */
     root: string;

package/dist/core/paths.js

@@ -1,16 +1,61 @@
 /** Filesystem layout for the Hunch (DESIGN.md §6 folder structure). */
 import { join } from "node:path";
 import { existsSync, realpathSync, statSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+import { basename, dirname, isAbsolute, relative, resolve } from "node:path";
 export const HUNCH_DIR = ".hunch";
-/** Canonicalize a free-form path/target to repo-relative POSIX form. Hunch stores
- *  every path with forward slashes (git emits "/" on all OSes), so any user- or
- *  agent-supplied target must be normalized before comparison — otherwise a
- *  Windows caller passing `src\auth\session.ts` never matches the stored
- *  `src/auth/session.ts`. Safe on symbol names too: they contain no backslashes. */
+/** Canonicalize a free-form path/target to forward-slash form (Hunch stores every
+ *  path with "/" — git emits it on all OSes — so any user- or agent-supplied
+ *  target must be normalized before comparison, otherwise a Windows caller passing
+ *  `src\auth\session.ts` never matches the stored `src/auth/session.ts`). Safe on
+ *  symbol names too: they contain no backslashes. This does NOT make a path
+ *  repo-relative — an absolute path passes through with its separators flipped,
+ *  unchanged otherwise; use `repoRelativeTarget` for that. */
 export function toPosixTarget(target) {
     return target.replace(/\\/g, "/").replace(/^\.\//, "");
 }
+/** realpath a path even if it doesn't exist yet (e.g. a new file an agent is about
+ *  to Write, or a glob whose concrete segments aren't literal): resolve the longest
+ *  existing ancestor, then re-append the missing tail. Idempotent on an
+ *  already-resolved path. */
+export function realpathNorm(p) {
+    try {
+        return realpathSync.native(p);
+    }
+    catch {
+        const parent = dirname(p);
+        if (parent === p)
+            return p; // hit the root; nothing more to resolve
+        return join(realpathNorm(parent), basename(p));
+    }
+}
+/** Rewrite an ABSOLUTE target to repo-relative POSIX form when it falls inside
+ *  `root`. Hunch's stored paths (symbols, constraint scopes, ...) are always
+ *  repo-relative, so a caller that hands over an absolute edit-payload path
+ *  matched nothing (issue #296: hunch_check_constraints / hunch_blast_radius
+ *  returned empty for an absolute target that plainly had a matching rule). A
+ *  relative target, a glob, or an absolute path outside `root` passes through
+ *  unchanged (toPosixTarget'd) — there is nothing safe to rewrite it to.
+ *
+ *  BOTH ends are realpath-normalized before the relative-path computation: on
+ *  macOS `process.cwd()` (hence `findRoot`) resolves /var → /private/var, but a
+ *  hook event's `file_path` arrives UN-resolved, so a naive `relative()` yields a
+ *  bogus "../" path under a symlinked root (/var, /tmp, symlinked $HOME) and the
+ *  caller treats the file as outside the repo, silently dropping all context
+ *  (dec_e0a36efbf5). */
+export function repoRelativeTarget(target, root) {
+    const t = toPosixTarget(target);
+    const looksAbsolute = isAbsolute(t) || /^[a-zA-Z]:/.test(t);
+    if (!looksAbsolute)
+        return t;
+    // `root` is posix'd too, not just `target`: realpathNorm's fallback walk decomposes
+    // by "/" (via node:path, which on a POSIX host does NOT treat "\" as a separator),
+    // so an un-posix'd root and a posix'd target would decompose into differently-shaped
+    // ancestor chains and never share a common realpath'd prefix.
+    const rel = toPosixTarget(relative(realpathNorm(toPosixTarget(root)), realpathNorm(t)));
+    if (!rel || rel === ".." || rel.startsWith("../") || isAbsolute(rel) || /^[a-zA-Z]:/.test(rel))
+        return t;
+    return rel;
+}
 export function hunchPaths(root) {
     const hunch = join(root, HUNCH_DIR);
     return {

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