@litfamily/litopencode 1.0.17 → 1.0.19

package/dist/cli/install.js

@@ -6,9 +6,9 @@ import { promisify } from "node:util";
 import { createRuntimePaths } from "../state.js";
 import { describeCommandAliasMutation, ensureCommandAliases, inspectCommandAliases } from "./command-aliases.js";
 import { openCodeHostCapabilities } from "./host-capabilities.js";
-import { describeHostLimitMutation, ensureHostLimits } from "./host-limits.js";
-import { assertExistingModelRoutesSafe, describeInstallRoutes, describeLitConfigMutation, ensureLitConfig, readExistingOutputStyle, readInstallModelClassification, readInstallModelSelection, writeTextAtomically } from "./install-config.js";
-import { readJsonObjectIfPresent, readPackageMetadata } from "./json.js";
+import { applyHostLimits, describeHostLimitMutation, ensureHostLimits } from "./host-limits.js";
+import { assertExistingModelRoutesSafe, describeInstallRoutes, describeLitConfigMutation, ensureLitConfig, OpenCodeConfigCommentError, readExistingOutputStyle, readInstallModelClassification, readInstallModelSelection, renderOpenCodeConfig, writeOpenCodeConfig } from "./install-config.js";
+import { readJsonObjectIfPresent, readPackageMetadata, readTextIfPresent } from "./json.js";
 import { renderInstallReport, wrapReceiptLine } from "./install-report.js";
 import { renderLitOpenCodeWordmark } from "./install-tui.js";
 import { promptModelSelection, promptOutputStyle, promptPermissionMode } from "./model-routing.js";
@@ -16,6 +16,7 @@ import { litOpenCodeConfigFileForOpenCodeRoot } from "../state.js";
 import { describeNativeSkillMutation, ensureNativeSkills, inspectNativeSkills } from "./native-skills.js";
 import { applyPluginMutation, describePluginMutation, isLitOpenCodeEntry } from "./plugin-mutation.js";
 import { prewarmMotionRuntime } from "./motion-runtime.js";
+import { applyTuiWrites, backupTuiFiles, inspectTuiPlugin, planTuiInstall } from "./tui-config.js";
 const execFileAsync = promisify(execFile);
 function withProgress(progress, label, task) {
     return progress === undefined ? task() : progress.run(label, task);
@@ -118,29 +119,72 @@ async function installWithOpenCode(target) {
         throw new Error("OpenCode plugin install failed for " + target.label + (detail ? ":\n" + detail : ""));
     }
 }
