@iowarp/clio-coder 0.3.0 → 0.3.2

package/src/cli/index.ts

@@ -0,0 +1,338 @@
+#!/usr/bin/env node
+// The process table is the only place an integrator can identify a running Clio
+// Coder without sniffing script paths, and the bin name never reaches it because
+// the entry is a node script. Set it before anything can fail so `--version` and
+// a crashed boot are both legible to `ps`, `pgrep -f`, and htop.
+process.title = "clio-coder";
+
+import { AI_AGENT_NAME } from "../core/agent-environment.js";
+
+// Pi and other agent-aware developer tools use this generic marker to
+// attribute subprocess activity without knowing Clio-specific variables.
+// Set it unconditionally so every child inherits the actual spawning agent.
+process.env.AI_AGENT = AI_AGENT_NAME;
+
+// Only argument parsing and boot tracing load statically. Every subcommand is
+// imported dynamically through the command registry (see `dispatch`), so a bare `clio`
+// (interactive) or `clio-coder --version` pays for its own module graph and nothing
+// else — this is the highest-value cut of the cold module-load tax. Code
+// splitting (tsup.config.ts) keeps each command's transitive heavy externals in
+// its own chunk.
+import { traceBoot } from "../core/boot-trace.js";
+import { incompleteInstallationAdvice } from "../core/incomplete-installation.js";
+import { extractGlobalFlags, parseFlags, printError } from "./argv.js";
+
+const HELP = `Clio Coder command line
+
+Coding agent for HPC and scientific-software work, part of IOWarp's CLIO ecosystem of agentic
+science. CLIO stands for Context Layer for Input/Output, named for the Greek muse of history.
+
+Usage:
+  clio-coder                      start interactive repository chat
+  clio-coder acp                  serve Clio as an ACP v1 agent over stdio
+  clio-coder run [flags] <task>   run one headless main-agent turn
+  clio-coder --version, -v        print the Clio Coder version
+  clio-coder --api-key <key>      override the active target API key for this run
+  clio-coder --no-context-files, -nc  skip CLIO-CODER.md project-context injection
+  clio-coder configure            interactive first-run/configuration wizard
+  clio-coder targets              list configured targets, health, auth, and capabilities
+  clio-coder targets add          add a target interactively or via flags
+  clio-coder targets use <id>     set chat and fleet defaults to a target
+  clio-coder targets profile      set a named fleet profile
+  clio-coder targets remove <id>  remove a target
+  clio-coder targets rename <old> <new>  rename a target
+  clio-coder models [search]      list models for configured targets
+  clio-coder auth list|status|login|logout [target-or-runtime]
+  clio-coder doctor [--fix]       diagnose state; --fix creates or repairs it
+  clio-coder paths [--json]       print resolved config/data/cache directories
+  clio-coder reset                recover or wipe Clio Coder state
+  clio-coder context              show project context status (CLIO-CODER.md, preload, codewiki)
+  clio-coder context init [--yes] [--preview|--heuristic]  explore the repo and bootstrap CLIO-CODER.md and codewiki
+  clio-coder context refresh [--wiki]  re-index the codewiki and optionally update the Markdown wiki
+  clio-coder context wiki [--update] [--status] [--depth auto|simple|medium|detailed] [--target <id>] [--model <id>]
+  clio-coder context reset [--all] [--yes]  clear accumulated project context artifacts
+  clio-coder context index [--json]  build the codewiki index without model calls
+  clio-coder uninstall            remove all Clio Coder state; --remove-binary also unlinks the launcher
+  clio-coder upgrade              upgrade Clio Coder and run pending migrations
+  clio-coder agents               list discovered agent recipes
+  clio-coder fleet list|run|status|drain|resume  fleet contracts, status, and admission control
+  clio-coder evidence             build, list, or inspect evidence artifacts
+  clio-coder eval                 run, report, or compare local eval task files
+  clio-coder memory               list, propose, approve, reject, or prune memory
+  clio-coder usage report         cross-session usage facts and opportunities (experimental)
+  clio-coder trace                query or view the durable dispatch trace mirror
+  clio-coder extensions           install, list, enable, disable, or remove extension packages
+  clio-coder skills               list, inspect, validate, or install skills
+  clio-coder docs [topic]         serve the HTML docs of a source checkout on 127.0.0.1 (--no-open to skip browser)
+  clio-coder dev <command>        harness instruments; run 'clio-coder dev' for the list
+  clio-coder --help, -h           this message
+  clio-coder --help --all         this message plus every command under 'clio-coder dev'
+`;
+
+/**
+ * Commands that answer a question about the harness rather than about the
+ * user's own work.
+ *
+ * Nothing here is removed or deprecated. An agent driving Clio over bash can
+ * reach a wider surface than a person reading a help screen can hold, so the
+ * capability stays and only the default listing shrinks: every name below still
+ * resolves at the top level, and `clio-coder --help --all` prints all of it.
+ */
+const DEV_COMMANDS: ReadonlyArray<{ name: string; summary: string }> = [
+	{ name: "components", summary: "list, snapshot, or diff harness components" },
+	{ name: "evolve", summary: "create, validate, or summarize change manifests" },
+	{ name: "share", summary: "export or import Clio project/resource archives" },
+];
+
+const DEV_HELP = `Clio Coder harness instruments
+
+Usage:
+${DEV_COMMANDS.map((entry) => `  clio-coder dev ${entry.name.padEnd(20)}${entry.summary}`).join("\n")}
+
+Each also resolves without the 'dev' prefix, so existing scripts and agent
+callers keep working. The prefix exists so the default help stays the set of
+commands a person needs to read.
+`;
+
+function helpText(all: boolean): string {
+	return all ? `${HELP}\n${DEV_HELP}` : HELP;
+}
+
+/** Engines floor from package.json; npm only warns on EBADENGINE, so the CLI
+ * states the requirement itself instead of failing with an arbitrary syntax
+ * or API error on old Node versions. */
+const MIN_NODE = [22, 19, 0] as const;
+
+interface CliBootOptions {
+	apiKey?: string;
+	noContextFiles?: boolean;
+	noSkills?: boolean;
+	skillPaths?: string[];
+}
+
+type CommandHandler = (subArgs: string[], bootOptions: CliBootOptions) => Promise<number>;
+
+function nodeVersionError(): string | null {
+	const parts = process.versions.node.split(".").map((part) => Number.parseInt(part, 10));
+	for (let i = 0; i < MIN_NODE.length; i += 1) {
+		const actual = parts[i] ?? 0;
+		const wanted = MIN_NODE[i] ?? 0;
+		if (actual > wanted) return null;
+		if (actual < wanted) {
+			return `clio-coder requires Node.js >=${MIN_NODE.join(".")}; this is ${process.versions.node}. Upgrade Node and retry.`;
+		}
+	}
+	return null;
+}
+
+async function main(argv: string[]): Promise<number> {
+	// First application statement after the static import graph resolved: the
+	// elapsed here is the cold module-load tax (see CLIO_CODER_TRACE_BOOT).
+	traceBoot("cli entry");
+	const versionError = nodeVersionError();
+	if (versionError !== null) {
+		printError(versionError);
+		return 1;
+	}
+	const {
+		apiKey,
+		noContextFiles,
+		noSkills,
+		skillPaths,
+		rest,
+		error: globalFlagError,
+	} = extractGlobalFlags(argv, isCommandToken);
+	if (globalFlagError) {
+		printError(globalFlagError);
+		return 2;
+	}
+	const { flags, positional } = parseFlags(rest);
+	const subcommand = positional[0];
+	const subcommandIndex = rest.findIndex((arg) => !arg.startsWith("-"));
+	const firstArg = rest[0];
+	if (firstArg === "--help" || firstArg === "-h" || ((flags.has("help") || flags.has("h")) && !subcommand)) {
+		process.stdout.write(helpText(flags.has("all")));
+		return 0;
+	}
+	if (flags.has("version") || flags.has("v")) {
+		const { runVersionCommand } = await import("./version.js");
+		return runVersionCommand();
+	}
+
+	const subArgs = subcommandIndex === -1 ? [] : rest.slice(subcommandIndex + 1);
+	const bootOptions = {
+		...(apiKey === undefined ? {} : { apiKey }),
+		...(noContextFiles ? { noContextFiles: true } : {}),
+		...(noSkills ? { noSkills: true } : {}),
+		...(skillPaths.length > 0 ? { skillPaths } : {}),
+	};
+	if (!subcommand) {
+		await enableBootCompileCache();
+		const { runClioCommand } = await import("./clio.js");
+		return runClioCommand(bootOptions);
+	}
+
+	return dispatch(subcommand, subArgs, bootOptions);
+}
+
+/**
+ * Cache the boot-path module graphs' bytecode. Only the three long-lived
+ * entrypoints that already write state enable it (interactive, `run`, `acp`);
+ * read-only and dry-run commands such as `paths` and bare `doctor` document
+ * that they create nothing, and enabling the cache creates its directory, so
+ * a dispatch-wide enable would break that promise on every initialized home.
+ * A help invocation of a boot command is itself zero-side-effect, so the
+ * guard runs before enablement, not after the module's own help check.
+ */
+async function enableBootCompileCache(subArgs: ReadonlyArray<string> = []): Promise<void> {
+	if (subArgs.includes("--help") || subArgs.includes("-h")) return;
+	const { enableClioCompileCache } = await import("../core/compile-cache.js");
+	enableClioCompileCache();
+}
+
+/**
+ * The dispatcher is also the command-recognition source used by top-level
+ * value flags. Every dynamic import stays a literal so tsup can split command
+ * graphs, while adding a command in one place cannot leave --api-key/--skill
+ * free to swallow it as a value.
+ */
+const extensionsCommand: CommandHandler = async (subArgs) =>
+	(await import("./extensions.js")).runExtensionsCommand(subArgs);
+
+const COMMAND_HANDLERS = new Map<string, CommandHandler>([
+	[
+		"acp",
+		async (subArgs, bootOptions) => {
+			await enableBootCompileCache(subArgs);
+			return (await import("./acp.js")).runAcpCommand(subArgs, bootOptions);
+		},
+	],
+	["auth", async (subArgs) => (await import("./auth.js")).runAuthCommand(subArgs)],
+	["config", async (subArgs) => (await import("./config.js")).runConfigCommand(subArgs)],
+	["configure", async (subArgs) => (await import("./configure.js")).runConfigureCommand(subArgs)],
+	["targets", async (subArgs) => (await import("./targets.js")).runTargetsCommand(subArgs)],
+	["models", async (subArgs) => (await import("./models.js")).runModelsCommand(subArgs)],
+	["agents", async (subArgs) => (await import("./agents.js")).runAgentsCommand(subArgs)],
+	["components", async (subArgs) => (await import("./components.js")).runComponentsCommand(subArgs)],
+	["evidence", async (subArgs) => (await import("./evidence.js")).runEvidenceCommand(subArgs)],
+	["eval", async (subArgs) => (await import("./eval.js")).runEvalCommand(subArgs)],
+	["memory", async (subArgs) => (await import("./memory.js")).runMemoryCommand(subArgs)],
+	["usage", async (subArgs) => (await import("./usage.js")).runUsageCommand(subArgs)],
+	["trace", async (subArgs) => (await import("./trace.js")).runTraceCommand(subArgs)],
+	["evolve", async (subArgs) => (await import("./evolve.js")).runEvolveCommand(subArgs)],
+	[
+		"dev",
+		async (subArgs, bootOptions) => {
+			const devSubcommand = subArgs[0];
+			// `clio-coder dev` is what the top-level help tells the user to run for this
+			// listing, so printing the listing is the command succeeding, not a
+			// usage error.
+			if (devSubcommand === undefined || devSubcommand === "--help" || devSubcommand === "-h") {
+				process.stdout.write(DEV_HELP);
+				return 0;
+			}
+			if (!DEV_COMMANDS.some((entry) => entry.name === devSubcommand)) {
+				printError(`unknown dev command: ${devSubcommand}`);
+				process.stdout.write(DEV_HELP);
+				return 2;
+			}
+			return dispatch(devSubcommand, subArgs.slice(1), bootOptions);
+		},
+	],
+	["extensions", extensionsCommand],
+	["ext", extensionsCommand],
+	["fleet", async (subArgs) => (await import("./fleet.js")).runFleetCommand(subArgs)],
+	["skills", async (subArgs) => (await import("./skills.js")).runSkillsCommand(subArgs)],
+	["docs", async (subArgs) => (await import("./docs.js")).runDocsCommand(subArgs)],
+	["share", async (subArgs) => (await import("./share.js")).runShareCommand(subArgs)],
+	["export", async (subArgs) => (await import("./share.js")).runExportCommand(subArgs)],
+	["import", async (subArgs) => (await import("./share.js")).runImportCommand(subArgs)],
+	["context", async (subArgs) => (await import("./context.js")).runContextCommand(subArgs)],
+	[
+		"run",
+		async (subArgs, bootOptions) => {
+			await enableBootCompileCache(subArgs);
+			return (await import("./run.js")).runClioRun(subArgs, bootOptions);
+		},
+	],
+	["doctor", async (subArgs) => (await import("./doctor.js")).runDoctorCommand(subArgs)],
+	["paths", async (subArgs) => (await import("./paths.js")).runPathsCommand(subArgs)],
+	["reset", async (subArgs) => (await import("./reset.js")).runResetCommand(subArgs)],
+	["uninstall", async (subArgs) => (await import("./uninstall.js")).runUninstallCommand(subArgs)],
+	["upgrade", async (subArgs) => (await import("./upgrade.js")).runUpgradeCommand(subArgs)],
+	["version", async () => (await import("./version.js")).runVersionCommand()],
+	[
+		"worker",
+		async () => {
+			// Internal: the native worker stream server (WorkerSpec on stdin,
+			// NDJSON on stdout). The entry module runs main() on import and owns
+			// process exit; this settles only on a pre-run import failure.
+			// This is how SSH placement launches a worker on the remote install,
+			// where no local spawn boundary injected NODE_COMPILE_CACHE, so the
+			// worker graph enables the remote cache itself before it loads. The
+			// enable is in-process only: no environment variable is set, so the
+			// worker's own children inherit nothing. Nothing on this path
+			// injected the provenance pair either, so any marker present is
+			// foreign; strip it (and only it) so the entry's consume can never
+			// match and delete an operator's own NODE_COMPILE_CACHE.
+			Reflect.deleteProperty(process.env, "CLIO_CODER_INJECTED_COMPILE_CACHE");
+			await enableBootCompileCache();
+			await import("../worker/entry.js");
+			return 0;
+		},
+	],
+]);
+
+// Retired commands are not dispatchable, but remain command-shaped tombstones
+// so top-level value flags cannot consume them and accidentally boot another mode.
+const RETIRED_SUBCOMMANDS = new Set<string>(["context-init", "context-index", "context-clear"]);
+
+function isCommandToken(token: string): boolean {
+	return COMMAND_HANDLERS.has(token) || RETIRED_SUBCOMMANDS.has(token);
+}
+
+/**
+ * Turn a missing command chunk into a repair instruction.
+ *
+ * Every subcommand is a dynamic import of a code-split chunk beside this
+ * entry, so an install that was interrupted between unpacking the entry and
+ * unpacking the rest produces a `clio` that starts, parses flags, prints
+ * `--version`, and then dies on `Cannot find module` the moment it is asked to
+ * do anything. That message names an internal build artifact nobody outside
+ * this repository can act on. The filter on our own output directory keeps a
+ * module error raised by a user's extension or hook reporting itself normally.
+ */
+/**
+ * Route a subcommand to its registered handler, importing only that command's
+ * module. Unknown names fail before loading any command graph.
+ */
+async function dispatch(subcommand: string, subArgs: string[], bootOptions: CliBootOptions): Promise<number> {
+	const handler = COMMAND_HANDLERS.get(subcommand);
+	if (handler) {
+		try {
+			return await handler(subArgs, bootOptions);
+		} catch (err) {
+			const advice = incompleteInstallationAdvice(err);
+			if (advice === null) throw err;
+			printError(advice);
+			return 1;
+		}
+	}
+	printError(`unknown subcommand: ${subcommand}`);
+	// The usage that explains a rejection belongs with the rejection on stderr.
+	// Writing it to stdout meant a mistyped command still produced a full page on
+	// the stream the caller was capturing for output, next to an error on the one
+	// it was probably not reading. `clio-coder --help` is the request for this
+	// text, and it still answers on stdout with exit 0.
+	process.stderr.write(helpText(false));
+	return 2;
+}
+
+main(process.argv.slice(2))
+	.then((code) => {
+		process.exitCode = code;
+	})
+	.catch((err) => {
+		printError(err instanceof Error ? err.message : String(err));
+		process.exitCode = 1;
+	});

