@tiphys/kernel 0.0.0 → 0.1.0

package/dist/src/commands/lock.js

@@ -0,0 +1,229 @@
+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 { acquireLease, leaseStatus, observeLease, releaseLease, renewLease, } from "../lock.js";
+/**
+ * tiphys lock <acquire [--take-over] [--duration <seconds>] | renew
+ * --holder <id> [--duration <seconds>] | release --holder <id> | status>
+ * (kernel plan v1, M1-P3 step 2). Runs in a fleet home (cwd). The holder
+ * identity for renew and release is the opaque holderId that acquire
+ * printed; it outlives any one command invocation (FM-022) and is never
+ * derived from the running program (plan constraint C-2).
+ */
+const USAGE = "usage: tiphys lock <acquire [--take-over] [--duration <seconds>] | " +
+    "renew --holder <id> [--duration <seconds>] | " +
+    "release --holder <id> | status>";
+/**
+ * Deterministic race-witness hold point (the plan's test determinism
+ * rule: scripted interleaves over sleep-based timing). When
+ * TIPHYS_LOCK_TEST_HOLD names a barrier path, the mutating subcommands
+ * observe the lease and freeze their decision clock first, write
+ * <barrier>.observed as a ready marker, then wait for the barrier file
+ * to appear before deciding and applying through the one mutation
+ * primitive. A test can thereby interleave two real CLI invocations at
+ * the exact compare-and-swap point. Inert unless the variable is set.
+ *
+ * The seam is LOUD about not holding (D-3). It previously had two exits
+ * from its wait and only one of them meant "held": on the other the
+ * command walked into the mutation carrying a stale observation and
+ * told nobody, so a witness could score a compare-and-swap it never
+ * staged and still pass. Both exits are now closed with a throw, the
+ * bound is monotonic (process.hrtime.bigint, not Date.now, because a
+ * realtime bound mixed with monotonic test durations is precisely what
+ * made "it failed fast" look like proof the bound was not reached), and
+ * the reason the wait ended is written to <barrier>.released so the
+ * test can assert the interleave actually happened. This is a test
+ * integrity fix; it is NOT a fix for the unattributed U-2 flake, whose
+ * trigger remains unexplained.
+ */
+const HOLD_WAIT_LIMIT_MS = 30_000;
+async function maybeHoldForTest(lockPath) {
+    const barrier = process.env.TIPHYS_LOCK_TEST_HOLD;
+    if (barrier === undefined || barrier === "") {
+        return undefined;
+    }
+    if (existsSync(barrier)) {
+        throw new Error(`lock test hold point: barrier ${barrier} already existed before the ` +
+            `hold; this interleave was never staged and the run is not evidence`);
+    }
+    const observed = observeLease(lockPath);
+    const nowMs = Date.now();
+    writeFileSync(`${barrier}.observed`, "");
+    const startNs = process.hrtime.bigint();
+    const limitNs = BigInt(HOLD_WAIT_LIMIT_MS) * 1000000n;
+    let held = false;
+    for (;;) {
+        if (existsSync(barrier)) {
+            held = true;
+            break;
+        }
+        if (process.hrtime.bigint() - startNs >= limitNs) {
+            break;
+        }
+        await sleep(10);
+    }
+    const waitedMs = Number((process.hrtime.bigint() - startNs) / 1000000n);
+    if (!held) {
+        throw new Error(`lock test hold point: barrier ${barrier} never appeared within ` +
+            `${String(HOLD_WAIT_LIMIT_MS)}ms (waited ${String(waitedMs)}ms on the ` +
+            `monotonic clock); this interleave was never staged and the run is ` +
+            `not evidence`);
+    }
+    // Record that the hold really held, and why the wait ended, so the
+    // witness can assert the interleave rather than assume it.
+    writeFileSync(`${barrier}.released`, `held after ${String(waitedMs)}ms (monotonic), barrier observed\n`);
+    return { observed, nowMs };
+}
+function usageError(message) {
+    if (message !== undefined) {
+        process.stderr.write(`tiphys lock: ${message}\n`);
+    }
+    process.stderr.write(`${USAGE}\n`);
+    return EX_USAGE;
+}
+/**
+ * The one failure emitter for acquire, renew, and release (CR-204).
+ * When the library classified the failure as a stale mutation claim,
+ * the operator is pointed at the claim file rather than at a holder
+ * that may not exist; the remedy text lives here, so a CLI that
+ * ignored the classification would visibly lose it. Operational
+ * failures exit 1 (usage errors alone use EX_USAGE).
+ */
+function failure(outcome) {
+    // D-2: the claim file is the sole serializer of lock mutations, so
+    // deleting one that is actually live lets a second mutation enter the
+    // critical section and can produce two live holders. The remedy text
+    // therefore states that cost instead of inviting the deletion, and it
+    // names the safe order: make sure no tiphys process is running first.
+    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`);
+    return 1;
+}
+function parseFlags(rest) {
+    const parsed = {
+        takeover: false,
+        holder: undefined,
+        durationSeconds: undefined,
+    };
+    for (let i = 0; i < rest.length; i += 1) {
+        const flag = rest[i];
+        if (flag === "--take-over") {
+            parsed.takeover = true;
+        }
+        else if (flag === "--holder" && i + 1 < rest.length) {
+            parsed.holder = rest[i + 1];
+            i += 1;
+        }
+        else if (flag === "--duration" && i + 1 < rest.length) {
+            const seconds = Number(rest[i + 1]);
+            if (!Number.isFinite(seconds) || seconds <= 0) {
+                return undefined;
+            }
+            parsed.durationSeconds = seconds;
+            i += 1;
+        }
+        else {
+            return undefined;
+        }
+    }
+    return parsed;
+}
+export async function cmdLock(args) {
+    const [subcommand, ...rest] = args;
+    if (subcommand === undefined) {
+        return usageError();
+    }
+    const flags = parseFlags(rest);
+    if (flags === undefined) {
+        return usageError();
+    }
+    let lockPath;
+    try {
+        lockPath = loadFleet(process.cwd()).lockPath;
+    }
+    catch (error) {
+        process.stderr.write(`tiphys lock: ${error.message}\n`);
+        return 1;
+    }
+    switch (subcommand) {
+        case "acquire": {
+            if (flags.holder !== undefined) {
+                return usageError("acquire does not take --holder");
+            }
+            const held = await maybeHoldForTest(lockPath);
+            const outcome = await acquireLease(lockPath, {
+                takeover: flags.takeover,
+                durationSeconds: flags.durationSeconds,
+                observed: held?.observed,
+                nowMs: held?.nowMs,
+            });
+            if (!outcome.ok) {
+                return failure(outcome);
+            }
+            const lease = outcome.lease;
+            if (lease === null) {
+                throw new Error("unreachable: acquire produced no lease");
+            }
+            process.stdout.write(`acquired ${lease.holderId} expires ${lease.expiresAt}\n`);
+            return 0;
+        }
+        case "renew": {
+            if (flags.holder === undefined || flags.takeover) {
+                return usageError("renew requires --holder <id>");
+            }
+            const held = await maybeHoldForTest(lockPath);
+            const outcome = await renewLease(lockPath, flags.holder, {
+                durationSeconds: flags.durationSeconds,
+                observed: held?.observed,
+                nowMs: held?.nowMs,
+            });
+            if (!outcome.ok) {
+                return failure(outcome);
+            }
+            const lease = outcome.lease;
+            if (lease === null) {
+                throw new Error("unreachable: renew produced no lease");
+            }
+            process.stdout.write(`renewed ${lease.holderId} expires ${lease.expiresAt}\n`);
+            return 0;
+        }
+        case "release": {
+            if (flags.holder === undefined || flags.takeover || flags.durationSeconds !== undefined) {
+                return usageError("release requires --holder <id> and no other flags");
+            }
+            const held = await maybeHoldForTest(lockPath);
+            const outcome = await releaseLease(lockPath, flags.holder, {
+                observed: held?.observed,
+            });
+            if (!outcome.ok) {
+                return failure(outcome);
+            }
+            process.stdout.write(`released ${flags.holder}\n`);
+            return 0;
+        }
+        case "status": {
+            if (flags.holder !== undefined || flags.takeover || flags.durationSeconds !== undefined) {
+                return usageError("status takes no flags");
+            }
+            const status = leaseStatus(lockPath);
+            if (status.state === "free") {
+                process.stdout.write("free\n");
+            }
+            else if (status.state === "corrupt") {
+                process.stdout.write(`corrupt ${status.detail}\n`);
+            }
+            else {
+                process.stdout.write(`${status.state} holder ${status.lease.holderId} acquired ` +
+                    `${status.lease.acquiredAt} expires ${status.lease.expiresAt}\n`);
+            }
+            // status always exits 0 so a human takeover decision is informed
+            // by reading, never blocked by an exit code.
+            return 0;
+        }
+        default:
+            return usageError(`unknown lock subcommand "${subcommand}"`);
+    }
+}

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

@@ -0,0 +1,40 @@
+/**
+ * `tiphys mode show --mode <id> [--file <path>]` (kernel plan M3, M3-P3
+ * step 5; fix round 1 finding B-002).
+ *
+ * WHY THIS COMMAND EXISTS: a brief or a human has to be able to read what a
+ * declared mode requires without parsing YAML by hand. That is the whole
+ * scope. It shows; it does not resolve a project into a mode, does not
+ * enforce one, and does not run one.
+ *
+ * IT VALIDATES BEFORE IT SERVES, and that is the point of the fix round.
+ * As first shipped this command read the document and printed it, invoking
+ * neither the schema nor any registered check, so every guard the phase built
+ * was bypassed on the one path built for humans and briefs. The mechanism is
+ * A READER THAT DOES NOT VALIDATE WHAT IT READS, and the fix is not "detect
+ * one more bad state": it is that this command now runs exactly what
+ * `tiphys validate --type assurance-modes --context <dir>` runs, and REFUSES
+ * rather than printing when the document fails. A partial answer from an
+ * invalid document is worse than an error, because the reader cannot tell.
+ *
+ * THE CONTEXT IS THE DOCUMENT'S OWN DIRECTORY. The cross-document checks
+ * resolve `gate-registry.yaml` and `schemas/charter.schema.json` beside the
+ * document, which is where the npm package puts them and where this repository
+ * keeps them. That makes the two `requiresContext` checks run here rather than
+ * SKIP, which matters: a skip fails the run, and a command that always failed
+ * would be a command nobody uses.
+ *
+ * Exit codes:
+ *   0   the document is valid and the mode was found and printed
+ *   1   the document could not be read, is invalid, or no mode carries that id
+ *   64  usage error (BSD sysexits EX_USAGE)
+ *
+ * A MODE ID THAT IS NOT DECLARED IS 1, NOT 64, and the difference is not
+ * pedantry. 64 means the caller used the command wrongly; 1 means the command
+ * worked and the answer is no. `--mode direct-pr` against a document that
+ * declares only `full` is a well-formed question with a negative answer, and a
+ * caller that cannot tell those apart cannot script this.
+ */
+/** Exit code for usage errors, per BSD sysexits EX_USAGE. */
+export declare const EX_USAGE = 64;
+export declare function cmdMode(argv: string[]): number;

package/dist/src/commands/mode.js

@@ -0,0 +1,134 @@
+/**
+ * `tiphys mode show --mode <id> [--file <path>]` (kernel plan M3, M3-P3
+ * step 5; fix round 1 finding B-002).
+ *
+ * WHY THIS COMMAND EXISTS: a brief or a human has to be able to read what a
+ * declared mode requires without parsing YAML by hand. That is the whole
+ * scope. It shows; it does not resolve a project into a mode, does not
+ * enforce one, and does not run one.
+ *
+ * IT VALIDATES BEFORE IT SERVES, and that is the point of the fix round.
+ * As first shipped this command read the document and printed it, invoking
+ * neither the schema nor any registered check, so every guard the phase built
+ * was bypassed on the one path built for humans and briefs. The mechanism is
+ * A READER THAT DOES NOT VALIDATE WHAT IT READS, and the fix is not "detect
+ * one more bad state": it is that this command now runs exactly what
+ * `tiphys validate --type assurance-modes --context <dir>` runs, and REFUSES
+ * rather than printing when the document fails. A partial answer from an
+ * invalid document is worse than an error, because the reader cannot tell.
+ *
+ * THE CONTEXT IS THE DOCUMENT'S OWN DIRECTORY. The cross-document checks
+ * resolve `gate-registry.yaml` and `schemas/charter.schema.json` beside the
+ * document, which is where the npm package puts them and where this repository
+ * keeps them. That makes the two `requiresContext` checks run here rather than
+ * SKIP, which matters: a skip fails the run, and a command that always failed
+ * would be a command nobody uses.
+ *
+ * Exit codes:
+ *   0   the document is valid and the mode was found and printed
+ *   1   the document could not be read, is invalid, or no mode carries that id
+ *   64  usage error (BSD sysexits EX_USAGE)
+ *
+ * A MODE ID THAT IS NOT DECLARED IS 1, NOT 64, and the difference is not
+ * pedantry. 64 means the caller used the command wrongly; 1 means the command
+ * worked and the answer is no. `--mode direct-pr` against a document that
+ * declares only `full` is a well-formed question with a negative answer, and a
+ * caller that cannot tell those apart cannot script this.
+ */
+import { dirname } from "node:path";
+import { runChecks } from "../checks.js";
+import { formatDiagnostics, validateInstance } from "../validate.js";
+import { loadTypeSchema } from "./validate.js";
+import { readModes, renderMode } from "../modes.js";
+/** The artifact type this command reads, and the type its checks are registered for. */
+const MODES_TYPE = "assurance-modes";
+/** Exit code for usage errors, per BSD sysexits EX_USAGE. */
+export const EX_USAGE = 64;
+function usage() {
+    return "usage: tiphys mode show --mode <id> [--file <path>]";
+}
+function parseArgs(argv) {
+    const options = {};
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (argument === "--mode" || argument === "--file") {
+            const value = argv[index + 1];
+            if (value === undefined || value.startsWith("--")) {
+                return { usageError: `${argument} requires a value` };
+            }
+            if (argument === "--mode") {
+                options.mode = value;
+            }
+            else {
+                options.file = value;
+            }
+            index += 1;
+            continue;
+        }
+        return { usageError: `unknown argument ${argument}` };
+    }
+    if (options.mode === undefined) {
+        return { usageError: "--mode is required" };
+    }
+    return { options };
+}
+function fail(reason, code) {
+    process.stderr.write(`tiphys mode: ${reason}\n`);
+    if (code === EX_USAGE) {
+        process.stderr.write(`${usage()}\n`);
+    }
+    return code;
+}
+export function cmdMode(argv) {
+    const [subcommand, ...rest] = argv;
+    if (subcommand !== "show") {
+        return fail(subcommand === undefined
+            ? "a subcommand is required"
+            : `unknown subcommand ${subcommand}`, EX_USAGE);
+    }
+    const parsed = parseArgs(rest);
+    if (parsed.options === undefined) {
+        return fail(parsed.usageError ?? "usage error", EX_USAGE);
+    }
+    let read;
+    try {
+        read = parsed.options.file === undefined ? readModes() : readModes(parsed.options.file);
+    }
+    catch (error) {
+        /* `packageRoot` throws when the shipped document is not above this module,
+           which is an incomplete installation rather than a caller error. One line,
+           never a stack trace, the same policy `tiphys validate` applies to its own
+           operator-supplied input. */
+        return fail(String(error instanceof Error ? error.message : error), 1);
+    }
+    if (!read.ok) {
+        return fail(read.reason, 1);
+    }
+    /* VALIDATE, THEN SERVE. Schema first and derived checks second, in the same
+       order and through the same functions `tiphys validate` uses, so the two
+       commands cannot drift into disagreeing about what a valid document is. */
+    const lines = formatDiagnostics(validateInstance(loadTypeSchema(MODES_TYPE), read.raw));
+    const checks = runChecks(MODES_TYPE, read.raw, dirname(read.path));
+    if (lines.length > 0 || checks.failed) {
+        process.stderr.write(`tiphys mode: ${read.path} is not a valid ${MODES_TYPE} document, so it is not served\n`);
+        for (const line of [...lines, ...checks.lines]) {
+            process.stderr.write(`${line}\n`);
+        }
+        return 1;
+    }
+    const wanted = parsed.options.mode;
+    const mode = read.modes.find((candidate) => candidate.id === wanted);
+    if (mode === undefined) {
+        const declared = read.modes.map((candidate) => candidate.id).sort();
+        return fail(`${read.path} declares no mode ${wanted}; it declares ${declared.length === 0 ? "none" : declared.join(", ")}`, 1);
+    }
+    /* WHICH DOCUMENT THIS IS, derived from the invocation rather than from the
+       path: no `--file` means `readModes()` walked to the package root and read
+       the kernel's own document. CR-004 item 2 turns on that distinction, because
+       "no phase has been delivered under this mode" is a claim about the kernel's
+       own delivery and is not knowable for a document a consumer supplied. */
+    for (const line of renderMode(mode, { shippedDocument: parsed.options.file === undefined })) {
+        process.stdout.write(`${line}\n`);
+    }
+    return 0;
+}

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

@@ -0,0 +1,20 @@
+/**
+ * `tiphys plan project --phase-id <id> [--plan <file>] [--out <dir>]`
+ * (kernel plan M3, M3-P1 step 2; D-M3-18).
+ *
+ * Emits the M2-P4 scope auditor's phase declaration from the plan, so the
+ * auditor's input becomes a GENERATED VIEW of one source instead of a second
+ * hand-authored source that can drift.
+ *
+ * The output path is `<out>/<phase-id-lowercased>.json`, defaulting to
+ * `delivery/plan/phase-declarations`, which is the directory
+ * `gates.manifest.json` passes to the auditor as `--declarations`.
+ *
+ * With no `--out` the document is written; with `--stdout` it is printed and
+ * nothing is written, which is what a test or a reviewer wants when checking
+ * WHAT would be emitted without touching the tree.
+ *
+ * Every path this command touches is operator-supplied and is classified
+ * before it is opened or written (D-M3-27).
+ */
+export declare function cmdPlan(argv: string[]): number;

package/dist/src/commands/plan.js

@@ -0,0 +1,105 @@
+/**
+ * `tiphys plan project --phase-id <id> [--plan <file>] [--out <dir>]`
+ * (kernel plan M3, M3-P1 step 2; D-M3-18).
+ *
+ * Emits the M2-P4 scope auditor's phase declaration from the plan, so the
+ * auditor's input becomes a GENERATED VIEW of one source instead of a second
+ * hand-authored source that can drift.
+ *
+ * The output path is `<out>/<phase-id-lowercased>.json`, defaulting to
+ * `delivery/plan/phase-declarations`, which is the directory
+ * `gates.manifest.json` passes to the auditor as `--declarations`.
+ *
+ * With no `--out` the document is written; with `--stdout` it is printed and
+ * nothing is written, which is what a test or a reviewer wants when checking
+ * WHAT would be emitted without touching the tree.
+ *
+ * Every path this command touches is operator-supplied and is classified
+ * before it is opened or written (D-M3-27).
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { EX_USAGE } from "../cli.js";
+import { projectPhase, renderDeclaration } from "../plan.js";
+import { refuseOpenForWrite } from "../task.js";
+import { classifyContextDirectory, decodeDocument, readOperatorPath, } from "../validate.js";
+const USAGE = "usage: tiphys plan project --phase-id <id> [--plan <file>] " +
+    "[--out <dir>] [--stdout]";
+const DEFAULT_PLAN = "templates/plan.example.yaml";
+const DEFAULT_OUT = join("delivery", "plan", "phase-declarations");
+function parseArgs(argv) {
+    const args = { plan: DEFAULT_PLAN, out: DEFAULT_OUT, toStdout: false };
+    for (let index = 0; index < argv.length; index += 1) {
+        const flag = argv[index];
+        if (flag === "--stdout") {
+            args.toStdout = true;
+            continue;
+        }
+        const value = argv[index + 1];
+        if (flag !== "--phase-id" && flag !== "--plan" && flag !== "--out") {
+            return { usageError: `unknown option ${flag}` };
+        }
+        if (value === undefined || value.startsWith("--")) {
+            return { usageError: `${flag} requires a value` };
+        }
+        index += 1;
+        if (flag === "--phase-id")
+            args.phaseId = value;
+        else if (flag === "--plan")
+            args.plan = value;
+        else
+            args.out = value;
+    }
+    if (args.phaseId === undefined) {
+        return { usageError: "--phase-id is required" };
+    }
+    return { args };
+}
+export function cmdPlan(argv) {
+    const [subcommand, ...rest] = argv;
+    if (subcommand !== "project") {
+        process.stderr.write(`${USAGE}\n`);
+        return EX_USAGE;
+    }
+    const parsed = parseArgs(rest);
+    if (parsed.args === undefined) {
+        process.stderr.write(`tiphys plan project: ${parsed.usageError ?? "usage error"}\n${USAGE}\n`);
+        return EX_USAGE;
+    }
+    const { phaseId, plan, out, toStdout } = parsed.args;
+    const read = readOperatorPath(plan);
+    if (!read.ok) {
+        process.stderr.write(`tiphys plan project: ${read.reason}\n`);
+        return 1;
+    }
+    const decoded = decodeDocument(read.body, plan);
+    if (!decoded.ok) {
+        process.stderr.write(`tiphys plan project: ${decoded.reason}\n`);
+        return 1;
+    }
+    const projection = projectPhase(decoded.value, phaseId);
+    if (!projection.ok) {
+        process.stderr.write(`tiphys plan project: ${projection.reason}\n`);
+        return 1;
+    }
+    const body = renderDeclaration(projection.declaration);
+    if (toStdout) {
+        process.stdout.write(body);
+        return 0;
+    }
+    mkdirSync(out, { recursive: true });
+    const problem = classifyContextDirectory(out);
+    if (problem !== undefined) {
+        process.stderr.write(`tiphys plan project: ${problem}\n`);
+        return 1;
+    }
+    const target = join(out, projection.filename);
+    const refusal = refuseOpenForWrite(target);
+    if (refusal !== undefined) {
+        process.stderr.write(`tiphys plan project: ${refusal}\n`);
+        return 1;
+    }
+    writeFileSync(target, body, "utf8");
+    process.stdout.write(`${target}\n`);
+    return 0;
+}

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

@@ -0,0 +1 @@
+export declare function cmdPool(args: string[]): Promise<number>;

package/dist/src/commands/pool.js

@@ -0,0 +1,128 @@
+import { EX_USAGE } from "../cli.js";
+import { loadFleet } from "../fleet.js";
+import { poolCreate, poolDestroy, poolList } from "../pool.js";
+/**
+ * tiphys pool <create --task <id> --project <path> [--offline] | list |
+ * destroy --task <id> [--discard]> (kernel plan v1, M1-P3 steps 3-4).
+ * Runs in a fleet home (cwd). create emits the fetched base SHA as its
+ * only stdout line (EXT-F-03 step 3; M1-P4 spawn captures it).
+ */
+const USAGE = "usage: tiphys pool <create --task <id> --project <path> [--offline] | " +
+    "list | destroy --task <id> [--discard] [--delete-branch-force]>";
+function usageError(message) {
+    if (message !== undefined) {
+        process.stderr.write(`tiphys pool: ${message}\n`);
+    }
+    process.stderr.write(`${USAGE}\n`);
+    return EX_USAGE;
+}
+function parseFlags(rest) {
+    const parsed = {
+        task: undefined,
+        project: undefined,
+        offline: false,
+        discard: false,
+        deleteBranchForce: false,
+    };
+    for (let i = 0; i < rest.length; i += 1) {
+        const flag = rest[i];
+        if (flag === "--task" && i + 1 < rest.length) {
+            parsed.task = rest[i + 1];
+            i += 1;
+        }
+        else if (flag === "--project" && i + 1 < rest.length) {
+            parsed.project = rest[i + 1];
+            i += 1;
+        }
+        else if (flag === "--offline") {
+            parsed.offline = true;
+        }
+        else if (flag === "--discard") {
+            parsed.discard = true;
+        }
+        else if (flag === "--delete-branch-force") {
+            parsed.deleteBranchForce = true;
+        }
+        else {
+            return undefined;
+        }
+    }
+    return parsed;
+}
+export async function cmdPool(args) {
+    const [subcommand, ...rest] = args;
+    if (subcommand === undefined) {
+        return usageError();
+    }
+    const flags = parseFlags(rest);
+    if (flags === undefined) {
+        return usageError();
+    }
+    let fleet;
+    try {
+        fleet = loadFleet(process.cwd());
+    }
+    catch (error) {
+        process.stderr.write(`tiphys pool: ${error.message}\n`);
+        return 1;
+    }
+    switch (subcommand) {
+        case "create": {
+            if (flags.task === undefined ||
+                flags.project === undefined ||
+                flags.discard ||
+                flags.deleteBranchForce) {
+                return usageError("create requires --task <id> and --project <path>");
+            }
+            const result = await poolCreate(fleet, {
+                taskId: flags.task,
+                project: flags.project,
+                offline: flags.offline,
+            });
+            if (!result.ok) {
+                process.stderr.write(`tiphys pool: ${result.reason}\n`);
+                return 1;
+            }
+            process.stdout.write(`${result.value.baseSha}\n`);
+            return 0;
+        }
+        case "list": {
+            if (flags.task !== undefined ||
+                flags.project !== undefined ||
+                flags.offline ||
+                flags.discard ||
+                flags.deleteBranchForce) {
+                return usageError("list takes no flags");
+            }
+            for (const entry of poolList(fleet)) {
+                process.stdout.write(`${entry.taskId} ${entry.headSha}\n`);
+            }
+            return 0;
+        }
+        case "destroy": {
+            if (flags.task === undefined || flags.project !== undefined || flags.offline) {
+                return usageError("destroy requires --task <id>");
+            }
+            const result = await poolDestroy(fleet, {
+                taskId: flags.task,
+                discard: flags.discard,
+                deleteBranchForce: flags.deleteBranchForce,
+            });
+            if (!result.ok) {
+                process.stderr.write(`tiphys pool: ${result.reason}\n`);
+                return 1;
+            }
+            // Name the deleted branch and its tip on success: that sha is the
+            // operator's only recovery handle if the destroy was a mistake
+            // (V-1), and it stays valid until the clone is garbage collected.
+            const { deletedBranch, deletedSha } = result.value;
+            const suffix = deletedBranch === undefined
+                ? ""
+                : ` (deleted branch ${deletedBranch} was ${deletedSha ?? "unknown"})`;
+            process.stdout.write(`destroyed ${flags.task}${suffix}\n`);
+            return 0;
+        }
+        default:
+            return usageError(`unknown pool subcommand "${subcommand}"`);
+    }
+}

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

@@ -0,0 +1 @@
+export declare function cmdSpawn(args: string[]): Promise<number>;