@tiphys/kernel 0.1.0 → 0.2.0

package/dist/src/pool.js

@@ -1,7 +1,10 @@
 import { spawnSync } from "node:child_process";
-import { existsSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { existsSync, readdirSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
 import { join, resolve } from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
+import { metaPath, readTaskMeta } from "./task.js";
+import { classifyPathEntry, readRegularPathIfPresent } from "./fleet.js";
+import { pathsNameSameObject } from "./path-identity.js";
 /**
  * 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
@@ -44,16 +47,86 @@ export function taskBranchName(taskId) {
 }
 /** Task ids are single safe path segments. */
 export const TASK_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
-function runGit(cwd, args) {
+/**
+ * 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 const NETWORK_TIMEOUT_MS = 20_000;
+/**
+ * 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 function resolveNetworkTimeoutMs(raw) {
+    if (raw === undefined) {
+        return NETWORK_TIMEOUT_MS;
+    }
+    const parsed = Number(raw);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        return NETWORK_TIMEOUT_MS;
+    }
+    return parsed;
+}
+function networkTimeoutMs() {
+    return resolveNetworkTimeoutMs(process.env["TIPHYS_GIT_NETWORK_TIMEOUT_MS"]);
+}
+function runGit(cwd, args, timeoutMs) {
     const result = spawnSync("git", ["-C", cwd, ...args], {
         encoding: "utf8",
         // The transient-contention classification below reads git's English
         // message text, so the locale is pinned rather than inherited
         // (U-8). Without this a translated git silently stops retrying.
         env: { ...process.env, LC_ALL: "C", LANG: "C" },
+        ...(timeoutMs === undefined ? {} : { timeout: timeoutMs }),
     });
     if (result.error !== undefined) {
-        return { status: null, stdout: "", stderr: String(result.error) };
+        // A killed-on-timeout child arrives here with an ETIMEDOUT error. It
+        // is named in terms rather than passed through as
+        // "Error: spawnSync git ETIMEDOUT", because the operator's remedy
+        // (an unreachable remote) is not readable from that string.
+        const timedOut = timeoutMs !== undefined &&
+            result.error.code === "ETIMEDOUT";
+        return {
+            status: null,
+            stdout: "",
+            stderr: timedOut
+                ? `git ${args.join(" ")} did not answer within ${String(timeoutMs)}ms and was killed`
+                : String(result.error),
+        };
     }
     return {
         status: result.status,
@@ -124,9 +197,30 @@ export function recordPath(fleet, taskId) {
 export function worktreePath(fleet, taskId) {
     return join(fleet.worktreesDir, taskId);
 }
+/**
+ * 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 function readPoolRecord(fleet, taskId) {
+    const read = readRegularPathIfPresent(recordPath(fleet, taskId));
+    if (read.kind === "absent") {
+        return undefined;
+    }
+    if (read.kind === "refused") {
+        throw new Error(read.reason);
+    }
     try {
-        return JSON.parse(readFileSync(recordPath(fleet, taskId), "utf8"));
+        return JSON.parse(read.body);
     }
     catch {
         return undefined;
@@ -161,8 +255,17 @@ function resolveRemote(project) {
  * set locally (no network); otherwise the remote's advertised default
  * via ls-remote --symref. The clone's own HEAD is never consulted, so a
  * detached HEAD in the clone is irrelevant.
+ *
+ * `network` IS A REQUIRED PARAMETER AND HAS NO DEFAULT (M4-P19 fix
+ * round). Every caller must state whether it is allowed to open a
+ * socket, because the two callers that exist have opposite answers and a
+ * default would hand the wrong one to whichever caller is added next
+ * without anybody having to decide. `false` stops at the local
+ * `origin/HEAD` lookup and refuses, naming the fact that the network was
+ * not consulted, so a caller reading the refusal can tell "this remote
+ * has no default branch" from "I was not permitted to ask".
  */
-function resolveDefaultBranch(project, remote) {
+function resolveDefaultBranch(project, remote, network) {
     const local = runGit(project, [
         "symbolic-ref",
         "--quiet",
@@ -175,7 +278,15 @@ function resolveDefaultBranch(project, remote) {
             return { ok: true, value: ref.slice(prefix.length) };
         }
     }
-    const advertised = runGit(project, ["ls-remote", "--symref", remote, "HEAD"]);
+    if (!network) {
+        return {
+            ok: false,
+            reason: `cannot resolve the default branch of remote ${remote} without the ` +
+                `network: ${remote}/HEAD is unset locally, and this caller reports ` +
+                `rather than writes, so it does not contact ${remote} to ask`,
+        };
+    }
+    const advertised = runGit(project, ["ls-remote", "--symref", remote, "HEAD"], networkTimeoutMs());
     if (advertised.status === 0) {
         const match = /^ref:\s+refs\/heads\/(\S+)\s+HEAD$/m.exec(advertised.stdout);
         if (match !== null) {
@@ -192,6 +303,69 @@ function resolveDefaultBranch(project, remote) {
             `${remote}/HEAD is unset locally and ls-remote failed: ${advertised.stderr.trim()}`,
     };
 }
+/**
+ * Rebuild a pool record for taskId from tasks/<id>/meta.json and git.
+ * Reads only; writes nothing anywhere, ever.
+ */
+export function reconstructPoolRecord(fleet, taskId, options) {
+    if (!TASK_ID_PATTERN.test(taskId)) {
+        return { kind: "absent", reason: `task id "${taskId}" is not a safe path segment` };
+    }
+    const meta = readTaskMeta(fleet, taskId);
+    if (meta === undefined) {
+        return {
+            kind: "absent",
+            reason: `no readable task meta at ${metaPath(fleet, taskId)}, so there is ` +
+                `nothing to reconstruct a pool record from`,
+        };
+    }
+    const unresolved = [];
+    const details = [];
+    let remote;
+    let branch;
+    if (!existsSync(meta.project)) {
+        // Both fields live in the clone, so losing the clone loses both. They
+        // are reported together rather than one at a time, because a caller
+        // that repaired only the first would be told about the second on the
+        // next run and learn nothing it could not have been told now.
+        unresolved.push("remote", "branch");
+        details.push(`the project clone ${meta.project} recorded in meta.json is absent`);
+    }
+    else {
+        const resolvedRemote = resolveRemote(meta.project);
+        if (resolvedRemote.ok) {
+            remote = resolvedRemote.value;
+            const resolvedBranch = resolveDefaultBranch(meta.project, remote, options.network);
+            if (resolvedBranch.ok) {
+                branch = resolvedBranch.value;
+            }
+            else {
+                unresolved.push("branch");
+                details.push(resolvedBranch.reason);
+            }
+        }
+        else {
+            unresolved.push("remote", "branch");
+            details.push(resolvedRemote.reason);
+        }
+    }
+    if (remote === undefined || branch === undefined) {
+        return { kind: "incomplete", unresolved, detail: details.join("; ") };
+    }
+    return {
+        kind: "complete",
+        record: {
+            taskId,
+            project: meta.project,
+            remote,
+            branch,
+            baseSha: meta.baseSha,
+            branchName: meta.branch,
+            offline: meta.baseOffline,
+            createdAt: meta.createdAt,
+        },
+    };
+}
 /**
  * pool create (EXT-F-03 five steps; see module doc). Returns the pool
  * record on success.
@@ -280,7 +454,9 @@ export async function poolCreate(fleet, options) {
     if (!remote.ok) {
         return remote;
     }
-    const branch = resolveDefaultBranch(project, remote.value);
+    // poolCreate is a write the operator invoked and it is about to fetch
+    // from this remote anyway, so it may ask the remote for its default.
+    const branch = resolveDefaultBranch(project, remote.value, true);
     if (!branch.ok) {
         return branch;
     }
@@ -381,24 +557,98 @@ export async function poolCreate(fleet, options) {
     }
     return { ok: true, value: poolRecord };
 }
-/** One entry per pool record, with the worktree's current HEAD SHA. */
+/** The worktree's current HEAD SHA, or "missing" when there is no worktree. */
+function headShaOf(fleet, taskId) {
+    const worktree = worktreePath(fleet, taskId);
+    const head = existsSync(worktree)
+        ? runGit(worktree, ["rev-parse", "HEAD"])
+        : undefined;
+    return head !== undefined && head.status === 0 ? head.stdout.trim() : "missing";
+}
+/**
+ * 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 function poolList(fleet) {
     const entries = [];
+    const seen = new Set();
     const names = readdirSync(fleet.worktreesDir)
         .filter((name) => name.endsWith(".pool.json"))
         .sort();
     for (const name of names) {
         const taskId = name.slice(0, -".pool.json".length);
-        const worktree = worktreePath(fleet, taskId);
-        const head = existsSync(worktree)
-            ? runGit(worktree, ["rev-parse", "HEAD"])
-            : undefined;
-        entries.push({
-            taskId,
-            headSha: head !== undefined && head.status === 0
-                ? head.stdout.trim()
-                : "missing",
-        });
+        seen.add(taskId);
+        entries.push({ taskId, headSha: headShaOf(fleet, taskId), origin: "record" });
+    }
+    /* AN UNLISTABLE tasks/ IS NOT AN ABSENCE OF TASKS (T-036's mechanism, and
+       src/commands/next.ts:40 states the standard: a category empty BY
+       CONSTRUCTION reported as empty BY OBSERVATION). This `catch` swallowed
+       it into `[]`, so `tiphys pool list` printed nothing and exited 0 and
+       doctor's CHECK worktrees printed the positive claim "no pool worktrees"
+       about a directory it had not read. It now reaches the caller through the
+       SAME channel the `readdirSync(fleet.worktreesDir)` above it already
+       uses, which src/commands/next.ts:334 already catches and reports into
+       its `unknown` list. */
+    const taskIds = readdirSync(fleet.tasksDir).sort();
+    for (const taskId of taskIds) {
+        if (seen.has(taskId) || !TASK_ID_PATTERN.test(taskId)) {
+            continue;
+        }
+        /* A task record that is PRESENT and did not READ is not a closed task.
+           `readTaskMeta` answers `undefined` for absent, unreadable and
+           unparseable alike, and dropping all three hid exactly the interrupted
+           spawn this listing exists to surface: with tasks/t-0001/meta.json
+           truncated mid-write, `pool list` printed NOTHING while doctor's CHECK
+           tasks reported the same task as open. The entry type is established
+           here rather than inferred from `readTaskMeta`'s one-word answer. */
+        const metaEntry = classifyPathEntry(metaPath(fleet, taskId));
+        const meta = readTaskMeta(fleet, taskId);
+        if (meta === undefined && metaEntry.kind !== "absent" && metaEntry.kind !== "dangling") {
+            entries.push({
+                taskId,
+                headSha: headShaOf(fleet, taskId),
+                origin: "unreconstructable",
+                unresolved: ["meta"],
+            });
+            continue;
+        }
+        if (meta === undefined || meta.status !== "open") {
+            continue;
+        }
+        // REPORTING, so NO NETWORK. `pool list` and doctor's CHECK worktrees
+        // both arrive here, and both must return. A task whose `branch`
+        // needs the network to resolve is reported `unreconstructable`,
+        // which is a true statement about what this path can establish.
+        const rebuilt = reconstructPoolRecord(fleet, taskId, { network: false });
+        if (rebuilt.kind === "absent") {
+            continue;
+        }
+        entries.push(rebuilt.kind === "complete"
+            ? { taskId, headSha: headShaOf(fleet, taskId), origin: "reconstructed" }
+            : {
+                taskId,
+                headSha: headShaOf(fleet, taskId),
+                origin: "unreconstructable",
+                unresolved: rebuilt.unresolved,
+            });
     }
     return entries;
 }
@@ -465,10 +715,15 @@ async function destroyGitStep(contextDir, args, worktree) {
     return result;
 }
 /** Stage 1: gather facts. Read only; mutates nothing. */
-async function resolveDestroy(fleet, taskId) {
+async function resolveDestroy(fleet, taskId, reconstructed) {
     const worktree = worktreePath(fleet, taskId);
     const recordFile = recordPath(fleet, taskId);
-    const record = readPoolRecord(fleet, taskId);
+    const onDisk = readPoolRecord(fleet, taskId);
+    // The on-disk record always wins. The reconstruction is a FALLBACK, so
+    // a present-but-different record can never be overridden by one.
+    const record = onDisk ?? reconstructed;
+    // Deliberately the FILE, not the record: this is what authorizes the
+    // unlink in stage 3, and a reconstruction has no file to unlink.
     const haveRecord = existsSync(recordFile);
     const haveWorktree = existsSync(worktree);
     if (!haveRecord && !haveWorktree) {
@@ -539,7 +794,19 @@ async function resolveDestroy(fleet, taskId) {
                 currentPath = line.slice("worktree ".length).trim();
             }
             else if (line.trim() === `branch refs/heads/${branchName}`) {
-                if (currentPath !== undefined && resolve(currentPath) !== resolve(worktree)) {
+                // IDENTITY, NOT STRING EQUALITY, and the difference is a shipped
+                // defect this comparison had until 2026-09-16 (macOS smoke job of
+                // pull request #155). `currentPath` is GIT'S spelling and `worktree`
+                // is THIS KERNEL'S: git canonicalizes every worktree path it records,
+                // so a fleet reached through a symlink makes the two sides different
+                // strings for one directory. `resolve` does not resolve symlinks, so
+                // the old comparison then reported the task's OWN worktree as a
+                // foreign worktree holding the branch, stage 2 refused the destroy
+                // that was never in danger, and spawn's rollback left the worktree,
+                // the pool record and the branch behind after a launch that never
+                // started. On macOS no unusual setup is needed to reach it: the
+                // platform puts `os.tmpdir()` behind `/var -> /private/var`.
+                if (currentPath !== undefined && !pathsNameSameObject(currentPath, worktree)) {
                     branchCheckedOutAt = currentPath;
                 }
             }
@@ -706,7 +973,7 @@ export async function poolDestroy(fleet, options) {
         return { ok: false, reason: `task id "${taskId}" is not a safe path segment` };
     }
     // Stage 1: read only.
-    const resolved = await resolveDestroy(fleet, taskId);
+    const resolved = await resolveDestroy(fleet, taskId, options.reconstructed);
     if (!resolved.ok) {
         return resolved;
     }

package/dist/src/roles.d.ts

@@ -46,6 +46,37 @@ import type { Diagnostic } from "./validate.ts";
  * three agree rather than trusting this comment.
  */
 export declare const ROLE_IDS: readonly string[];
+/**
+ * WHERE EACH ROLE'S BRIEF ACTUALLY SHIPS, relative to the kernel root.
+ *
+ * The vocabulary above has six members and `roles/` holds FIVE briefs. The
+ * sixth, the orchestrator's, ships as `AGENTS.md` at the package root, with
+ * `role: orchestrator` frontmatter, which roles/README.md states and
+ * package.json's `files` list carries. Until this constant existed, the
+ * composer resolved every id to `roles/<id>.md`, so
+ * `tiphys brief compose --role orchestrator` answered, against the PUBLISHED
+ * TARBALL, "role brief .../roles/orchestrator.md: ... does not exist" for a
+ * brief that is in the same tarball at a path the resolver never looked in.
+ * A consumer reads that as a broken install.
+ *
+ * This is a composition defect no per-phase review could have caught: M3-P5
+ * built the six-member resolver over `roles/<id>.md`, M3-P6 added files to
+ * that directory, and M3-P9 put the sixth brief somewhere else. Each is
+ * correct alone.
+ *
+ * DECLARED RATHER THAN DERIVED ON PURPOSE. A resolver that fell back to
+ * "look for <id>.md anywhere" would answer for a file that happened to be
+ * there, and the property wanted is the opposite: the package states where
+ * each declared role's brief IS, and test/sweep-exclusion-sync.test.ts turns
+ * a role added without one into a red test rather than a failure at use.
+ */
+export declare const ROLE_BRIEF_FILES: Readonly<Record<string, string>>;
+/**
+ * The brief path for a role, relative to the kernel root, or undefined when
+ * the vocabulary declares a role the package does not ship. The second case
+ * is a REFUSAL the caller names, never a path that is then found missing.
+ */
+export declare function roleBriefFile(roleId: string): string | undefined;
 /** The fence a role brief's YAML frontmatter block is delimited by. */
 export declare const FRONTMATTER_FENCE = "---";
 /** The include directive, on a line of its own. */

package/dist/src/roles.js

@@ -56,6 +56,48 @@ export const ROLE_IDS = [
     "implementer",
     "clean-room-reviewer",
 ];
+/**
+ * WHERE EACH ROLE'S BRIEF ACTUALLY SHIPS, relative to the kernel root.
+ *
+ * The vocabulary above has six members and `roles/` holds FIVE briefs. The
+ * sixth, the orchestrator's, ships as `AGENTS.md` at the package root, with
+ * `role: orchestrator` frontmatter, which roles/README.md states and
+ * package.json's `files` list carries. Until this constant existed, the
+ * composer resolved every id to `roles/<id>.md`, so
+ * `tiphys brief compose --role orchestrator` answered, against the PUBLISHED
+ * TARBALL, "role brief .../roles/orchestrator.md: ... does not exist" for a
+ * brief that is in the same tarball at a path the resolver never looked in.
+ * A consumer reads that as a broken install.
+ *
+ * This is a composition defect no per-phase review could have caught: M3-P5
+ * built the six-member resolver over `roles/<id>.md`, M3-P6 added files to
+ * that directory, and M3-P9 put the sixth brief somewhere else. Each is
+ * correct alone.
+ *
+ * DECLARED RATHER THAN DERIVED ON PURPOSE. A resolver that fell back to
+ * "look for <id>.md anywhere" would answer for a file that happened to be
+ * there, and the property wanted is the opposite: the package states where
+ * each declared role's brief IS, and test/sweep-exclusion-sync.test.ts turns
+ * a role added without one into a red test rather than a failure at use.
+ */
+export const ROLE_BRIEF_FILES = {
+    orchestrator: "AGENTS.md",
+    investigator: "roles/investigator.md",
+    "plan-writer": "roles/plan-writer.md",
+    "adversarial-plan-reviewer": "roles/adversarial-plan-reviewer.md",
+    implementer: "roles/implementer.md",
+    "clean-room-reviewer": "roles/clean-room-reviewer.md",
+};
+/**
+ * The brief path for a role, relative to the kernel root, or undefined when
+ * the vocabulary declares a role the package does not ship. The second case
+ * is a REFUSAL the caller names, never a path that is then found missing.
+ */
+export function roleBriefFile(roleId) {
+    return Object.prototype.hasOwnProperty.call(ROLE_BRIEF_FILES, roleId)
+        ? ROLE_BRIEF_FILES[roleId]
+        : undefined;
+}
 /** The fence a role brief's YAML frontmatter block is delimited by. */
 export const FRONTMATTER_FENCE = "---";
 /** The include directive, on a line of its own. */