@tiphys/kernel 0.1.0 → 0.2.0

package/dist/src/commands/init.d.ts

@@ -23,8 +23,8 @@ export declare const KERNEL_PACKAGE_NAME = "@tiphys/kernel";
 export declare const MACHINE_IDENTITY_NAME = "Tiphys Fleet";
 export declare const MACHINE_IDENTITY_EMAIL = "fleet@tiphys.invalid";
 /**
- * tiphys init <dir>: create a fleet home in an empty or absent directory
- * (kernel plan v1, M1-P2 step 2). Substrate-neutral: pure filesystem and
- * git (DR-0007).
+ * tiphys init <dir> [--shared-exclusion]: create a fleet home in an empty or
+ * absent directory (kernel plan v1, M1-P2 step 2). Substrate-neutral: pure
+ * filesystem and git (DR-0007).
  */
 export declare function cmdInit(args: string[]): number;

package/dist/src/commands/init.js

@@ -2,7 +2,9 @@ import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync, } from "node:fs";
 import { join, resolve } from "node:path";
 import { EX_USAGE } from "../cli.js";
+import { DEFAULT_SHARED_REF, DEFAULT_SHARED_REMOTE, SHARED_EXCLUSION_FIELD, } from "../exclusion.js";
 import { FLEET_DIRS, FLEET_IGNORED } from "../fleet.js";
+import { DURABLE_STATUS_DIR } from "../status.js";
 import { readOwnVersion } from "../version.js";
 /**
  * THE PUBLISHED KERNEL NAME (DR-0008, decided 2026-08-05: public npmjs under
@@ -34,8 +36,17 @@ export const MACHINE_IDENTITY_EMAIL = "fleet@tiphys.invalid";
  * the durable layout (SC-002) would not survive a clone of the fleet repo.
  * The ignored ephemera (state/, worktrees/, projects/) get no keep file:
  * they are recreated locally and are deliberately not repository content.
+ *
+ * `status` JOINED THIS LIST AT M4-P18 AND IT IS THE HALF OF M4-D-13 THAT IS
+ * VISIBLE IN THE LAYOUT. The status pointer used to live beside its stream
+ * under the ignored `state/` prefix, where the sentence that says where the
+ * pipeline stands could be neither committed nor pushed; the split moved it
+ * here. It is created at init rather than on first emit so that a fleet home
+ * carries the durable directory from its bootstrap commit, and so a CLONE of
+ * one carries it too: `tiphys resume` rebuilds the EPHEMERAL three and does
+ * not, and must not, fabricate durable content (src/commands/resume.ts).
  */