+async function normalizedPluginEntries(root, target, pluginValue) {
+    const nextPlugin = [];
+    let registered = false;
+    for (const entry of pluginValue) {
+        const id = Array.isArray(entry) ? entry[0] : entry;
+        if (id === target.value || isLitOpenCodeEntry(entry) || (await isLitOpenCodePathEntry(root, id))) {
+            if (!registered)
+                nextPlugin.push(Array.isArray(entry) ? [target.value, ...entry.slice(1)] : target.value);
+            registered = true;
+        }
+        else {
+            nextPlugin.push(entry);
+        }
+    }
+    return nextPlugin;
+}
 async function normalizeOpenCodeEntries(root, target) {
     for (const configFile of openCodeConfigCandidates(root)) {
         const config = await readJsonObjectIfPresent(configFile);
         const pluginValue = config?.plugin;
         if (!Array.isArray(pluginValue))
             continue;
-        const nextPlugin = [];
-        let registered = false;
-        for (const entry of pluginValue) {
-            const id = Array.isArray(entry) ? entry[0] : entry;
-            if (id === target.value || isLitOpenCodeEntry(entry) || (await isLitOpenCodePathEntry(root, id))) {
-                if (!registered)
-                    nextPlugin.push(Array.isArray(entry) ? [target.value, ...entry.slice(1)] : target.value);
-                registered = true;
-            }
-            else {
-                nextPlugin.push(entry);
-            }
-        }
+        const nextPlugin = await normalizedPluginEntries(root, target, pluginValue);
         if (JSON.stringify(nextPlugin) === JSON.stringify(pluginValue))
             continue;
-        await writeTextAtomically(configFile, JSON.stringify({ ...config, plugin: nextPlugin }, null, 2) + "\n");
+        await writeOpenCodeConfig(configFile, { ...config, plugin: nextPlugin });
+    }
+}
+// Works out every OpenCode config edit the install will make before anything is written, and returns
+// the refusal when one of them would delete a user comment. On the default root OpenCode registers the
+// plugin itself; LitOpenCode then only cleans up stale entries and sets host limits.
+async function commentLossRefusal(root, configFile, target, before, mutation, reconfigureHostLimits, useOpenCodeInstaller) {
+    const planned = [];
+    if (!useOpenCodeInstaller) {
+        const next = applyPluginMutation(before, mutation, target.value);
+        planned.push({ file: configFile, next: reconfigureHostLimits ? applyHostLimits(next) : next });
+    }
+    else {
+        for (const file of openCodeConfigCandidates(root)) {
+            const config = file === configFile ? before : await readJsonObjectIfPresent(file);
+            let next = config;
+            const pluginValue = config?.plugin;
+            if (config !== null && Array.isArray(pluginValue)) {
+                const registered = file === configFile &&
+                    !pluginValue.some((entry) => (Array.isArray(entry) ? entry[0] : entry) === target.value)
+                    ? [...pluginValue, target.value]
+                    : pluginValue;
+                const normalized = await normalizedPluginEntries(root, target, registered);
+                if (JSON.stringify(normalized) !== JSON.stringify(registered))
+                    next = { ...config, plugin: normalized };
+            }
+            planned.push({ file, next: file === configFile && reconfigureHostLimits ? applyHostLimits(next) : next });
+        }
+    }
+    try {
+        for (const { file, next } of planned) {
+            if (next !== null)
+                renderOpenCodeConfig(file, await readTextIfPresent(file), next);
+        }
     }
+    catch (error) {
+        if (error instanceof OpenCodeConfigCommentError)
+            return error.message;
+        throw error;
+    }
+    return undefined;
 }
 async function verifyInstalledSurfaces(root, configFile, target, metadata, selectedModel, selectedPermissionMode, selectedPermissionExplicit, selectedOutputStyle) {
     const config = await readJsonObjectIfPresent(configFile);
@@ -151,9 +195,12 @@ async function verifyInstalledSurfaces(root, configFile, target, metadata, selec
     const litConfig = await describeLitConfigMutation(root, selectedModel, selectedPermissionMode, selectedPermissionExplicit, selectedOutputStyle);
     const commandAliases = await inspectCommandAliases(root);
     const nativeSkills = await inspectNativeSkills(root, metadata);
+    const tui = await inspectTuiPlugin(root, target.value);
     const failures = [];
     if (targetCount !== 1 || staleLitEntries.length > 0)
         failures.push("plugin registration");
+    if (!tui.ok)
+        failures.push("TUI plugin registration in " + tui.path);
     if (litConfig.changed)
         failures.push("LitOpenCode routes");
     if (!commandAliases.ok)
@@ -202,12 +249,14 @@ export async function install(root, dryRun, modelSelection = undefined, modelPro
             commandAliases: await describeCommandAliasMutation(root),
             nativeSkills: await describeNativeSkillMutation(root, metadata),
             hostLimits: describeHostLimitMutation(before, selectedModel !== undefined),
+            tui: await planTuiInstall(root, resolved.target.value),
             routes: dryRun
                 ? await describeInstallRoutes(root, before, selectedModel, selectedPermissionMode, selectedPermissionExplicit, selectedOutputStyle)
                 : undefined
         };
     });
