codecartographer-pi 0.24.1 → 0.26.0

package/dist/core/completion.js

@@ -280,6 +280,91 @@ function mentionsAnyId(text, ids) {
     }
     return false;
 }
+/**
+ * The handoff gates that depend on the state they are judged against —
+ * carry_forward targets against the pipeline order, D1 against the open
+ * questions and derives_from links, D3 against question kinds. Run once
+ * before the lock as the cheap refusal and again on the locked read: a
+ * status change between the two (a concurrent completion, an amendment, a
+ * rollback) used to be applied over as if the first verdict still held
+ * (#360; the same shape as #337 for amendments). Returns the warnings the
+ * version-gated D3 produces on an older scaffold.
+ */
+function judgeHandoffAgainstState(state, handoff, validation) {
+    const warnings = [];
+    if (handoff) {
+        const activePhases = new Set(state.pipeline.phase_order);
+        const sourceIndex = state.pipeline.phase_order.indexOf(validation.phaseId);
+        for (const entry of handoff.carry_forward) {
+            const targetIndex = entry.target_phase ? state.pipeline.phase_order.indexOf(entry.target_phase) : -1;
+            if (!entry.target_phase || !activePhases.has(entry.target_phase) || targetIndex <= sourceIndex) {
+                throw new Error(`Invalid handoff: carry_forward target_phase ${entry.target_phase ?? "(missing)"} is not a downstream active pipeline phase; use post_pipeline for work after the pipeline`);
+            }
+        }
+        for (const entry of handoff.post_pipeline) {
+            if (!entry.id?.trim())
+                throw new Error("Invalid handoff: post_pipeline entries require a canonical id");
+        }
+        // Closure integrity, gating (#122, #186). Both checks are deterministic
+        // reads of ids the model wrote itself, so neither can wedge an --auto run
+        // on a heuristic; both sit here, before the lock, alongside the
+        // target_phase check, so a refusal mutates nothing.
+        const questionsById = new Map();
+        const derivesFromById = new Map();
+        for (const phaseState of Object.values(state.status.phases)) {
+            for (const entry of phaseState.open_questions ?? []) {
+                if (entry.id)
+                    questionsById.set(entry.id, entry);
+            }
+            for (const entry of phaseState.carry_forward ?? []) {
+                if (entry.id && entry.derives_from)
+                    derivesFromById.set(entry.id, entry.derives_from);
+            }
+        }
+        const closingQuestionIds = new Set(handoff.open_question_closures.map((closure) => closure.id).filter(Boolean));
+        // D1: a routed item that declares `derives_from` is one candidate answer
+        // to that question. Closing it while the question stands is exactly the
+        // contradiction #122 reported — the routed candidate shipped as settled
+        // while the question that said "source alone cannot determine which" was
+        // still open. A derives_from naming an id that no longer exists is fine:
+        // the question was already resolved.
+        for (const closureId of handoff.carry_forward_closures) {
+            const questionId = derivesFromById.get(closureId);
+            if (!questionId || !questionsById.has(questionId))
+                continue;
+            if (closingQuestionIds.has(questionId))
+                continue;
+            throw new Error(`Refusing to complete ${validation.phaseId}: the handoff closes carry_forward ${closureId}, which derives_from open question ${questionId} — and ${questionId} is still unresolved and is not in this handoff's open_question_closures. `
+                + `A routed item is one candidate answer to the question it came from; closing it does not settle the question. `
+                + `Either close ${questionId} in this same handoff with the evidence that settles it, or leave ${closureId} routed and give the finding an unsettled action ("verify at runtime") instead.`);
+        }
+        // D3: a `needs-runtime-test` question closes on runtime evidence, not on
+        // another source read. Requiring the evidence string to be non-empty is
+        // the whole gate — judging what it says stays prose guidance.
+        //
+        // Unlike D1, this one can fire on a handoff that uses none of the new
+        // fields: a bare-string closure was the only shape before this release.
+        // Gating it unconditionally would apply a rule to workspaces whose own
+        // templates never state it, so it is version-gated exactly like Stage
+        // 2's pairing check — refuse on a scaffold that documents the rule, warn
+        // on one that predates it.
+        const evidenceGateActive = closureEvidenceGateActive(state.scaffoldVersion);
+        for (const closure of handoff.open_question_closures) {
+            if (questionsById.get(closure.id)?.kind !== "needs-runtime-test")
+                continue;
+            if (closure.evidence?.trim())
+                continue;
+            const detail = `open_question_closures closes ${closure.id}, whose kind is needs-runtime-test, without evidence. `
+                + `A runtime question closes on runtime evidence — a spike report or an observation against the running system — not on a source read. `
+                + `Write the closure as an object: { id: ${closure.id}, evidence: <where that evidence lives> }. If you do not have it, leave the question open.`;
+            if (evidenceGateActive)
+                throw new Error(`Refusing to complete ${validation.phaseId}: ${detail}`);
+            warnings.push(`${detail} Warning only: this workspace's scaffold predates the requirement — refresh it `
+                + `(codecarto_refresh_scaffold on MCP, /codecarto-refresh-scaffold on Pi) to make this gating.`);
+        }
+    }
+    return warnings;
+}
 /**
  * Turn each PARTIAL validation row into a `needs-maintainer-decision`
  * question on the phase, unless the row's criterion or evidence cell names an
@@ -354,78 +439,10 @@ export async function completeValidatedPhase(cwd, validation, sourceLabel) {
                 + `plus closeout_summary and optional closeout_content. Then re-run completion.`);
         }
     }
+    // The cheap refusal, before the lock; the verdict that counts is taken
+    // again on the locked read below.
+    let stateWarnings = judgeHandoffAgainstState(initialState, handoff, validation);
     const warnings = [];
-    if (handoff) {
-        const activePhases = new Set(initialState.pipeline.phase_order);
-        const sourceIndex = initialState.pipeline.phase_order.indexOf(validation.phaseId);
-        for (const entry of handoff.carry_forward) {
-            const targetIndex = entry.target_phase ? initialState.pipeline.phase_order.indexOf(entry.target_phase) : -1;
-            if (!entry.target_phase || !activePhases.has(entry.target_phase) || targetIndex <= sourceIndex) {
-                throw new Error(`Invalid handoff: carry_forward target_phase ${entry.target_phase ?? "(missing)"} is not a downstream active pipeline phase; use post_pipeline for work after the pipeline`);
-            }
-        }
-        for (const entry of handoff.post_pipeline) {
-            if (!entry.id?.trim())
-                throw new Error("Invalid handoff: post_pipeline entries require a canonical id");
-        }
-        // Closure integrity, gating (#122, #186). Both checks are deterministic
-        // reads of ids the model wrote itself, so neither can wedge an --auto run
-        // on a heuristic; both sit here, before the lock, alongside the
-        // target_phase check, so a refusal mutates nothing.
-        const questionsById = new Map();
-        const derivesFromById = new Map();
-        for (const phaseState of Object.values(initialState.status.phases)) {
-            for (const entry of phaseState.open_questions ?? []) {
-                if (entry.id)
-                    questionsById.set(entry.id, entry);
-            }
-            for (const entry of phaseState.carry_forward ?? []) {
-                if (entry.id && entry.derives_from)
-                    derivesFromById.set(entry.id, entry.derives_from);
-            }
-        }
-        const closingQuestionIds = new Set(handoff.open_question_closures.map((closure) => closure.id).filter(Boolean));
-        // D1: a routed item that declares `derives_from` is one candidate answer
-        // to that question. Closing it while the question stands is exactly the
-        // contradiction #122 reported — the routed candidate shipped as settled
-        // while the question that said "source alone cannot determine which" was
-        // still open. A derives_from naming an id that no longer exists is fine:
-        // the question was already resolved.
-        for (const closureId of handoff.carry_forward_closures) {
-            const questionId = derivesFromById.get(closureId);
-            if (!questionId || !questionsById.has(questionId))
-                continue;
-            if (closingQuestionIds.has(questionId))
-                continue;
-            throw new Error(`Refusing to complete ${validation.phaseId}: the handoff closes carry_forward ${closureId}, which derives_from open question ${questionId} — and ${questionId} is still unresolved and is not in this handoff's open_question_closures. `
-                + `A routed item is one candidate answer to the question it came from; closing it does not settle the question. `
-                + `Either close ${questionId} in this same handoff with the evidence that settles it, or leave ${closureId} routed and give the finding an unsettled action ("verify at runtime") instead.`);
-        }
-        // D3: a `needs-runtime-test` question closes on runtime evidence, not on
-        // another source read. Requiring the evidence string to be non-empty is
-        // the whole gate — judging what it says stays prose guidance.
-        //
-        // Unlike D1, this one can fire on a handoff that uses none of the new
-        // fields: a bare-string closure was the only shape before this release.
-        // Gating it unconditionally would apply a rule to workspaces whose own
-        // templates never state it, so it is version-gated exactly like Stage
-        // 2's pairing check — refuse on a scaffold that documents the rule, warn
-        // on one that predates it.
-        const evidenceGateActive = closureEvidenceGateActive(initialState.scaffoldVersion);
-        for (const closure of handoff.open_question_closures) {
-            if (questionsById.get(closure.id)?.kind !== "needs-runtime-test")
-                continue;
-            if (closure.evidence?.trim())
-                continue;
-            const detail = `open_question_closures closes ${closure.id}, whose kind is needs-runtime-test, without evidence. `
-                + `A runtime question closes on runtime evidence — a spike report or an observation against the running system — not on a source read. `
-                + `Write the closure as an object: { id: ${closure.id}, evidence: <where that evidence lives> }. If you do not have it, leave the question open.`;
-            if (evidenceGateActive)
-                throw new Error(`Refusing to complete ${validation.phaseId}: ${detail}`);
-            warnings.push(`${detail} Warning only: this workspace's scaffold predates the requirement — refresh it `
-                + `(codecarto_refresh_scaffold on MCP, /codecarto-refresh-scaffold on Pi) to make this gating.`);
-        }
-    }
     // Closure integrity (#122, warning only): a handoff can close a carry-forward
     // or open question the report never addressed — "closed in the handoff,
     // resolved nowhere." The id of every claimed closure should appear somewhere
@@ -444,6 +461,8 @@ export async function completeValidatedPhase(cwd, validation, sourceLabel) {
     let closeoutPath;
     let orchestratorCheckpoint;
     const updatedState = await updateStatusAtomically(cwd, async (lockedState) => {
+        // The verdict that counts is the one on the state about to be written.
+        stateWarnings = judgeHandoffAgainstState(lockedState, handoff, validation);
         const phase = resolvePhase(lockedState, validation.phaseId);
         if (!phase?.primary_output)
             throw new Error(`Phase ${validation.phaseId} is missing primary_output.`);
@@ -510,6 +529,6 @@ export async function completeValidatedPhase(cwd, validation, sourceLabel) {
         updatedState,
         closeoutNotice: closeoutPath ? `Closeout: ${closeoutPath}` : undefined,
         orchestratorCheckpoint,
-        warnings,
+        warnings: [...stateWarnings, ...warnings],
     };
 }

package/dist/core/dashboard-writer.js

@@ -9,7 +9,15 @@
 // a core primitive like everything else they share.
 import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { atomicWriteFile, DASHBOARD_RELATIVE_PATH, getWorkspaceState, loadUsage, NARRATION_CACHE_RELATIVE_PATH, parseSimpleYaml, pathExists, renderDashboard, } from "./index.js";
+// From the modules that define them, not the barrel: `core/index.ts`
+// re-exports this file, and a module that imports the barrel that exports it
+// is a cycle that only resolves because every binding is read at call time
+// (#371).
+import { DASHBOARD_RELATIVE_PATH, NARRATION_CACHE_RELATIVE_PATH, renderDashboard } from "./dashboard.js";
+import { loadUsage } from "./usage.js";
+import { atomicWriteFile, pathExists } from "./utils.js";
+import { getWorkspaceState } from "./workspace.js";
+import { parseSimpleYaml } from "./yaml.js";
 const CLOSEOUT_FILENAME_RE = /^(\d{4}-\d{2}-\d{2})-(.+)\.md$/;
 /**
  * Render and atomically replace `.codecarto/dashboard.html`.

package/dist/core/index.d.ts

@@ -16,6 +16,5 @@ export * from "./dashboard.ts";
 export * from "./library.ts";
 export * from "./synthesis.ts";
 export * from "./broadside.ts";
-export * from "./broadside-verify.ts";
 export * from "./secrets.ts";
 export * from "./dashboard-writer.ts";

package/dist/core/index.js

@@ -19,6 +19,5 @@ export * from "./dashboard.js";
 export * from "./library.js";
 export * from "./synthesis.js";
 export * from "./broadside.js";
-export * from "./broadside-verify.js";
 export * from "./secrets.js";
 export * from "./dashboard-writer.js";

package/dist/core/library.d.ts

@@ -271,8 +271,31 @@ export interface ListEntriesFilter {
     slug?: string;
     source_repo?: string;
 }
+/** How `listEntries` found the index it answered from (#357). */
+export type LibraryIndexState = "indexed" | "missing" | "unparseable";
 export declare function listEntries(libraryRoot: string, filter?: ListEntriesFilter): Promise<LibraryIndexEntry[]>;
