@tiphys/kernel 0.0.0 → 0.2.0

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,139 @@
+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)) {
+                // M4-P19: an entry whose pool record did not survive a reclaim is
+                // MARKED. The original two-field line is unchanged, so nothing
+                // that reads this output learns a new field it did not ask for,
+                // and a reconstruction can never be read as an original.
+                let marker = "";
+                if (entry.origin === "reconstructed") {
+                    marker = " reconstructed";
+                }
+                else if (entry.origin === "unreconstructable") {
+                    marker = ` unreconstructable (unresolved: ${(entry.unresolved ?? []).join(", ")})`;
+                }
+                process.stdout.write(`${entry.taskId} ${entry.headSha}${marker}\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/resume.d.ts

@@ -0,0 +1 @@
+export declare function cmdResume(args: string[]): number;

package/dist/src/commands/resume.js

@@ -0,0 +1,88 @@
+import { mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { EX_USAGE } from "../cli.js";
+import { EPHEMERAL_DIRS, classifyLayoutEntry, missingDurableEntries, } from "../fleet.js";
+/**
+ * The plan, or the one reason it cannot be made. Deciding every entry BEFORE
+ * creating any of them is what makes criterion 2's "creates nothing" true of
+ * the refusal arms: a refusal discovered halfway through a creating loop has
+ * already changed the tree.
+ */
+function planRebuild(root) {
+    const steps = [];
+    for (const name of EPHEMERAL_DIRS) {
+        const entry = classifyLayoutEntry(join(root, name));
+        if (entry.kind === "directory") {
+            steps.push({ name, rebuild: false });
+            continue;
+        }
+        if (entry.kind === "absent") {
+            steps.push({ name, rebuild: true });
+            continue;
+        }
+        return {
+            refusal: `tiphys resume: ${root} cannot be rehydrated: ${entry.reason}, ` +
+                `and resume never removes anything to make room`,
+        };
+    }
+    return { steps };
+}
+export function cmdResume(args) {
+    const [dir, ...extra] = args;
+    if (extra.length > 0) {
+        process.stderr.write("usage: tiphys resume [dir]\n");
+        return EX_USAGE;
+    }
+    const root = resolve(dir ?? ".");
+    const rootEntry = classifyLayoutEntry(root);
+    if (rootEntry.kind !== "directory") {
+        process.stderr.write(`tiphys resume: ${root} is not a directory, so there is no fleet home here to rebuild\n`);
+        return 1;
+    }
+    /* THE FIRST PRECONDITION: a fleet home is a git repository, and a clone of
+       one is what this command exists to repair. A directory with no `.git` is
+       not a fleet clone whatever else it holds, and creating three directories
+       inside it would be a success report about a fleet that does not exist. */
+    const gitEntry = classifyLayoutEntry(join(root, ".git"));
+    if (gitEntry.kind === "absent") {
+        process.stderr.write(`tiphys resume: ${root} is not a git repository, .git is absent, ` +
+            `so it is not a cloned fleet home; run tiphys init <dir> to create one\n`);
+        return 1;
+    }
+    if (gitEntry.kind === "unexaminable") {
+        process.stderr.write(`tiphys resume: ${gitEntry.reason}\n`);
+        return 1;
+    }
+    /* THE SECOND PRECONDITION, and it is a different failure from the first.
+       A git repository that is not a fleet home (any other clone, including the
+       kernel's own) passes the `.git` test. Rebuilding the ephemeral three
+       inside it would litter a stranger's repository and report success. The
+       durable entries are what a clone of a fleet home carries, so their absence
+       means either "not a fleet home" or "a fleet home that has lost durable
+       content", and resume fabricates NEITHER: durable content comes back from
+       the remote, never from this command. */
+    const missingDurable = missingDurableEntries(root);
+    if (missingDurable.length > 0) {
+        process.stderr.write(`tiphys resume: ${root} is a git repository but not a fleet home, ` +
+            `missing ${missingDurable.join(", ")}; durable content is restored by ` +
+            `fetching from the remote, never by resume\n`);
+        return 1;
+    }
+    const planned = planRebuild(root);
+    if ("refusal" in planned) {
+        process.stderr.write(`${planned.refusal}\n`);
+        return 1;
+    }
+    /* PER ENTRY, never all-or-nothing. An interrupted resume leaves a
+       half-rebuilt layout, and that half is the common case rather than an edge:
+       rebuilding the set because one member is missing is how a live worktree
+       that survived the reclaim gets reported as rebuilt when it was not. */
+    for (const step of planned.steps) {
+        if (!step.rebuild) {
+            continue;
+        }
+        mkdirSync(join(root, step.name));
+        process.stdout.write(`REBUILT ${step.name}/\n`);
+    }
+    return 0;
+}

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

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

package/dist/src/commands/spawn.js

@@ -0,0 +1,195 @@
+import { EX_USAGE } from "../cli.js";
+import { loadFleet } from "../fleet.js";
+import { warnIfWatcherStale } from "../liveness.js";
+import { spawnTask } from "../spawn.js";
+import { singleLine } from "../task.js";
+/**
+ * tiphys spawn --task <id> --project <path> --brief <file> --shape
+ * ship|scout --exec <cmd> [--deadline <seconds>] [--offline]
+ * [--role <name>] [--tier <name>] [--phase <id>] [--adapter <specifier>]
+ * (kernel plan v1, M1-P4 step 4; --role, --tier and --phase added by
+ * M4-P3 and --adapter by M4-P4). Runs in a fleet home (cwd).
+ *
+ * --exec is REQUIRED in M1: spawn without it exits 64 with usage,
+ * because the multiplexer-window adapter that would make an exec-less
+ * spawn meaningful is M4-era work (PR-013). The payload runs to
+ * completion before this command returns (plan constraint C-3: nothing
+ * is auto-backgrounded).
+ *
+ * --offline is passed through to pool create, and is a deviation from
+ * the plan's enumerated flag list, recorded in the M1-P4 work history:
+ * meta.json's baseOffline field (criterion 13 of M1-P3, this phase's
+ * named obligation) can only ever be true for a worktree created under
+ * pool create --offline, and spawn is the only command that creates the
+ * worktree a task's meta describes.
+ */
+const USAGE = "usage: tiphys spawn --task <id> --project <path> --brief <file> " +
+    "--shape ship|scout --exec <cmd> [--deadline <seconds>] [--offline] " +
+    "[--role <name>] [--tier <name>] [--phase <id>] [--adapter <specifier>]";
+function usageError(message) {
+    if (message !== undefined) {
+        process.stderr.write(`tiphys spawn: ${message}\n`);
+    }
+    process.stderr.write(`${USAGE}\n`);
+    return EX_USAGE;
+}
+function parseFlags(args) {
+    const parsed = {
+        task: undefined,
+        project: undefined,
+        brief: undefined,
+        shape: undefined,
+        exec: undefined,
+        deadlineSeconds: undefined,
+        offline: false,
+        role: undefined,
+        tier: undefined,
+        phase: undefined,
+        adapter: undefined,
+    };
+    for (let i = 0; i < args.length; i += 1) {
+        const flag = args[i];
+        const value = args[i + 1];
+        if (flag === "--task" && value !== undefined) {
+            parsed.task = value;
+            i += 1;
+        }
+        else if (flag === "--project" && value !== undefined) {
+            parsed.project = value;
+            i += 1;
+        }
+        else if (flag === "--brief" && value !== undefined) {
+            parsed.brief = value;
+            i += 1;
+        }
+        else if (flag === "--shape" && value !== undefined) {
+            if (value !== "ship" && value !== "scout") {
+                return undefined;
+            }
+            parsed.shape = value;
+            i += 1;
+        }
+        else if (flag === "--exec" && value !== undefined) {
+            parsed.exec = value;
+            i += 1;
+        }
+        else if (flag === "--deadline" && value !== undefined) {
+            const seconds = Number(value);
+            // N-403: finite and positive is not enough. The adapter turns the
+            // deadline into an instant, and any value at or above roughly
+            // 8.64e12 seconds is outside the Date range, so it used to raise
+            // INSIDE the adapter, after pool create had made a worktree, a
+            // branch and a pool record. A deadline this kernel cannot
+            // represent is a usage error, and a usage error creates nothing.
+            if (!Number.isFinite(seconds) ||
+                seconds <= 0 ||
+                !Number.isFinite(new Date(Date.now() + seconds * 1000).getTime())) {
+                return undefined;
+            }
+            parsed.deadlineSeconds = seconds;
+            i += 1;
+        }
+        else if (flag === "--role" && value !== undefined) {
+            parsed.role = value;
+            i += 1;
+        }
+        else if (flag === "--tier" && value !== undefined) {
+            // VERBATIM, and deliberately unvalidated: this is the DECLARED TIER,
+            // whatever role-model-config.yaml declares, and the tier-to-model
+            // mapping lives in the plugin. A kernel that checked this value
+            // against a list would be holding the vocabulary the plugin owns.
+            parsed.tier = value;
+            i += 1;
+        }
+        else if (flag === "--phase" && value !== undefined) {
+            // CARRIED, never derived from the branch name (M4-D-22 is open).
+            parsed.phase = value;
+            i += 1;
+        }
+        else if (flag === "--adapter" && value !== undefined) {
+            // VERBATIM, and it is a MODULE SPECIFIER rather than a path: the
+            // kernel resolves it with Node module resolution rooted at the fleet
+            // home (src/adapters/load.ts), which is the one root that is
+            // owner-controlled. Nothing is checked here, because a check here
+            // would run against this process's own resolution root, which is the
+            // kernel checkout, and that is precisely the root this phase exists to
+            // keep out of the answer.
+            parsed.adapter = value;
+            i += 1;
+        }
+        else if (flag === "--offline") {
+            parsed.offline = true;
+        }
+        else {
+            return undefined;
+        }
+    }
+    return parsed;
+}
+export async function cmdSpawn(args) {
+    const flags = parseFlags(args);
+    if (flags === undefined) {
+        return usageError();
+    }
+    if (flags.task === undefined ||
+        flags.project === undefined ||
+        flags.brief === undefined ||
+        flags.shape === undefined) {
+        return usageError("spawn requires --task <id> --project <path> --brief <file> --shape ship|scout");
+    }
+    if (flags.exec === undefined) {
+        // PR-013: an exec-less spawn has no meaning in M1.
+        return usageError("spawn requires --exec <cmd> in M1");
+    }
+    let fleet;
+    try {
+        fleet = loadFleet(process.cwd());
+    }
+    catch (error) {
+        process.stderr.write(`tiphys spawn: ${singleLine(error.message)}\n`);
+        return 1;
+    }
+    // Liveness guard (M1-P5 step 2), completing the seam this phase left.
+    // It WARNS and never blocks: one stderr line when work is in flight
+    // and supervision has gone quiet, and the command then does exactly
+    // what it would have done anyway (blueprint liveness-guard contract,
+    // criteria 10 and 11).
+    warnIfWatcherStale(fleet);
+    const result = await spawnTask(fleet, {
+        taskId: flags.task,
+        project: flags.project,
+        briefFile: flags.brief,
+        shape: flags.shape,
+        exec: flags.exec,
+        deadlineSeconds: flags.deadlineSeconds,
+        offline: flags.offline,
+        /*
+         * PROJECT, ALWAYS, AND THE CLI HAS NO FLAG TO SAY OTHERWISE (M4-P8
+         * step 2). `tiphys spawn` launches a payload into a project worktree,
+         * and the declared credential escape hatch is not reachable from this
+         * command at all: `allowPrCredentials` is a library-seam field with no
+         * flag behind it, which is exactly why the orchestrator class is not
+         * offered here. An operator who could type --payload-class orchestrator
+         * would be able to ask for the pairing spawnTask exists to refuse.
+         */
+        payloadClass: "project",
+        role: flags.role,
+        declaredTier: flags.tier,
+        phaseId: flags.phase,
+        adapterSpecifier: flags.adapter,
+    });
+    if (!result.ok) {
+        // One reason line, structurally (CR-303): a reason may carry a
+        // raised error message or git output, and an operator or the M1-P6
+        // harness reading "the reason line" must get all of it.
+        process.stderr.write(`tiphys spawn: ${singleLine(result.reason)}\n`);
+        return 1;
+    }
+    // The payload's exit code is reported, not adopted: the task's state
+    // authority is meta.json plus the turn-end record (plan constraint
+    // C-1), and a nonzero payload is a completed task with a failing
+    // payload, not a failed spawn.
+    const { meta, exitCode } = result.value;
+    process.stdout.write(`spawned ${meta.id} worktree ${meta.worktree} exec exited ${String(exitCode)}\n`);
+    return 0;
+}

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

@@ -0,0 +1,21 @@
+/**
+ * `tiphys status <emit | show>` (kernel plan M3, M3-P1 step 6; R-084).
+ *
+ *   tiphys status emit --run <id> --state <state> [--project <name>]
+ *                      [--detail <text>] [--ref <r>]...
+ *   tiphys status show
+ *
+ * Runs in a fleet home (cwd). `emit` composes a record, VALIDATES it against
+ * the shipped `status-line` schema before writing anything, appends one line
+ * to `state/status/stream.jsonl`, then rewrites the DURABLE
+ * `status/current.json` atomically. `show` reads `current.json` ONLY and
+ * never opens the stream (constraint C-1: never read current state from the
+ * tail of an append-only log). The two documents sit on opposite sides of the
+ * fleet `.gitignore` since M4-D-13, which is why the paths differ in prefix;
+ * src/status.ts carries the reasoning.
+ *
+ * The state vocabulary is closed and is enforced, not requested: `--state
+ * progress` is refused naming the permitted values, because R-084's
+ * sparseness is worth nothing if the emitter accepts whatever it is handed.
+ */
+export declare function cmdStatus(argv: string[]): number;

package/dist/src/commands/status.js

@@ -0,0 +1,122 @@
+/**
+ * `tiphys status <emit | show>` (kernel plan M3, M3-P1 step 6; R-084).
+ *
+ *   tiphys status emit --run <id> --state <state> [--project <name>]
+ *                      [--detail <text>] [--ref <r>]...
+ *   tiphys status show
+ *
+ * Runs in a fleet home (cwd). `emit` composes a record, VALIDATES it against
+ * the shipped `status-line` schema before writing anything, appends one line
+ * to `state/status/stream.jsonl`, then rewrites the DURABLE
+ * `status/current.json` atomically. `show` reads `current.json` ONLY and
+ * never opens the stream (constraint C-1: never read current state from the
+ * tail of an append-only log). The two documents sit on opposite sides of the
+ * fleet `.gitignore` since M4-D-13, which is why the paths differ in prefix;
+ * src/status.ts carries the reasoning.
+ *
+ * The state vocabulary is closed and is enforced, not requested: `--state
+ * progress` is refused naming the permitted values, because R-084's
+ * sparseness is worth nothing if the emitter accepts whatever it is handed.
+ */
+import { basename } from "node:path";
+import { EX_USAGE } from "../cli.js";
+import { loadFleet } from "../fleet.js";
+import { loadTypeSchema } from "./validate.js";
+import { formatDiagnostics, validateInstance } from "../validate.js";
+import { STATUS_STATES, emitStatus, makeStatusRecord, readCurrent, renderStatus, } from "../status.js";
+const USAGE = "usage: tiphys status <emit --run <id> --state <" +
+    STATUS_STATES.join("|") +
+    "> [--project <name>] [--detail <text>] [--ref <r>] | show>";
+function parseEmit(argv) {
+    const args = { refs: [] };
+    for (let index = 0; index < argv.length; index += 1) {
+        const flag = argv[index];
+        const value = argv[index + 1];
+        if (flag !== "--run" &&
+            flag !== "--state" &&
+            flag !== "--project" &&
+            flag !== "--detail" &&
+            flag !== "--ref" &&
+            flag !== "--at") {
+            return { usageError: `unknown option ${flag}` };
+        }
+        if (value === undefined) {
+            return { usageError: `${flag} requires a value` };
+        }
+        index += 1;
+        if (flag === "--run")
+            args.run = value;
+        else if (flag === "--state")
+            args.state = value;
+        else if (flag === "--project")
+            args.project = value;
+        else if (flag === "--detail")
+            args.detail = value;
+        else if (flag === "--at")
+            args.at = value;
+        else
+            args.refs.push(value);
+    }
+    if (args.run === undefined) {
+        return { usageError: "--run is required" };
+    }
+    if (args.state === undefined) {
+        return { usageError: "--state is required" };
+    }
+    return { args };
+}
+export function cmdStatus(argv) {
+    const [subcommand, ...rest] = argv;
+    if (subcommand === "show") {
+        if (rest.length > 0) {
+            process.stderr.write(`tiphys status show: takes no arguments\n${USAGE}\n`);
+            return EX_USAGE;
+        }
+        const fleet = loadFleet(process.cwd());
+        const current = readCurrent(fleet.root);
+        if (!current.ok) {
+            process.stderr.write(`tiphys status show: ${current.reason}\n`);
+            return 1;
+        }
+        process.stdout.write(`${renderStatus(current.record)}\n`);
+        return 0;
+    }
+    if (subcommand !== "emit") {
+        process.stderr.write(`${USAGE}\n`);
+        return EX_USAGE;
+    }
+    const parsed = parseEmit(rest);
+    if (parsed.args === undefined) {
+        process.stderr.write(`tiphys status emit: ${parsed.usageError ?? "usage error"}\n${USAGE}\n`);
+        return EX_USAGE;
+    }
+    const fleet = loadFleet(process.cwd());
+    const record = makeStatusRecord({
+        run: parsed.args.run,
+        project: parsed.args.project ?? basename(fleet.root),
+        state: parsed.args.state,
+        detail: parsed.args.detail,
+        refs: parsed.args.refs,
+        at: parsed.args.at,
+    });
+    /* The record is validated against the SHIPPED schema before anything is
+       written. Validating a composed record against the same document the
+       validator command uses is what makes the closed state vocabulary one
+       rule rather than two: `--state progress` fails here for exactly the
+       reason it would fail `tiphys validate --type status-line`. */
+    const diagnostics = validateInstance(loadTypeSchema("status-line"), record);
+    if (diagnostics.length > 0) {
+        for (const line of formatDiagnostics(diagnostics)) {
+            process.stderr.write(`${line}\n`);
+        }
+        process.stderr.write(`tiphys status emit: the permitted states are ${STATUS_STATES.join(", ")}\n`);
+        return 1;
+    }
+    const emitted = emitStatus(fleet.root, record);
+    if (!emitted.ok) {
+        process.stderr.write(`tiphys status emit: ${emitted.reason}\n`);
+        return 1;
+    }
+    process.stdout.write(`${renderStatus(emitted.record)}\n`);
+    return 0;
+}