@latysh-development/monolith 0.0.0-stage → 0.1.0-alpha.1

package/dist/cli/ui.js

@@ -0,0 +1,180 @@
+/* eslint-disable no-console */
+/**
+ * `monolith ui` — launches Mission Control (ADR-010) for the project in the
+ * current directory.
+ *
+ *   monolith ui       production: the built UI (dist/ui) and the read-only API on
+ *                     one loopback port. No Vite, no devDependencies.
+ *   monolith ui dev   development: the same API on a free loopback port plus a
+ *                     Vite dev server (HMR) that proxies /api/dashboard to it.
+ *
+ * Nothing here writes to the project, runs project code or opens a browser.
+ * Expected user errors are one line on stderr and exit code 1, never a stack.
+ */
+import { spawn } from 'child_process';
+import { existsSync, lstatSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { startDashboardServer, loadUiAssets, UiAssetsError } from '../http/index.js';
+import { RootContainmentError, resolveMonolithRoot } from '../root/index.js';
+import { DEFAULT_DEV_UI_PORT, DEFAULT_UI_PORT, UI_DEV_USAGE, UI_USAGE, parseUiArgs } from './ui-args.js';
+/** Thrown for expected, user-fixable failures. */
+export class UiLaunchError extends Error {
+}
+const moduleDir = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_UI_DIR = resolve(moduleDir, '..', 'ui');
+const DEFAULT_PACKAGE_ROOT = resolve(moduleDir, '..', '..');
+/** The project must be a MONOLITH instance: contained `monolithRoot` that exists as a real directory. */
+export function assertMonolithProject(projectRoot) {
+    let rootAbs;
+    try {
+        rootAbs = resolveMonolithRoot(projectRoot).rootAbs;
+    }
+    catch (err) {
+        if (err instanceof RootContainmentError) {
+            throw new UiLaunchError(`Not a usable MONOLITH project: ${err.message}`);
+        }
+        throw new UiLaunchError(`Cannot inspect the project at ${projectRoot}.`);
+    }
+    let isDir = false;
+    try {
+        isDir = lstatSync(rootAbs).isDirectory();
+    }
+    catch {
+        // reported below
+    }
+    if (!isDir) {
+        throw new UiLaunchError(`No MONOLITH instance found in ${projectRoot} (expected directory ${rootAbs}). Run 'monolith init' here, or cd into a MONOLITH project.`);
+    }
+}
+async function listen(projectRoot, port, assets) {
+    try {
+        return await startDashboardServer({ projectRoot, port, assets });
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'EADDRINUSE') {
+            throw new UiLaunchError(`Port ${port} is already in use. Choose another with --port N.`);
+        }
+        if (code === 'EACCES') {
+            throw new UiLaunchError(`Not permitted to listen on port ${port}. Choose another with --port N.`);
+        }
+        throw new UiLaunchError(`Could not start the server: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+export async function launchUi(opts) {
+    const projectRoot = resolve(opts.projectRoot ?? process.cwd());
+    const log = opts.log ?? ((line) => console.log(line));
+    assertMonolithProject(projectRoot);
+    let assets;
+    try {
+        assets = loadUiAssets(opts.uiDir ?? DEFAULT_UI_DIR);
+    }
+    catch (err) {
+        if (err instanceof UiAssetsError) {
+            throw new UiLaunchError(`Mission Control UI build is not usable: ${err.message} Reinstall the package, or run 'pnpm build:ui' in a source checkout.`);
+        }
+        throw err;
+    }
+    const server = await listen(projectRoot, opts.port, assets);
+    log(`MONOLITH Mission Control: ${server.url}`);
+    log(`Project: ${projectRoot}`);
+    log('Read-only. Listening on 127.0.0.1 only. Press Ctrl+C to stop.');
+    return {
+        url: server.url,
+        stop: () => server.close(),
+        ended: new Promise(() => undefined),
+    };
+}
+export async function launchUiDev(opts) {
+    const projectRoot = resolve(opts.projectRoot ?? process.cwd());
+    const packageRoot = opts.packageRoot ?? DEFAULT_PACKAGE_ROOT;
+    const log = opts.log ?? ((line) => console.log(line));
+    assertMonolithProject(projectRoot);
+    const viteBin = join(packageRoot, 'node_modules', 'vite', 'bin', 'vite.js');
+    const viteConfig = join(packageRoot, 'ui', 'vite.config.ts');
+    if (!existsSync(viteConfig) || !existsSync(viteBin)) {
+        throw new UiLaunchError("'monolith ui dev' needs a source checkout of MONOLITH with devDependencies installed (ui/ and vite were not found). Use 'monolith ui' for the built interface.");
+    }
+    // The API takes any free port; Vite is told where it is through the env var its config reads.
+    const api = await listen(projectRoot, 0);
+    const child = spawn(process.execPath, [viteBin, '--config', viteConfig, '--host', '127.0.0.1', '--port', String(opts.port), '--strictPort'], { stdio: 'inherit', env: { ...process.env, MONOLITH_API_PORT: String(api.port) } });
+    let childExited = false;
+    const exited = new Promise((resolveExit) => {
+        child.once('exit', (code, signal) => {
+            childExited = true;
+            resolveExit(code ?? (signal === null ? 1 : 0));
+        });
+        child.once('error', () => {
+            childExited = true;
+            resolveExit(1);
+        });
+    });
+    let stopping = null;
+    const stop = () => {
+        stopping ??= (async () => {
+            if (!childExited)
+                child.kill('SIGTERM');
+            await exited;
+            await api.close();
+        })();
+        return stopping;
+    };
+    const ended = exited.then(async (code) => {
+        await stop();
+        return code;
+    });
+    log(`MONOLITH Mission Control (dev, HMR): http://127.0.0.1:${opts.port}`);
+    log(`Project: ${projectRoot}  (dashboard API on ${api.url}, read-only)`);
+    log('Listening on 127.0.0.1 only. Press Ctrl+C to stop.');
+    return { url: `http://127.0.0.1:${opts.port}`, stop, ended };
+}
+/** CLI entry for `monolith ui ...`. Resolves with the process exit code once the launch has ended. */
+export async function runUi(args) {
+    const parsed = parseUiArgs(args);
+    if (!parsed.ok) {
+        console.error(`${parsed.message}\n\n${UI_USAGE}`);
+        return 1;
+    }
+    if (parsed.help) {
+        console.log(parsed.dev ? UI_DEV_USAGE : UI_USAGE);
+        return 0;
+    }
+    // Handlers go in before anything starts listening, so a signal that arrives right after the
+    // "listening" line can never hit the default action (killed by signal, exit code null).
+    let handle = null;
+    let signalled = false;
+    let finish = () => undefined;
+    const result = new Promise((resolveCode) => {
+        let done = false;
+        finish = (code) => {
+            if (done)
+                return;
+            done = true;
+            resolveCode(code);
+        };
+    });
+    const onSignal = () => {
+        signalled = true;
+        if (handle !== null)
+            void handle.stop().then(() => finish(0), () => finish(1));
+    };
+    process.once('SIGINT', onSignal);
+    process.once('SIGTERM', onSignal);
+    try {
+        handle = parsed.dev
+            ? await launchUiDev({ port: parsed.port ?? DEFAULT_DEV_UI_PORT })
+            : await launchUi({ port: parsed.port ?? DEFAULT_UI_PORT });
+    }
+    catch (err) {
+        if (err instanceof UiLaunchError) {
+            console.error(err.message);
+            return 1;
+        }
+        throw err;
+    }
+    void handle.ended.then(finish);
+    if (signalled)
+        onSignal();
+    return result;
+}

package/dist/coordinatorium/checkpoint.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Tactical Coordinatorium — Mission Checkpoints (COORDINATORIUM-002).
+ *
+ * A Checkpoint is a durable, append-only progress note belonging to exactly
+ * one Mission. This module owns checkpoint semantics (ID generation,
+ * validation, the "only an active mission may be checkpointed" rule) —
+ * state-keeper.ts owns persistence and schema shape, exactly mirroring the
+ * mission.ts / state-keeper.ts split established in ADR-008.
+ *
+ * API surface is deliberately append-only: `createCheckpoint`,
+ * `listCheckpoints`, `getCheckpoint`. There is no update or delete path —
+ * once written, a checkpoint record never changes.
+ */
+import { type StateReadTarget, type StateWriteTarget } from './state-keeper.js';
+import type { Checkpoint } from './types.js';
+export interface CreateCheckpointInput {
+    summary: string;
+    remainingSteps?: string[];
+    context?: string | null;
+}
+/**
+ * Append a checkpoint to an existing, in_progress mission. Validation
+ * happens before the lock is taken (pure input checks); the
+ * mission-existence check, the active-status check, and the ID derivation
+ * all happen inside the same mutateState critical section as the write, so
+ * two concurrent calls for the same mission can never collide on an ID or
+ * lose an update — a direct consequence of reusing mutateState, not new
+ * concurrency design.
+ */
+export declare function createCheckpoint(target: StateWriteTarget, missionId: string, input: CreateCheckpointInput): Promise<Checkpoint>;
+/**
+ * List a mission's checkpoints, oldest first. Never throws for an unknown
+ * or checkpoint-less mission — returns `[]`, consistent with a purely
+ * read-side filter over tactical.checkpoints (mirrors listMissions's
+ * "no missions yet" behavior). Remains available for a finished mission —
+ * only *creation* is gated on mission status.
+ */
+export declare function listCheckpoints(target: StateReadTarget, missionId: string): Promise<Checkpoint[]>;
+/**
+ * Fetch a single checkpoint by id, regardless of its mission's current
+ * status — reading history never stops working for a finished mission.
+ */
+export declare function getCheckpoint(target: StateReadTarget, id: string): Promise<Checkpoint>;
+//# sourceMappingURL=checkpoint.d.ts.map

package/dist/coordinatorium/checkpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.d.ts","sourceRoot":"","sources":["../../src/coordinatorium/checkpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAA0B,KAAK,eAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAExG,OAAO,KAAK,EAAuB,UAAU,EAAE,MAAM,YAAY,CAAC;AA8ClE,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,gBAAgB,EACxB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,qBAAqB,GAC3B,OAAO,CAAC,UAAU,CAAC,CAwCrB;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAKvG;AAED;;;GAGG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,eAAe,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAK5F"}

package/dist/coordinatorium/checkpoint.js

@@ -0,0 +1,124 @@
+/**
+ * Tactical Coordinatorium — Mission Checkpoints (COORDINATORIUM-002).
+ *
+ * A Checkpoint is a durable, append-only progress note belonging to exactly
+ * one Mission. This module owns checkpoint semantics (ID generation,
+ * validation, the "only an active mission may be checkpointed" rule) —
+ * state-keeper.ts owns persistence and schema shape, exactly mirroring the
+ * mission.ts / state-keeper.ts split established in ADR-008.
+ *
+ * API surface is deliberately append-only: `createCheckpoint`,
+ * `listCheckpoints`, `getCheckpoint`. There is no update or delete path —
+ * once written, a checkpoint record never changes.
+ */
+import { mutateState, readState } from './state-keeper.js';
+import { MissionNotFoundError, MissionNotActiveError, CheckpointNotFoundError, ValidationError } from './errors.js';
+// `context` must not become an unbounded free-form blob (explicit
+// requirement for this story) — every text field carries an explicit upper
+// bound, enforced here at creation time. These are generous for a human/AI
+// progress note but not unbounded.
+const MAX_SUMMARY_LENGTH = 4000;
+const MAX_CONTEXT_LENGTH = 4000;
+const MAX_REMAINING_STEP_LENGTH = 500;
+const MAX_REMAINING_STEPS = 50;
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function requireBoundedString(value, field, maxLength) {
+    if (typeof value !== 'string') {
+        throw new ValidationError(`"${field}" must be a string`);
+    }
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        throw new ValidationError(`"${field}" must be a non-empty string`);
+    }
+    if (trimmed.length > maxLength) {
+        throw new ValidationError(`"${field}" must be at most ${maxLength} characters (got ${trimmed.length})`);
+    }
+    return trimmed;
+}
+/**
+ * Derive the next per-mission checkpoint ordinal by scanning existing
+ * checkpoint IDs for the given mission, inside the caller's locked
+ * mutateState section — same pattern, same rationale, as mission.ts's
+ * nextMissionId: no separate counter field, one source of truth, computed
+ * atomically with the write so concurrent creators can never collide.
+ */
+function nextCheckpointId(checkpoints, missionId) {
+    const re = new RegExp(`^${escapeRegExp(missionId)}-CKPT-(\\d+)$`);
+    let max = 0;
+    for (const id of Object.keys(checkpoints)) {
+        const match = re.exec(id);
+        if (match)
+            max = Math.max(max, Number(match[1]));
+    }
+    return `${missionId}-CKPT-${String(max + 1).padStart(4, '0')}`;
+}
+/**
+ * Append a checkpoint to an existing, in_progress mission. Validation
+ * happens before the lock is taken (pure input checks); the
+ * mission-existence check, the active-status check, and the ID derivation
+ * all happen inside the same mutateState critical section as the write, so
+ * two concurrent calls for the same mission can never collide on an ID or
+ * lose an update — a direct consequence of reusing mutateState, not new
+ * concurrency design.
+ */
+export async function createCheckpoint(target, missionId, input) {
+    const summary = requireBoundedString(input.summary, 'summary', MAX_SUMMARY_LENGTH);
+    const remainingStepsRaw = input.remainingSteps ?? [];
+    if (!Array.isArray(remainingStepsRaw)) {
+        throw new ValidationError('"remainingSteps" must be an array of strings');
+    }
+    if (remainingStepsRaw.length > MAX_REMAINING_STEPS) {
+        throw new ValidationError(`"remainingSteps" must contain at most ${MAX_REMAINING_STEPS} items`);
+    }
+    const remainingSteps = remainingStepsRaw.map((s, i) => requireBoundedString(s, `remainingSteps[${i}]`, MAX_REMAINING_STEP_LENGTH));
+    let context = null;
+    if (input.context !== undefined && input.context !== null) {
+        context = requireBoundedString(input.context, 'context', MAX_CONTEXT_LENGTH);
+    }
+    const { result } = await mutateState(target, (draft) => {
+        const mission = draft.tactical.missions[missionId];
+        if (!mission)
+            throw new MissionNotFoundError(missionId);
+        if (mission.status !== 'in_progress') {
+            throw new MissionNotActiveError(missionId, mission.status);
+        }
+        const id = nextCheckpointId(draft.tactical.checkpoints, missionId);
+        const checkpoint = {
+            id,
+            missionId,
+            createdAt: new Date().toISOString(),
+            summary,
+            remainingSteps,
+            context,
+        };
+        draft.tactical.checkpoints[id] = checkpoint;
+        return checkpoint;
+    });
+    return result;
+}
+/**
+ * List a mission's checkpoints, oldest first. Never throws for an unknown
+ * or checkpoint-less mission — returns `[]`, consistent with a purely
+ * read-side filter over tactical.checkpoints (mirrors listMissions's
+ * "no missions yet" behavior). Remains available for a finished mission —
+ * only *creation* is gated on mission status.
+ */
+export async function listCheckpoints(target, missionId) {
+    const state = await readState(target);
+    return Object.values(state.tactical.checkpoints)
+        .filter((c) => c.missionId === missionId)
+        .sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id));
+}
+/**
+ * Fetch a single checkpoint by id, regardless of its mission's current
+ * status — reading history never stops working for a finished mission.
+ */
+export async function getCheckpoint(target, id) {
+    const state = await readState(target);
+    const checkpoint = state.tactical.checkpoints[id];
+    if (!checkpoint)
+        throw new CheckpointNotFoundError(id);
+    return checkpoint;
+}

