@davesheffer/hunch 1.43.0 → 1.44.0

package/dist/core/docanchors.js

@@ -58,14 +58,18 @@ function thematicBreakSuffixes(probe) {
     }
     return ok;
 }
-/** Character ranges covered by fenced code blocks (``` or ~~~), so a
- *  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.
- *  The "≤3 leading spaces" is measured relative to the enclosing LIST ITEM's
- *  content offset, so a fence indented under `1. step` (issue #331) is still a
- *  fence and not an indented code block.
+/** Character ranges covered by code blocks — fenced (``` or ~~~) and indented —
+ *  so a documentation EXAMPLE of a marker never registers as a live anchor.
+ *  A hand scanner, not a markdown parser: it answers only "is this offset inside
+ *  code as a renderer shows it?", line by line and linear in each line's length.
+ *
+ *  Fences, 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
+ *  (reported as `unclosed`, which drift surfaces — issue #381); a backtick
+ *  fence's info string may not itself contain a backtick. The "≤3 leading
+ *  spaces" is measured relative to the enclosing LIST ITEM's content offset, so a
+ *  fence indented under `1. step` (issue #331) is still a fence and not an
+ *  indented code block.
  *
  *  A fence hosted in a list item ends where the ITEM ends: at the first
  *  non-blank line dedented below the item's content base. That is what the
@@ -75,134 +79,286 @@ function thematicBreakSuffixes(probe) {
  *  reader sees, not with the author's intent. In sloppy docs that differs from
  *  a flat fence scan; the rendering is the tiebreaker.
  *
+ *  Also as a renderer reads them (issue #381):
+ *  - indented code: ≥4 columns past the container's content, not continuing a
+ *    paragraph, runs until a line dedents below that (blank lines inside it);
+ *  - blockquotes: `>` prefixes are peeled first, so `> ```` opens a fence inside
+ *    the quote, and a line that leaves the quote ends it;
+ *  - HTML blocks (CommonMark types 1–6: script/pre/style/textarea, comments,
+ *    `<?`, `<!X`, CDATA, block-level tags): their lines are raw HTML, so a ``` or
+ *    an indented line inside one opens no code block. A marker inside an HTML
+ *    block stays LIVE: it is an HTML comment there too, not shown as an example;
+ *  - lazy continuation: a paragraph line dedented out of its list item or quote
+ *    that starts no block of its own keeps that item/quote open.
+ *
  *  Tabs expand to the next 4-column tab stop (not a flat 4), so `\t``` ` sits
  *  at column 4 exactly as a renderer places it. Offsets always come from the
  *  ORIGINAL line, never from the expanded probe.
  *
- *  Deliberate limits: no lazy continuations and no blockquote containers — a
- *  `>` prefix is still read as ordinary text. With no list open the item stack
- *  is empty, the base is 0 and behaviour is the plain CommonMark-lite one.
- *  Expects LF-normalized text — see parseDocAnchors's normalization; a caller
- *  that skips it re-opens the CRLF fence-detection bug. */
-function fencedRanges(text) {
-    const FENCE = /^ {0,3}(`{3,}|~{3,})(.*)$/;
+ *  Deliberate limits, each a case where it can still disagree with a renderer:
+ *  HTML block type 7 (a lone arbitrary tag line) reads as text; a blockquote
+ *  nested INSIDE a list item is read as a top-level quote; after a tab right
+ *  after a `>`, later tabs on that line expand from the quote's content, not
+ *  the line. With no container
+ *  open the base is 0 and behaviour is the plain CommonMark-lite one.
+ *  Expects LF-normalized, BOM-free text — see parseDocAnchors's normalization;
+ *  a caller that skips it re-opens the CRLF fence-detection bug. */
+function codeRanges(text) {
     const ranges = [];
     let open = null;
-    // Content offsets (columns) of the currently open list items, outermost first.
+    // Open list items, outermost first: the quote depth each lives in and its content column.
     const items = [];
+    let curQ = 0; // quote depth of the current block
     let offset = 0;
+    let lineNo = 0;
     // Whether the previous line was a paragraph-continuation line: non-blank,
     // and not itself a container/leaf opener. Only a bullet or a `1.`/`1)` with
     // non-empty content may interrupt such a paragraph (CommonMark), so prose
     // like "see item\n2. the second point" stays one paragraph.
     let inParagraph = false;
+    const closeOpen = (lineStart) => {
+        if (open?.kind === "fence")
+            ranges.push([open.start, lineStart - 1]);
+        else if (open?.kind === "indent")
+            ranges.push([open.start, open.end]);
+        open = null;
+    };
     for (const line of text.split("\n")) {
+        lineNo++;
+        const lineStart = offset;
+        offset += line.length + 1;
         // Matching-only copy: tabs advance to the next 4-column tab stop.
         const probe = expandTabs(line);
-        const indent = probe.length - probe.replace(/^ +/, "").length;
-        const blank = probe.trim() === "";
         if (open) {
-            if (!blank && indent < open.base) {
-                // The list item holding the fence ended, which ends the fence too.
-                ranges.push([open.start, offset - 1]);
-                open = null;
+            const held = peelQuotes(probe, open.q);
+            if (held.q < open.q) {
+                closeOpen(lineStart); // the quote holding the block ended, which ends the block too
             }
             else {
-                const m = FENCE.exec(probe.slice(Math.min(open.base, indent)));
-                if (m && m[1][0] === open.ch && m[1].length >= open.len && m[2].trim() === "") {
-                    ranges.push([open.start, offset + line.length]);
-                    open = null;
+                const rest = held.rest;
+                const indent = leadingSpaces(rest);
+                const blank = rest.trim() === "";
+                if (open.kind === "fence") {
+                    if (!blank && indent < open.base) {
+                        closeOpen(lineStart); // the list item holding the fence ended, which ends the fence too
+                    }
+                    else {
+                        const m = FENCE.exec(rest.slice(Math.min(open.base, indent)));
+                        if (m && m[1][0] === open.ch && m[1].length >= open.len && m[2].trim() === "") {
+                            ranges.push([open.start, lineStart + line.length]);
+                            open = null;
+                        }
+                        continue; // the container stacks are frozen while a fence is open
+                    }
+                }
+                else if (open.kind === "indent") {
+                    if (blank)
+                        continue;
+                    if (indent >= open.base + 4) {
+                        open.end = lineStart + line.length;
+                        continue;
+                    }
+                    closeOpen(lineStart);
+                }
+                else {
+                    if (open.end === "blank" ? blank : open.end.test(rest)) {
+                        open = null;
+                        inParagraph = false;
+                    }
+                    continue;
                 }
-                offset += line.length + 1;
-                continue; // the item stack is frozen while a fence is open
             }
         }
-        if (blank) {
-            offset += line.length + 1;
+        const { q, rest } = peelQuotes(probe, Infinity);
+        const indent = leadingSpaces(rest);
+        if (rest.trim() === "") {
+            while (items.length && items.at(-1).q > q)
+                items.pop();
+            curQ = q;
             inParagraph = false;
             continue; // a blank line neither opens nor closes an item here
         }
+        const isBreak = thematicBreakSuffixes(rest);
+        // Lazy continuation: a paragraph line that falls out of its item or quote but
+        // starts no block of its own still belongs to that paragraph, so every
+        // container stays open (`- foo\nbar` — bar is item text).
+        const top = items.at(-1);
+        const leaves = q < curQ || (top !== undefined && top.q === q && top.base > indent);
+        if (inParagraph && leaves && !startsBlock(rest, indent, isBreak))
+            continue;
         // A dedent that closes an item also closes the paragraph inside it, so the
         // line is a fresh block start: `1. one\n2. two` is two sibling items, not
         // item one's paragraph being "interrupted" by a `2.`.
-        let popped = false;
-        while (items.length && items.at(-1) > indent) {
+        let popped = q !== curQ;
+        while (items.length && (items.at(-1).q !== q || items.at(-1).base > indent)) {
             items.pop();
             popped = true;
         }
-        const isBreak = thematicBreakSuffixes(probe);
+        curQ = q;
         // Walk the line with an INDEX, peeling one list marker per step. Each step
         // is O(marker) and the cheap checks are O(1), so a line costs O(length)
         // however many markers it carries.
-        let base = items.at(-1) ?? 0;
+        let base = items.at(-1)?.base ?? 0;
         let opened = false;
         let thematic = false;
+        let indented = false;
+        let at = base;
         for (;;) {
             // Leading spaces of this nesting level: ≤3, else it is indented content
             // (and `    ---` is paragraph text or code, never a thematic break).
             let i = base;
-            while (i < probe.length && probe[i] === " " && i - base < 4)
+            while (i < rest.length && rest[i] === " " && i - base < 4)
                 i++;
-            const lead = i - base;
-            if (lead > 3)
+            at = i;
+            if (i - base > 3) {
+                indented = true;
                 break;
+            }
             if (isBreak[i]) {
                 thematic = true;
                 break;
             } // thematic break, not a list marker
-            const c = probe[i];
+            const c = rest[i];
             let markerLen = 0;
             if (c === "-" || c === "*" || c === "+")
                 markerLen = 1;
             else if (c !== undefined && c >= "0" && c <= "9") {
                 let d = i;
-                while (d < probe.length && probe[d] >= "0" && probe[d] <= "9" && d - i < 9)
+                while (d < rest.length && rest[d] >= "0" && rest[d] <= "9" && d - i < 9)
                     d++;
-                if (probe[d] === "." || probe[d] === ")")
+                if (rest[d] === "." || rest[d] === ")")
                     markerLen = d - i + 1;
             }
             if (!markerLen)
                 break;
             // Spaces between the marker and the item's content.
             let s = i + markerLen;
-            while (s < probe.length && probe[s] === " ")
+            while (s < rest.length && rest[s] === " ")
                 s++;
             const gap = s - (i + markerLen);
-            const emptyItem = s >= probe.length;
+            const emptyItem = s >= rest.length;
             if (!emptyItem && gap === 0)
                 break; // `-foo` / `1.foo` is not a marker
             if (!opened && !popped && inParagraph && items.length === 0) {
                 // Interrupting a paragraph: only a bullet, or `1.`/`1)`, and never with
                 // empty content. `2. the second point` mid-prose stays paragraph text.
-                const ordinal = markerLen > 1 ? probe.slice(i, i + markerLen - 1) : "";
+                const ordinal = markerLen > 1 ? rest.slice(i, i + markerLen - 1) : "";
                 if (emptyItem || (ordinal !== "" && ordinal !== "1"))
                     break;
             }
             // ≥5 spaces after the marker starts an indented code block, so the
             // item's content begins one column after the marker instead.
             const w = gap >= 1 && gap <= 4 ? gap : 1;
-            base = base + lead + markerLen + w;
-            items.push(base);
+            base = i + markerLen + w;
+            items.push({ q, base });
             opened = true;
             continue; // `- 1. x` nests, and "- ```js" opens a fence on the marker line
         }
