@tiphys/kernel 0.0.0 → 0.1.0

package/dist/src/modes.js

@@ -0,0 +1,258 @@
+/**
+ * READING THE SHIPPED ASSURANCE MODE DEFINITIONS (kernel plan M3, M3-P3
+ * step 5).
+ *
+ * `assurance-modes.yaml` ships at the package root, beside `gate-registry.yaml`
+ * and the `schemas/` directory. This module locates it, decodes it, and
+ * answers one question: what does a declared mode require. Nothing here
+ * RESOLVES a mode into behaviour and nothing here enforces one. M3 never
+ * executes `direct-pr` or `local-only`, and building an enforcement engine for
+ * a mode this milestone never enters is the M1-P3 failure the plan is trying
+ * not to repeat.
+ *
+ * NO VALIDATION HAPPENS HERE, deliberately. `tiphys validate --type
+ * assurance-modes` is the command that says whether the document is
+ * well-formed, and duplicating its rules in a reader would produce a second
+ * opinion to keep in sync. This module reads what is there and reports what it
+ * cannot find.
+ */
+import { readdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { decodeDocument, readOperatorPath } from "./validate.js";
+/** The shipped document's basename, at the package root. */
+export const MODES_FILENAME = "assurance-modes.yaml";
+/**
+ * Locate the package root by walking UP from this module and testing for the
+ * shipped document.
+ *
+ * The depth differs between the two layouts this code runs in: from source it
+ * is `src/` and the root is one level up, and from the built entry it is
+ * `dist/src/` and the root is two levels up. Counting `..` would be right in
+ * exactly one of them, which is the layout-dependent break
+ * `schemasDirectory()` already documents. Walking up and TESTING is right in
+ * both, and in a relocated copy as well.
+ */
+export function packageRoot() {
+    let directory = dirname(fileURLToPath(import.meta.url));
+    for (let depth = 0; depth < 8; depth += 1) {
+        try {
+            if (readdirSync(directory).includes(MODES_FILENAME)) {
+                return directory;
+            }
+        }
+        catch {
+            /* not readable here; keep walking */
+        }
+        const parent = dirname(directory);
+        if (parent === directory) {
+            break;
+        }
+        directory = parent;
+    }
+    throw new Error(`the shipped ${MODES_FILENAME} was not found above this module; the installation is incomplete`);
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function strings(record, key) {
+    const value = record[key];
+    return Array.isArray(value)
+        ? value.filter((entry) => typeof entry === "string")
+        : [];
+}
+function optionalStrings(record, key) {
+    return record[key] === undefined ? undefined : strings(record, key);
+}
+/** Read and decode the shipped document, or say why it could not be read. */
+export function readModes(path = join(packageRoot(), MODES_FILENAME)) {
+    const read = readOperatorPath(path);
+    if (!read.ok) {
+        return { ok: false, reason: read.reason };
+    }
+    const decoded = decodeDocument(read.body, path);
+    if (!decoded.ok) {
+        return { ok: false, reason: decoded.reason };
+    }
+    const document = asRecord(decoded.value);
+    if (document === undefined) {
+        return { ok: false, reason: `${path} does not decode to a mapping` };
+    }
+    const raw = document["modes"];
+    if (!Array.isArray(raw)) {
+        return { ok: false, reason: `${path} declares no modes list` };
+    }
+    const modes = [];
+    for (const entry of raw) {
+        const record = asRecord(entry);
+        if (record === undefined) {
+            continue;
+        }
+        modes.push({
+            id: String(record["id"] ?? ""),
+            declaredBy: String(record["declared-by"] ?? ""),
+            pipeline: strings(record, "pipeline"),
+            skips: strings(record, "skips"),
+            gateSets: strings(record, "gate-sets"),
+            mergeAuthority: String(record["merge-authority"] ?? ""),
+            grantedBy: typeof record["granted-by"] === "string" ? record["granted-by"] : undefined,
+            conditions: optionalStrings(record, "conditions"),
+            reviewContracts: optionalStrings(record, "review-contracts"),
+            escalationBounds: asRecord(record["escalation-bounds"]),
+        });
+    }
+    return { ok: true, path, raw: decoded.value, modes };
+}
+/**
+ * The id blueprint section 8 gives the un-downgraded process BY NAME: "The
+ * current proven process is the definition of `full`."
+ *
+ * SIBLING LITERAL, named so neither site can drift unnoticed:
+ * `REFERENCE_MODE_ID` at src/checks.ts:275 is the same string, used as the
+ * reference pipeline every other mode's omissions are measured against. The two
+ * are pinned from opposite directions by registered tests: the checks-side
+ * literal by the assertion that deleting `full` produces `no mode declares id
+ * full` (test/assurance-modes.test.ts:314), and this one by the assertion that
+ * the mode `mode show` annotates as un-downgraded is the mode named `full`.
+ */
+const UNDOWNGRADED_MODE_ID = "full";
+/**
+ * The execution status of one mode, DERIVED rather than looked up in a list of
+ * ids (CR-004 item 2, DR-0020).
+ *
+ * Two facts are available and both are checkable by the reader: whether this is
+ * the kernel's own document, and whether this mode IS the one blueprint section
+ * 8 names as the un-downgraded process, "The current proven process is the
+ * definition of `full`. Downgrades are declared, never improvised."
+ *
+ * WHY THE NAME AND NOT THE SKIP COUNT (CR-002, round 9). This function used
+ * `mode.skips.length === 0` as its proxy for "this is the un-downgraded mode".
+ * The proxy held only because `full` happened to be the only mode with an empty
+ * list, nothing enforced that, and `skips[]` is shipped DATA. Two measured
+ * consequences, both at exit 0 with every registry gate green: giving `full` one
+ * bogus `skips[]` entry made this function say that no phase of the tiphys
+ * project had ever been delivered under `full`, which is false about the mode
+ * this project has delivered every phase under; and giving `direct-pr` an empty
+ * `skips[]` made a mode nobody has ever entered claim to be the one the project
+ * follows, with `merge-authority: owner` printed beneath it, which is not the
+ * regime in force (DR-0015). Blueprint section 8 defines `full` BY NAME, so the
+ * name is the primary fact and the skip count is a consequence of it.
+ *
+ * THE COUNT IS STILL REPORTED, as a fact about the mode rather than as the
+ * ground of the claim. That distinction is the whole finding: a number may be
+ * shown without being believed.
+ *
+ * WHAT MAKES THE `full` SENTENCE TRUE IS DATA, AND IT IS GUARDED IN TWO PLACES
+ * THAT COVER DIFFERENT DOCUMENTS. Keying off the name moves the burden: the
+ * claim is only as good as the `full` in the document being served genuinely
+ * being un-downgraded.
+ *
+ * The VALIDATOR carries it for EVERY document (round 10, CRB9-02).
+ * `mode-no-undeclared-downgrade` rejects a `skips[]` entry that the same mode's
+ * pipeline runs, and also one that the reference does not run; on the reference
+ * those two exhaust the cases, so a `full` declaring any skipped stage at all is
+ * refused and this sentence is never printed over it. Until that second part
+ * existed, a `full` whose stage had MOVED from `pipeline` into `skips` was an
+ * HONEST downgrade that validated at exit 0, and `tiphys mode show --mode full`
+ * printed this sentence about fifteen lines above a `skips: deploy-verify` row.
+ *
+ * A REGISTERED TEST carries it for THIS repository's own document, asserting the
+ * shipped `full` declares no skipped stage. It is kept rather than superseded:
+ * a test guards the document, the check guards every other document, and the
+ * failure this pair exists to prevent is a property asserted where it is stated
+ * and not enforced where it is consumed.
+ *
+ * WHAT THIS DELIBERATELY DOES NOT SAY. It does not say that tiphys runs
+ * anything: nothing runs on tiphys before M4. The un-downgraded mode of the
+ * kernel's own document is the process the tiphys PROJECT follows for its own
+ * delivery; the downgraded ones have never been entered at all. And for a
+ * document that is not the kernel's own, the answer is that tiphys does not
+ * know, because it does not.
+ */
+export function executionStatus(mode, context) {
+    if (!context.shippedDocument) {
+        return ("not determinable here. This is not the kernel's own assurance-modes.yaml, " +
+            "so nothing tiphys ships records whether any phase has been delivered under " +
+            "this mode (DR-0020).");
+    }
+    if (mode.id === UNDOWNGRADED_MODE_ID) {
+        return (`this mode is ${UNDOWNGRADED_MODE_ID}, which blueprint section 8 defines by name as the ` +
+            "un-downgraded process, and it is the one the tiphys project follows for its own delivery.");
+    }
+    return (`DECLARED AND VALIDATED, NEVER EXERCISED. This mode is not ${UNDOWNGRADED_MODE_ID}, which ` +
+        "blueprint section 8 defines by name as the un-downgraded process, so no phase of the " +
+        `tiphys project has ever been delivered under it. It declares ${String(mode.skips.length)} ` +
+        "skipped stage(s). Its pipeline and its gate selection are checked by validation only " +
+        "(DR-0020).");
+}
+/**
+ * The standing limits of this release, printed on every invocation.
+ *
+ * IT SAYS ONLY WHAT THE SHIPPED SCHEMAS DO. The vocabularies really are closed
+ * enums, so "a document naming any other id is rejected" is the enum's own
+ * behaviour and not a claim about intent. The M4 sentence is attributed to
+ * DR-0020 rather than stated as a property of the code.
+ */
+export const RELEASE_LIMITS = "limits: the mode, stage and role vocabularies in the shipped schemas are this " +
+    "repository's own closed enums, so a document naming any other id is rejected and a " +
+    "consuming project cannot extend them at v0.1.0; whether to open them is an M4 question " +
+    "(DR-0020). This command SHOWS a declared mode: nothing in this release resolves a " +
+    "project into a mode, enforces one, or runs one.";
+/**
+ * Render one mode for a human or for a brief.
+ *
+ * THE SHAPE IS PART OF THE CONTRACT, because criterion 2 asserts over it: a
+ * section is a line ending in a colon at column zero, and its items are the
+ * lines indented by exactly two spaces beneath it. That makes "prints exactly
+ * the twelve stage ids in order" something a test can extract rather than
+ * something a reader has to eyeball.
+ */
+export function renderMode(mode, context) {
+    const lines = [`mode: ${mode.id}`];
+    /* SECOND LINE, not a footnote. CR-004 measured that `mode show` printed a
+       never-exercised mode with exactly the confidence of the exercised one, and
+       that the only disclosure lived in `delivery/`, which the package excludes. */
+    lines.push(`execution-status: ${executionStatus(mode, context)}`);
+    lines.push(`merge-authority: ${mode.mergeAuthority}`);
+    if (mode.grantedBy !== undefined) {
+        lines.push(`granted-by: ${mode.grantedBy}`);
+    }
+    const section = (name, items) => {
+        if (items === undefined) {
+            return;
+        }
+        lines.push(`${name}:`);
+        if (items.length === 0) {
+            lines.push("  (none)");
+            return;
+        }
+        for (const item of items) {
+            lines.push(`  ${item}`);
+        }
+    };
+    section("pipeline", mode.pipeline);
+    section("skips", mode.skips);
+    section("gate-sets", mode.gateSets);
+    section("review-contracts", mode.reviewContracts);
+    if (mode.escalationBounds !== undefined) {
+        /* CR-004 item 3. The bounds are DATA an orchestrator brief cites. Nothing
+           in this release counts a fix round or detects a recurrence, so a bare
+           `escalation-bounds:` header invites the reader to assume an enforcement
+           engine that does not exist. */
+        lines.push("escalation-bounds (data an orchestrator brief cites; nothing in this release counts fix rounds, detects recurrence, or enforces these):");
+        for (const key of Object.keys(mode.escalationBounds).sort()) {
+            lines.push(`  ${key}: ${String(mode.escalationBounds[key])}`);
+        }
+    }
+    if (mode.conditions !== undefined) {
+        lines.push("conditions:");
+        for (const condition of mode.conditions) {
+            lines.push(`  ${condition.replace(/\s+/g, " ").trim()}`);
+        }
+    }
+    lines.push(`declared-by: ${mode.declaredBy.replace(/\s+/g, " ").trim()}`);
+    lines.push(RELEASE_LIMITS);
+    return lines;
+}

package/dist/src/path-identity.d.ts

@@ -0,0 +1,2 @@
+/** Compare two existing paths by their canonical filesystem identity. */
+export declare function pathsIdentifySameObject(left: string, right: string): boolean;

package/dist/src/path-identity.js

@@ -0,0 +1,10 @@
+import { realpathSync } from "node:fs";
+/** Compare two existing paths by their canonical filesystem identity. */
+export function pathsIdentifySameObject(left, right) {
+    try {
+        return realpathSync(left) === realpathSync(right);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/src/plan.d.ts

@@ -0,0 +1,73 @@
+/**
+ * THE PHASE-DECLARATION PROJECTION (kernel plan M3, M3-P1 step 2; D-M3-18).
+ *
+ * The M2-P4 scope auditor reads one document per phase from
+ * `delivery/plan/phase-declarations/<phase-id-lowercased>.json`, out of the
+ * MERGE BASE of the audited branch. Until now that document was a SECOND
+ * HAND-AUTHORED SOURCE beside the plan, and two hand-authored sources of the
+ * same fact drift. This module makes it a GENERATED VIEW of the plan, so the
+ * plan is the one source and the auditor's input is derived from it.
+ *
+ * WHAT THE PROJECTION EMITS, taken from the DELIVERED
+ * `src/gates/schemas/phase-declaration.schema.json` rather than from a
+ * description of it. The delivered schema sets `additionalProperties: false`,
+ * so an extra property is a REJECTION and not an ignored field, and the
+ * emitted key set is exactly these five, camelCase:
+ *
+ *   id, branch, filesToTouch, declaredExtras, citations
+ *
+ * TWO VOCABULARIES MEET HERE AND NOWHERE ELSE. The plan spells the same
+ * fields `files-to-touch` and `extras`, because the plan is a document
+ * authored for people. This projector is the single translation point, and
+ * that is D-M3-18's whole value.
+ *
+ * THE GLOSS IS STRIPPED HERE OR NOWHERE (M2R-016). The auditor matches a
+ * declared path as a literal string or as a directory prefix and interprets
+ * nothing, so a plan entry written as
+ *
+ *   `src/cli.ts` (edit only if step 4 requires it)
+ *
+ * must project to `src/cli.ts`. A projector that passed the glossed form
+ * through would emit a declaration under which every real change is
+ * undeclared, and the auditor would be right to reject it.
+ */
+/** The five properties the delivered phase-declaration schema requires. */
+export interface PhaseDeclaration {
+    id: string;
+    branch: string;
+    filesToTouch: string[];
+    declaredExtras: string[];
+    citations: string[];
+}
+export declare function stripGloss(entry: string): string;
+/**
+ * Is this a literal path the scope auditor can match?
+ *
+ * The auditor compares strings exactly or as a directory prefix and
+ * interprets nothing, so an entry still carrying whitespace after the gloss
+ * strip is prose. The projector REFUSES rather than emitting it: an emitted
+ * prose entry is a declaration nobody can satisfy, and the failure would
+ * surface as an unrelated scope-gate red on some later branch.
+ */
+export declare function isLiteralPath(entry: string): boolean;
+export interface ProjectionResult {
+    ok: true;
+    declaration: PhaseDeclaration;
+    /** `m3-p1.json`, the filename the auditor looks for. */
+    filename: string;
+}
+export interface ProjectionFailure {
+    ok: false;
+    reason: string;
+}
+/**
+ * Project one phase of a decoded plan into its declaration.
+ *
+ * The filename is the phase id LOWERCASED, because CI derives `--phase` from
+ * the branch with a lowercase regex and the auditor looks the declaration up
+ * by that name. An uppercase filename is a declaration the auditor never
+ * finds, which reads exactly like a phase with no declaration at all.
+ */
+export declare function projectPhase(plan: unknown, phaseId: string): ProjectionResult | ProjectionFailure;
+/** The declaration as the auditor reads it: JSON, one trailing newline. */
+export declare function renderDeclaration(declaration: PhaseDeclaration): string;

package/dist/src/plan.js

@@ -0,0 +1,153 @@
+/**
+ * THE PHASE-DECLARATION PROJECTION (kernel plan M3, M3-P1 step 2; D-M3-18).
+ *
+ * The M2-P4 scope auditor reads one document per phase from
+ * `delivery/plan/phase-declarations/<phase-id-lowercased>.json`, out of the
+ * MERGE BASE of the audited branch. Until now that document was a SECOND
+ * HAND-AUTHORED SOURCE beside the plan, and two hand-authored sources of the
+ * same fact drift. This module makes it a GENERATED VIEW of the plan, so the
+ * plan is the one source and the auditor's input is derived from it.
+ *
+ * WHAT THE PROJECTION EMITS, taken from the DELIVERED
+ * `src/gates/schemas/phase-declaration.schema.json` rather than from a
+ * description of it. The delivered schema sets `additionalProperties: false`,
+ * so an extra property is a REJECTION and not an ignored field, and the
+ * emitted key set is exactly these five, camelCase:
+ *
+ *   id, branch, filesToTouch, declaredExtras, citations
+ *
+ * TWO VOCABULARIES MEET HERE AND NOWHERE ELSE. The plan spells the same
+ * fields `files-to-touch` and `extras`, because the plan is a document
+ * authored for people. This projector is the single translation point, and
+ * that is D-M3-18's whole value.
+ *
+ * THE GLOSS IS STRIPPED HERE OR NOWHERE (M2R-016). The auditor matches a
+ * declared path as a literal string or as a directory prefix and interprets
+ * nothing, so a plan entry written as
+ *
+ *   `src/cli.ts` (edit only if step 4 requires it)
+ *
+ * must project to `src/cli.ts`. A projector that passed the glossed form
+ * through would emit a declaration under which every real change is
+ * undeclared, and the auditor would be right to reject it.
+ */
+/**
+ * Reduce one plan `files-to-touch` entry to the bare path.
+ *
+ * THIS FUNCTION FEEDS THE GATE THAT EXISTS TO PREVENT SCOPE WIDENING, so an
+ * over-eager strip here is worse than no strip at all.
+ *
+ * MEASURED DEFECT, fix round 1 (B-001, high). The first version truncated at
+ * the FIRST `(` and produced:
+ *
+ *   "src/app/(marketing)/page.tsx"  ->  "src/app/"
+ *   "src/(lib)/util.ts"             ->  "src/"
+ *
+ * `src/gates/scope.ts` treats a trailing slash as a DIRECTORY PREFIX GRANT, so
+ * each of those turned one declared file into an entire tree. Parenthesised
+ * path segments are ordinary in real projects (Next.js route groups are the
+ * obvious case), so this is not a corner.
+ *
+ * THE RULE NOW, and each clause is load-bearing:
+ *
+ *   1. A gloss is stripped only when it is TRAILING and the whole of it is
+ *      parenthesised: `<path> (anything)` with the closing paren at the end.
+ *   2. It is stripped only when WHITESPACE separates it from the path. A path
+ *      whose own last segment is parenthesised, `src/app/(marketing)`, has no
+ *      such whitespace and is left alone.
+ *   3. What precedes the gloss must be ONE non-whitespace token, which is what
+ *      a literal path is. That is the "plausible path" test, and it is why an
+ *      interior `(` can never trigger a strip: the interior case never matches
+ *      the trailing form at all.
+ *
+ * Anything the rule does not recognise is returned UNCHANGED and rejected
+ * loudly by `projectPhase`, because a prose entry that reaches the auditor as
+ * a literal string fails visibly, while a silently truncated one grants a
+ * tree.
+ */
+const TRAILING_GLOSS = /^(\S+)\s+\([\s\S]*\)$/;
+export function stripGloss(entry) {
+    let text = entry.trim();
+    const trailing = TRAILING_GLOSS.exec(text);
+    if (trailing !== null) {
+        text = trailing[1].trim();
+    }
+    /* Backticks are markdown, never part of a path. Stripped AFTER the gloss,
+       because the plan writes `` `path` (gloss) `` and the backticks close
+       before the gloss opens. */
+    text = text.replace(/^`+/, "").replace(/`+$/, "").trim();
+    /* A trailing comma survives a list written inline. */
+    text = text.replace(/,+$/, "").trim();
+    return text;
+}
+/**
+ * Is this a literal path the scope auditor can match?
+ *
+ * The auditor compares strings exactly or as a directory prefix and
+ * interprets nothing, so an entry still carrying whitespace after the gloss
+ * strip is prose. The projector REFUSES rather than emitting it: an emitted
+ * prose entry is a declaration nobody can satisfy, and the failure would
+ * surface as an unrelated scope-gate red on some later branch.
+ */
+export function isLiteralPath(entry) {
+    return entry !== "" && !/\s/.test(entry);
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function stringArray(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === "string")
+        : [];
+}
+/**
+ * Project one phase of a decoded plan into its declaration.
+ *
+ * The filename is the phase id LOWERCASED, because CI derives `--phase` from
+ * the branch with a lowercase regex and the auditor looks the declaration up
+ * by that name. An uppercase filename is a declaration the auditor never
+ * finds, which reads exactly like a phase with no declaration at all.
+ */
+export function projectPhase(plan, phaseId) {
+    const document = asRecord(plan);
+    if (document === undefined) {
+        return { ok: false, reason: "the plan document is not a mapping" };
+    }
+    const phases = Array.isArray(document["phases"]) ? document["phases"] : [];
+    const phase = asRecord(phases.find((candidate) => asRecord(candidate)?.["id"] === phaseId));
+    if (phase === undefined) {
+        return { ok: false, reason: `the plan contains no phase ${phaseId}` };
+    }
+    const filesToTouch = stringArray(phase["files-to-touch"])
+        .map(stripGloss)
+        .filter((path) => path !== "");
+    const declaredExtras = stringArray(phase["extras"])
+        .map(stripGloss)
+        .filter((path) => path !== "");
+    const prose = [...filesToTouch, ...declaredExtras].filter((path) => !isLiteralPath(path));
+    if (prose.length > 0) {
+        return {
+            ok: false,
+            reason: `phase ${phaseId} declares an entry that is not a literal path and ` +
+                `cannot be projected: ${prose.map((p) => JSON.stringify(p)).join(", ")}`,
+        };
+    }
+    const declaration = {
+        id: String(phase["id"]),
+        branch: String(phase["branch"]),
+        filesToTouch,
+        declaredExtras,
+        citations: stringArray(phase["citations"]),
+    };
+    return {
+        ok: true,
+        declaration,
+        filename: `${phaseId.toLowerCase()}.json`,
+    };
+}
+/** The declaration as the auditor reads it: JSON, one trailing newline. */
+export function renderDeclaration(declaration) {
+    return `${JSON.stringify(declaration, undefined, 2)}\n`;
+}

package/dist/src/pool.d.ts

@@ -0,0 +1,130 @@
+import type { Fleet } from "./fleet.ts";
+/**
+ * Worktree pool over a project clone (kernel plan v1, M1-P3 step 3).
+ * BUILD from the contract (plan decision D-1, FM-026): a clean disposable
+ * worktree per task at <fleet>/worktrees/<task-id>, parallel-safe through
+ * unique paths, O_EXCL record creation, and git worktree add's own
+ * locking. That safety is claimed only at the width M1 actually uses:
+ * criterion 15's two concurrent creates, which are witnessed. This
+ * phase's own verification measured failures above roughly six-way
+ * concurrency on both the fetch and the worktree add, and hardening
+ * for that width is deferred to M5 (see the deferral list in
+ * delivery/work-history/m1-p3.md). Do not read this as a guarantee at
+ * arbitrary concurrency. Substrate-neutral: pure filesystem and git
+ * (DR-0007).
+ *
+ * Base resolution is the five binding steps of EXT-F-03: resolve the
+ * project's configured remote and its default branch, fetch that branch,
+ * record the fetched base SHA in the pool record (and the CLI emits it on
+ * stdout; M1-P4 spawn copies it into tasks/<id>/meta.json as baseSha),
+ * create the task branch and worktree directly from that exact SHA, and
+ * on fetch failure fail rather than silently use a stale local branch,
+ * unless --offline was explicitly passed, in which case the last fetched
+ * remote-tracking SHA is used and offline: true is recorded. The clone's
+ * local branches are never consulted: a stale local branch is never the
+ * base, whether behind or ahead of the remote.
+ *
+ * The pool record lives BESIDE the worktree (worktrees/<task-id>.pool.json,
+ * plain JSON per D-3), never inside it, so the record can never dirty the
+ * destroy-time cleanliness check (FM-059: no exemption list, ever).
+ *
+ * Destroy refuses a dirty worktree (uncommitted changes or untracked
+ * files) unless --discard, which is reserved for the teardown scout path
+ * (PR-010). A transient git index.lock during destroy is retried; the
+ * lock file is removed only under a fail-safe staleness proof (provably
+ * no holder via lsof plus mtime age beyond a threshold; any uncertainty
+ * means leave it and fail loudly), per FM-036 and FM-051.
+ */
+/** Task branch created by the pool at the fetched base SHA. */
+export declare function taskBranchName(taskId: string): string;
+/** Task ids are single safe path segments. */
+export declare const TASK_ID_PATTERN: RegExp;
+export interface PoolRecord {
+    taskId: string;
+    project: string;
+    remote: string;
+    branch: string;
+    baseSha: string;
+    branchName: string;
+    offline: boolean;
+    createdAt: string;
+}
+export type PoolResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Exported for the contention-classification test. */
+export declare function isTransientGitLockError(stderr: string): boolean;
+export declare function recordPath(fleet: Fleet, taskId: string): string;
+export declare function worktreePath(fleet: Fleet, taskId: string): string;
+export declare function readPoolRecord(fleet: Fleet, taskId: string): PoolRecord | undefined;
+export interface CreateOptions {
+    taskId: string;
+    project: string;
+    offline: boolean;
+}
+/**
+ * pool create (EXT-F-03 five steps; see module doc). Returns the pool
+ * record on success.
+ *
+ * On failure NOTHING IS REMOVED. The pool record, the worktree
+ * directory and the task branch may each survive, depending on how far
+ * the attempt got, and the reason line names exactly which of them did
+ * and the command that clears them. The automatic rollback this
+ * docstring used to promise was deleted deliberately: it served a
+ * concurrent-create path M1 never enters (parallelism is off until M5)
+ * and produced four consecutive rounds of defects, including deleting
+ * state it had not validated. Failing loudly and leaving state is the
+ * chosen contract, not an oversight.
+ */
+export declare function poolCreate(fleet: Fleet, options: CreateOptions): Promise<PoolResult<PoolRecord>>;
+export interface PoolListEntry {
+    taskId: string;
+    headSha: string;
+}
+/** One entry per pool record, with the worktree's current HEAD SHA. */
+export declare function poolList(fleet: Fleet): PoolListEntry[];
+export interface LsofProbe {
+    available: boolean;
+    exitCode: number | null;
+    stdout: string;
+}
+/** Age a lock file must reach before a staleness proof is even considered. */
+export declare const STALE_LOCK_AGE_MS = 300000;
+/**
+ * Fail-safe staleness proof for a git lock file (FM-036, FM-051): true
+ * only when the lock exists, its mtime age exceeds the threshold, and
+ * lsof is available and shows provably no holder (exit 1, empty stdout).
+ * Any uncertainty (lsof missing, erroring, or listing holders) is false:
+ * the lock is left in place and the operation fails loudly.
+ */
+export declare function provablyStaleLock(lockFile: string, opts?: {
+    nowMs?: number;
+    ageThresholdMs?: number;
+    runLsof?: (path: string) => LsofProbe;
+}): boolean;
+export interface DestroyOptions {
+    taskId: string;
+    /** Override the dirty-worktree refusal (plan step 3, PR-010). */
+    discard: boolean;
+    /**
+     * Authorize deleting a task branch that carries commits beyond its
+     * recorded base (V-1). Deliberately distinct from discard, whose
+     * plan-defined meaning is the dirty-tree override only: conflating
+     * them would make the scout path silently destroy committed work.
+     * M1-P4 teardown passes this from its ship path after its landedness
+     * judgement, which makes the dependency on teardown explicit rather
+     * than assumed.
+     */
+    deleteBranchForce: boolean;
+}
+/** What a completed destroy removed, for the operator's record. */
+export interface DestroyOutcome {
+    deletedBranch?: string;
+    /** The branch tip at deletion time: the recovery handle (V-1). */
+    deletedSha?: string;
+}
+export declare function poolDestroy(fleet: Fleet, options: DestroyOptions): Promise<PoolResult<DestroyOutcome>>;