package/src/cli/init.ts

@@ -0,0 +1,219 @@
+import { stdin as input, stdout as output } from "node:process";
+import { createInterface } from "node:readline/promises";
+import { runBootstrap } from "../domains/context/index.js";
+import {
+	bootstrapInputFromInitOptions,
+	CONTEXT_INIT_FLAG_TABLE,
+	type ContextInitOptions,
+	validateInitOptions,
+} from "../domains/context/init-options.js";
+import { type ThinkingLevel, VALID_THINKING_LEVELS } from "../domains/providers/index.js";
+import { modelBootstrapGenerate } from "./bootstrap-generate.js";
+
+const HELP = `Usage:
+  clio-coder context init [--preview] [--heuristic] [--yes] [--json] [--adopt] [--global] [--propose|--apply|--rewrite]
+                    [--target <id> [--model <id>] [--thinking <level>]]
+
+Explore the repository and bootstrap the project context in one pass: CLIO-CODER.md,
+the codewiki index, and the .clio-coder state. The configured Clio
+target drafts CLIO-CODER.md grounded in the existing handbook, codewiki structure, and
+sibling agent context. Existing CLIO-CODER.md files are preserved by default; use
+--propose for an ignored draft, --apply to update the handbook using it as source,
+or --rewrite to replace it with a fresh draft that ignores the current CLIO-CODER.md.
+
+Options:
+  --preview        show the plan without writing any files
+  --heuristic      skip model exploration; use the deterministic generator (offline)
+  --adopt          refresh only the managed Imported agent context section
+  --global         include global sibling agent context from user home directory
+  --propose        write an ignored .clio-coder/proposals/CLIO-CODER-*.md draft when CLIO-CODER.md exists
+  --apply          replace an existing CLIO-CODER.md with a draft grounded in the existing handbook
+  --rewrite        replace an existing CLIO-CODER.md with a fresh draft that ignores it as source
+  --json           emit one machine-readable result object on stdout
+  --yes, -y        update .gitignore without prompting
+  --target <id>    override the configured Scout target for this noninteractive run
+  --model <id>     override the Scout wire model (requires --target)
+  --thinking <n>   override Scout thinking: ${VALID_THINKING_LEVELS.join("|")} (requires --target)
+`;
+
+function hasFlag(args: ReadonlyArray<string>, name: string): boolean {
+	return args.includes(name);
+}
+
+function parseContextInitArgs(args: ReadonlyArray<string>): {
+	options: ContextInitOptions;
+	json: boolean;
+	target?: string;
+	model?: string;
+	thinkingLevel?: ThinkingLevel;
+	error: string | null;
+} {
+	const options: ContextInitOptions = {};
+	let json = false;
+	let target: string | undefined;
+	let model: string | undefined;
+	let thinkingLevel: ThinkingLevel | undefined;
+	const thinkingLevels = new Set<ThinkingLevel>(VALID_THINKING_LEVELS);
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index] as string;
+		if (arg === "--help" || arg === "-h" || arg === "--yes" || arg === "-y") continue;
+		if (arg === "--json") {
+			json = true;
+			continue;
+		}
+		if (arg === "--target" || arg === "--model" || arg === "--thinking") {
+			const value = args[index + 1];
+			if (!value || value.startsWith("-")) return { options, json, error: `${arg} requires a value` };
+			index += 1;
+			if (arg === "--target") target = value;
+			else if (arg === "--model") model = value;
+			else {
+				if (!thinkingLevels.has(value as ThinkingLevel)) {
+					return { options, json, error: `--thinking must be one of: ${[...thinkingLevels].join("|")}` };
+				}
+				thinkingLevel = value as ThinkingLevel;
+			}
+			continue;
+		}
+		const row = CONTEXT_INIT_FLAG_TABLE.find((candidate) => candidate.flag === arg || candidate.aliases?.includes(arg));
+		if (!row) {
+			return { options, json, error: arg.startsWith("-") ? `unknown flag ${arg}` : `unexpected argument ${arg}` };
+		}
+		options[row.field] = true;
+	}
+	if (!target && (model || thinkingLevel)) {
+		return { options, json, error: "--model and --thinking require --target" };
+	}
+	return {
+		options,
+		json,
+		...(target ? { target } : {}),
+		...(model ? { model } : {}),
+		...(thinkingLevel ? { thinkingLevel } : {}),
+		error: null,
+	};
+}
+
+interface InitPhaseTiming {
+	startedAt: number;
+	completedMs?: number;
+}
+
+async function confirmGitignore(assumeYes: boolean): Promise<boolean> {
+	if (assumeYes) return true;
+	if (!input.isTTY) return false;
+	const rl = createInterface({ input, output });
+	try {
+		const answer = await rl.question("Update .gitignore for Clio context artifacts? [y/N] ");
+		return answer.trim().toLowerCase() === "y" || answer.trim().toLowerCase() === "yes";
+	} finally {
+		rl.close();
+	}
+}
+
+export async function runInitCommand(args: string[]): Promise<number> {
+	if (hasFlag(args, "--help") || hasFlag(args, "-h")) {
+		process.stdout.write(HELP);
+		return 0;
+	}
+	const assumeYes = hasFlag(args, "--yes") || hasFlag(args, "-y");
+	const parsed = parseContextInitArgs(args);
+	if (parsed.error) {
+		process.stderr.write(`clio-coder context init: ${parsed.error}\n`);
+		process.stdout.write(HELP);
+		return 2;
+	}
+	const validationError = validateInitOptions(parsed.options);
+	if (validationError) {
+		process.stderr.write(`${validationError}\n`);
+		process.stdout.write(HELP);
+		return 2;
+	}
+	const bootstrapOptions = bootstrapInputFromInitOptions(parsed.options);
+	// Model-driven exploration is the default. --heuristic
+	// forces the deterministic generator; preview never spawns a model.
+	const useModel = parsed.options.heuristic !== true && parsed.options.preview !== true;
+	const startedAt = performance.now();
+	const phaseTimings = new Map<string, InitPhaseTiming>();
+	try {
+		const result = await runBootstrap({
+			cwd: process.cwd(),
+			io: {
+				stdout: (s) => {
+					if (!parsed.json) process.stdout.write(s);
+				},
+				stderr: (s) => process.stderr.write(s),
+			},
+			onProgress: (event) => {
+				const now = performance.now();
+				const timing = phaseTimings.get(event.phase);
+				if (event.status === "started") phaseTimings.set(event.phase, { startedAt: now });
+				else if (event.status === "completed" && timing) timing.completedMs = Math.max(0, now - timing.startedAt);
+			},
+			confirmGitignore: () => confirmGitignore(assumeYes),
+			...bootstrapOptions,
+			...(useModel
+				? {
+						generate: modelBootstrapGenerate({
+							...(parsed.target
+								? {
+										route: {
+											target: parsed.target,
+											...(parsed.model ? { model: parsed.model } : {}),
+											...(parsed.thinkingLevel ? { thinkingLevel: parsed.thinkingLevel } : {}),
+										},
+									}
+								: {}),
+							onFallback: (err, mode) =>
+								process.stderr.write(
+									`clio-coder context init: model exploration unavailable, using ${mode === "existing" ? "existing CLIO-CODER.md" : "heuristic"} (${err.message})\n`,
+								),
+						}),
+						modelId: "configured-clio-target",
+					}
+				: {}),
+		});
+		if (parsed.json) {
+			process.stdout.write(
+				`${JSON.stringify({
+					version: 1,
+					action: result.summary.action,
+					projectType: result.projectType,
+					codewikiEntries: result.summary.codewikiEntries,
+					clioMdPath: result.clioMdPath,
+					statePath: result.statePath,
+					preload: result.preload,
+					adoption: result.summary.adoption,
+					generation: result.telemetry.generation,
+					timings: {
+						wallMs: Math.max(0, performance.now() - startedAt),
+						...(phaseTimings.get("codewiki")?.completedMs !== undefined
+							? { codewikiMs: phaseTimings.get("codewiki")?.completedMs }
+							: {}),
+						...(phaseTimings.get("generate")?.completedMs !== undefined
+							? { generationMs: phaseTimings.get("generate")?.completedMs }
+							: {}),
+					},
+				})}\n`,
+			);
+		}
+		// `--rewrite` asks for a draft that ignores the current CLIO-CODER.md. When the
+		// model pass fails, the fallback rebuilds the handbook from that very
+		// file and the write is reported as a refresh, so a caller scripting the
+		// exit code is told a rewrite happened that did not. Name what was
+		// written, name the two ways forward, and fail. The plain heuristic
+		// fallback still exits 0: it is a legitimate degraded mode, and the
+		// warning line above already names it.
+		if (parsed.options.rewriteClioMd === true && result.telemetry.generation.mode === "existing") {
+			process.stderr.write(
+				"clio-coder context init: --rewrite did not rewrite CLIO-CODER.md; the model draft failed and the fallback rebuilt the handbook from the existing file.\n" +
+					"  rerun `clio-coder context init --rewrite` once the bootstrap target answers, or `clio-coder context init --rewrite --heuristic` to replace it with the deterministic draft.\n",
+			);
+			return 1;
+		}
+		return 0;
+	} catch (err) {
+		process.stderr.write(`clio-coder context init failed: ${err instanceof Error ? err.message : String(err)}\n`);
+		return 1;
+	}
+}