-        const m = FENCE.exec(probe.slice(base));
+        if (indented) {
+            // An indented code block cannot interrupt a paragraph: there it is text.
+            if (!inParagraph || opened) {
+                open = { kind: "indent", start: lineStart, end: lineStart + line.length, base, q };
+                inParagraph = false;
+            }
+            continue;
+        }
+        const content = rest.slice(at);
+        const html = htmlBlockEnd(content);
+        if (html) {
+            if (html === "blank" || !html.test(content))
+                open = { kind: "html", end: html, q };
+            inParagraph = false;
+            continue;
+        }
+        const m = FENCE.exec(rest.slice(base));
         if (m) {
             const ch = m[1][0];
             if (!(ch === "`" && m[2].includes("`")))
-                open = { ch, len: m[1].length, start: offset, base };
+                open = { kind: "fence", ch, len: m[1].length, start: lineStart, base, q, line: lineNo };
         }
-        // A fence line or a thematic break ends the paragraph it follows; ordinary
+        // A fence line, a thematic break or a heading (ATX, or a `===` setext
+        // underline beneath a paragraph) ends the paragraph it follows; ordinary
         // text (including an item's own content) continues or starts one.
-        inParagraph = !m && !thematic;
-        offset += line.length + 1;
+        const setext = inParagraph && /^=+[ \t]*$/.test(content);
+        inParagraph = !m && !thematic && !setext && content.trim() !== "" && !/^#{1,6}(?:[ \t]|$)/.test(content);
     }
