@tiphys/kernel 0.1.0 → 0.2.0

package/dist/src/model-resolution.js

@@ -0,0 +1,307 @@
+import { join } from "node:path";
+import { readRegularFileIfPresent, taskDir } from "./task.js";
+/**
+ * THE MODEL-RESOLUTION RECORD, KERNEL SIDE (kernel plan M4, M4-P7;
+ * delivery/plan/kernel-plan-m4.md:1018, discharging M4-D-06's four parts at
+ * delivery/plan/m4-intake.md:732).
+ *
+ * WHAT THIS MODULE IS AND, MORE IMPORTANTLY, WHAT IT IS NOT. It READS a
+ * record a harness adapter wrote. It holds NO vocabulary: no tier-to-model
+ * table, no model-to-family table, and no vendor name of any kind. The whole
+ * vocabulary lives in the plugin (plugin/src/vocabulary.ts) and this module
+ * dereferences a vocabulary's IDENTITY and never its CONTENT. That single
+ * property is what makes a second harness plugin possible at all: a mapping
+ * here would close off every harness that is not the one it names
+ * (delivery/plan/m4-intake.md:377), and `test/schemas.test.ts` already asserts
+ * the absence over the whole shipped surface rather than trusting this
+ * paragraph.
+ *
+ * THE ORDER OF THE CHECKS IS PART OF THE CONTRACT, and it is the release
+ * record's order (src/gates/release.ts): the SUBJECT ECHO is compared field by
+ * field BEFORE anything reads the resolved identity. A record about another
+ * task is not a record with a wrong answer, it is a record about something
+ * else, and reading its answer first is how a misattributed family token
+ * reaches a decorrelation check as though it belonged there.
+ *
+ * WHY `observed` IS NOT `attested`, stated here because the vocabulary is the
+ * thing most likely to be widened later by someone who did not read M4-P1.
+ * The probe measured that the observation channel is harness-written, that it
+ * can be EMPTY at hook time under load, and that a process at the agent's own
+ * uid can rewrite it in place so the result is byte-shaped exactly like the
+ * truth (delivery/verification/m4-prototype-probes.md:410). So `observed`
+ * ranks above `self-reported`, which costs nothing to forge, and below any
+ * notion of attestation, which would need a signer this environment has not
+ * been shown to have.
+ */
+/** The record's file name inside the task directory. */
+export const MODEL_RESOLUTION_RECORD_NAME = "model-resolution.json";
+/** The contract versions this kernel accepts. */
+export const MODEL_RESOLUTION_CONTRACT_VERSIONS = ["1"];
+/**
+ * Where the record lives: `tasks/<id>/model-resolution.json`, NEVER inside the
+ * worktree (M4-P7 criterion 5, src/task.ts:31 and FM-059). The task directory
+ * sits outside the worktree precisely so the pool's dirty check needs no
+ * exemption list for the kernel's own injected files, and a record written
+ * into the worktree would be indistinguishable from the agent's own work.
+ */
+export function modelResolutionPath(fleet, taskId) {
+    return join(taskDir(fleet, taskId), MODEL_RESOLUTION_RECORD_NAME);
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function stringAt(container, field) {
+    const value = container?.[field];
+    return typeof value === "string" ? value : undefined;
+}
+/**
+ * Read the record for a task.
+ *
+ * AN ABSENT RECORD IS AN ERROR AND IS NEVER GREEN AND NEVER NOT-APPLICABLE
+ * (M4-P7 criterion 5). This is not a new rule and deliberately not a second
+ * implementation of one: src/gates/release.ts:609 already produces the
+ * sentence for the same hazard on the release seam, and the wording is kept
+ * in the same shape so that a reader who has met one meets the other.
+ * `test/model-resolution.test.ts` drives the real release gate to capture that
+ * sentence and derives its assertion from the capture, rather than pinning a
+ * hand-written copy of it.
+ *
+ * THE READ GOES THROUGH `readRegularFileIfPresent`, which is M2-C-6 and the
+ * mechanism-index row `reading-a-path-whose-type-is-not-established`: a named
+ * pipe at this path is a REPORTED refusal, never a blocked open.
+ */
+export function readModelResolutionRecord(path, writerExitCode) {
+    const read = readRegularFileIfPresent(path);
+    if (read.kind === "absent") {
+        return {
+            kind: "error",
+            reason: `fail-closed rule 1: adapter exited ${String(writerExitCode)} without ` +
+                `writing a model-resolution record at ${path}; exit 0 with no ` +
+                `record is error, not success`,
+        };
+    }
+    if (read.kind === "refused") {
+        return { kind: "error", reason: read.reason };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(read.body);
+    }
+    catch (error) {
+        return {
+            kind: "error",
+            reason: `${path} is not readable as JSON: ${String(error).replace(/\s+/g, " ").trim()}`,
+        };
+    }
+    const record = asRecord(parsed);
+    if (record === undefined) {
+        return { kind: "error", reason: `${path} does not hold a JSON object` };
+    }
+    return { kind: "read", record };
+}
+/**
+ * The vocabulary IDENTITY of a record, and nothing else about the vocabulary.
+ *
+ * TWO FIELDS ARE READ AND THEY ARE NAMED HERE RATHER THAN SPREAD, which is
+ * the whole of criterion 4's mechanical half. A spread, an `Object.keys`, a
+ * `JSON.stringify` or a `structuredClone` of the vocabulary object would
+ * ENUMERATE it, and enumeration is dereferencing the content whatever the
+ * intent. `test/model-resolution.test.ts` hands this function a Proxy that
+ * records every property read and asserts the recorded set against these two
+ * names, so a later edit that reaches for a third reddens.
+ */
+export function vocabularyIdentity(record) {
+    const resolved = asRecord(record["resolved"]);
+    const vocabulary = asRecord(resolved?.["vocabulary"]);
+    if (vocabulary === undefined) {
+        return undefined;
+    }
+    const id = vocabulary["id"];
+    const version = vocabulary["version"];
+    if (typeof id !== "string" || typeof version !== "number") {
+        return undefined;
+    }
+    return { id, version };
+}
+/**
+ * Accept or refuse one record against the launch request the kernel holds.
+ *
+ * FOUR REFUSALS, IN THIS ORDER, and the order is the point.
+ *
+ * 1. THE CONTRACT VERSION, because a record written to a contract this kernel
+ *    does not know is not a record this kernel can read fields out of.
+ * 2. THE SUBJECT ECHO, FIELD BY FIELD, BEFORE THE OUTCOME IS READ. This is
+ *    src/gates/schemas/release-record.schema.json:26's misattribution guard.
+ * 3. THE VOCABULARY IDENTITY, because a family token with no vocabulary is a
+ *    token nobody can say the meaning of.
+ * 4. THE PROVENANCE, which is M4-P7 criterion 6 member TWO. Member one (a
+ *    record claiming `observed` with no observation at all) is the schema's
+ *    and is a missing field. THIS is the present-but-inconsistent half, and a
+ *    schema-only guard passes it green: an observation about another task, or
+ *    naming a model other than the one the record claims, is a self-report
+ *    with a decoration on it.
+ */
+export function acceptModelResolution(record, subject) {
+    const contractVersion = stringAt(record, "contractVersion");
+    if (contractVersion === undefined || !MODEL_RESOLUTION_CONTRACT_VERSIONS.includes(contractVersion)) {
+        return {
+            kind: "refused",
+            reason: `the record declares contract version ${String(contractVersion)}, and this ` +
+                `kernel accepts ${MODEL_RESOLUTION_CONTRACT_VERSIONS.join(", ")}`,
+        };
+    }
+    const echo = asRecord(record["subject"]);
+    if (echo === undefined) {
+        return {
+            kind: "refused",
+            reason: "the record carries no subject echo, so what it is about could not be established",
+        };
+    }
+    const echoed = [
+        ["taskId", stringAt(echo, "taskId")],
+        ["role", stringAt(echo, "role")],
+        ["requestedTier", stringAt(echo, "requestedTier")],
+    ];
+    for (const [field, value] of echoed) {
+        if (value !== subject[field]) {
+            return {
+                kind: "refused",
+                reason: `the record's subject echo says ${field} is ${String(value)} and the ` +
+                    `launch request says ${subject[field]}, so this record is about a ` +
+                    `different subject`,
+            };
+        }
+    }
+    const identity = vocabularyIdentity(record);
+    if (identity === undefined) {
+        return {
+            kind: "refused",
+            reason: "the record carries no resolved.vocabulary identity, so its family token " +
+                "belongs to no stated vocabulary and cannot be compared with any other",
+        };
+    }
+    const resolved = asRecord(record["resolved"]);
+    const provenance = stringAt(resolved, "provenance");
+    const family = stringAt(resolved, "family");
+    const model = stringAt(resolved, "model");
+    if (provenance === "observed") {
+        const observation = asRecord(resolved?.["observation"]);
+        if (observation === undefined) {
+            return {
+                kind: "refused",
+                reason: "the record claims provenance observed and carries no observation, so " +
+                    "the claim is a self-report wearing the word observed",
+            };
+        }
+        const observedTask = stringAt(observation, "taskId");
+        if (observedTask !== subject.taskId) {
+            return {
+                kind: "refused",
+                reason: `the record claims provenance observed and its observation is about ` +
+                    `task ${String(observedTask)}, while the echoed request is about task ` +
+                    `${subject.taskId}, so the observation contradicts the subject it is ` +
+                    `offered as evidence for`,
+            };
+        }
+        const observedModel = stringAt(observation, "model");
+        if (observedModel !== model) {
+            return {
+                kind: "refused",
+                reason: `the record claims model ${String(model)} with provenance observed and ` +
+                    `its observation saw ${String(observedModel)}, so the claimed identity ` +
+                    `is not the observed one`,
+            };
+        }
+    }
+    else if (provenance === "self-reported") {
+        if (resolved?.["observation"] !== undefined) {
+            return {
+                kind: "refused",
+                reason: "the record ranks itself self-reported and carries an observation, so " +
+                    "it claims evidence it also says it does not have",
+            };
+        }
+    }
+    else if (provenance === "unresolved") {
+        if (family !== undefined || model !== undefined) {
+            return {
+                kind: "refused",
+                reason: "the record reports the identity unresolved and still names a family " +
+                    "or a model, which is the quiet fallback to the forgeable value that " +
+                    "an unresolved observation exists to prevent",
+            };
+        }
+    }
+    else {
+        return {
+            kind: "refused",
+            reason: `the record declares provenance ${String(provenance)}, which this kernel has no rule for`,
+        };
+    }
+    return { kind: "accepted", family, provenance: provenance };
+}
+/**
+ * Compare two accepted records' family tokens (M4-P7 criterion 3).
+ *
+ * TWO VOCABULARIES ARE NOT COMPARABLE AND THE REFUSAL NAMES BOTH IDS. A family
+ * token means whatever the vocabulary that minted it says it means, so
+ * comparing a token from one against a token from another is comparing two
+ * strings and calling the result a fact about models. That comparison is what
+ * `check-dual-review`'s decorrelation assertion rests on, and DR-0038 exists
+ * for exactly the environment where the two reviews come from different
+ * places, so a silent cross-vocabulary compare would make the assertion
+ * meaningless precisely where it is load-bearing.
+ *
+ * ONLY `id` IS READ HERE. The version is part of the identity a reader may
+ * print and is deliberately NOT part of the comparison: a vocabulary that
+ * added a family in v2 did not change what its v1 tokens mean, and refusing
+ * on version would turn a routine vocabulary revision into an outage.
+ */
+export function compareResolvedFamilies(left, right) {
+    const leftIdentity = vocabularyIdentity(left);
+    const rightIdentity = vocabularyIdentity(right);
+    if (leftIdentity === undefined || rightIdentity === undefined) {
+        return {
+            kind: "refused",
+            reason: "one of the two records carries no resolved.vocabulary identity, so the " +
+                "two family tokens belong to no stated common vocabulary",
+        };
+    }
+    if (leftIdentity.id !== rightIdentity.id) {
+        return {
+            kind: "refused",
+            reason: `the two records name different vocabularies, ${leftIdentity.id} and ` +
+                `${rightIdentity.id}, so their family tokens are not comparable and no ` +
+                `decorrelation claim can be made from them`,
+        };
+    }
+    const leftFamily = stringAt(asRecord(left["resolved"]), "family");
+    const rightFamily = stringAt(asRecord(right["resolved"]), "family");
+    if (leftFamily === undefined || rightFamily === undefined) {
+        return {
+            kind: "refused",
+            reason: "one of the two records names no resolved family, so there is nothing to " +
+                "compare; an unresolved identity is not a difference and not a match",
+        };
+    }
+    return {
+        kind: "compared",
+        differ: leftFamily !== rightFamily,
+        families: [leftFamily, rightFamily],
+    };
+}
+/**
+ * The value closeout copies into a verdict's `produced-by` (M4-P7 criterion 8).
+ *
+ * VERBATIM, AND THE FUNCTION EXISTS SO THAT "VERBATIM" IS TESTABLE. DR-0031
+ * requires a pull request to carry all its own evidence, so the family token
+ * has to reach the verdict document rather than being left in a task
+ * directory that no reviewer of the pull request can see. A copy that
+ * normalised, lowercased or prefixed the token would satisfy every reading of
+ * that sentence and would break the one comparison the token exists for.
+ */
+export function producedByFromRecord(record) {
+    return stringAt(asRecord(record["resolved"]), "family");
+}

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

@@ -1,2 +1,34 @@
 /** Compare two existing paths by their canonical filesystem identity. */
 export declare function pathsIdentifySameObject(left: string, right: string): boolean;
+/**
+ * Decide whether two paths NAME THE SAME filesystem object when at least
+ * one of them was produced by ANOTHER PROGRAM rather than composed here.
+ *
+ * THE MECHANISM THIS EXISTS FOR, measured 2026-09-16 on the macOS smoke
+ * job of pull request #155. `path.resolve` normalizes `.`, `..` and
+ * relative segments and does NOT resolve symlinks, so two spellings of one
+ * directory stay unequal as strings. Programs the kernel shells out to do
+ * not preserve the caller's spelling: git canonicalizes every worktree
+ * path it records (`git worktree add /link/wt` then `git worktree list
+ * --porcelain` reports `/real/wt`, measured on Linux), and node reports
+ * the canonical path of a test file in its reporter's `file` field. So a
+ * kernel-composed path compared by string against such a value answers
+ * "different object" for the same object, silently, and every decision
+ * taken on that answer is wrong in the direction that does nothing.
+ *
+ * On macOS the symlink is supplied by the platform and needs no unusual
+ * setup: `/tmp` is a symlink to `/private/tmp` and `os.tmpdir()` returns a
+ * path under `/var/folders`, where `/var` is a symlink to `/private/var`.
+ * The CLI is accidentally immune because `process.cwd()` is already
+ * canonical, so only a caller that hands a path in makes this reachable,
+ * which is exactly what a library consumer does.
+ *
+ * The string comparison is tried FIRST and kept, rather than replaced, for
+ * two reasons: it answers without touching the filesystem in the common
+ * case, and it still gives the right answer for two paths that do not
+ * exist, where `realpathSync` can only raise. This function therefore says
+ * "same" strictly more often than `resolve(left) === resolve(right)` does,
+ * and never says "same" about two objects that are genuinely different:
+ * equal canonical paths ARE one object.
+ */
+export declare function pathsNameSameObject(left: string, right: string): boolean;

package/dist/src/path-identity.js

@@ -1,4 +1,5 @@
 import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
 /** Compare two existing paths by their canonical filesystem identity. */
 export function pathsIdentifySameObject(left, right) {
     try {
@@ -8,3 +9,40 @@ export function pathsIdentifySameObject(left, right) {
         return false;
     }
 }
+/**
+ * Decide whether two paths NAME THE SAME filesystem object when at least
+ * one of them was produced by ANOTHER PROGRAM rather than composed here.
+ *
+ * THE MECHANISM THIS EXISTS FOR, measured 2026-09-16 on the macOS smoke
+ * job of pull request #155. `path.resolve` normalizes `.`, `..` and
+ * relative segments and does NOT resolve symlinks, so two spellings of one
+ * directory stay unequal as strings. Programs the kernel shells out to do
+ * not preserve the caller's spelling: git canonicalizes every worktree
+ * path it records (`git worktree add /link/wt` then `git worktree list
+ * --porcelain` reports `/real/wt`, measured on Linux), and node reports
+ * the canonical path of a test file in its reporter's `file` field. So a
+ * kernel-composed path compared by string against such a value answers
+ * "different object" for the same object, silently, and every decision
+ * taken on that answer is wrong in the direction that does nothing.
+ *
+ * On macOS the symlink is supplied by the platform and needs no unusual
+ * setup: `/tmp` is a symlink to `/private/tmp` and `os.tmpdir()` returns a
+ * path under `/var/folders`, where `/var` is a symlink to `/private/var`.
+ * The CLI is accidentally immune because `process.cwd()` is already
+ * canonical, so only a caller that hands a path in makes this reachable,
+ * which is exactly what a library consumer does.
+ *
+ * The string comparison is tried FIRST and kept, rather than replaced, for
+ * two reasons: it answers without touching the filesystem in the common
+ * case, and it still gives the right answer for two paths that do not
+ * exist, where `realpathSync` can only raise. This function therefore says
+ * "same" strictly more often than `resolve(left) === resolve(right)` does,
+ * and never says "same" about two objects that are genuinely different:
+ * equal canonical paths ARE one object.
+ */
+export function pathsNameSameObject(left, right) {
+    if (resolve(left) === resolve(right)) {
+        return true;
+    }
+    return pathsIdentifySameObject(left, right);
+}

package/dist/src/pool.d.ts

@@ -56,11 +56,154 @@ export type PoolResult<T> = {
     ok: false;
     reason: string;
 };
+/**
+ * THE BOUND ON A NETWORK-REACHING GIT SUBPROCESS (M4-P19 fix round).
+ *
+ * `spawnSync` with no `timeout` waits for the child forever. For a local
+ * git command that is harmless: it either answers or fails. For one that
+ * opens a socket it is not, and the failure mode is not a slow command,
+ * it is a command that NEVER RETURNS. Measured by the clean-room
+ * reviewer against head abde402: a remote pointed at a TCP listener that
+ * accepts and never speaks made `tiphys pool list` and `tiphys doctor`
+ * run until killed (exit 124 under `timeout 25`), where the same fixture
+ * on the phase base exited 0 in about a second.
+ *
+ * This bound is applied to `ls-remote --symref <remote> HEAD` only, and
+ * the reason it is safe THERE and not elsewhere is a property of the
+ * command rather than a judgement about it: that invocation transfers a
+ * ref advertisement and nothing else, so a legitimate one is bounded by
+ * round-trip latency. `git fetch` (src/pool.ts, src/teardown.ts) and
+ * `git push` (src/teardown.ts) transfer objects, so their legitimate
+ * duration IS unbounded and a wall-clock cap on them would abort real
+ * work. They are left unbounded deliberately, and they are reached only
+ * from a command the operator invoked to do that work, never from a
+ * reporting path; keeping reporting paths off the network entirely is
+ * the other half of this fix (see `reconstructPoolRecord`).
+ *
+ * TIPHYS_GIT_NETWORK_TIMEOUT_MS is a TEST SEAM in the style of
+ * TIPHYS_WATCH_TEST_HOLD (src/watcher.ts) and TIPHYS_LOCK_TEST_HOLD
+ * (src/commands/lock.ts): a test cannot afford to wait out the shipped
+ * bound, and a shipped bound short enough for a test would abort a
+ * legitimate ls-remote over a slow link. A value that is not a positive
+ * integer is IGNORED rather than honoured, so a malformed environment
+ * cannot silently remove the bound.
+ */
+export declare const NETWORK_TIMEOUT_MS = 20000;
+/**
+ * Exported as a PURE function so the validation has a witness that does
+ * not have to wait out a twenty-second bound to observe it. The
+ * end-to-end bound is witnessed separately, against a real remote that
+ * never answers; this is the arm that says a malformed environment
+ * cannot silently switch the bound off.
+ *
+ * `Number("")` is 0 and `Number("0x10")` is 16, so neither a blank value
+ * nor a hexadecimal one is passed through: the accepted set is exactly
+ * the positive integers, and everything else falls back.
+ */
+export declare function resolveNetworkTimeoutMs(raw: string | undefined): number;
 /** 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;
+/**
+ * THE RECORD'S ENTRY TYPE IS ESTABLISHED BEFORE IT IS OPENED. A bare read
+ * here hung `tiphys pool destroy` forever with zero output against a named
+ * pipe at `worktrees/<id>.pool.json`; measured before the fix, `pool list`
+ * (which reads only the NAME) returned in the same second while
+ * `pool destroy --task t-0001` was killed at ten seconds. The two commands
+ * differ by whether this function runs, which is what makes the mechanism
+ * the open and not the command.
+ *
+ * A non-regular record is a REFUSAL rather than `undefined`: `undefined`
+ * already means "there is no record", and a caller that cannot tell that
+ * apart from "the record could not be opened" would rebuild a worktree over
+ * a record it never read.
+ */
 export declare function readPoolRecord(fleet: Fleet, taskId: string): PoolRecord | undefined;
+/**
+ * POST-RECLAIM RECONSTRUCTION (M4-D-12, kernel plan M4 section M4-P19).
+ *
+ * THE RULE, and it is the whole design: RECONSTRUCT FOR REPORTING, NEVER
+ * FOR DESTRUCTION. A reconstructed record exists in memory for the life
+ * of one command and is NEVER written to worktrees/<id>.pool.json, so a
+ * later reader can never mistake a reconstruction for an original.
+ *
+ * THE DEFECT IT CLOSES, measured rather than assumed. tasks/<id>/meta.json
+ * is TRACKED and survives a reclaim; worktrees/<id>.pool.json cannot,
+ * because it sits beside the worktree BY DESIGN so it can never dirty the
+ * destroy-time cleanliness check (see the module header above, FM-059).
+ * Teardown then refuses without a pool record and says so in terms
+ * (src/teardown.ts), so the plan's stated fallback of "recovery is manual
+ * teardown" does not work post-reclaim: the manual path is itself blocked.
+ *
+ * WHAT IS DERIVED AND WHAT IS NOT. meta.json carries six of the eight
+ * PoolRecord fields directly (taskId, project, baseSha, branchName,
+ * offline, createdAt). It carries NEITHER `remote` NOR `branch`, which are
+ * the project's configured remote and that remote's default branch. Those
+ * two are re-derived from git through the SAME two resolvers poolCreate
+ * uses, so a reconstruction is a repeat of the original derivation and
+ * never a remembered value.
+ *
+ * WHEN EITHER OF THOSE TWO CANNOT BE DERIVED THE RESULT IS INCOMPLETE AND
+ * NAMES THE FIELD. It is never filled with a plausible default. "origin"
+ * and "main" are right often enough to look harmless and wrong often
+ * enough to destroy work: a guessed default branch sends the landed-ness
+ * judgement at a ref that is not the project's default, and teardown's
+ * authorization to delete a task branch comes from exactly that judgement
+ * (V-1, the defect src/spawn.ts was rewritten to prevent). An unresolvable
+ * field is therefore a refusal, not a gap to fill.
+ */
+export type ReconstructResult = 
+/** Every field derived. Safe to report, and safe to pass to a GATED path. */
+{
+    kind: "complete";
+    record: PoolRecord;
+}
+/** meta.json read, but git could not answer for the named fields. */
+ | {
+    kind: "incomplete";
+    unresolved: string[];
+    detail: string;
+}
+/** No readable task meta, so there is nothing to reconstruct from. */
+ | {
+    kind: "absent";
+    reason: string;
+};
+/**
+ * What a caller of `reconstructPoolRecord` is permitted to do to answer.
+ *
+ * THE FIELD IS REQUIRED AND THE TYPE IS WHY (M4-P19 fix round). The
+ * reconstruction rebuilds `branch` through `resolveDefaultBranch`, which
+ * falls back to `git ls-remote` when `<remote>/HEAD` is unset locally,
+ * and that fallback opens a socket. `<remote>/HEAD` unset is not an
+ * exotic state: it is the NORMAL state of a clone made by `git init` +
+ * `git remote add` + `git fetch`, which is how this kernel's own tests
+ * and fixtures build one. So the fallback is reached on ordinary fleets,
+ * and a caller that must return, such as `pool list` or `doctor`, must
+ * not reach it.
+ *
+ * Measured against head abde402, where this option did not exist and
+ * every caller got the network: with the remote pointed at a TCP
+ * listener that accepts and never speaks, `tiphys pool list` and
+ * `tiphys doctor` ran until killed. Making the decision a required field
+ * rather than a defaulted one is the part of the fix that survives the
+ * next caller: adding one without choosing does not compile.
+ */
+export interface ReconstructOptions {
+    /**
+     * True only for a caller the operator invoked to CHANGE something and
+     * which may therefore wait on a remote. False for every reporting
+     * path, which then reports `unreconstructable (unresolved: branch)`
+     * rather than blocking.
+     */
+    network: boolean;
+}
+/**
+ * Rebuild a pool record for taskId from tasks/<id>/meta.json and git.
+ * Reads only; writes nothing anywhere, ever.
+ */
+export declare function reconstructPoolRecord(fleet: Fleet, taskId: string, options: ReconstructOptions): ReconstructResult;
 export interface CreateOptions {
     taskId: string;
     project: string;
@@ -81,11 +224,46 @@ export interface CreateOptions {
  * chosen contract, not an oversight.
  */
 export declare function poolCreate(fleet: Fleet, options: CreateOptions): Promise<PoolResult<PoolRecord>>;
+/**
+ * Where an entry's pool record came from. `record` is an original read
+ * from worktrees/<id>.pool.json; the other two exist only after a reclaim
+ * has taken worktrees/ with it, and are computed fresh on every call.
+ */
+export type PoolEntryOrigin = "record" | "reconstructed" | "unreconstructable";
 export interface PoolListEntry {
     taskId: string;
     headSha: string;
+    origin: PoolEntryOrigin;
+    /**
+     * Set only for `unreconstructable`: what this listing could not establish.
+     * Usually the PoolRecord fields git could not answer for; `meta` means the
+     * task record itself was present and did not read, which is a different
+     * state from a task that is closed and from one that is not there.
+     */
+    unresolved?: string[];
 }
-/** One entry per pool record, with the worktree's current HEAD SHA. */
+/**
+ * One entry per pool record, with the worktree's current HEAD SHA, PLUS
+ * one per OPEN task that has no pool record beside it (M4-P19).
+ *
+ * The second group is what a reclaim leaves behind: tasks/ is tracked and
+ * survives, worktrees/ is gitignored and does not, so a task can be open
+ * with its record gone. Reporting only the first group makes those tasks
+ * invisible to `pool list` and to doctor, which is the state the plan
+ * calls a defect. Every such entry is marked, never silently blended in
+ * with the originals, and NOTHING here is written to disk.
+ *
+ * Closed tasks are excluded: a closed task is not in the pool, and
+ * listing every task this fleet ever finished as a missing worktree would
+ * make the report useless within a week.
+ *
+ * THIS FUNCTION OPENS NO SOCKET (M4-P19 fix round). It reads the
+ * filesystem and runs local git commands, and its reconstruction is
+ * asked for with `{ network: false }`. An entry whose default branch
+ * cannot be established from the clone alone is reported
+ * `unreconstructable (unresolved: branch)` rather than waited on. See
+ * `ReconstructOptions` for the measured hang that this closes.
+ */
 export declare function poolList(fleet: Fleet): PoolListEntry[];
 export interface LsofProbe {
     available: boolean;
@@ -120,6 +298,24 @@ export interface DestroyOptions {
      * than assumed.
      */
     deleteBranchForce: boolean;
+    /**
+     * An IN-MEMORY reconstructed record (M4-P19), used ONLY when no record
+     * exists on disk. It is never written: `haveRecord` still comes from
+     * the file, so nothing here creates worktrees/<id>.pool.json and
+     * nothing unlinks a file that is not there.
+     *
+     * WHY THIS EXISTS AT ALL, since the whole design is "never for
+     * destruction". Without it, stage 2's base-sha gate has no base to
+     * compare against and returns its "pool record missing or unreadable"
+     * refusal, so the post-reclaim path would be blocked at the one gate
+     * that was ALREADY going to do the right thing. Passing the
+     * reconstruction in makes that gate WORK rather than abstain, which is
+     * strictly safer than the alternative of relaxing it. The caller is
+     * responsible for having derived it (src/teardown.ts's
+     * --from-reconstructed path is the only one), and `pool destroy` on
+     * the command line never sets it.
+     */
+    reconstructed?: PoolRecord;
 }
 /** What a completed destroy removed, for the operator's record. */
 export interface DestroyOutcome {