package/src/cli/initial-message.ts

@@ -0,0 +1,47 @@
+import type { ImageContent } from "../engine/types.js";
+
+export interface InitialMessageInput {
+	messages: ReadonlyArray<string>;
+	stdinContent?: string;
+	fileText?: string;
+	fileImages?: ImageContent[];
+}
+
+export interface InitialMessageResult {
+	initialMessage?: string;
+	initialImages?: ImageContent[];
+	remainingMessages: string[];
+}
+
+export async function readPipedStdin(): Promise<string | undefined> {
+	if (process.stdin.isTTY) return undefined;
+	return new Promise((resolve) => {
+		let data = "";
+		process.stdin.setEncoding("utf8");
+		process.stdin.on("data", (chunk) => {
+			data += chunk;
+		});
+		process.stdin.on("end", () => {
+			resolve(data.length > 0 ? data : undefined);
+		});
+		process.stdin.resume();
+	});
+}
+
+export function shouldReadPipedStdin(messages: ReadonlyArray<string>): boolean {
+	return messages.length === 0;
+}
+
+export function buildInitialMessage(input: InitialMessageInput): InitialMessageResult {
+	const parts: string[] = [];
+	if (input.stdinContent !== undefined) parts.push(input.stdinContent);
+	if (input.fileText) parts.push(input.fileText);
+
+	const [first, ...rest] = input.messages;
+	if (first !== undefined) parts.push(first);
+
+	const result: InitialMessageResult = { remainingMessages: rest };
+	if (parts.length > 0) result.initialMessage = parts.join("");
+	if (input.fileImages && input.fileImages.length > 0) result.initialImages = [...input.fileImages];
+	return result;
+}