-    if (open)
-        ranges.push([open.start, text.length]);
-    return ranges;
+    let unclosed = null;
+    const last = open;
+    if (last?.kind === "fence") {
+        ranges.push([last.start, text.length]);
+        unclosed = { start: last.start, line: last.line };
+    }
+    else if (last?.kind === "indent")
+        ranges.push([last.start, last.end]);
+    return { ranges, unclosed };
+}
+const FENCE = /^ {0,3}(`{3,}|~{3,})(.*)$/;
+const leadingSpaces = (s) => s.length - s.replace(/^ +/, "").length;
+/** Peel up to `max` blockquote markers (`>`, ≤3 spaces before it, one optional
+ *  space after) off a tab-expanded line: the quote depth and what follows. */
+function peelQuotes(probe, max) {
+    let q = 0;
+    let i = 0;
+    let col = 0;
+    let pad = 0;
+    while (q < max) {
+        let j = i;
+        while (j < probe.length && probe[j] === " " && j - i < 3)
+            j++;
+        if (probe[j] !== ">")
+            break;
+        col += j - i + 1;
+        i = j + 1;
+        pad = 0;
+        if (probe[i] === " ") {
+            i++;
+            col++;
+        }
+        else if (probe[i] === "\t") {
+            // The tab's first column is the quote's optional space; the rest of it is
+            // content indentation (CommonMark 5.1). `>\t<!-- … -->` is a paragraph, not code.
+            const width = 4 - (col % 4);
+            i++;
+            col += width;
+            pad = width - 1;
+        }
+        q++;
+    }
+    return q ? { q, rest: " ".repeat(pad) + expandTabs(probe.slice(i)) } : { q, rest: probe };
+}
+/** Whether a line (≤3 columns in) opens a block of its own, which a lazy
+ *  continuation line by definition does not. */
+function startsBlock(rest, indent, isBreak) {
+    if (indent > 3)
+        return false;
+    const s = rest.slice(indent);
+    return isBreak[indent] === true || FENCE.test(rest) || /^#{1,6}(?:[ \t]|$)/.test(s) || s[0] === ">"
+        || htmlBlockEnd(s) !== null || /^(?:[-*+]|\d{1,9}[.)])(?:[ \t]|$)/.test(s);
+}
+const HTML_BLOCK_TAGS = new Set(("address article aside base basefont blockquote body caption center col colgroup dd details dialog dir div dl dt "
+    + "fieldset figcaption figure footer form frame frameset h1 h2 h3 h4 h5 h6 head header hr html iframe legend li link main menu menuitem "
+    + "nav noframes ol optgroup option p param search section summary table tbody td tfoot th thead title tr track ul").split(" "));
+/** The end condition of the HTML block (CommonMark types 1–6) a line opens:
+ *  a pattern that closes it on a later (or the same) line, "blank" for a block
+ *  that runs to the next blank line, or null when the line opens none. */
+function htmlBlockEnd(s) {
+    if (s[0] !== "<")
+        return null;
+    if (/^<(?:script|pre|style|textarea)(?:[\s>]|$)/i.test(s))
+        return /<\/(?:script|pre|style|textarea)>/i;
+    if (s.startsWith("<!--"))
+        return /-->/;
+    if (s.startsWith("<?"))
+        return /\?>/;
+    if (s.startsWith("<![CDATA["))
+        return /\]\]>/;
+    if (/^<![A-Za-z]/.test(s))
+        return />/;
+    const tag = /^<\/?([A-Za-z][A-Za-z0-9-]*)(?:[\s>]|\/>|$)/.exec(s);
+    return tag && HTML_BLOCK_TAGS.has(tag[1].toLowerCase()) ? "blank" : null;
 }
 /** Character ranges covered by inline code spans (`…`), same rationale as
- *  fencedRanges: prose quoting a marker in backticks is showing an example.
+ *  codeRanges: 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.
  *  Expects LF-normalized text — see parseDocAnchors's normalization.
@@ -229,28 +385,39 @@ function inlineSpanRanges(text) {
     return ranges;
 }
 /** Parse every hunch:topic marker out of a markdown document. Markers inside
- *  fenced code blocks or inline code spans are examples, not declarations,
- *  and are skipped. */
+ *  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
+    return scanDocAnchors(text).anchors;
+}
+/** parseDocAnchors plus what drift reports about the document: a fence that
+ *  never closes hides every marker below it, almost always by mistake (#381). */
+export function scanDocAnchors(text) {
+    // codeRanges 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 = normalizeEol(text);
-    const out = [];
-    const skip = [...fencedRanges(text), ...inlineSpanRanges(text)];
+    // codeRanges/inlineSpanRanges/MARKER offsets consistent with each other
+    // and with the line numbers reported below. A leading BOM is dropped too, so
+    // line 1 starts at column 0 (#381); it is one char on line 1, so line numbers hold.
+    text = normalizeEol(text).replace(/^\uFEFF/, "");
+    const anchors = [];
+    const code = codeRanges(text);
+    const skip = [...code.ranges, ...inlineSpanRanges(text)];
+    let hidden = 0;
     MARKER.lastIndex = 0;
     let m;
     while ((m = MARKER.exec(text))) {
         const at = m.index;
-        if (skip.some(([s, e]) => at >= s && at <= e))
+        if (skip.some(([s, e]) => at >= s && at <= e)) {
+            if (code.unclosed && at > code.unclosed.start)
+                hidden++;
             continue;
-        out.push({ topic: m[1], pin: m[2] ?? null, line: text.slice(0, at).split("\n").length });
+        }
+        anchors.push({ topic: m[1], pin: m[2] ?? null, line: text.slice(0, at).split("\n").length });
     }
-    return out;
+    return { anchors, unclosedFence: code.unclosed && hidden ? { line: code.unclosed.line, hidden } : null };
 }
 const clip = (s, n = 220) => (s.length > n ? s.slice(0, n - 1).trimEnd() + "…" : s);
 /** Pre-edit grounding for a markdown document that carries topic anchors: the

package/dist/core/drift.d.ts

@@ -1,5 +1,5 @@
 import type { HunchStore } from "../store/hunchStore.js";
-export declare const DRIFT_KINDS: readonly ["dead-ref", "supersede", "doc-stale", "anchor-stale", "doc-anchor-stale", "doc-anchor-dangling", "wiki-stale", "finding-stale", "premise-stale", "commit-unresolvable", "madr-stale", "madr-edited", "madr-orphan"];
+export declare const DRIFT_KINDS: readonly ["dead-ref", "supersede", "doc-stale", "anchor-stale", "doc-anchor-stale", "doc-anchor-dangling", "doc-fence-unclosed", "wiki-stale", "finding-stale", "premise-stale", "commit-unresolvable", "madr-stale", "madr-edited", "madr-orphan"];
 export type DriftKind = typeof DRIFT_KINDS[number];
 export interface DriftFinding {
     kind: DriftKind;

package/dist/core/drift.js

@@ -22,12 +22,12 @@ import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { toPosixTarget } from "./paths.js";
 import { currentForTopic, isLive } from "./topics.js";
 import { evaluatePremises } from "./premises.js";
-import { parseDocAnchors } from "./docanchors.js";
+import { scanDocAnchors } from "./docanchors.js";
 import { markdownDocs, STALE_MARKER, SRC_REF } from "./docscan.js";
 import { computeWikiDrift } from "../wiki/wiki.js";
 import { computeMadrDrift } from "../integrations/madrManifest.js";
 import { commitsExist, isGitRepo } from "../extractors/git.js";
-export const DRIFT_KINDS = ["dead-ref", "supersede", "doc-stale", "anchor-stale", "doc-anchor-stale", "doc-anchor-dangling", "wiki-stale", "finding-stale", "premise-stale", "commit-unresolvable", "madr-stale", "madr-edited", "madr-orphan"];
+export const DRIFT_KINDS = ["dead-ref", "supersede", "doc-stale", "anchor-stale", "doc-anchor-stale", "doc-anchor-dangling", "doc-fence-unclosed", "wiki-stale", "finding-stale", "premise-stale", "commit-unresolvable", "madr-stale", "madr-edited", "madr-orphan"];
 export function computeDrift(store, root, deps = {}) {
     const findings = [];
     const decisions = store.recs("decisions");
@@ -157,7 +157,14 @@ export function computeDrift(store, root, deps = {}) {
         //    been superseded (doc-anchor-stale, the CI-gateable one) or that doesn't
         //    exist (doc-anchor-dangling). Unpinned markers only ground the pre-edit
         //    hook — an explicit pin is the ONLY thing that can fire drift here.
-        for (const a of parseDocAnchors(text)) {
+        //    A fence that never closes hides every marker below it (doc-fence-unclosed,
+        //    advisory): almost always an authoring mistake that disables real anchors.
+        const scan = scanDocAnchors(text);
+        if (scan.unclosedFence) {
+            const { line, hidden } = scan.unclosedFence;
+            findings.push({ kind: "doc-fence-unclosed", id: doc.rel, detail: `fence opened at line ${line} never closes; ${hidden} marker(s) below it are hidden` });
+        }
+        for (const a of scan.anchors) {
             if (!a.pin)
                 continue;
             const pinned = byId.get(a.pin);

package/dist/core/eol.d.ts

@@ -2,6 +2,8 @@
 export declare function normalizeEol(text: string): string;
 /** Remove the CR retained by split("\n") without changing source offsets. */
 export declare function lineContent(line: string): string;
+/** Length of the line break (CRLF, CR, or LF) starting at `at`, or 0. */
+export declare function eolLengthAt(text: string, at: number): number;
 /** Read logical lines while keeping offsets in the original UTF-16 source. */
 export declare function sourceLines(text: string): Generator<{
     content: string;

package/dist/core/eol.js

@@ -6,6 +6,12 @@ export function normalizeEol(text) {
 export function lineContent(line) {
     return line.endsWith("\r") ? line.slice(0, -1) : line;
 }
+/** Length of the line break (CRLF, CR, or LF) starting at `at`, or 0. */
+export function eolLengthAt(text, at) {
+    if (text[at] === "\r")
+        return text[at + 1] === "\n" ? 2 : 1;
+    return text[at] === "\n" ? 1 : 0;
+}
 /** Read logical lines while keeping offsets in the original UTF-16 source. */
 export function* sourceLines(text) {
     let start = 0;

package/dist/core/procstart.d.ts

@@ -66,10 +66,14 @@ export declare function ownerInstance(ownerStart: string | undefined, pid: numbe
  *  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";
+ *  - `stale`    — provably not the owner's process any more: take it over.
+ *  - `live`     — authoritative, however old the file looks: never steal it.
+ *  - `unproven` — a live pid whose process instance no token can compare (macOS,
+ *                 Windows, a legacy record). Treated as live; a caller with a
+ *                 better probe may still disprove it (src/serve/writelock.ts
+ *                 asks the OS when that process was created, issue #287).
+ *  - `age`      — nothing is proven; fall back to the caller's own age rule. */
+export type SameHostVerdict = "stale" | "live" | "unproven" | "age";
 /** The parts of a lock record this decision reads. Both lock formats supply it. */
 export interface SameHostOwner {
     pid: number;
@@ -91,4 +95,11 @@ export interface SameHostEnv {
  * process state beyond what `env` hands it.
  */
 export declare function judgeSameHostOwner(owner: SameHostOwner, env: SameHostEnv): SameHostVerdict;
+/** Wall-clock ms at which the process now holding `pid` was created, from the
+ *  OS, or null when it cannot be read. SPAWNS (PowerShell on Windows, `ps` on
+ *  macOS), so it is for rare paths only — a lock that already looks stale —
+ *  never for every acquisition. Precision is a second on `ps`. Null on every
+ *  other platform: linux derives `lstart` from boot time, which a forward clock
+ *  step shifts for live processes too (see the header). */
+export declare function processStartedAt(pid: number): number | null;
 export {};

package/dist/core/procstart.js

@@ -23,19 +23,23 @@
  * puts two writers inside the mutex. Reproduced by simply `utimes`-ing a held
  * lock 30 s into the past. Nothing in this file may read a clock.
  *
- * REMAINING GAP. Only linux exposes a spawn-free, stable process-instance id
- * (`/proc/<pid>/stat` field 22 plus the boot id and the pid/time namespaces). On
- * macOS and Windows a DIFFERENT live process that recycled the owner's pid
- * therefore stays "not proven" and keeps the lock until the age rule applies —
- * today's behaviour, and the safe direction. `ps -o lstart` and PowerShell's
- * `Get-Process ... StartTime` were rejected: both cost a spawn per probe on the
- * contended path, and both return locale/TZ-dependent strings we would have to
- * parse back into a comparable identity. Gating such a probe on age does not
- * rescue them either: the CONTENDER can read the current holder's start time,
- * but a verdict needs something to compare it WITH — either a start time the
- * OWNER recorded when it took the lock (which puts that spawn on every writing
- * process, not just the contended path) or a start-time-vs-mtime comparison,
- * i.e. exactly the cross-clock arithmetic rejected above.
+ * OFF LINUX (issue #287). Only linux exposes a spawn-free, stable process-instance
+ * id (`/proc/<pid>/stat` field 22 plus the boot id and the pid/time namespaces), so
+ * on macOS and Windows a DIFFERENT live process that recycled the owner's pid is
+ * "unproven" here, which this table treats as live. The write lock closes that
+ * forever-deadlock on its own rare path, once a lock already looks stale: it asks
+ * the OS when the process now holding the pid was CREATED (`processStartedAt`, a
+ * spawn) and compares that with the `at` the owner recorded when it took the lock.
+ * A process created after the lock was taken cannot have taken it. Both instants
+ * are the HOST's wall clock, read on this same host, so the filesystem clock never
+ * enters; only a backward clock step of more than the slack between the owner's
+ * start and its acquisition could fake it. macOS and Windows record that creation
+ * instant absolutely; linux does not (`ps lstart` is boot time + uptime, so a
+ * forward clock step after boot moves every live process's "creation" forward and
+ * would fake a reuse), so on linux the probe reports nothing and a tokenless
+ * record keeps main's pid rule — linux writers record a token instead. The earlier objection to such a probe —
+ * that it needs either an owner-recorded start time (a spawn on every write) or a
+ * start-vs-mtime comparison — missed that `at` is already in every record.
  *
  * UNSUPPORTED TOPOLOGIES. A linux-written token carries its boot id and its pid
  * and time namespaces, so a lock written under another boot or another namespace
@@ -51,12 +55,14 @@
  * while our own token is memoized from before the checkpoint — so a restored
  * holder may judge itself against a token that no longer describes it. Tokenless
  * records (a legacy pre-token hunch, any non-linux writer, an unreadable /proc)
- * get main's unchanged pid rule — a live same-host pid keeps its lock, a dead one
- * is stealable — with exactly one exception, the own-pid + foreign-nonce row
+ * get main's unchanged pid rule — a live same-host pid keeps its lock (unless the
+ * write lock's creation-time check above proves the pid reused), a dead one is
+ * stealable — with exactly one exception, the own-pid + foreign-nonce row
  * described in `judgeSameHostOwner`, which gets the AGE rule instead of main's
  * "live forever".
  */
 import { readFileSync, readlinkSync } from "node:fs";
+import { spawnSync } from "node:child_process";
 /** `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
@@ -237,8 +243,40 @@ export function judgeSameHostOwner(owner, env) {
     //    that a live writer may still hold.
     if (owner.pid === env.selfPid && owner.nonce !== undefined)
         return "age";
-    // A nonce-less own-pid record stays live: there is nothing to compare, and a
-    // live pid is never stolen on a guess.
-    return "live";
+    // 7. A live pid no token can compare — another process's, or a nonce-less
+    //    record of our own pid. Never stolen on a guess: "unproven" is "live" to a
+    //    caller that has nothing better. The write lock asks the OS for that
+    //    process's creation time, which can prove the pid was reused (issue #287).
+    return "unproven";
+}
+/** Wall-clock ms at which the process now holding `pid` was created, from the
+ *  OS, or null when it cannot be read. SPAWNS (PowerShell on Windows, `ps` on
+ *  macOS), so it is for rare paths only — a lock that already looks stale —
+ *  never for every acquisition. Precision is a second on `ps`. Null on every
+ *  other platform: linux derives `lstart` from boot time, which a forward clock
+ *  step shifts for live processes too (see the header). */
+export function processStartedAt(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return null;
+    try {
+        if (process.platform === "win32") {
+            // Epoch milliseconds, not a formatted date: a custom format string follows the
+            // culture's time separator (fi-FI prints `09.04.19`), which Date.parse rejects.
+            const r = spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", `([DateTimeOffset](Get-Process -Id ${pid} -ErrorAction Stop).StartTime).ToUnixTimeMilliseconds()`], { encoding: "utf8", timeout: 3_000, windowsHide: true });
+            const ms = r.status === 0 && /^\d+$/.test(r.stdout.trim()) ? Number(r.stdout.trim()) : NaN;
+            return Number.isFinite(ms) ? ms : null;
+        }
+        if (process.platform !== "darwin")
+            return null;
+        const r = spawnSync("ps", ["-o", "lstart=", "-p", String(pid)], { encoding: "utf8", timeout: 3_000, env: { ...process.env, LC_ALL: "C", LANG: "C" } });
+        const m = /^\s*\w{3}\s+(\w{3})\s+(\d{1,2})\s+(\d{1,2}):(\d{2}):(\d{2})\s+(\d{4})\s*$/.exec(r.status === 0 ? r.stdout : "");
+        const month = m ? ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"].indexOf(m[1]) : -1;
+        if (!m || month < 0)
+            return null;
+        return new Date(Number(m[6]), month, Number(m[2]), Number(m[3]), Number(m[4]), Number(m[5])).getTime(); // ps prints local time
+    }
+    catch {
+        return null;
+    }
 }
 //# sourceMappingURL=procstart.js.map

package/dist/core/runbookDraft.d.ts

@@ -0,0 +1,7 @@
+export declare function runbookDraft(commits: readonly {
+    subject: string;
+    files: readonly string[];
+}[], rangeFiles: readonly string[]): {
+    steps: string[];
+    files: string[];
+};