-export declare function reindex(libraryRoot: string): Promise<ReindexResult>;
+/**
+ * The entries plus where they came from. A list is read-only: when
+ * `index.yaml` is missing or does not parse, the entries are built from the
+ * entry directories in memory and `indexState` says so, so a caller can ask
+ * for a reindex — the list itself never writes the index, which is the
+ * publisher's under the publish lock (#357; it used to rewrite a corrupt
+ * index unlocked, racing a publish for the same file).
+ */
+export declare function listEntriesWithIndexState(libraryRoot: string, filter?: ListEntriesFilter): Promise<{
+    entries: LibraryIndexEntry[];
+    indexState: LibraryIndexState;
+}>;
+/**
+ * Rebuild `index.yaml` and `INDEX.md` from the entry directories. Every
+ * writer of the index takes the publish lock: a reindex that scanned the
+ * directories before a publish's rename and wrote after the publish's own
+ * reindex used to drop the new version from the index until the next
+ * reindex (#357). `holdingLock` is for the publisher, which already has it.
+ */
+export declare function reindex(libraryRoot: string, opts?: {
+    holdingLock?: boolean;
+}): Promise<ReindexResult>;
 /**
  * Read-only check over the given entries: does every version of each entry
  * record the same repository as its newest version? Comparison goes through

package/dist/core/library.js

@@ -443,7 +443,7 @@ export async function publishEntry(libraryRoot, spec, input, opts = {}) {
             const metadata = buildMetadata({ ...input, provenance }, latestVersion);
             await atomicWriteYaml(join(latestVersionDir, METADATA_FILE), metadata);
             if (!opts.skipReindex)
-                await reindex(libraryRoot);
+                await reindex(libraryRoot, { holdingLock: true });
             return {
                 slug: input.slug,
                 namespace,
@@ -479,7 +479,7 @@ export async function publishEntry(libraryRoot, spec, input, opts = {}) {
         }
         await writeLatestPointer(entryDir, `v${nextVersion}`);
         if (!opts.skipReindex)
-            await reindex(libraryRoot);
+            await reindex(libraryRoot, { holdingLock: true });
         return {
             slug: input.slug,
             namespace,
@@ -653,25 +653,38 @@ function isReasoning(v) {
     return v === "high" || v === "medium" || v === "low" || v === "default" || v === "unknown";
 }
 export async function listEntries(libraryRoot, filter = {}) {
+    return (await listEntriesWithIndexState(libraryRoot, filter)).entries;
+}
+/**
+ * The entries plus where they came from. A list is read-only: when
+ * `index.yaml` is missing or does not parse, the entries are built from the
+ * entry directories in memory and `indexState` says so, so a caller can ask
+ * for a reindex — the list itself never writes the index, which is the
+ * publisher's under the publish lock (#357; it used to rewrite a corrupt
+ * index unlocked, racing a publish for the same file).
+ */
+export async function listEntriesWithIndexState(libraryRoot, filter = {}) {
     const marker = await readMarker(libraryRoot);
     if (!marker)
-        return [];
-    // Prefer the index if it's present; fall back to a fresh reindex if not.
+        return { entries: [], indexState: "missing" };
     const indexPath = join(libraryRoot, LIBRARY_INDEX_FILE);
     let index;
+    let indexState = "indexed";
     if (await pathExists(indexPath)) {
         try {
             const raw = await readFile(indexPath, "utf8");
             index = normalizeIndex(parseSimpleYaml(raw), marker);
         }
         catch {
-            index = await reindex(libraryRoot);
+            index = await scanLibrary(libraryRoot, marker);
+            indexState = "unparseable";
         }
     }
     else {
-        index = await reindex(libraryRoot);
+        index = await scanLibrary(libraryRoot, marker);
+        indexState = "missing";
     }
-    return index.entries.filter((e) => {
+    const entries = index.entries.filter((e) => {
         if (filter.namespace !== undefined && e.namespace !== filter.namespace)
             return false;
         if (filter.slug !== undefined && e.slug !== filter.slug)
@@ -685,13 +698,37 @@ export async function listEntries(libraryRoot, filter = {}) {
             return false;
         return true;
     });
+    return { entries, indexState };
 }
 // ─── Reindex ────────────────────────────────────────────────────────────────
-export async function reindex(libraryRoot) {
+/**
+ * Rebuild `index.yaml` and `INDEX.md` from the entry directories. Every
+ * writer of the index takes the publish lock: a reindex that scanned the
+ * directories before a publish's rename and wrote after the publish's own
+ * reindex used to drop the new version from the index until the next
+ * reindex (#357). `holdingLock` is for the publisher, which already has it.
+ */
+export async function reindex(libraryRoot, opts = {}) {
     const marker = await readMarker(libraryRoot);
     if (!marker) {
         throw new Error(`Not a CodeCartographer library: ${LIBRARY_MARKER_FILE} missing at ${libraryRoot}`);
     }
+    const lock = opts.holdingLock ? null : await acquireLock(join(libraryRoot, PUBLISH_LOCK_FILE));
+    try {
+        const index = await scanLibrary(libraryRoot, marker);
+        await atomicWriteYaml(join(libraryRoot, LIBRARY_INDEX_FILE), index);
+        await writeIndexMarkdown(libraryRoot, index, marker);
+        // Reported, not written. The index files above are ABI, so the conflict
+        // list travels on the return value only (see ReindexResult).
+        const provenance_conflicts = await detectProvenanceConflicts(libraryRoot, index.entries);
+        return { ...index, provenance_conflicts };
+    }
+    finally {
+        await lock?.release();
+    }
+}
+/** The index as the entry directories would have it — a read, nothing written. */
+async function scanLibrary(libraryRoot, marker) {
     const entries = [];
     const namespacesSeen = new Set();
     const entriesRoot = join(libraryRoot, ENTRIES_DIR);
@@ -737,7 +774,7 @@ export async function reindex(libraryRoot) {
             return nsA < nsB ? -1 : 1;
         return a.slug < b.slug ? -1 : a.slug > b.slug ? 1 : 0;
     });
-    const index = {
+    return {
         schema_version: INDEX_SCHEMA_VERSION,
         library_name: marker.name,
         generated_at: new Date().toISOString(),
@@ -745,12 +782,6 @@ export async function reindex(libraryRoot) {
         namespaces: [...namespacesSeen].sort(),
         entries,
     };
-    await atomicWriteYaml(join(libraryRoot, LIBRARY_INDEX_FILE), index);
-    await writeIndexMarkdown(libraryRoot, index, marker);
-    // Reported, not written. The index files above are ABI, so the conflict
-    // list travels on the return value only (see ReindexResult).
-    const provenance_conflicts = await detectProvenanceConflicts(libraryRoot, entries);
-    return { ...index, provenance_conflicts };
 }
 async function buildIndexEntry(libraryRoot, namespace, slug) {
     const entryDir = entryRoot(libraryRoot, namespace, slug);

package/dist/core/orchestrator-config.js

@@ -21,8 +21,9 @@
 // launch directory.
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, resolve } from "node:path";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { expandTilde, pathExists } from "./utils.js";
+import { mkdir, readFile } from "node:fs/promises";
+import { atomicWriteFile, expandTilde, pathExists } from "./utils.js";
+import { acquireLock } from "./status.js";
 import { loadYamlFile, parseSimpleYaml, stringifySimpleYaml } from "./yaml.js";
 export const CONFIG_RELATIVE_PATH = "workflow/config.yaml";
 export const USER_CONFIG_DIR = join(homedir(), ".codecarto");
@@ -187,6 +188,24 @@ function cloneDefault() {
  * never overwritten: the caller is told to fix it first.
  */
 export async function writeLibraryConfig(configPath, libraryPath, namespace = null) {
+    // dirname() honors the platform separator; the previous hand-rolled
+    // `includes("/")` check treated every Windows path as a bare filename
+    // and left mkdir a no-op before the writeFile ENOENT'd (#128).
+    const dir = dirname(configPath);
+    await mkdir(dir, { recursive: true });
+    // A read-modify-write of a file every workspace on the machine reads:
+    // under a lock beside it, and landed atomically, so two library-inits
+    // (two hosts, or MCP and Pi) cannot lose each other's change and a crash
+    // mid-write cannot truncate it (#361).
+    const lock = await acquireLock(`${configPath}.lock`);
+    try {
+        await writeLibraryConfigLocked(configPath, libraryPath, namespace);
+    }
+    finally {
+        await lock.release();
+    }
+}
+async function writeLibraryConfigLocked(configPath, libraryPath, namespace) {
     let existing = {};
     if (await pathExists(configPath)) {
         const raw = await readFile(configPath, "utf8");
@@ -213,10 +232,5 @@ export async function writeLibraryConfig(configPath, libraryPath, namespace = nu
     if (namespace)
         library.namespace = namespace;
     const updated = { ...existing, library };
-    // dirname() honors the platform separator; the previous hand-rolled
-    // `includes("/")` check treated every Windows path as a bare filename
-    // and left mkdir a no-op before the writeFile ENOENT'd (#128).
-    const dir = dirname(configPath);
-    await mkdir(dir, { recursive: true });
-    await writeFile(configPath, `${stringifySimpleYaml(updated)}\n`, "utf8");
+    await atomicWriteFile(configPath, `${stringifySimpleYaml(updated)}\n`);
 }

package/dist/core/status.d.ts

@@ -1,13 +1,12 @@
 import type { ClosureEntry, NormalizedStatus, OpenQuestionEntry, PostPipelineEntry, PhaseHandoff, PipelineFile, ProposedConventionEntry, StatusFile, StatusPhase } from "./types.ts";
 export declare const LOCK_RETRY_MS = 125;
 export declare const LOCK_TIMEOUT_MS = 5000;
-export declare const STALE_LOCK_MS = 60000;
 /**
- * How old the removal lock (`<lock>.break`, see {@link withRemovalLock}) may
- * be before it is treated as left behind by a crashed process. It is held
- * across one stat and one rm, so anything this old was abandoned.
+ * How long a lock ticket may go unrefreshed before its owner is presumed
+ * hung. Owners refresh every quarter of this while they wait or hold, so a
+ * live holder is never broken by age; a dead one is removed at once.
  */
-export declare const BREAK_LOCK_STALE_MS = 5000;
+export declare const STALE_LOCK_MS = 60000;
 export declare function assertSafePhaseId(phaseId: string): void;
 /**
  * A YAML scalar as text: strings as written, numbers and booleans spelled
@@ -58,34 +57,54 @@ export declare function parseHandoff(value: unknown): PhaseHandoff;
 export declare function ensureProposedConventionArray(value: unknown): ProposedConventionEntry[];
 export declare function loadHandoffFile(phaseId: string, workspaceDir: string): Promise<PhaseHandoff | null>;
 export declare function applyHandoff(status: NormalizedStatus, handoff: PhaseHandoff): NormalizedStatus;
-/** What {@link acquireLock} hands back: a release that only ever removes its own lock. */
+/** What {@link acquireLock} hands back: a release that only ever removes its own ticket. */
 export interface LockHandle {
     release: () => Promise<void>;
     /**
-     * Set when acquiring meant breaking a lock older than {@link STALE_LOCK_MS}:
-     * the previous holder as its lock file recorded it, for callers that log.
+     * Set when acquiring meant removing a ticket whose holder was dead or had
+     * stopped refreshing it for {@link STALE_LOCK_MS}: the previous holder as
+     * its ticket recorded it, for callers that log.
      */
     brokeStale?: {
         pid: number | null;
         since: string | null;
     };
 }
+export interface AcquireLockOptions {
+    /** How long to wait for the lock; default {@link LOCK_TIMEOUT_MS}. */
+    timeoutMs?: number;
+    /**
+     * How long a ticket may go unrefreshed before its holder is presumed
+     * hung; default {@link STALE_LOCK_MS}. A dead holder is removed at once.
+     */
+    staleMs?: number;
+}
 /**
- * Take the O_EXCL lock at `lockPath`, waiting up to {@link LOCK_TIMEOUT_MS}
- * and breaking a lock older than {@link STALE_LOCK_MS}.
+ * Take the lock named by `lockPath`, waiting up to `timeoutMs`.
+ *
+ * The lock is a queue of **tickets**: files beside `lockPath` named
+ * `<lock>.t.<order>-<pid>-<token>`, one per waiter, each written by its
+ * owner alone. The holder is the owner of the first ticket in name order
+ * whose process is alive and whose ticket has been refreshed within
+ * `staleMs`; every owner refreshes its ticket on a timer while it waits and
+ * while it holds, so a live holder is never broken however long it holds
+ * (#355 — a publish across a full reindex used to lose its lock at 60 s).
+ * A ticket whose owner is dead, or has not refreshed it in `staleMs`, is
+ * removed by whoever notices — by its own unique name, so two waiters
+ * removing the same dead ticket remove the same inode and nothing else.
+ * No shared path is ever removed and re-created, which is the race every
+ * `rm`-then-recreate stale break carries (#342, #344, #355).
  *
- * The lock file records `pid`, timestamp, and a per-acquisition token, and
- * release removes the file only while it still carries that token. Without
- * the token, release removed whoever's lock was there: after a stale break
- * the previous holder's release deleted the new holder's lock, and a third
- * writer walked straight in (#227).
+ * Ordering follows Lamport's bakery: a waiter announces it is *choosing*
+ * (`<lock>.c.<token>`), takes a number one larger than any ticket it can
+ * see, writes its ticket, and withdraws the marker; nobody concludes it
+ * holds the lock while a marker it does not own exists — so a waiter that
+ * took its number but has not yet written its ticket cannot be overtaken.
+ * Two tickets with the same number (chosen at the same moment) break the
+ * tie on the rest of the name, which every observer sorts the same way.
  *
- * Every removal — a release or a stale break — happens under the removal
- * lock (`<lock>.break`) and re-checks what it is about to remove there.
- * Two waiters that both saw a stale lock used to both `rm` it: the second
- * `rm` landed after the first waiter had re-created the file, so both held
- * the lock (#342). A file can only be created while the path is free, and
- * only a removal-lock holder removes, so what a holder verified is what it
- * removes.
+ * A plain `lockPath` file left by a pre-#355 process is honoured while it is
+ * younger than `staleMs` and removed once it is not, so an upgrade under a
+ * live older process does not let two writers in.
  */
-export declare function acquireLock(lockPath: string): Promise<LockHandle>;
+export declare function acquireLock(lockPath: string, options?: AcquireLockOptions): Promise<LockHandle>;