package/src/cli/internal-dispatch.ts

@@ -0,0 +1,55 @@
+/**
+ * Wall-clock deadline for internal generator dispatches (the wiki documenter
+ * and the bootstrap scout). These runs are unattended and headless: the worker
+ * tool-call cap bounds tool spam and the heartbeat watchdog bounds silence,
+ * but a model that keeps streaming tokens without finishing satisfies both
+ * indefinitely, so the caller must bound wall-clock time itself. The deadline
+ * aborts through the dispatch contract's timeout convention (AbortReason
+ * cause "timeout") so the run's receipt records the real cause instead of an
+ * operator cancel.
+ */
+
+import { GUARDRAIL_ENV_VARS, resolveGuardrail } from "../core/guardrails.js";
+import type { DispatchContract } from "../domains/dispatch/contract.js";
+
+export interface InternalDispatchDeadline {
+	/** True once the deadline fired and the run was aborted. */
+	timedOut(): boolean;
+	/** Cancel the pending timer; call from a finally block. */
+	clear(): void;
+	/** Operator-facing failure message for a fired deadline. */
+	message(): string;
+}
+
+export function armInternalDispatchDeadline(
+	dispatch: DispatchContract,
+	runId: string,
+	label: string,
+	env: NodeJS.ProcessEnv = process.env,
+	maxTimeoutMs?: number,
+): InternalDispatchDeadline {
+	const configuredTimeoutMs = resolveGuardrail("internalDispatchTimeoutMs", env);
+	const timeoutMs =
+		maxTimeoutMs === undefined ? configuredTimeoutMs : Math.min(configuredTimeoutMs, Math.max(1, maxTimeoutMs));
+	const productCapped = timeoutMs < configuredTimeoutMs;
+	let fired = false;
+	const timer = setTimeout(() => {
+		fired = true;
+		try {
+			dispatch.abort(runId, { cause: "timeout", detail: `${label} timed out after ${timeoutMs}ms` });
+		} catch {
+			// The run may have finalized between the timer firing and the abort.
+		}
+	}, timeoutMs);
+	// The timer must hold the event loop: its firing is what aborts a runaway
+	// run. Callers clear it in a finally block, so it never outlives the run.
+	return {
+		timedOut: () => fired,
+		clear: () => clearTimeout(timer),
+		message: () =>
+			productCapped
+				? `${label} exceeded its ${Math.round(timeoutMs / 1000)}s latency ceiling and was aborted.`
+				: `${label} timed out after ${Math.round(timeoutMs / 1000)}s and was aborted. ` +
+					`Raise guardrails.internalDispatchTimeoutMs (env ${GUARDRAIL_ENV_VARS.internalDispatchTimeoutMs}) for slower targets.`,
+	};
+}