package/dist/coordinatorium/cli.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `monolith mission ...` command handlers.
+ *
+ * Thin layer: parses flags, resolves the instance's state directory, calls
+ * into mission.ts, and formats output. All lifecycle/validation logic lives
+ * in mission.ts.
+ */
+import { SafeWriteError } from '../root/index.js';
+import { LockCreationError } from './errors.js';
+/**
+ * A write whose outcome is UNKNOWN (SEC-001B.2) was NOT retried and nothing was
+ * cleaned up. The wrapper keeps the machine-readable fields of the original
+ * error (`code`, `publication`, `phase`, `path`) and the error itself as
+ * `cause`; only the message gains guidance, which depends on WHAT is unknown:
+ *
+ *  - `state`: `state.json` may or may not have been replaced. Look at the
+ *    missions before repeating a command that is not idempotent (a second
+ *    `start` would register a second mission).
+ *  - `lock`: it is the creation of the lock file that is unknown; no state was
+ *    written. The mission list says nothing about it — inspect the lock and its
+ *    staging files, and remove nothing while another command may be running.
+ */
+export declare class UnknownWriteOutcomeError extends Error {
+    readonly code: string;
+    readonly publication: "UNKNOWN";
+    readonly phase: string;
+    readonly path: string;
+    readonly subject: 'state' | 'lock';
+    readonly cause: unknown;
+    constructor(original: SafeWriteError | LockCreationError);
+}
+export declare function withWriteGuidance<T>(run: () => Promise<T>): Promise<T>;
+export declare function runMissionStart(args: string[], targetDir?: string): Promise<void>;
+export declare function runMissionList(_args: string[], targetDir?: string): Promise<void>;
+export declare function runMissionShow(args: string[], targetDir?: string): Promise<void>;
+export declare function runMissionCheckpoint(args: string[], targetDir?: string): Promise<void>;
+export declare function runMissionCheckpoints(args: string[], targetDir?: string): Promise<void>;
+export declare function runMissionFinish(args: string[], targetDir?: string): Promise<void>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/coordinatorium/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/coordinatorium/cli.ts"],"names":[],"mappings":"AACA;;;;;;GAMG;AAEH,OAAO,EAAgE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAChH,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAwBhD;;;;;;;;;;;;GAYG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAG,SAAS,CAAU;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;gBAEZ,QAAQ,EAAE,cAAc,GAAG,iBAAiB;CAiBzD;AAED,wBAAsB,iBAAiB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAS5E;AA8BD,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAS9F;AAED,wBAAsB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAsB9F;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAO7F;AAeD,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmBnG;AAED,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAepG;AAED,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAe/F"}