-const DURABLE_KEEP_DIRS = ["charter", "decisions", "tasks"];
+const DURABLE_KEEP_DIRS = ["charter", "decisions", "tasks", DURABLE_STATUS_DIR];
 function runGit(cwd, args, extraEnv) {
     const result = spawnSync("git", ["-C", cwd, ...args], {
         encoding: "utf8",
@@ -44,14 +55,29 @@ function runGit(cwd, args, extraEnv) {
     return { status: result.status, stderr: result.stderr ?? "" };
 }
 /**
- * tiphys init <dir>: create a fleet home in an empty or absent directory
- * (kernel plan v1, M1-P2 step 2). Substrate-neutral: pure filesystem and
- * git (DR-0007).
+ * THE OPT-IN FLAG FOR THE SHARED EXCLUSION REGISTER (M4-P21 criterion 1).
+ *
+ * The layer is DECLARED, never inferred, and the declaration lives in the
+ * fleet home's own `package.json` because that file is already the fleet's
+ * owner-controlled pin file. Without this flag `init` writes exactly the
+ * package.json it wrote before, with no `tiphys` section at all, so a fleet
+ * created today behaves exactly as it did and `src/exclusion.ts` returns
+ * before spawning anything. That default is the H-D carve-out in the plan's
+ * hazard table: a fleet that cannot reach a remote is not forced to switch
+ * the layer off globally, because it was never on.
+ */
+const SHARED_EXCLUSION_FLAG = "--shared-exclusion";
+/**
+ * tiphys init <dir> [--shared-exclusion]: create a fleet home in an empty or
+ * absent directory (kernel plan v1, M1-P2 step 2). Substrate-neutral: pure
+ * filesystem and git (DR-0007).
  */
 export function cmdInit(args) {
-    const [dir, ...extra] = args;
+    const rest = args.filter((arg) => arg !== SHARED_EXCLUSION_FLAG);
+    const sharedExclusion = args.length !== rest.length;
+    const [dir, ...extra] = rest;
     if (dir === undefined || extra.length > 0) {
-        process.stderr.write("usage: tiphys init <dir>\n");
+        process.stderr.write(`usage: tiphys init <dir> [${SHARED_EXCLUSION_FLAG}]\n`);
         return EX_USAGE;
     }
     const root = resolve(dir);
@@ -65,7 +91,14 @@ export function cmdInit(args) {
             const fleetMarkers = new Set([...FLEET_DIRS, "backlog.md", ".git"]);
             const looksInitialized = entries.some((entry) => fleetMarkers.has(entry));
             if (looksInitialized) {
-                process.stderr.write(`tiphys init: ${root} is already initialized\n`);
+                /* THE REMEDY TOKEN IS THE POINT OF THIS LINE (M4-P16 criterion 6).
+                   The exit code was already 1 and already correct, so a reader who
+                   got here learned only that init refused. A CLONE of a fleet home
+                   lands here too, because the marker set contains `.git`, and that
+                   reader's actual next step is `tiphys resume`, which rebuilds the
+                   three gitignored directories the clone does not carry. Naming it
+                   here is the difference between a refusal and an instruction. */
+                process.stderr.write(`tiphys init: ${root} is already initialized; run tiphys resume to rebuild the ephemeral directories a clone does not carry\n`);
             }
             else {
                 process.stderr.write(`tiphys init: ${root} is not empty and not a fleet home, refusing\n`);
@@ -76,7 +109,7 @@ export function cmdInit(args) {
     else {
         mkdirSync(root, { recursive: true });
     }
-    for (const name of FLEET_DIRS) {
+    for (const name of [...FLEET_DIRS, DURABLE_STATUS_DIR]) {
         mkdirSync(join(root, name), { recursive: true });
     }
     for (const name of DURABLE_KEEP_DIRS) {
@@ -101,6 +134,19 @@ export function cmdInit(args) {
             [KERNEL_PACKAGE_NAME]: readOwnVersion(),
         },
     };
+    if (sharedExclusion) {
+        /* The declared form is written out in full rather than as `true` so the
+           owner can see, and edit, the remote and the ref this fleet's shared
+           lease lives on. The ref is a BRANCH because only refs/heads/* is
+           pushable against the remote this kernel is built for (CLAUDE.md
+           standing warning 14, re-measured for M4-P21). */
+        fleetPackageJson["tiphys"] = {
+            sharedExclusion: {
+                remote: DEFAULT_SHARED_REMOTE,
+                ref: DEFAULT_SHARED_REF,
+            },
+        };
+    }
     writeFileSync(join(root, "package.json"), `${JSON.stringify(fleetPackageJson, null, 2)}\n`);
     writeFileSync(join(root, ".gitignore"), `${FLEET_IGNORED.join("\n")}\n`);
     const steps = [
@@ -124,5 +170,8 @@ export function cmdInit(args) {
         }
     }
     process.stdout.write(`initialized fleet home at ${root}\n`);
+    if (sharedExclusion) {
+        process.stdout.write(`declared ${SHARED_EXCLUSION_FIELD} on ${DEFAULT_SHARED_REMOTE} at ${DEFAULT_SHARED_REF}\n`);
+    }
     return 0;
 }

package/dist/src/commands/lock.d.ts

@@ -1 +1,34 @@
+/**
+ * THE DECISION-CLOCK SEAM (M4-P21 criteria 4 and 5). When
+ * TIPHYS_LOCK_TEST_NOW_MS carries a finite number of milliseconds, every
+ * mutating subcommand decides against that instant instead of `Date.now()`,
+ * by feeding the EXISTING `nowMs` option the lease library already takes
+ * (src/lock.ts:568). It exists because the two clock-skew witnesses must
+ * move ONE environment's clock ten minutes without touching a system clock,
+ * which the plan requires by name, and because criterion 6 is about what the
+ * COMMAND prints, so the skew has to reach the command rather than only the
+ * library. Inert unless the variable is set, exactly like the hold point
+ * above, and a value that does not parse is a loud refusal rather than a
+ * silent fall back to the real clock: a seam that quietly ignores its input
+ * would make a skew witness green while measuring no skew at all.
+ *
+ * AND IT IS GATED, BECAUSE IT SHIPS. `judgeByCounter` (src/exclusion.ts:553)
+ * computes `unchangedForMs = nowMs - previous.firstSeenMs`, so the module's
+ * promised "two readings of ONE clock" become one reading of a clock the
+ * CALLER supplies. Measured in the published CLI before this gate existed:
+ * the honest challenger was refused with "fencing counter 1 has stood still
+ * for 0ms of the 900000ms this environment requires", and the SAME command
+ * with this one variable set an hour ahead took a live lease over instantly
+ * and still printed `signal=counter`. A captured witness of that run was
+ * indistinguishable from an honest one.
+ *
+ * TWO CHANGES, and they are different in kind. The ALLOWANCE
+ * (TIPHYS_ALLOW_TEST_CLOCK=1) makes reaching the seam a declared act rather
+ * than a side effect of one environment variable. The LABEL makes the run
+ * SAY SO: `injectedClockSuffix` below is appended to every verdict line the
+ * shared layer prints, so the output of a measurement can never be quoted as
+ * the output of a real judgement. An allowance alone would leave the second
+ * hole open, which is why both are here.
+ */
+export declare const TEST_CLOCK_ALLOWANCE = "TIPHYS_ALLOW_TEST_CLOCK";
 export declare function cmdLock(args: string[]): Promise<number>;

package/dist/src/commands/lock.js

@@ -1,7 +1,7 @@
 import { existsSync, writeFileSync } from "node:fs";
 import { setTimeout as sleep } from "node:timers/promises";
 import { EX_USAGE } from "../cli.js";
-import { loadFleet } from "../fleet.js";
+import { loadFleet, refuseOpenPathForWrite } from "../fleet.js";
 import { acquireLease, leaseStatus, observeLease, releaseLease, renewLease, } from "../lock.js";
 /**
  * tiphys lock <acquire [--take-over] [--duration <seconds>] | renew
@@ -49,6 +49,16 @@ async function maybeHoldForTest(lockPath) {
     }
     const observed = observeLease(lockPath);
     const nowMs = Date.now();
+    /* THE MARKER PATHS ARE DERIVED FROM A CALLER-SUPPLIED PATH, so their entry
+       type is established before either is opened for writing. A named pipe at
+       `<barrier>.observed` blocked this seam forever with zero output, which is
+       the same class this round closed in the lease and brief readers; the seam
+       is inert unless the variable is set, which changes how it is REACHED and
+       not what it does once reached. */
+    const observedRefusal = refuseOpenPathForWrite(`${barrier}.observed`);
+    if (observedRefusal !== undefined) {
+        throw new Error(`lock test hold point: ${observedRefusal}`);
+    }
     writeFileSync(`${barrier}.observed`, "");
     const startNs = process.hrtime.bigint();
     const limitNs = BigInt(HOLD_WAIT_LIMIT_MS) * 1000000n;
@@ -72,9 +82,102 @@ async function maybeHoldForTest(lockPath) {
     }
     // Record that the hold really held, and why the wait ended, so the
     // witness can assert the interleave rather than assume it.
+    /* Re-established immediately before this second write rather than once
+       per call: the two writes are separated by a wait of up to thirty seconds
+       and the path is derived from one the CALLER supplied. */
+    const releasedRefusal = refuseOpenPathForWrite(`${barrier}.released`);
+    if (releasedRefusal !== undefined) {
+        throw new Error(`lock test hold point: ${releasedRefusal}`);
+    }
     writeFileSync(`${barrier}.released`, `held after ${String(waitedMs)}ms (monotonic), barrier observed\n`);
     return { observed, nowMs };
 }
+/**
+ * THE DECISION-CLOCK SEAM (M4-P21 criteria 4 and 5). When
+ * TIPHYS_LOCK_TEST_NOW_MS carries a finite number of milliseconds, every
+ * mutating subcommand decides against that instant instead of `Date.now()`,
+ * by feeding the EXISTING `nowMs` option the lease library already takes
+ * (src/lock.ts:568). It exists because the two clock-skew witnesses must
+ * move ONE environment's clock ten minutes without touching a system clock,
+ * which the plan requires by name, and because criterion 6 is about what the
+ * COMMAND prints, so the skew has to reach the command rather than only the
+ * library. Inert unless the variable is set, exactly like the hold point
+ * above, and a value that does not parse is a loud refusal rather than a
+ * silent fall back to the real clock: a seam that quietly ignores its input
+ * would make a skew witness green while measuring no skew at all.
+ *
+ * AND IT IS GATED, BECAUSE IT SHIPS. `judgeByCounter` (src/exclusion.ts:553)
+ * computes `unchangedForMs = nowMs - previous.firstSeenMs`, so the module's
+ * promised "two readings of ONE clock" become one reading of a clock the
+ * CALLER supplies. Measured in the published CLI before this gate existed:
+ * the honest challenger was refused with "fencing counter 1 has stood still
+ * for 0ms of the 900000ms this environment requires", and the SAME command
+ * with this one variable set an hour ahead took a live lease over instantly
+ * and still printed `signal=counter`. A captured witness of that run was
+ * indistinguishable from an honest one.
+ *
+ * TWO CHANGES, and they are different in kind. The ALLOWANCE
+ * (TIPHYS_ALLOW_TEST_CLOCK=1) makes reaching the seam a declared act rather
+ * than a side effect of one environment variable. The LABEL makes the run
+ * SAY SO: `injectedClockSuffix` below is appended to every verdict line the
+ * shared layer prints, so the output of a measurement can never be quoted as
+ * the output of a real judgement. An allowance alone would leave the second
+ * hole open, which is why both are here.
+ */
+export const TEST_CLOCK_ALLOWANCE = "TIPHYS_ALLOW_TEST_CLOCK";
+function testClockMs() {
+    const raw = process.env.TIPHYS_LOCK_TEST_NOW_MS;
+    if (raw === undefined || raw === "") {
+        return undefined;
+    }
+    if (process.env[TEST_CLOCK_ALLOWANCE] !== "1") {
+        throw new Error(`lock test clock: TIPHYS_LOCK_TEST_NOW_MS is set and ` +
+            `${TEST_CLOCK_ALLOWANCE}=1 is not, so this run would have decided ` +
+            `cross-environment exclusion against a clock its caller supplied ` +
+            `while printing the same verdict an honest run prints; set ` +
+            `${TEST_CLOCK_ALLOWANCE}=1 to declare that this run is a measurement, ` +
+            `or unset TIPHYS_LOCK_TEST_NOW_MS`);
+    }
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed)) {
+        throw new Error(`lock test clock: TIPHYS_LOCK_TEST_NOW_MS=${raw} does not parse as a ` +
+            `number of milliseconds; this run would have measured the real clock ` +
+            `and is not evidence`);
+    }
+    return parsed;
+}
+/**
+ * What a verdict line gains when the decision clock was injected. Empty on
+ * every honest run, so no shipped output changes for anyone who does not set
+ * the variable.
+ */
+function injectedClockSuffix() {
+    return process.env.TIPHYS_LOCK_TEST_NOW_MS === undefined ||
+        process.env.TIPHYS_LOCK_TEST_NOW_MS === ""
+        ? ""
+        : "(injected-clock)";
+}
+/**
+ * Emit the shared exclusion layer's verdict line. One line, and it always
+ * names the SIGNAL that reached the verdict (criterion 6): `signal=counter`
+ * where the register was reachable and its fencing counter decided, or
+ * `signal=clock` where it was not and the command therefore refused rather
+ * than deciding cross-environment exclusion on a local clock.
+ */
+function reportShared(outcome) {
+    if (outcome.shared !== undefined) {
+        process.stdout.write(`${labelClock(outcome.shared.line)}\n`);
+    }
+}
+/**
+ * Mark every `signal=<basis>` token in a verdict line when this run's
+ * decision clock was injected. The token is what criterion 6 asks the
+ * command to print, so it is the token that has to carry the caveat.
+ */
+function labelClock(line) {
+    const suffix = injectedClockSuffix();
+    return suffix === "" ? line : line.replace(/signal=(counter|clock)/g, `signal=$1${suffix}`);
+}
 function usageError(message) {
     if (message !== undefined) {
         process.stderr.write(`tiphys lock: ${message}\n`);
@@ -99,7 +202,7 @@ function failure(outcome) {
     const remedy = outcome.claimTimeout === true
         ? "; a crashed mutation can leave this file behind, but deleting it while a mutation is genuinely in flight can produce two lock holders, so confirm no tiphys process is running against this fleet before removing it"
         : "";
-    process.stderr.write(`tiphys lock: ${outcome.reason}${remedy}\n`);
+    process.stderr.write(`tiphys lock: ${labelClock(outcome.reason)}${remedy}\n`);
     return 1;
 }
 function parseFlags(rest) {
@@ -158,7 +261,7 @@ export async function cmdLock(args) {
                 takeover: flags.takeover,
                 durationSeconds: flags.durationSeconds,
                 observed: held?.observed,
-                nowMs: held?.nowMs,
+                nowMs: testClockMs() ?? held?.nowMs,
             });
             if (!outcome.ok) {
                 return failure(outcome);
@@ -168,6 +271,7 @@ export async function cmdLock(args) {
                 throw new Error("unreachable: acquire produced no lease");
             }
             process.stdout.write(`acquired ${lease.holderId} expires ${lease.expiresAt}\n`);
+            reportShared(outcome);
             return 0;
         }
         case "renew": {
@@ -178,7 +282,7 @@ export async function cmdLock(args) {
             const outcome = await renewLease(lockPath, flags.holder, {
                 durationSeconds: flags.durationSeconds,
                 observed: held?.observed,
-                nowMs: held?.nowMs,
+                nowMs: testClockMs() ?? held?.nowMs,
             });
             if (!outcome.ok) {
                 return failure(outcome);
@@ -188,6 +292,7 @@ export async function cmdLock(args) {
                 throw new Error("unreachable: renew produced no lease");
             }
             process.stdout.write(`renewed ${lease.holderId} expires ${lease.expiresAt}\n`);
+            reportShared(outcome);
             return 0;
         }
         case "release": {
@@ -195,13 +300,19 @@ export async function cmdLock(args) {
                 return usageError("release requires --holder <id> and no other flags");
             }
             const held = await maybeHoldForTest(lockPath);
-            const outcome = await releaseLease(lockPath, flags.holder, {
+            const releaseOptions = {
                 observed: held?.observed,
-            });
+            };
+            const releaseClock = testClockMs();
+            if (releaseClock !== undefined) {
+                releaseOptions.nowMs = releaseClock;
+            }
+            const outcome = await releaseLease(lockPath, flags.holder, releaseOptions);
             if (!outcome.ok) {
                 return failure(outcome);
             }
             process.stdout.write(`released ${flags.holder}\n`);
+            reportShared(outcome);
             return 0;
         }
         case "status": {

package/dist/src/commands/next.d.ts

@@ -0,0 +1,130 @@
+import type { Fleet } from "../fleet.ts";
+/**
+ * Work remains. DISTINCT FROM 1, which is the command failing, and from 0,
+ * which is every in-flight category empty (criterion 1).
+ */
+export declare const EXIT_WORK_REMAINS = 3;
+/**
+ * WHAT THIS COMMAND CANNOT SEE, as a NAMED LIST (criterion 4).
+ *
+ * Printed unconditionally. It is not derived from a probe and it does not
+ * shorten when something is unreachable, because a list that shrinks when the
+ * network is gone tells the reader that fewer things are unknown at exactly
+ * the moment more of them are.
+ */
+export declare const CANNOT_SEE: readonly string[];
+/** The heading the cannot-see block is printed under. */
+export declare const CANNOT_SEE_HEADING = "cannot see (this command has no network; an absence here is not evidence of absence):";
+/** How a branch turned out to have been delivered, or why that is not settled. */
+export type Delivery = {
+    kind: "delivered";
+    how: "ancestor" | "squash" | "patch-equivalent";
+} | {
+    kind: "open";
+} | {
+    kind: "unknown";
+    detail: string;
+};
+/**
+ * THE DELIVERED-ELSEWHERE PREDICATE (criterion 3).
+ *
+ * `git branch --merged` reports a squash-merged branch as UNMERGED, because
+ * the squash commit's sha is not the branch tip and the branch tip is not an
+ * ancestor of the base. This process squash-merges every phase, so under the
+ * naive implementation EVERY delivered branch reads as open forever and the
+ * stop condition never goes green.
+ *
+ * THE CITATION THAT STOOD HERE UNTIL ROUND 1 WAS WRONG, AND IT WAS WRONG IN
+ * THE SILENT DIRECTION. It read `delivery/STATE.md:54`, which resolves, which
+ * is why no gate reddened; the line it resolves to is about two merge blockers
+ * and says nothing about `git branch --merged`. Measured:
+ * `grep -n 'branch --merged' delivery/STATE.md` returns nothing, at this head
+ * and at the merge base, so the sentence is absent rather than moved. The
+ * claim itself is measured in this repository and the measurement is the
+ * citation now: witness/captures/next-delivered-elsewhere-git.txt records
+ * `git branch --merged main` listing neither the squash-merged branch nor the
+ * one delivered through another pull request. The same wrong citation is in
+ * the plan at delivery/plan/kernel-plan-m4.md:3239 and in this phase's work
+ * history; the work history is corrected, and the plan is an owner-approved
+ * document this phase does not edit, so it is raised rather than changed.
+ *
+ * THREE ARMS, AND THE THIRD IS WHY THIS IS NOT JUST A CALL TO `landedness`.
+ *
+ *   1. ANCESTOR. An ordinary merge or a fast-forward. `landedness` arm one.
+ *   2. CONTENT. Merging the branch into the base changes no tree, so the base
+ *      already carries everything the branch did however it got there. This is
+ *      MEMBER A, the squash merge, and it is `landedness` arm two.
+ *   3. PATCH EQUIVALENCE. Every commit the branch carries has an equivalent
+ *      patch already upstream, found by patch id rather than by sha. This is
+ *      MEMBER B: commits that landed inside ANOTHER branch's pull request, so
+ *      they appear on the base interleaved with commits the branch never had.
+ *
+ * ARM 3 IS NOT REDUNDANT WITH ARM 2, and the case that separates them is the
+ * ordinary one. Once the base moves on and edits the same region again, a
+ * three-way merge of the delivered branch CONFLICTS, so arm 2 answers `open`
+ * for a branch whose every commit is demonstrably already upstream. Arm 3
+ * answers it by patch id, which survives the later edit.
+ *
+ * ARM 2 IS NOT REDUNDANT WITH ARM 3 EITHER. A squash collapses N commits into
+ * one, whose patch id is the id of the COMBINED diff and therefore equals no
+ * individual commit's. For any branch of more than one commit, arm 3 sees only
+ * unmatched commits and answers `open`.
+ *
+ * REUSE, NOT A SECOND IMPLEMENTATION (T-005). Arms 1 and 2 are
+ * `landedness` at src/teardown.ts:123, the predicate `tiphys teardown` already
+ * refuses on. A second copy here would be a second thing to keep true.
+ *
+ * INCONCLUSIVE IS NOT `open` AND IT IS NOT `delivered`. A git failure returns
+ * `unknown`, which the caller counts as work remaining, because the one answer
+ * this predicate must never invent is a confident one.
+ */
+export declare function deliveredElsewhere(contextDir: string, branchRef: string, baseRef: string): Delivery;
+/** One thing that is in flight, in the category that found it. */
+export interface InFlightItem {
+    category: "task" | "worktree" | "branch";
+    what: string;
+}
+/**
+ * Everything in flight in a fleet home, plus every candidate left unread, plus
+ * the disclosures a reader needs to check the judgement rather than trust it.
+ *
+ * `notes` DOES NOT COUNT TOWARD THE EXIT CODE and that is deliberate. It
+ * carries facts about HOW a judgement was made (which base ref each project's
+ * branches were compared against, and by which rule that base was chosen), not
+ * facts about whether work remains. Putting them in `unknown` would hold the
+ * exit at `EXIT_WORK_REMAINS` forever; leaving them out is what let a clone
+ * whose `origin/HEAD` points at a feature branch judge every branch against
+ * that branch with nothing in the output saying so.
+ */
+export interface InFlight {
+    items: InFlightItem[];
+    unknown: string[];
+    notes: string[];
+}
+export declare function baseRefOf(projectDir: string): {
+    ok: true;
+    ref: string;
+    how: string;
+    doubt?: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Every in-flight category in a fleet home, in dependency order: the task
+ * record, the checkout it owns, and the branch that outlives both.
+ */
+export declare function collectInFlight(fleet: Fleet): InFlight;
+/**
+ * THE ONE NEXT ACTION (criterion 1). Exactly one, chosen by the first
+ * non-empty category in the order above, so the answer is derived from the
+ * report rather than picked.
+ */
+export declare function nextAction(report: InFlight): string;
+/** The cannot-see block. Unconditional, and it probes nothing to build. */
+export declare function cannotSeeBlock(): string[];
+/** The whole report, as lines, with exactly one `next action:` line. */
+export declare function renderReport(fleet: Fleet, report: InFlight): string[];
+/** Work remains whenever anything is in flight OR anything could not be read. */
+export declare function exitCodeFor(report: InFlight): number;
+export declare function cmdNext(args: string[]): number;