-    const { configFile, before, mutation, litopencodeConfig, commandAliases, nativeSkills, hostLimits, routes } = inspected;
+    const { configFile, before, mutation, litopencodeConfig, commandAliases, nativeSkills, hostLimits, routes, tui } = inspected;
+    const blocked = (await commentLossRefusal(root, configFile, resolved.target, before, mutation, hostLimits.reconfigure, resolved.useOpenCodeInstaller)) ?? tui.blocked;
     const report = {
         dryRun,
         path: configFile,
@@ -215,20 +264,28 @@ export async function install(root, dryRun, modelSelection = undefined, modelPro
         plugin: mutation.plugin,
         commandAliases,
         nativeSkills,
+        tui: tui.report,
         patch: mutation.patch,
-        changed: mutation.changed || litopencodeConfig.changed || commandAliases.changed || nativeSkills.changed || hostLimits.changed,
+        changed: mutation.changed || litopencodeConfig.changed || commandAliases.changed || nativeSkills.changed || hostLimits.changed || tui.report.changed,
+        ...(blocked === undefined ? {} : { blocked }),
         routes,
         hostLimits: { path: configFile, ...hostLimits },
         capabilities: openCodeHostCapabilities(),
         package: { name: metadata.name, version: metadata.version }
     };
     if (dryRun) {
-        return { exitCode: 0, stdout: JSON.stringify(report, null, 2) };
+        return {
+            exitCode: blocked === undefined ? 0 : 1,
+            stdout: JSON.stringify(report, null, 2),
+            ...(blocked === undefined ? {} : { stderr: "ERROR: " + blocked })
+        };
     }
     if (nativeSkills.collisions.length > 0) {
         throw new Error("Native skill collision: refusing to overwrite pre-existing roots without managed entrypoints: " +
             nativeSkills.collisions.join(", "));
     }
+    if (blocked !== undefined)
+        throw new OpenCodeConfigCommentError(blocked);
     await withProgress(activeProgress, "Write litopencode.json", async () => {
         await ensureLitConfig(root, selectedModel, selectedPermissionMode, selectedPermissionExplicit, selectedOutputStyle);
         await ensureNativeSkills(root, metadata);
@@ -236,23 +293,27 @@ export async function install(root, dryRun, modelSelection = undefined, modelPro
     });
     await withProgress(activeProgress, "Register plugin", async () => {
         if (resolved.useOpenCodeInstaller) {
+            // The package's `./tui` export makes `opencode plugin` add the TUI entry itself, so back up
+            // first, then normalize whatever it wrote without a second backup.
+            await backupTuiFiles(tui);
             await installWithOpenCode(resolved.target);
             const installed = await readJsonObjectIfPresent(configFile);
             if (!Array.isArray(installed?.plugin) || !installed.plugin.some((entry) => (Array.isArray(entry) ? entry[0] : entry) === resolved.target.value))
                 throw new Error("OpenCode did not register the requested package target");
             await normalizeOpenCodeEntries(root, resolved.target);
             await ensureHostLimits(configFile, await readJsonObjectIfPresent(configFile), hostLimits.reconfigure);
+            const settled = await planTuiInstall(root, resolved.target.value);
+            if (settled.blocked !== undefined)
+                throw new OpenCodeConfigCommentError(settled.blocked);
+            await applyTuiWrites(settled.writes, { backup: false });
             return;
         }
-        const next = applyPluginMutation(before, mutation, resolved.target.value);
-        if (hostLimits.reconfigure) {
-            await ensureHostLimits(configFile, next, true);
-            return;
-        }
-        if (!mutation.changed)
+        await applyTuiWrites(tui.writes);
+        const withPlugin = applyPluginMutation(before, mutation, resolved.target.value);
+        const next = hostLimits.reconfigure ? applyHostLimits(withPlugin) : withPlugin;
+        if (JSON.stringify(next) === JSON.stringify(before))
             return;
-        await fs.mkdir(path.dirname(configFile), { recursive: true });
-        await writeTextAtomically(configFile, JSON.stringify(next, null, 2) + "\n");
+        await writeOpenCodeConfig(configFile, next);
     });
     await withProgress(activeProgress, "Verify install", async () => verifyInstalledSurfaces(root, configFile, resolved.target, metadata, selectedModel, selectedPermissionMode, selectedPermissionExplicit, selectedOutputStyle));
     await activeProgress?.complete();

package/dist/cli/json.d.ts

@@ -1,4 +1,5 @@
 import type { PackageMetadata } from "./types.ts";
 export declare function isRecord(value: unknown): value is Record<string, unknown>;
 export declare function readPackageMetadata(): Promise<PackageMetadata>;
+export declare function readTextIfPresent(filePath: string): Promise<string | null>;
 export declare function readJsonObjectIfPresent(filePath: string): Promise<Record<string, unknown> | null>;

package/dist/cli/json.js

@@ -1,6 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { parseJsonc } from "./jsonc.js";
 export function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -13,17 +14,22 @@ export async function readPackageMetadata() {
     }
     return { name: parsed.name, version: parsed.version, packageRoot };
 }
-export async function readJsonObjectIfPresent(filePath) {
-    let raw;
+export async function readTextIfPresent(filePath) {
     try {
-        raw = await fs.readFile(filePath, "utf8");
+        return await fs.readFile(filePath, "utf8");
     }
     catch (error) {
         if (error instanceof Error && "code" in error && error.code === "ENOENT")
             return null;
         throw error;
     }
-    const parsed = JSON.parse(raw);
+}
+// OpenCode configs are JSONC, so every reader here accepts comments and trailing commas.
+export async function readJsonObjectIfPresent(filePath) {
+    const raw = await readTextIfPresent(filePath);
+    if (raw === null)
+        return null;
+    const parsed = parseJsonc(raw);
     if (!isRecord(parsed)) {
         throw new Error(`Malformed JSON at ${filePath}: expected an object.`);
     }

package/dist/cli/jsonc.d.ts

@@ -0,0 +1,17 @@
+export type JsoncEdit = {
+    readonly ok: true;
+    readonly text: string;
+} | {
+    readonly ok: false;
+    readonly key: string;
+};
+export declare function lineEnding(text: string): string;
+export declare function parseJsonc(text: string): unknown;
+export declare function hasJsoncComments(text: string): boolean;
+export declare function formatJsoncMember(key: string, value: unknown, eol?: string): string;
+/**
+ * Rewrites only the top-level entries of `text` whose value differs from `next`, leaving every other
+ * byte (comments, a leading BOM and the line ending included) in place. Refuses, naming the entry,
+ * when an edited value holds a comment or when an entry would have to be removed.
+ */
+export declare function editJsoncObject(text: string, next: Record<string, unknown>): JsoncEdit;

package/dist/cli/jsonc.js

@@ -0,0 +1,174 @@
+// OpenCode reads its config as JSONC (line and block comments, trailing commas). Comments are blanked
+// in place, keeping every offset, so structure found in the blanked copy addresses the original text.
+function stringEnd(text, start) {
+    let index = start + 1;
+    while (index < text.length) {
+        if (text[index] === "\\")
+            index += 2;
+        else if (text[index] === '"')
+            return index + 1;
+        else
+            index += 1;
+    }
+    return text.length;
+}
+function blankComments(text) {
+    let out = "";
+    let index = 0;
+    while (index < text.length) {
+        if (text[index] === '"') {
+            const end = stringEnd(text, index);
+            out += text.slice(index, end);
+            index = end;
+        }
+        else if (text.startsWith("//", index)) {
+            const newline = text.indexOf("\n", index);
+            const end = newline === -1 ? text.length : newline;
+            out += " ".repeat(end - index);
+            index = end;
+        }
+        else if (text.startsWith("/*", index)) {
+            const close = text.indexOf("*/", index + 2);
+            if (close === -1) {
+                throw new SyntaxError(`Unterminated block comment in JSONC starting at line ${text.slice(0, index).split("\n").length}`);
+            }
+            const end = close + 2;
+            out += text.slice(index, end).replace(/[^\r\n]/gu, " ");
+            index = end;
+        }
+        else {
+            out += text[index];
+            index += 1;
+        }
+    }
+    return out;
+}
+function blankTrailingCommas(text) {
+    let out = "";
+    let index = 0;
+    while (index < text.length) {
+        if (text[index] === '"') {
+            const end = stringEnd(text, index);
+            out += text.slice(index, end);
+            index = end;
+            continue;
+        }
+        if (text[index] === "," && /^\s*[\]}]/u.test(text.slice(index + 1)))
+            out += " ";
+        else
+            out += text[index];
+        index += 1;
+    }
+    return out;
+}
+const bom = "\uFEFF";
+function withoutBom(text) {
+    return text.startsWith(bom) ? text.slice(1) : text;
+}
+export function lineEnding(text) {
+    return text.includes("\r\n") ? "\r\n" : "\n";
+}
+export function parseJsonc(text) {
+    return JSON.parse(blankTrailingCommas(blankComments(withoutBom(text))));
+}
+export function hasJsoncComments(text) {
+    return blankComments(text) !== text;
+}
+function skipWhitespace(text, index) {
+    while (index < text.length && /\s/u.test(text[index]))
+        index += 1;
+    return index;
+}
+function valueEnd(text, start) {
+    if (text[start] === '"')
+        return stringEnd(text, start);
+    if (text[start] !== "{" && text[start] !== "[") {
+        let index = start;
+        while (index < text.length && !/[\s,\]}]/u.test(text[index]))
+            index += 1;
+        return index;
+    }
+    let depth = 0;
+    let index = start;
+    while (index < text.length) {
+        const char = text[index];
+        if (char === '"') {
+            index = stringEnd(text, index);
+            continue;
+        }
+        if (char === "{" || char === "[")
+            depth += 1;
+        if (char === "}" || char === "]")
+            depth -= 1;
+        index += 1;
+        if (depth === 0)
+            return index;
+    }
+    return index;
+}
+// `blanked` is text that already parsed as a JSONC object, with its comments blanked.
+function topLevelMembers(blanked) {
+    const members = [];
+    let index = skipWhitespace(blanked, 0) + 1;
+    for (;;) {
+        index = skipWhitespace(blanked, index);
+        if (blanked[index] === ",")
+            index = skipWhitespace(blanked, index + 1);
+        if (blanked[index] === "}" || index >= blanked.length)
+            return { close: index, members };
+        const keyEnd = stringEnd(blanked, index);
+        const key = JSON.parse(blanked.slice(index, keyEnd));
+        const valueStart = skipWhitespace(blanked, skipWhitespace(blanked, keyEnd) + 1);
+        const end = valueEnd(blanked, valueStart);
+        members.push({ key, valueStart, valueEnd: end });
+        index = end;
+    }
+}
+function formatValue(value, eol = "\n") {
+    return JSON.stringify(value, null, 2).replace(/\n/gu, `${eol}  `);
+}
+export function formatJsoncMember(key, value, eol = "\n") {
+    return `${JSON.stringify(key)}: ${formatValue(value, eol)}`;
+}
+/**
+ * Rewrites only the top-level entries of `text` whose value differs from `next`, leaving every other
+ * byte (comments, a leading BOM and the line ending included) in place. Refuses, naming the entry,
+ * when an edited value holds a comment or when an entry would have to be removed.
+ */
+export function editJsoncObject(text, next) {
+    if (text.startsWith(bom)) {
+        const edit = editJsoncObject(text.slice(1), next);
+        return edit.ok ? { ok: true, text: bom + edit.text } : edit;
+    }
+    const eol = lineEnding(text);
+    const current = parseJsonc(text);
+    const removed = Object.keys(current).find((key) => !(key in next));
+    if (removed !== undefined)
+        return { ok: false, key: removed };
+    let edited = text;
+    for (const [key, value] of Object.entries(next)) {
+        if (JSON.stringify(current[key]) === JSON.stringify(value))
+            continue;
+        const blanked = blankComments(edited);
+        const { close, members } = topLevelMembers(blanked);
+        const member = [...members].reverse().find((candidate) => candidate.key === key);
+        if (member !== undefined) {
+            if (blanked.slice(member.valueStart, member.valueEnd) !== edited.slice(member.valueStart, member.valueEnd)) {
+                return { ok: false, key };
+            }
+            edited = edited.slice(0, member.valueStart) + formatValue(value, eol) + edited.slice(member.valueEnd);
+            continue;
+        }
+        let lineStart = close;
+        while (lineStart > 0 && (edited[lineStart - 1] === " " || edited[lineStart - 1] === "\t"))
+            lineStart -= 1;
+        const ownLine = lineStart > 0 && edited[lineStart - 1] === "\n";
+        const at = ownLine ? lineStart : close;
+        edited = edited.slice(0, at) + (ownLine ? "" : eol) + "  " + formatJsoncMember(key, value, eol) + eol + edited.slice(at);
+        const last = members.at(-1);
+        if (last !== undefined && !blanked.slice(last.valueEnd, close).includes(",")) {
+            edited = edited.slice(0, last.valueEnd) + "," + edited.slice(last.valueEnd);
+        }
+    }
+    return { ok: true, text: edited };
+}