package/dist/coordinatorium/cli.js

@@ -0,0 +1,203 @@
+/* eslint-disable no-console */
+/**
+ * `monolith mission ...` command handlers.
+ *
+ * Thin layer: parses flags, resolves the instance's state directory, calls
+ * into mission.ts, and formats output. All lifecycle/validation logic lives
+ * in mission.ts.
+ */
+import { resolveMonolithRoot, assertContainedFile, reportWriteWarning, SafeWriteError } from '../root/index.js';
+import { LockCreationError } from './errors.js';
+import { STATE_FILE_NAME, projectTarget } from './state-keeper.js';
+import { startMission, listMissions, getMission, finishMission } from './mission.js';
+import { createCheckpoint, listCheckpoints } from './checkpoint.js';
+// Reads use the same PROJECT scope as writes (SEC-001B.1-R): the project root is
+// the explicit boundary, so a symlink anywhere below it is refused.
+function readTargetFor(targetDir) {
+    const root = resolveMonolithRoot(targetDir);
+    assertContainedFile(root, STATE_FILE_NAME);
+    return projectTarget(root.projectRoot, root.rootAbs);
+}
+// Writes always use PROJECT scope (ADR-012): the project root is the boundary,
+// so a symlinked `monolithRoot` or intermediate directory is refused even when
+// it stays inside the project.
+function writeTargetFor(targetDir) {
+    const root = resolveMonolithRoot(targetDir);
+    assertContainedFile(root, STATE_FILE_NAME);
+    assertContainedFile(root, `${STATE_FILE_NAME}.lock`);
+    return projectTarget(root.projectRoot, root.rootAbs, (w) => reportWriteWarning(w));
+}
+/**
+ * A write whose outcome is UNKNOWN (SEC-001B.2) was NOT retried and nothing was
+ * cleaned up. The wrapper keeps the machine-readable fields of the original
+ * error (`code`, `publication`, `phase`, `path`) and the error itself as
+ * `cause`; only the message gains guidance, which depends on WHAT is unknown:
+ *
+ *  - `state`: `state.json` may or may not have been replaced. Look at the
+ *    missions before repeating a command that is not idempotent (a second
+ *    `start` would register a second mission).
+ *  - `lock`: it is the creation of the lock file that is unknown; no state was
+ *    written. The mission list says nothing about it — inspect the lock and its
+ *    staging files, and remove nothing while another command may be running.
+ */
+export class UnknownWriteOutcomeError extends Error {
+    code;
+    publication = 'UNKNOWN';
+    phase;
+    path;
+    subject;
+    cause;
+    constructor(original) {
+        const lock = original instanceof LockCreationError;
+        const guidance = lock
+            ? `The outcome of creating the lock is UNKNOWN. It was not retried and nothing was removed; no state was written. ` +
+                `Inspect, read-only, "${original.lockPath}" and any "${original.lockPath}.creating.*" or "${original.lockPath}.recovery" ` +
+                'next to it. MONOLITH never deletes these automatically (FS-CLEAN-001); remove nothing while another monolith ' +
+                'command may be running.'
+            : 'The outcome of this write is UNKNOWN. It was not retried. Check the current state with ' +
+                '`monolith mission list` (and `monolith mission show <id>`) before running this command again.';
+        super(`${original.message}\n${guidance}`);
+        this.name = 'UnknownWriteOutcomeError';
+        this.code = original.code;
+        this.phase = original.phase;
+        this.path = lock ? original.lockPath : original.path;
+        this.subject = lock ? 'lock' : 'state';
+        this.cause = original;
+    }
+}
+export async function withWriteGuidance(run) {
+    try {
+        return await run();
+    }
+    catch (err) {
+        if ((err instanceof SafeWriteError || err instanceof LockCreationError) && err.publication === 'UNKNOWN') {
+            throw new UnknownWriteOutcomeError(err);
+        }
+        throw err;
+    }
+}
+function parseFlag(args, name) {
+    const i = args.indexOf(name);
+    if (i === -1 || i === args.length - 1)
+        return undefined;
+    return args[i + 1];
+}
+/** Like parseFlag, but collects every occurrence (e.g. repeated `--remaining`). */
+function parseRepeatedFlag(args, name) {
+    const values = [];
+    for (let i = 0; i < args.length - 1; i++) {
+        if (args[i] === name)
+            values.push(args[i + 1]);
+    }
+    return values;
+}
+function formatMission(m) {
+    const lines = [
+        `  id:         ${m.id}`,
+        `  title:      ${m.title}`,
+        `  system:     ${m.system}`,
+        `  status:     ${m.status}`,
+        `  startedAt:  ${m.startedAt}`,
+        `  updatedAt:  ${m.updatedAt}`,
+        `  summary:    ${m.summary ?? '(none)'}`,
+    ];
+    return lines.join('\n');
+}
+export async function runMissionStart(args, targetDir = process.cwd()) {
+    const title = parseFlag(args, '--title');
+    const system = parseFlag(args, '--system');
+    if (!title || !system) {
+        throw new Error('Usage: monolith mission start --title "..." --system "..."');
+    }
+    const mission = await withWriteGuidance(() => startMission(writeTargetFor(targetDir), { title, system }));
+    console.log(`Started mission ${mission.id} (${mission.status})`);
+    console.log(formatMission(mission));
+}
+export async function runMissionList(_args, targetDir = process.cwd()) {
+    const missions = await listMissions(readTargetFor(targetDir));
+    if (missions.length === 0) {
+        console.log('No missions.');
+        return;
+    }
+    const active = missions.filter((m) => m.status === 'in_progress');
+    const finished = missions.filter((m) => m.status !== 'in_progress');
+    console.log(`Active missions (${active.length}):`);
+    if (active.length === 0)
+        console.log('  (none)');
+    for (const m of active) {
+        console.log(`  ${m.id}  [${m.status}]  ${m.title} (${m.system})`);
+    }
+    console.log('');
+    console.log(`Finished missions (${finished.length}):`);
+    if (finished.length === 0)
+        console.log('  (none)');
+    for (const m of finished) {
+        console.log(`  ${m.id}  [${m.status}]  ${m.title} (${m.system})`);
+    }
+}
+export async function runMissionShow(args, targetDir = process.cwd()) {
+    const id = args[0];
+    if (!id) {
+        throw new Error('Usage: monolith mission show <id>');
+    }
+    const mission = await getMission(readTargetFor(targetDir), id);
+    console.log(formatMission(mission));
+}
+function formatCheckpoint(c) {
+    const lines = [
+        `  id:              ${c.id}`,
+        `  missionId:       ${c.missionId}`,
+        `  createdAt:       ${c.createdAt}`,
+        `  summary:         ${c.summary}`,
+        `  remainingSteps:  ${c.remainingSteps.length === 0 ? '(none)' : ''}`,
+        ...c.remainingSteps.map((s) => `    - ${s}`),
+        `  context:         ${c.context ?? '(none)'}`,
+    ];
+    return lines.join('\n');
+}
+export async function runMissionCheckpoint(args, targetDir = process.cwd()) {
+    const missionId = args[0];
+    const summary = parseFlag(args, '--summary');
+    if (!missionId || !summary) {
+        throw new Error('Usage: monolith mission checkpoint <missionId> --summary "..." [--remaining "..." ...] [--context "..."]');
+    }
+    const remainingSteps = parseRepeatedFlag(args, '--remaining');
+    const context = parseFlag(args, '--context');
+    const checkpoint = await withWriteGuidance(() => createCheckpoint(writeTargetFor(targetDir), missionId, {
+        summary,
+        remainingSteps,
+        context: context ?? null,
+    }));
+    console.log(`Created checkpoint ${checkpoint.id} for mission ${checkpoint.missionId}`);
+    console.log(formatCheckpoint(checkpoint));
+}
+export async function runMissionCheckpoints(args, targetDir = process.cwd()) {
+    const missionId = args[0];
+    if (!missionId) {
+        throw new Error('Usage: monolith mission checkpoints <missionId>');
+    }
+    const checkpoints = await listCheckpoints(readTargetFor(targetDir), missionId);
+    if (checkpoints.length === 0) {
+        console.log(`No checkpoints for mission ${missionId}.`);
+        return;
+    }
+    console.log(`Checkpoints for mission ${missionId} (${checkpoints.length}):`);
+    for (const c of checkpoints) {
+        console.log('');
+        console.log(formatCheckpoint(c));
+    }
+}
+export async function runMissionFinish(args, targetDir = process.cwd()) {
+    const id = args[0];
+    const result = parseFlag(args, '--result');
+    const summary = parseFlag(args, '--summary');
+    if (!id || !result) {
+        throw new Error('Usage: monolith mission finish <id> --result completed|failed|cancelled [--summary "..."]');
+    }
+    const mission = await withWriteGuidance(() => finishMission(writeTargetFor(targetDir), id, {
+        result: result,
+        summary: summary ?? undefined,
+    }));
+    console.log(`Mission ${mission.id} finished as ${mission.status}`);
+    console.log(formatMission(mission));
+}