@iowarp/clio-coder 0.4.4 → 0.4.5

package/skills/README.md

@@ -193,7 +193,7 @@ clio-coder skills install find-skills --project  # strongest discovered project
 
 ## Publishing: the marketplace index
 
-`npm run skills:pin` writes two files. `registry.yaml` pins content hashes and
+`pnpm run skills:pin` writes two files. `registry.yaml` pins content hashes and
 is what drift is measured against. `skill-marketplace.json` is the published
 index: one entry per skill with `name`, `description`, optional `triggers`,
 `sourceUrl` (the skill's own `clio-coder.source-url`), `version`, `audit`, and
@@ -213,7 +213,7 @@ Install then clones the repository named in that entry's `sourceUrl` and copies
 the skill out of it, so the index is only as live as the branch its URLs name.
 The catalog's `source-url` values all point at `main`; until a release branch
 lands there, an install through the index fails naming the repository, the
-branch, and the missing path. `npm run skills:check` fails if a skill's
+branch, and the missing path. `pnpm run skills:check` fails if a skill's
 `source-url` stops ending with its catalog path, which is how a skill moved
 between categories cannot ship a stale pointer.
 
@@ -292,7 +292,7 @@ dependency warnings, and other harnesses ignore it like any unknown key.
 
 The deprecated nested `clio:` mapping and legacy flat keys (`registry-id`,
 `source-url`, `audit` at the top level) are still read as fallbacks for older
-installed copies. The catalog itself must use `clio-coder:`, and `npm run
+installed copies. The catalog itself must use `clio-coder:`, and `pnpm run
 skills:check` enforces that.
 
 ### Versioning policy
@@ -350,7 +350,7 @@ names rather than mapping them. Translating `bash` to `Bash` for
 Claude-compatibility would not restrict anything; it would silently add `Bash`
 to the always-allow rules of every session that loaded the skill. The same goes
 for a `clio-coder skills export --for claude` lane, so there is no such lane. To keep
-a well-meaning edit from introducing that, `npm run skills:check` fails on any
+a well-meaning edit from introducing that, `pnpm run skills:check` fails on any
 `allowed-tools` entry that is not a Clio tool name in canonical lowercase.
 
 The rest of the surface, read from the same build:
@@ -401,10 +401,10 @@ observed writing outside its workspace. Eval numbers are evidence about a
 cooperative model, not an isolation guarantee. Run campaigns with `CLIO_CODER_*`
 pointed at throwaway directories.
 
-`npm run skills:pin` enforces this contract structurally: it refuses to pin a
+`pnpm run skills:pin` enforces this contract structurally: it refuses to pin a
 catalog where any skill is missing the required frontmatter, `audit: pass`, or
 its `evals.md`, declares a tool name Clio does not have, or carries a
-`source-url` that no longer ends with its catalog path. `npm run skills:check`
+`source-url` that no longer ends with its catalog path. `pnpm run skills:check`
 (run in CI) fails on any drift between the catalog and either generated file,
 `registry.yaml` or `skill-marketplace.json`. Each pin covers the normalized
 `SKILL.md`, not the whole skill directory. Install-lifecycle stamps such as

package/skills/registry.yaml

@@ -1,5 +1,5 @@
 # Pinned marketplace skill content hashes (provenance-stripped sha256).
-# Generated by `npm run skills:pin`. At activation, an installed skill
+# Generated by `pnpm run skills:pin`. At activation, an installed skill
 # carrying registry-id provenance is compared against its pinned hash;
 # a mismatch surfaces a drift warning.
 skills:

package/skills/skill-marketplace.json

@@ -1,5 +1,5 @@
 {
-	"generatedBy": "npm run skills:pin",
+	"generatedBy": "pnpm run skills:pin",
 	"skills": [
 		{
 			"name": "ast-grep",

package/src/cli/bootstrap-generate.ts

@@ -22,6 +22,7 @@ import {
 } from "../domains/context/index.js";
 import type { DispatchContract } from "../domains/dispatch/contract.js";
 import { DispatchDomainModule } from "../domains/dispatch/index.js";
+import { declaredScopeIntent } from "../domains/dispatch/intent.js";
 import type { RunReceipt } from "../domains/dispatch/types.js";
 import { MiddlewareDomainModule } from "../domains/middleware/index.js";
 import { createObservabilityDomainModule } from "../domains/observability/index.js";
@@ -384,6 +385,10 @@ async function generateBootstrapWithModel(
 	route?: BootstrapRoute,
 ): Promise<BootstrapStructuredOutput> {
 	const prompt = buildBootstrapPrompt(input);
+	// The internal researcher reads this repository and returns JSON. Authored
+	// handbook text is evidence, not a source of inferred filesystem authority.
+	const scope = declaredScopeIntent({ readRoots: ["."] });
+	if (!scope.ok) throw new Error(`${scope.reason}: ${scope.message}`);
 	const startedAtClock = performance.now();
 	input.progress?.({
 		phase: "generate",
@@ -393,6 +398,7 @@ async function generateBootstrapWithModel(
 	});
 	const dispatchBootstrap = (nativeSchema: boolean) =>
 		dispatch.dispatch({
+			intent: scope.intent,
 			agentId: CONTEXT_BOOTSTRAP_AGENT_ID,
 			executionRole: "researcher",
 			task: prompt,

package/src/cli/config-inspect.ts

@@ -11,7 +11,7 @@
  * everything reports the same columns.
  */
 
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { basename, join } from "node:path";
 import type { ClioSettings } from "../core/config.js";
 import { resolvePackageRoot } from "../core/package-root.js";
@@ -32,8 +32,9 @@ import {
 	readHookSources,
 	readPersistedHookReceipts,
 } from "../domains/middleware/index.js";
-import { classifyProjectPreload } from "../domains/prompts/preload.js";
+import { selectProjectPreload } from "../domains/prompts/preload.js";
 import { defaultScopedResourceRoots } from "../domains/resources/common-loader.js";
+import { createSafetyPolicyEngine } from "../domains/safety/policy-engine.js";
 import { ceilChars } from "../domains/session/context-accounting.js";
 import { capturedHookSourcesFor } from "../entry/extension-hook-sources.js";
 
@@ -120,9 +121,9 @@ function inspectClioMd(cwd: string, graph: CustomizationGraph): void {
 	if (loaded.files.length === 0) return;
 	try {
 		const promptContext = renderPromptContext(cwd);
-		const preload = classifyProjectPreload({ hasClioMd: promptContext.clioMd !== null, text: promptContext.text });
-		for (const [index, file] of loaded.files.entries()) {
-			const text = readFileSync(file.path, "utf8");
+		const preload = selectProjectPreload(promptContext, null).classification;
+		for (const [index, file] of promptContext.handbookSources.entries()) {
+			const text = file.source;
 			graph.entries.push({
 				category: "clio-md",
 				id: basename(file.path),
@@ -130,15 +131,19 @@ function inspectClioMd(cwd: string, graph: CustomizationGraph): void {
 				sourcePath: file.path,
 				hash: shortHash(text),
 				trust: "trusted",
-				precedence: loaded.files.length === 1 ? "single" : "layer",
+				precedence: promptContext.handbookSources.length === 1 ? "single" : "layer",
 				reloadClass: "next-turn",
 				contextCostTokens: ceilChars(text.length),
 				detail: {
 					layer: index + 1,
-					layers: loaded.files.length,
+					layers: promptContext.handbookSources.length,
 					preload: preload.label,
 					preloadChars: preload.chars,
 					preloadLines: preload.lines,
+					preloadIncludedChars: preload.includedChars ?? 0,
+					preloadIncludedLines: preload.includedLines ?? 0,
+					preloadSourceIncludedChars: preload.sources?.[index]?.includedChars ?? 0,
+					preloadSourceHash: preload.sources?.[index]?.contentHash ?? "",
 					...(preload.nearLimit ? { preloadNearLimit: true } : {}),
 				},
 			});
@@ -367,6 +372,18 @@ function inspectResourceRoots(cwd: string, graph: CustomizationGraph): void {
 function inspectSafetyAndMemory(cwd: string, graph: CustomizationGraph): void {
 	try {
 		const layered = readLayeredSettings(cwd);
+		const metadata = createSafetyPolicyEngine({ cwd }).metadata();
+		graph.entries.push({
+			category: "safety",
+			id: "safety.policy",
+			scope: "effective",
+			reloadClass: "next-turn",
+			trust: metadata.workspaceTrustVerdict === "trusted" ? "trusted" : "untrusted",
+			precedence: "single",
+			...(metadata.projectPolicyPath === null ? {} : { sourcePath: metadata.projectPolicyPath }),
+			detail: { ...metadata },
+		});
+
 		graph.entries.push({
 			category: "safety",
 			id: "safety.autonomy",

package/src/cli/config-trust.ts

@@ -0,0 +1,62 @@
+import {
+	captureProjectSurface,
+	type ProjectTrustSurface,
+	recordProjectSurfaceTrust,
+	revokeProjectSurfaceTrust,
+} from "../core/workspace-trust.js";
+import { printError } from "./shared.js";
+
+const SURFACES: ReadonlyArray<ProjectTrustSurface> = ["safety", "hooks", "settings"];
+
+/** Review is read-only. Approval names the digest the operator reviewed, so edits cannot borrow stale consent. */
+export function runConfigTrustCommand(args: ReadonlyArray<string>, cwd = process.cwd()): number {
+	const surface = args[0] as ProjectTrustSurface | undefined;
+	if (surface === undefined || !SURFACES.includes(surface)) {
+		printError("usage: clio-coder config trust safety|hooks|settings [--json | --hash SHA256 | --revoke]");
+		return 2;
+	}
+	const rest = args.slice(1);
+	const preview = rest.length === 0 || (rest.length === 1 && rest[0] === "--json");
+	const revoke = rest.length === 1 && rest[0] === "--revoke";
+	const approve = rest.length === 2 && rest[0] === "--hash" && /^[a-f0-9]{64}$/.test(rest[1] ?? "");
+	if (!preview && !revoke && !approve) {
+		printError("trust expects --json, --revoke, or --hash followed by the full reviewed SHA-256 digest");
+		return 2;
+	}
+	try {
+		if (revoke) {
+			revokeProjectSurfaceTrust(cwd, surface);
+			process.stdout.write(
+				`Project ${surface} trust revoked. Restart to reload settings and safety; project hooks stop before their next execution.\n`,
+			);
+			return 0;
+		}
+		const snapshot = captureProjectSurface(cwd, surface);
+		if (preview) {
+			// JSON escapes terminal control sequences in repository-controlled text.
+			process.stdout.write(`${JSON.stringify(snapshot, null, 2)}\n`);
+			if (rest[0] !== "--json" && snapshot.contentHash !== null && snapshot.files.some((file) => file.text !== null)) {
+				process.stdout.write(
+					`Review the captured files above. Approve exactly these bytes with:\nclio-coder config trust ${surface} --hash ${snapshot.contentHash}\n`,
+				);
+			}
+			return 0;
+		}
+		if (snapshot.contentHash === null || !snapshot.files.some((file) => file.text !== null)) {
+			printError(`no readable project ${surface} files to approve`);
+			return 1;
+		}
+		if (snapshot.contentHash !== rest[1]) {
+			printError(`project ${surface} changed since review; inspect it again before approving`);
+			return 1;
+		}
+		recordProjectSurfaceTrust(snapshot.workspaceRoot, surface, snapshot.contentHash);
+		process.stdout.write(
+			`Project ${surface} approved for ${snapshot.workspaceRoot} at ${snapshot.contentHash}. Restart to reload settings and safety; reload extensions to register newly approved hooks.\n`,
+		);
+		return 0;
+	} catch (error) {
+		printError(error instanceof Error ? error.message : String(error));
+		return 1;
+	}
+}

package/src/cli/config.ts

@@ -1,7 +1,9 @@
 import { buildCustomizationGraph, type CustomizationEntry } from "./config-inspect.js";
+import { runConfigTrustCommand } from "./config-trust.js";
 import { printError } from "./shared.js";
 
 const HELP = `clio-coder config inspect [--json]
+clio-coder config trust safety|hooks|settings [--json | --hash SHA256 | --revoke]
 
 Print the effective-customization graph: what settings, context files, rules,
 skills, prompts, agents, fleets, extensions, safety, memory, hooks, and the operator
@@ -10,6 +12,10 @@ context cost. Read-only; nothing is created.
 
 This is the "why is Clio behaving this way" surface. Parse the --json form in
 scripts instead of the table.
+
+Trust previews show the captured project files and their digest. Approve only
+the reviewed digest with --hash, or remove a surface's approval with --revoke.
+Settings and safety reload on restart; project hooks also check trust before execution.
 `;
 
 function renderText(cwd: string): string {
@@ -37,6 +43,7 @@ function renderText(cwd: string): string {
 			const precedence = entry.precedence ? `, ${entry.precedence}` : "";
 			out.push(`  ${entry.id}  [${entry.scope}${precedence}, reload:${entry.reloadClass}${hash}${cost}]`);
 			if (entry.sourcePath) out.push(`    from ${entry.sourcePath}`);
+			if (entry.id === "safety.policy" && entry.detail !== undefined) out.push(`    ${JSON.stringify(entry.detail)}`);
 		}
 		out.push("");
 	}
@@ -56,6 +63,7 @@ export function runConfigCommand(args: ReadonlyArray<string> = []): number {
 	}
 	const positional = args.filter((arg) => !arg.startsWith("-"));
 	const sub = positional[0] ?? "inspect";
+	if (sub === "trust") return runConfigTrustCommand(args.slice(1));
 	if (sub !== "inspect") {
 		printError(`unknown config subcommand: ${sub}`);
 		process.stderr.write(HELP);

package/src/cli/context-map.ts

@@ -1,8 +1,10 @@
 import { execFileSync } from "node:child_process";
-import { mkdirSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { CLIO_ARTIFACT_DIR } from "../core/artifact-paths.js";
-import { readCodewiki } from "../domains/context/codewiki/artifact.js";
+import { type CodewikiCoordinatedResult, coordinateCodewikiWrite } from "../domains/context/codewiki/coordinator.js";
+import type { Codewiki } from "../domains/context/codewiki/schema.js";
 import { buildArchitectureSeed, serializeArchitectureSeed } from "../domains/context/wiki/map-seed.js";
 
 const HELP = `Usage:
@@ -11,7 +13,8 @@ const HELP = `Usage:
 Write an archify architecture seed for the current repository from the codewiki
 index, without model calls. The seed is the starting spec for the archify skill:
 components are the largest directory areas, connections are collapsed import
-edges, and sources point at indexed files and lines.
+edges. The index is reconciled with current files before mapping; sources are
+pinned only when clean Git evidence matches those files.
 
 Options:
   --out <path>    where to write the seed (default: ${CLIO_ARTIFACT_DIR}/maps/<repo>.architecture.json)
@@ -28,21 +31,53 @@ function gitValue(cwd: string, args: string[]): string | null {
 		const out = execFileSync("git", args, { cwd, timeout: 5000, stdio: ["ignore", "pipe", "ignore"] })
 			.toString("utf8")
 			.trim();
-		return out.length > 0 ? out : null;
+		return out;
 	} catch {
 		return null;
 	}
 }
 
-/** The origin remote as an https URL and HEAD as a full sha, when git can say. */
-function repositoryFacts(cwd: string): { url: string; revision: string } | undefined {
-	const remote = gitValue(cwd, ["remote", "get-url", "origin"]);
+type SourceState = "clean" | "dirty" | "unknown";
+
+/** A successful empty status means clean; unavailable Git evidence never does. */
+function repositoryFacts(
+	cwd: string,
+	codewiki: Codewiki,
+	indexedHead: string | null,
+): { sourceState: SourceState; repository?: { url: string; revision: string } } {
 	const revision = gitValue(cwd, ["rev-parse", "--verify", "HEAD"]);
-	if (!remote || !revision) return undefined;
+	const status = gitValue(cwd, ["status", "--porcelain", "--untracked-files=normal"]);
+	if (!revision || status === null) return { sourceState: "unknown" };
+	if (status !== "" || revision !== indexedHead) return { sourceState: "dirty" };
+	// Source paths in the seed are workspace-relative. A nested workspace has
+	// no proven repository-relative path mapping, so cannot supply citations.
+	if (gitValue(cwd, ["rev-parse", "--show-prefix"]) !== "") return { sourceState: "unknown" };
+	const tree = gitValue(cwd, ["ls-tree", "-r", "-z", revision]);
+	if (tree === null) return { sourceState: "unknown" };
+	const blobs = new Map<string, string>();
+	for (const entry of tree.split("\0")) {
+		const match = /^100[0-7]{3} blob ([a-f0-9]{40})\t([\s\S]+)$/.exec(entry);
+		if (match) blobs.set(match[2] as string, match[1] as string);
+	}
+	try {
+		for (const file of codewiki.files) {
+			const contents = readFileSync(path.join(cwd, file.path));
+			// Verify both parser input identity and immutable Git blob identity.
+			// This also catches ignored/untracked inputs and assume-unchanged files
+			// that a successful `git status` alone cannot certify.
+			const indexedHash = createHash("sha256").update(contents.toString("utf8")).digest("hex").slice(0, 16);
+			const blob = createHash("sha1").update(`blob ${contents.length}\0`).update(contents).digest("hex");
+			if (indexedHash !== file.hash || blobs.get(file.path) !== blob) return { sourceState: "dirty" };
+		}
+	} catch {
+		return { sourceState: "unknown" };
+	}
+	const remote = gitValue(cwd, ["remote", "get-url", "origin"]);
+	if (!remote) return { sourceState: "clean" };
 	let url = remote.endsWith(".git") ? remote.slice(0, -4) : remote;
 	const ssh = /^git@([^:]+):(.+)$/.exec(url);
 	if (ssh) url = `https://${ssh[1]}/${ssh[2]}`;
-	return { url, revision };
+	return { sourceState: "clean", repository: { url, revision } };
 }
 
 export async function runContextMapCommand(args: string[]): Promise<number> {
@@ -72,16 +107,40 @@ export async function runContextMapCommand(args: string[]): Promise<number> {
 		return 2;
 	}
 	const cwd = process.cwd();
-	const codewiki = readCodewiki(cwd);
-	if (!codewiki) {
+	let reconciled: CodewikiCoordinatedResult | null;
+	try {
+		reconciled = await coordinateCodewikiWrite(
+			cwd,
+			(current, workspace) =>
+				current
+					? {
+							kind: "ensure",
+							cwd: workspace,
+							current,
+							language: current.language,
+							// Map evidence must reconcile actual inputs, even if a state file
+							// happens to carry a matching fingerprint from another operation.
+							previous: null,
+						}
+					: null,
+			{ requireExisting: true },
+		);
+	} catch (error) {
+		process.stderr.write(
+			`clio-coder context map: index refresh failed: ${error instanceof Error ? error.message : String(error)}\n`,
+		);
+		return 1;
+	}
+	if (!reconciled) {
 		process.stderr.write(
 			"clio-coder context map: no codewiki index in .clio-coder/codewiki.json; run `clio-coder context index` first\n",
 		);
 		return 1;
 	}
-	const seed = buildArchitectureSeed(codewiki, {
+	const facts = repositoryFacts(cwd, reconciled.codewiki, reconciled.worker.fingerprint.gitHead);
+	const seed = buildArchitectureSeed(reconciled.codewiki, {
 		title: path.basename(cwd),
-		repository: repositoryFacts(cwd),
+		repository: facts.repository,
 	});
 	const target = out ? path.resolve(cwd, out) : defaultMapSeedPath(cwd);
 	mkdirSync(path.dirname(target), { recursive: true });
@@ -91,6 +150,8 @@ export async function runContextMapCommand(args: string[]): Promise<number> {
 		components: seed.components.length,
 		connections: seed.connections.length,
 		repository: seed.meta.repository ?? null,
+		index: "reconciled",
+		sourceState: facts.sourceState,
 	};
 	if (json) {
 		process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
@@ -102,7 +163,7 @@ export async function runContextMapCommand(args: string[]): Promise<number> {
 			`  ${payload.components} components, ${payload.connections} connections${
 				payload.repository
 					? `, sources pinned at ${payload.repository.revision.slice(0, 12)}`
-					: "; no GitHub origin at a full revision, so no source citations"
+					: `; no source citations (source state: ${payload.sourceState}; requires verified clean files and a GitHub origin at a full revision)`
 			}`,
 			payload.repository
 				? "  next: validate and deliver it with the archify skill, passing --repo-root ."

package/src/cli/context.ts

@@ -1,12 +1,15 @@
 import { join, resolve } from "node:path";
 import type { BootstrapProgressEvent } from "../domains/context/index.js";
 import type { BootstrapGenerationState } from "../domains/context/state.js";
+import type { RunWikiGenerateResult } from "../domains/context/wiki/generate.js";
+import type { WikiMeta } from "../domains/context/wiki/meta.js";
+import { MAX_PAGE_ATTEMPTS } from "../domains/context/wiki/plan-store.js";
 
 const HELP = `Usage:
   clio-coder context
   clio-coder context init [--yes] [--preview|--heuristic] [--adopt] [--propose|--apply|--rewrite]
   clio-coder context refresh [--wiki]
-  clio-coder context wiki [--update] [--status] [--depth auto|simple|medium|detailed]
+  clio-coder context wiki [--update|--retry-pending] [--status] [--depth auto|simple|medium|detailed]
                     [--target <id>] [--model <id>] [--thinking off|low|medium|high]
   clio-coder context reset [--all] [--yes]
   clio-coder context index [--json]
@@ -32,6 +35,36 @@ function printWikiProgress(event: BootstrapProgressEvent): void {
 	process.stderr.write(`clio-coder context wiki: ${event.message}${detail}\n`);
 }
 
+function wikiRecoveryLines(meta: WikiMeta | null): string[] {
+	const pending = meta?.plan?.pages.filter((page) => page.status !== "written") ?? [];
+	if (pending.length === 0) return [];
+	const exhausted = pending.filter((page) => page.attempts >= MAX_PAGE_ATTEMPTS).length;
+	const failures = pending.filter((page) => page.lastFailure);
+	return [
+		`pending: ${pending.length} page(s)${exhausted > 0 ? `; ${exhausted} exhausted ordinary writer attempts` : ""}`,
+		...failures.slice(0, 8).map((page) => `${page.path}: ${page.lastFailure?.phase}: ${page.lastFailure?.detail}`),
+		...(failures.length > 8 ? [`${failures.length - 8} more page failures retained in wiki metadata`] : []),
+		"Run `clio-coder context wiki --retry-pending` to retry pending pages once, including exhausted pages, without replanning.",
+	];
+}
+
+function printWikiOutcome(prefix: string, result: RunWikiGenerateResult, meta: WikiMeta | null): void {
+	const pending = result.pending ?? meta?.plan?.pages.filter((page) => page.status !== "written").length ?? 0;
+	const complete = meta?.plan
+		? meta.plan.pages.filter((page) => page.status === "written").length
+		: (meta?.generation?.pagesWritten ?? Math.max(0, result.pages - pending));
+	const published = `${result.pages} published page${result.pages === 1 ? "" : "s"}`;
+	const progress = `${complete} complete, ${pending} pending`;
+	const outcome = pending > 0 ? "incomplete" : result.status === "noop" ? "unchanged" : "generated";
+	process.stdout.write(`${prefix}: ${outcome} (${published}; ${progress})\n`);
+	if (pending > 0) {
+		const recovery = wikiRecoveryLines(meta);
+		process.stdout.write(
+			`${recovery.length > 0 ? recovery.join("\n") : "Run `clio-coder context wiki --update` to continue pending pages."}\n`,
+		);
+	}
+}
+
 function compactMetric(value: number, suffix: string): string {
 	if (value < 1000) return `${value}${suffix}`;
 	return `${(value / 1000).toFixed(1)}k${suffix}`;
@@ -82,10 +115,7 @@ async function printContextStatus(): Promise<number> {
 					: "ok";
 
 	const prompt = context.renderPromptContext(cwd);
-	const preloadClass = preload.classifyProjectPreload({
-		hasClioMd: prompt.clioMd !== null,
-		text: prompt.text,
-	});
+	const preloadClass = preload.selectProjectPreload(prompt, null).classification;
 
 	const codewiki = context.readCodewiki(cwd);
 	const codewikiCount = codewiki ? context.codewikiEntries(codewiki).length : 0;
@@ -134,7 +164,7 @@ async function runRefreshCommand(args: string[]): Promise<number> {
 		return 2;
 	}
 	try {
-		const { runContextRefresh } = await import("../domains/context/index.js");
+		const { runContextRefresh, readWikiMeta } = await import("../domains/context/index.js");
 		const wikiEntry = updateWiki ? await import("./wiki-generate.js") : null;
 		const result = await runContextRefresh({
 			cwd: process.cwd(),
@@ -155,11 +185,7 @@ async function runRefreshCommand(args: string[]): Promise<number> {
 				);
 				return 1;
 			}
-			process.stdout.write(
-				result.wiki.status === "noop"
-					? `clio-coder context refresh: wiki unchanged (${result.wiki.pages} page${result.wiki.pages === 1 ? "" : "s"})\n`
-					: `clio-coder context refresh: wiki updated (${result.wiki.pages} page${result.wiki.pages === 1 ? "" : "s"})\n`,
-			);
+			printWikiOutcome("clio-coder context refresh: wiki", result.wiki, readWikiMeta(process.cwd()));
 		}
 		return 0;
 	} catch (err) {
@@ -189,10 +215,11 @@ async function runWikiStatusCommand(): Promise<number> {
 			`depth: ${depth} (requested ${requestedDepth}; ${sourceFiles} source files; ` +
 				`${pagesWritten}/${pagesPlanned} planned pages written)`,
 		);
-		if (pagesWritten < pagesPlanned) {
+		if (pagesWritten < pagesPlanned && !meta.plan) {
 			lines.push(`pending: ${pagesPlanned - pagesWritten} page(s); run \`clio-coder context wiki --update\` to finish`);
 		}
 	}
+	lines.push(...wikiRecoveryLines(meta));
 	if (currentHead !== meta.gitHead) {
 		lines.push(`staleness: gitHead differs from current HEAD (${currentHead ?? "none"})`);
 	}
@@ -215,6 +242,7 @@ function isThinkingLevel(value: unknown): value is WikiCliThinking {
 
 async function runWikiCommand(args: string[]): Promise<number> {
 	let forceUpdate = false;
+	let retryPending = false;
 	let status = false;
 	let depth: WikiCliDepth = "auto";
 	let target: string | undefined;
@@ -230,6 +258,10 @@ async function runWikiCommand(args: string[]): Promise<number> {
 			forceUpdate = true;
 			continue;
 		}
+		if (arg === "--retry-pending") {
+			retryPending = true;
+			continue;
+		}
 		if (arg === "--status") {
 			status = true;
 			continue;
@@ -277,6 +309,7 @@ async function runWikiCommand(args: string[]): Promise<number> {
 		const result = await context.runWikiGenerate({
 			cwd: process.cwd(),
 			...(forceUpdate ? { mode: "update" as const } : {}),
+			...(retryPending ? { retryPending: true } : {}),
 			depth,
 			model: await resolveDocumenterModelId(route),
 			generate: modelWikiGenerate({ route }),
@@ -286,11 +319,7 @@ async function runWikiCommand(args: string[]): Promise<number> {
 			process.stderr.write(`clio-coder context wiki failed: ${(result.problems ?? ["unknown failure"]).join("; ")}\n`);
 			return 1;
 		}
-		process.stdout.write(
-			result.status === "noop"
-				? `clio-coder context wiki: unchanged (${result.pages} page${result.pages === 1 ? "" : "s"})\n`
-				: `clio-coder context wiki: generated ${result.pages} page${result.pages === 1 ? "" : "s"}\n`,
-		);
+		printWikiOutcome("clio-coder context wiki", result, context.readWikiMeta(process.cwd()));
 		return 0;
 	} catch (err) {
 		process.stderr.write(`clio-coder context wiki failed: ${err instanceof Error ? err.message : String(err)}\n`);

package/src/cli/eval.ts

@@ -1,7 +1,9 @@
+import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { InvalidIdError } from "../core/safe-id.js";
+import { shellQuote } from "../core/shell-quote.js";
 import { clioDataDir } from "../core/xdg.js";
-import { loadEvalArtifactV4, writeEvalArtifactV4 } from "../domains/eval/artifacts/store.js";
+import { loadEvalArtifactV4, parseEvalArtifactV4, writeEvalArtifactV4 } from "../domains/eval/artifacts/store.js";
 import { compareEvalArtifactsV4 } from "../domains/eval/compare/compare.js";
 import { evaluateGate, renderGateFailure, renderInformationalBudget } from "../domains/eval/compare/gates.js";
 import { loadThresholds } from "../domains/eval/compare/thresholds.js";
@@ -50,6 +52,7 @@ interface ParsedEvalArgs {
 	out?: string;
 	clioEntry?: string;
 	evalId?: string;
+	artifact?: string;
 	format: EvalReportFormat;
 	compareIds: string[];
 	metric?: string;
@@ -133,6 +136,11 @@ function parseEvalArgs(args: ReadonlyArray<string>): ParsedEvalArgs {
 			throw new Error(`unknown eval run argument: ${arg}`);
 		}
 		if (parsed.command === "report") {
+			if (arg === "--artifact") {
+				parsed.artifact = requiredValue(args, index, "--artifact");
+				index += 1;
+				continue;
+			}
 			if (arg === "--format") {
 				parsed.format = reportFormat(requiredValue(args, index, "--format"));
 				index += 1;
@@ -189,7 +197,9 @@ function parseEvalArgs(args: ReadonlyArray<string>): ParsedEvalArgs {
 	if (parsed.command === "run" && (parsed.suite === undefined) === (parsed.taskFile === undefined)) {
 		throw new Error("run requires exactly one of --suite or --task-file");
 	}
-	if (parsed.command === "report" && parsed.evalId === undefined) throw new Error("report requires an eval id");
+	if (parsed.command === "report" && (parsed.evalId === undefined) === (parsed.artifact === undefined)) {
+		throw new Error("report requires exactly one of an eval id or --artifact <path>");
+	}
 	if (parsed.command === "compare" && parsed.compareIds.length !== 2) {
 		throw new Error("compare requires <baselineEvalId> <candidateEvalId>");
 	}
@@ -259,6 +269,7 @@ async function runEvalRun(parsed: ParsedEvalArgs): Promise<number> {
 		);
 		const artifactPath = await writeEvalArtifactV4(clioDataDir(), artifact, parsed.out);
 		process.stdout.write(`${renderEvalTextReportV4(artifact)}artifact: ${artifactPath}\n`);
+		process.stdout.write(`report: clio-coder eval report --artifact ${shellQuote(resolve(artifactPath))} --format md\n`);
 		// A suite that declares thresholds is gated by them here, on the artifact
 		// it just produced. Declaring a gate that only a later `eval gate`
 		// invocation enforces means the run that broke it still exited zero.
@@ -280,7 +291,10 @@ async function runEvalRun(parsed: ParsedEvalArgs): Promise<number> {
 async function runEvalReportCommand(parsed: ParsedEvalArgs): Promise<number> {
 	try {
 		const dataDir = clioDataDir();
-		const artifact = await loadEvalArtifactV4(dataDir, parsed.evalId ?? "");
+		const artifact =
+			parsed.artifact === undefined
+				? await loadEvalArtifactV4(dataDir, parsed.evalId ?? "")
+				: parseEvalArtifactV4(JSON.parse(await readFile(parsed.artifact, "utf8")) as unknown, parsed.artifact);
 		process.stdout.write(renderArtifactReport(artifact, parsed.format, dataDir));
 		return 0;
 	} catch (error) {