package/dist/cli/loop.d.ts

@@ -1,3 +1,3 @@
 import type { CliResult, LoopArgs } from "./types.ts";
 import type { LoopCommand } from "./args.ts";
-export declare function runLoopCommand(command: LoopCommand, loop: LoopArgs): Promise<CliResult>;
+export declare function runLoopCommand(command: LoopCommand, loop: LoopArgs, dryRun?: boolean): Promise<CliResult>;

package/dist/cli/loop.js

@@ -1,4 +1,8 @@
 import { completeGoals, createGoals, EvidenceLedgerError, evaluateGoalGate, readEvidenceLedgerStatus, recordCheckpoint, recordEvidence, recordReviewBlocker, recordSteering, resolveReviewBlocker } from "../ledger.js";
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
 import { createRuntimePaths } from "../state.js";
 // Exit codes are distinct so a caller can tell a refusal from a usage error: 2 is a malformed
 // invocation, 3 is a deliberate refusal, 1 is a gate that did not pass.
@@ -38,7 +42,83 @@ function describeGoal(goal) {
             lines.push(`  - ${reason}`);
     return lines.join("\n");
 }
-export async function runLoopCommand(command, loop) {
+async function snapshotTree(dir) {
+    const files = new Map();
+    const walk = async (current) => {
+        let entries;
+        try {
+            entries = await fs.readdir(current, { withFileTypes: true });
+        }
+        catch (error) {
+            if (error instanceof Error && "code" in error && error.code === "ENOENT")
+                return;
+            throw error;
+        }
+        for (const entry of entries) {
+            const full = path.join(current, entry.name);
+            if (entry.isDirectory())
+                await walk(full);
+            else
+                files.set(path.relative(dir, full), createHash("sha256").update(await fs.readFile(full)).digest("hex"));
+        }
+    };
+    await walk(dir);
+    return files;
+}
+// A dry run executes the verb against a private copy of the project's .litopencode state, so the
+// same validation, refusals and gates apply, then reports which files the real run would change.
+// The copy dereferences symlinks, so a write in the copy can never reach a linked target.
+async function dryRunLoopCommand(command, loop) {
+    const realRuntimeDir = createRuntimePaths(loop.projectRoot).runtimeDir;
+    const shadowRoot = await fs.realpath(await fs.mkdtemp(path.join(os.tmpdir(), "litopencode-dry-run-shadow-")));
+    try {
+        const shadowRuntimeDir = createRuntimePaths(shadowRoot).runtimeDir;
+        try {
+            await fs.cp(realRuntimeDir, shadowRuntimeDir, { recursive: true, dereference: true });
+        }
+        catch (error) {
+            if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+                throw error;
+        }
+        const before = await snapshotTree(shadowRuntimeDir);
+        const result = await runLoopCommandAt(command, { ...loop, projectRoot: shadowRoot });
+        const after = await snapshotTree(shadowRuntimeDir);
+        const writes = [];
+        for (const [file, hash] of after) {
+            const previous = before.get(file);
+            if (previous === undefined)
+                writes.push({ path: path.join(realRuntimeDir, file), change: "create" });
+            else if (previous !== hash)
+                writes.push({ path: path.join(realRuntimeDir, file), change: "update" });
+        }
+        for (const file of before.keys())
+            if (!after.has(file))
+                writes.push({ path: path.join(realRuntimeDir, file), change: "delete" });
+        writes.sort((left, right) => left.path.localeCompare(right.path));
+        const realProjectRoot = path.resolve(loop.projectRoot);
+        const relabel = (text) => text?.split(shadowRoot).join(realProjectRoot);
+        if (loop.json && result.stdout !== undefined) {
+            const payload = { dryRun: true, command, wouldWrite: writes, result: JSON.parse(relabel(result.stdout) ?? "null") };
+            return { exitCode: result.exitCode, stdout: JSON.stringify(payload, null, 2), stderr: relabel(result.stderr) };
+        }
+        const plan = writes.length === 0
+            ? `DRY RUN: nothing was written. ${command} would change no files.`
+            : [`DRY RUN: nothing was written. ${command} would change:`, ...writes.map((entry) => `  ${entry.change} ${entry.path}`)].join("\n");
+        const preview = relabel(result.stdout);
+        const stdout = preview === undefined || preview === "" ? plan : `${plan}\nThe real run would report:\n${preview}`;
+        return { exitCode: result.exitCode, stdout, stderr: relabel(result.stderr) };
+    }
+    finally {
+        await fs.rm(shadowRoot, { recursive: true, force: true });
+    }
+}
+// status only reads, so --dry-run changes nothing about it; every other verb writes the ledger.
+export async function runLoopCommand(command, loop, dryRun = false) {
+    if (dryRun && command !== "status")
+        return await dryRunLoopCommand(command, loop);
+    return await runLoopCommandAt(command, loop);
+}
+async function runLoopCommandAt(command, loop) {
     const root = loop.projectRoot;
     try {
         if (command === "create-goals") {

package/dist/cli/motion-runtime.d.ts

@@ -1,6 +1,18 @@
 import type { CliResult } from "./types.ts";
 export declare const motionInstallCommand = "litopencode motion-runtime install";
-export declare function runMotionRuntime(packageRoot: string, args: readonly string[]): CliResult;
+export type MotionRuntimeArgs = {
+    readonly command: "help";
+} | {
+    readonly command: "install";
+    readonly audio: boolean;
+    readonly wordTiming: boolean;
+    readonly dryRun: boolean;
+} | {
+    readonly command: "status";
+    readonly json: boolean;
+};
+export declare function parseMotionRuntimeArgs(args: readonly string[]): MotionRuntimeArgs;
+export declare function runMotionRuntime(packageRoot: string, args: readonly string[]): Promise<CliResult>;
 export declare function motionPrewarmSkipped(env?: NodeJS.ProcessEnv): string | undefined;
 export declare function prewarmMotionRuntime(packageRoot: string, env?: NodeJS.ProcessEnv): string;
 export declare function probeMotionRuntime(packageRoot: string): unknown;

package/dist/cli/motion-runtime.js

@@ -1,5 +1,14 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
 import { spawnSync } from "node:child_process";
 import path from "node:path";
+import { pathToFileURL } from "node:url";
 // lit-typographic-motion's runtime lives in the managed skill (runtime.mjs, probe.mjs). The CLI verb
 // `litopencode motion-runtime install|status` runs it under this same Node binary; the installer
 // attempts the same pre-warm and reduces the outcome to one receipt line.
@@ -7,8 +16,86 @@ function motionScript(packageRoot, file) {
     return path.join(packageRoot, "skills", "lit-typographic-motion", file);
 }
 export const motionInstallCommand = "litopencode motion-runtime install";
-export function runMotionRuntime(packageRoot, args) {
-    const result = spawnSync(process.execPath, [motionScript(packageRoot, "runtime.mjs"), ...args], { stdio: "inherit" });
+const motionUsage = "Usage: litopencode motion-runtime install [--audio] [--word-timing] [--dry-run] | status [--json]";
+// Every flag is checked before the runtime script runs, because install downloads and writes the
+// cache: an unknown or misspelled flag must stop the command, never be ignored.
+export function parseMotionRuntimeArgs(args) {
+    const [command, ...flags] = args;
+    const refuse = (reason) => {
+        throw new Error(`motion-runtime: ${reason}\n${motionUsage}`);
+    };
+    if (command === undefined || command === "help" || command === "--help" || command === "-h") {
+        if (flags.length > 0)
+            refuse(`unexpected argument after ${command ?? "motion-runtime"}: ${flags[0]}`);
+        return { command: "help" };
+    }
+    if (command === "install") {
+        let audio = false;
+        let wordTiming = false;
+        let dryRun = false;
+        for (const flag of flags) {
+            if (flag === "--audio")
+                audio = true;
+            else if (flag === "--word-timing")
+                wordTiming = true;
+            else if (flag === "--dry-run" || flag === "--dry-run=true")
+                dryRun = true;
+            else
+                refuse(`unknown install flag ${flag}`);
+        }
+        return { command: "install", audio, wordTiming, dryRun };
+    }
+    if (command === "status") {
+        let json = false;
+        for (const flag of flags) {
+            if (flag === "--json")
+                json = true;
+            else if (flag === "--dry-run" || flag.startsWith("--dry-run="))
+                refuse("status only reads the cache, so --dry-run does not apply");
+            else
+                refuse(`unknown status flag ${flag}`);
+        }
+        return { command: "status", json };
+    }
+    return refuse(`unknown command ${command}`);
+}
+// Reads the same pins and cache state the install uses and reports each step it would take.
+// Nothing here downloads, creates the cache, or takes the install lock.
+async function describeMotionInstall(packageRoot, options) {
+    const runtime = await import(__rewriteRelativeImportExtension(pathToFileURL(motionScript(packageRoot, "runtime.mjs")).href));
+    const paths = runtime.runtimePaths(process.env);
+    const state = runtime.inspectWarmState(process.env);
+    const lines = ["DRY RUN: nothing was downloaded or written.", `motion runtime cache: ${paths.base}`];
+    if (options.wordTiming) {
+        lines.push(runtime.describeWordTiming());
+        if (!runtime.inspectWordTiming().pinned) {
+            lines.push("would stop: no licence-verified Korean alignment model is pinned, so the real install exits 14 (BLOCKED_DEPS_NOT_PREWARMED) before downloading anything.");
+            return lines.join("\n");
+        }
+    }
+    const fonts = [...state.missingFonts, ...state.mismatchedFonts];
+    lines.push(fonts.length === 0 ? "fonts: all pinned fonts are present" : `would fetch and verify ${fonts.length} pinned font file(s) into ${paths.fonts}: ${fonts.join(", ")}`);
+    lines.push(state.deps.length === 0 ? "engine dependencies: already installed" : `would run npm ci for ${state.deps.join(", ")} into ${paths.node}`);
+    if (options.audio)
+        lines.push(state.audio.ready ? "audio venv: already ready" : `would create the pinned librosa audio venv in ${paths.audio}`);
+    lines.push("Run the same command without --dry-run to install.");
+    return lines.join("\n");
+}
+export async function runMotionRuntime(packageRoot, args) {
+    let parsed;
+    try {
+        parsed = parseMotionRuntimeArgs(args);
+    }
+    catch (error) {
+        return { exitCode: 2, stderr: error instanceof Error ? error.message : String(error) };
+    }
+    if (parsed.command === "install" && parsed.dryRun) {
+        return { exitCode: 0, stdout: await describeMotionInstall(packageRoot, parsed) };
+    }
+    const forwarded = parsed.command === "help" ? ["--help"]
+        : parsed.command === "status" ? ["status", ...(parsed.json ? ["--json"] : [])]
+            : ["install", ...(parsed.audio ? ["--audio"] : []), ...(parsed.wordTiming ? ["--word-timing"] : [])];
+    const result = spawnSync(process.execPath, [motionScript(packageRoot, "runtime.mjs"), ...forwarded], { stdio: "inherit" });
     return { exitCode: typeof result.status === "number" ? result.status : 1 };
 }
 // A test run never reaches the network or the real cache from the installer: node --test marks its