@iowarp/clio-coder 0.4.3 → 0.4.5

package/src/cli/wiki-generate.ts

@@ -1,12 +1,15 @@
 import { existsSync } from "node:fs";
-import { join } from "node:path";
+import { join, relative } from "node:path";
 import { performance } from "node:perf_hooks";
 import { type LoadResult, loadDomains } from "../core/domain-loader.js";
+import { asDirectoryPathBoundary } from "../core/path-boundary.js";
+import { runWithBudget, writeShutdownNotice } from "../core/termination.js";
 import { ToolNames } from "../core/tool-names.js";
 import { AgentsDomainModule } from "../domains/agents/index.js";
 import type { ConfigContract } from "../domains/config/contract.js";
 import { ConfigDomainModule } from "../domains/config/index.js";
 import { ContextDomainModule } from "../domains/context/runtime.js";
+import { inspectWikiPageEvidence } from "../domains/context/wiki/evidence.js";
 import type { WikiGenerate, WikiGenerateInput } from "../domains/context/wiki/generate.js";
 import type { WikiPlan, WikiPlanPage } from "../domains/context/wiki/plan.js";
 import {
@@ -18,6 +21,7 @@ import {
 import { buildWikiPagePrompt, buildWikiPlanPrompt } from "../domains/context/wiki/prompts.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 type { JobSpec, JobThinkingLevel } from "../domains/dispatch/validation.js";
 import { MiddlewareDomainModule } from "../domains/middleware/index.js";
@@ -28,7 +32,6 @@ import { ResourcesDomainModule } from "../domains/resources/index.js";
 import { SafetyDomainModule } from "../domains/safety/index.js";
 import { SchedulingDomainModule } from "../domains/scheduling/index.js";
 import { SessionDomainModule } from "../domains/session/index.js";
-import { armInternalDispatchDeadline } from "./internal-dispatch.js";
 
 /**
  * Model id recorded on wiki metadata when the documenter target cannot be
@@ -41,25 +44,10 @@ const UNRESOLVED_DOCUMENTER_MODEL = "unresolved-documenter-target";
 /** The agent recipe that plans and writes pages. */
 const WIKI_AGENT_ID = "wiki-writer";
 
-/**
- * Wall-clock ceiling for one page dispatch, clamped against the configured
- * internal-dispatch guardrail. A page is a small job: read a handful of named
- * sources and write one file. Bounding it here is what keeps one degenerate
- * page from consuming the time every other page needed, and losing it costs
- * exactly that page because the plan records it as still owed.
- */
-const PAGE_DEADLINE_MS = 6 * 60 * 1000;
-
-/** Wall-clock ceiling for the single planning dispatch. */
-const PLAN_DEADLINE_MS = 8 * 60 * 1000;
-
-/**
- * Wall-clock budget for a whole generation, checked between page dispatches and
- * never during one. Exceeding it ends the run cleanly with every finished page
- * promoted and the rest recorded as owed, so a repository too large for one
- * sitting is finished by the next run instead of failing forever.
- */
-const RUN_BUDGET_MS = 60 * 60 * 1000;
+/** Planning estimates inform progress, never admission or execution limits. */
+const PAGE_ESTIMATE_MS = 6 * 60 * 1000;
+const PLAN_ESTIMATE_MS = 8 * 60 * 1000;
+const RUN_ESTIMATE_MS = 60 * 60 * 1000;
 
 export interface WikiModelRoute {
 	target?: string;
@@ -70,8 +58,10 @@ export interface WikiModelRoute {
 export interface ModelWikiGenerateOptions {
 	dispatch?: DispatchContract;
 	route?: WikiModelRoute;
-	/** Overrides the whole-run wall-clock budget. Tests use it to force an early stop. */
+	/** Explicit whole-run duration; omission leaves ordinary estimates advisory. */
 	runBudgetMs?: number;
+	/** Explicit absolute deadline, shared unchanged by planning and every page. */
+	deadlineAt?: number;
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -122,13 +112,7 @@ interface DispatchSummary {
 	mix: string;
 }
 
-/**
- * Longest an in-flight phase may go without saying anything. The planner is
- * allowed eight minutes and a page six, and the operator who reported this saw
- * two lines in five minutes, concluded the command had deadlocked, and killed
- * it. Narrating every tool call would scroll the terminal for nothing, so the
- * heartbeat is throttled to this and carries only elapsed time and tool count.
- */
+/** Throttle activity summaries so long-running healthy work remains visible. */
 const HEARTBEAT_MS = 30_000;
 
 /**
@@ -180,9 +164,30 @@ function summaryDetail(summary: DispatchSummary, startedAtClock: number): string
 	);
 }
 
-interface WikiDispatchOutcome {
-	ok: boolean;
-	detail: string;
+type WikiDispatchOutcome =
+	| { ok: false; phase: "admission"; detail: string }
+	| { ok: boolean; phase: "writer"; detail: string; runId: string };
+
+interface WikiDeadline {
+	at: number;
+	remainingMs(): number;
+}
+
+function explicitWikiDeadline(options: ModelWikiGenerateOptions): WikiDeadline | undefined {
+	if (options.runBudgetMs !== undefined && (!Number.isFinite(options.runBudgetMs) || options.runBudgetMs < 0))
+		throw new Error("wiki runBudgetMs must be a finite non-negative duration");
+	if (options.deadlineAt !== undefined && !Number.isFinite(options.deadlineAt))
+		throw new Error("wiki deadlineAt must be a finite timestamp");
+	if (options.deadlineAt === undefined && options.runBudgetMs === undefined) return undefined;
+	const wallNow = Date.now();
+	const at = Math.min(
+		options.deadlineAt ?? Number.POSITIVE_INFINITY,
+		wallNow + (options.runBudgetMs ?? Number.POSITIVE_INFINITY),
+	);
+	if (!Number.isFinite(new Date(at).getTime())) throw new Error("wiki deadline exceeds the supported timestamp range");
+	const clockNow = performance.now();
+	// Keep the admission timestamp fixed while elapsed enforcement is monotonic.
+	return { at, remainingMs: () => at - wallNow - (performance.now() - clockNow) };
 }
 
 /**
@@ -195,22 +200,33 @@ async function runWikiDispatch(input: {
 	cwd: string;
 	outputDir: string;
 	task: string;
+	/** Caller-owned page path, relative to cwd; the planner remains unbound. */
+	artifactPath?: string;
 	route: WikiModelRoute;
-	deadlineMs: number;
-	label: string;
+	deadline: WikiDeadline | undefined;
 	/** Liveness signal while the dispatch runs, already throttled by the caller. */
 	onHeartbeat?: (info: { elapsedMs: number; tools: number }) => void;
 }): Promise<WikiDispatchOutcome> {
-	// `startedAt` is a wall anchor because the admission deadline below is one
-	// too; every elapsed figure spans the monotonic twin instead.
-	const startedAt = Date.now();
 	const startedAtClock = performance.now();
 	let handle: Awaited<ReturnType<DispatchContract["dispatch"]>>;
 	try {
+		if (input.deadline && input.deadline.remainingMs() <= 0)
+			throw new Error("explicit wiki deadline reached before admission");
+		const stagingRoot = relative(input.cwd, input.outputDir);
+		if (!stagingRoot) throw new Error("wiki staging directory must be below the repository root");
+		// The repository is readable; only this staging tree is writable. Declare
+		// those paths directly so absolute filenames in prompt prose cannot become
+		// legacy scope tokens (including a sentence-ending period).
+		const scope = declaredScopeIntent({ readRoots: ["."], writeRoots: [asDirectoryPathBoundary(stagingRoot)] });
+		if (!scope.ok) throw new Error(`${scope.reason}: ${scope.message}`);
 		handle = await input.dispatch.dispatch({
+			intent: scope.intent,
 			agentId: WIKI_AGENT_ID,
 			executionRole: "builder",
 			task: input.task,
+			...(input.artifactPath !== undefined
+				? { resultContractOverride: { kind: "artifact-report" as const, path: input.artifactPath } }
+				: {}),
 			cwd: input.cwd,
 			requestOrigin: "internal",
 			noSkills: true,
@@ -222,21 +238,29 @@ async function runWikiDispatch(input: {
 			denyTools: [ToolNames.Git],
 			// Containment: the worker safety seam blocks any write-class tool call
 			// whose target escapes the staging dir.
-			writeRoots: [input.outputDir],
-			// Admission patience must match execution patience. Without this the
-			// queue applies its 60s default while `deadlineMs` below allows six
-			// minutes to run, so a page waiting behind two in-flight writers was
-			// dropped before it ever started. Observed live: a 33-page plan lost
-			// `core.md` to `dispatch: admission timed_out` at 10/33 while every
-			// page ahead of it was taking 110 to 125 seconds. A page the caller is
-			// willing to wait six minutes for is a page it should be willing to
-			// queue for six minutes.
-			assignmentDeadlineAt: startedAt + input.deadlineMs,
+			writeRoots: [asDirectoryPathBoundary(input.outputDir)],
+			// Only an explicit caller deadline constrains admission; recipe estimates
+			// must not become assignment deadlines or restart for each page.
+			...(input.deadline ? { assignmentDeadlineAt: input.deadline.at } : {}),
 		});
 	} catch (err) {
-		return { ok: false, detail: err instanceof Error ? err.message : String(err) };
+		return { ok: false, phase: "admission", detail: err instanceof Error ? err.message : String(err) };
 	}
-	const deadline = armInternalDispatchDeadline(input.dispatch, handle.runId, input.label, input.deadlineMs);
+	let timedOut = false;
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const armDeadline = (): void => {
+		if (!input.deadline) return;
+		const remaining = input.deadline.remainingMs();
+		if (remaining <= 0) {
+			timedOut = true;
+			input.dispatch.abort(handle.runId, { cause: "timeout", detail: "explicit wiki deadline reached" });
+			return;
+		}
+		// Long explicit deadlines must not overflow Node's timer range into 1ms.
+		timer = setTimeout(armDeadline, Math.min(remaining, 2_147_483_647));
+		timer.unref();
+	};
+	armDeadline();
 	let lastHeartbeatAt = startedAtClock;
 	try {
 		const summary = await drainDispatchEvents(handle.events, (tools) => {
@@ -246,25 +270,42 @@ async function runWikiDispatch(input: {
 			input.onHeartbeat({ elapsedMs: Math.round(nowMs - startedAtClock), tools });
 		});
 		const receipt = await handle.finalPromise;
-		if (deadline.timedOut()) return { ok: false, detail: `timed out; ${summaryDetail(summary, startedAtClock)}` };
+		if (timedOut)
+			return {
+				ok: false,
+				phase: "writer",
+				runId: handle.runId,
+				detail: `timed out; ${summaryDetail(summary, startedAtClock)}`,
+			};
 		if (receipt.exitCode !== 0) {
 			input.dispatch.abort(handle.runId);
-			return { ok: false, detail: `${receiptFailure(receipt)}; ${summaryDetail(summary, startedAtClock)}` };
+			return {
+				ok: false,
+				phase: "writer",
+				runId: handle.runId,
+				detail: `${receiptFailure(receipt)}; ${summaryDetail(summary, startedAtClock)}`,
+			};
 		}
-		return { ok: true, detail: summaryDetail(summary, startedAtClock) };
+		return { ok: true, phase: "writer", runId: handle.runId, detail: summaryDetail(summary, startedAtClock) };
 	} catch (err) {
-		if (!deadline.timedOut()) input.dispatch.abort(handle.runId);
+		if (!timedOut) input.dispatch.abort(handle.runId);
 		await handle.finalPromise.catch(() => undefined);
-		const reason = deadline.timedOut() ? "timed out" : err instanceof Error ? err.message : String(err);
-		return { ok: false, detail: `${reason}; ${formatElapsed(performance.now() - startedAtClock)}` };
+		const reason = timedOut ? "timed out" : err instanceof Error ? err.message : String(err);
+		return {
+			ok: false,
+			phase: "writer",
+			runId: handle.runId,
+			detail: `${reason}; ${formatElapsed(performance.now() - startedAtClock)}`,
+		};
 	} finally {
-		deadline.clear();
+		clearTimeout(timer);
 	}
 }
 
 function receiptFailure(receipt: RunReceipt): string {
 	const code = receipt.outcomeCode ? ` (${receipt.outcomeCode})` : "";
-	return `exit ${receipt.exitCode}${code}`;
+	const detail = receipt.outcomeDetail?.replace(/\s+/gu, " ").slice(0, 350);
+	return `exit ${receipt.exitCode}${code}${detail ? `: ${detail}` : ""}`;
 }
 
 /**
@@ -276,6 +317,7 @@ async function runPlanPhase(
 	dispatch: DispatchContract,
 	input: WikiGenerateInput,
 	route: WikiModelRoute,
+	deadline: WikiDeadline | undefined,
 ): Promise<WikiPlan> {
 	input.progress?.({ phase: "generate", status: "running", message: "planning wiki pages" });
 	const outcome = await runWikiDispatch({
@@ -293,14 +335,13 @@ async function runPlanPhase(
 			gitHead: input.gitHead ?? null,
 		}),
 		route,
-		deadlineMs: PLAN_DEADLINE_MS,
-		label: "wiki planner",
+		deadline,
 		onHeartbeat: ({ elapsedMs, tools }) =>
 			input.progress?.({
 				phase: "generate",
 				status: "running",
 				message: `still planning (${formatElapsed(elapsedMs)}, ${tools} tool calls)`,
-				detail: `planner deadline ${Math.round(PLAN_DEADLINE_MS / 60000)}m`,
+				detail: `planner estimate ${Math.round(PLAN_ESTIMATE_MS / 60000)}m; healthy work may continue longer`,
 			}),
 	});
 	const revised = readAuthoredWikiPlan(input.outputDir, input.plan);
@@ -324,49 +365,72 @@ async function runPagePhase(
 	page: WikiPlanPage,
 	route: WikiModelRoute,
 	position: { index: number; total: number },
+	deadline: WikiDeadline | undefined,
 ): Promise<WikiPlan> {
 	const seeded = existsSync(join(input.outputDir, page.path));
 	const outcome = await runWikiDispatch({
 		dispatch,
 		cwd: input.cwd,
 		outputDir: input.outputDir,
+		artifactPath: relative(input.cwd, join(input.outputDir, page.path)),
 		task: buildWikiPagePrompt({
+			depth: input.generation.depth,
 			cwd: input.cwd,
 			mode: input.mode,
 			codewiki: input.codewiki,
 			page,
 			siblings: plan.pages,
+			...(input.decisions ? { decisions: input.decisions } : {}),
 			outputDir: input.outputDir,
 			seeded,
 		}),
 		route,
-		deadlineMs: PAGE_DEADLINE_MS,
-		label: `wiki page ${page.path}`,
+		deadline,
 		onHeartbeat: ({ elapsedMs, tools }) =>
 			input.progress?.({
 				phase: "generate",
 				status: "running",
 				message: `still writing ${page.path} (${position.index}/${position.total}, ${formatElapsed(elapsedMs)}, ${tools} tool calls)`,
-				detail: `page deadline ${Math.round(PAGE_DEADLINE_MS / 60000)}m`,
+				detail: `page estimate ${Math.round(PAGE_ESTIMATE_MS / 60000)}m; healthy work may continue longer`,
 			}),
 	});
-	// The file on disk is the postcondition, not what the writer reported. A run
-	// that ended on its budget after writing the page still wrote the page.
-	const written = existsSync(join(input.outputDir, page.path));
+	// Keep failed refresh prose available, but require both a successful writer
+	// and mechanically valid evidence before crediting a page as completed.
+	const evidence = outcome.ok
+		? inspectWikiPageEvidence({
+				pagePath: page.path,
+				outputDir: input.outputDir,
+				sourceRoot: input.cwd,
+			})
+		: undefined;
+	const written = outcome.ok && evidence?.ok === true;
+	const detail = evidence && !evidence.ok ? `evidence check failed: ${evidence.reasons.join("; ")}` : outcome.detail;
 	const next: WikiPlan = {
 		...plan,
-		pages: plan.pages.map((entry) =>
-			entry.path === page.path
-				? { ...entry, status: written ? ("written" as const) : ("pending" as const), attempts: entry.attempts + 1 }
-				: entry,
-		),
+		pages: plan.pages.map((entry) => {
+			if (entry.path !== page.path) return entry;
+			const nextPage: WikiPlanPage = {
+				...entry,
+				status: written ? "written" : "pending",
+				...(written ? { dependencies: evidence?.dependencies ?? [] } : {}),
+				attempts: entry.attempts + (outcome.phase === "writer" ? 1 : 0),
+			};
+			if (written) delete nextPage.lastFailure;
+			else
+				nextPage.lastFailure = {
+					phase: outcome.ok ? "validation" : outcome.phase,
+					detail: detail.replace(/\s+/gu, " ").slice(0, 500),
+					...(outcome.phase === "writer" ? { runId: outcome.runId } : {}),
+				};
+			return nextPage;
+		}),
 	};
 	writeWikiPlanFile(input.outputDir, next);
 	input.progress?.({
 		phase: "generate",
 		status: "running",
 		message: `${written ? "wrote" : "could not write"} ${page.path} (${position.index}/${position.total})`,
-		detail: outcome.detail,
+		detail,
 	});
 	return next;
 }
@@ -375,8 +439,10 @@ async function generateWikiWithDocumenter(
 	dispatch: DispatchContract,
 	input: WikiGenerateInput,
 	route: WikiModelRoute = {},
-	runBudgetMs: number = RUN_BUDGET_MS,
+	deadline?: WikiDeadline,
+	signal?: AbortSignal,
 ): Promise<void> {
+	signal?.throwIfAborted();
 	const startedAtClock = performance.now();
 	const routeDetail = [route.target, route.model, route.thinkingLevel ? `thinking=${route.thinkingLevel}` : undefined]
 		.filter((value): value is string => value !== undefined)
@@ -392,43 +458,61 @@ async function generateWikiWithDocumenter(
 	// re-planning would churn the paths those pages already link to. Every other
 	// run plans, including an update, which is the only thing allowed to change
 	// a wiki's shape as the repository grows.
-	let plan = input.resumed ? input.plan : await runPlanPhase(dispatch, input, route);
+	let plan = input.resumed ? input.plan : await runPlanPhase(dispatch, input, route, deadline);
+	signal?.throwIfAborted();
 	if (!input.resumed) writeWikiPlanFile(input.outputDir, plan);
 
-	const queue = pendingPages(plan);
+	const queue = pendingPages(plan, input.retryPending);
 	if (queue.length === 0) {
-		input.progress?.({ phase: "generate", status: "running", message: "every planned page is already current" });
+		const pending = plan.pages.filter((page) => page.status !== "written").length;
+		input.progress?.({
+			phase: "generate",
+			status: "running",
+			message:
+				pending > 0
+					? `${pending} pending page${pending === 1 ? " has" : "s have"} exhausted writer attempts`
+					: "every planned page is already current",
+		});
 		return;
 	}
 	// Say the shape of the wait before starting it. A 20-page wiki is 20 model
 	// runs and can legitimately take most of an hour, which is longer than any
 	// default command timeout an operator is likely to have wrapped around it.
 	{
-		const worstCaseMs = Math.min(runBudgetMs, queue.length * PAGE_DEADLINE_MS);
+		const estimateMs = Math.min(RUN_ESTIMATE_MS, queue.length * PAGE_ESTIMATE_MS);
 		input.progress?.({
 			phase: "generate",
 			status: "running",
 			message: `${queue.length} page${queue.length === 1 ? "" : "s"} to write, one model run each`,
-			detail: `up to ${Math.round(worstCaseMs / 60000)}m; progress is reported at least every ${Math.round(HEARTBEAT_MS / 1000)}s and finished pages are kept if the run stops early`,
+			detail: `estimate ${Math.round(estimateMs / 60000)}m; activity summaries every ${Math.round(HEARTBEAT_MS / 1000)}s; finished pages are kept if the run stops early${deadline ? `; explicit deadline ${new Date(deadline.at).toISOString()}` : "; healthy work may continue beyond estimates"}`,
 		});
 	}
 	for (const [index, page] of queue.entries()) {
-		if (performance.now() - startedAtClock >= runBudgetMs) {
+		signal?.throwIfAborted();
+		if (deadline && deadline.remainingMs() <= 0) {
 			const left = queue.length - index;
 			input.progress?.({
 				phase: "generate",
 				status: "running",
-				message: `run budget reached with ${left} page${left === 1 ? "" : "s"} unwritten`,
+				message: `explicit deadline reached with ${left} page${left === 1 ? "" : "s"} unwritten`,
 				detail: `${formatElapsed(performance.now() - startedAtClock)}; staged pages are kept and promoted`,
 			});
 			return;
 		}
 		const current = plan.pages.find((entry) => entry.path === page.path) ?? page;
-		if (current.status === "written" || current.attempts >= MAX_PAGE_ATTEMPTS) continue;
-		plan = await runPagePhase(dispatch, input, plan, current, route, {
-			index: index + 1,
-			total: queue.length,
-		});
+		if (current.status === "written" || (!input.retryPending && current.attempts >= MAX_PAGE_ATTEMPTS)) continue;
+		plan = await runPagePhase(
+			dispatch,
+			input,
+			plan,
+			current,
+			route,
+			{
+				index: index + 1,
+				total: queue.length,
+			},
+			deadline,
+		);
 	}
 }
 
@@ -492,19 +576,79 @@ export async function resolveDocumenterModelId(route: WikiModelRoute = {}): Prom
 	}
 }
 
+/**
+ * A standalone wiki command owns a dispatch runtime outside the main entry
+ * orchestrator. Hold its signal ownership until workers settle, including
+ * their 500ms forced-kill window, then stop domains before exiting. This is
+ * scoped to the runtime we loaded; injected dispatches keep their caller's
+ * lifecycle. The signal budget fits inside the enclosing editor shell grace.
+ */
+export async function withWikiDispatchLifecycle(
+	runtime: { dispatch: Pick<DispatchContract, "drain">; stop(): Promise<void> },
+	generate: (signal: AbortSignal) => Promise<void>,
+): Promise<void> {
+	const abort = new AbortController();
+	let closing: Promise<void> | null = null;
+	let interrupted: Promise<void> | null = null;
+	const close = (): Promise<void> => {
+		closing ??= (async () => {
+			let failure: { error: unknown } | null = null;
+			try {
+				await runtime.dispatch.drain();
+			} catch (error) {
+				failure = { error };
+			}
+			try {
+				await runtime.stop();
+			} catch (error) {
+				if (failure) writeShutdownNotice(`clio-coder context wiki: domain cleanup failed: ${String(error)}`);
+				else failure = { error };
+			}
+			if (failure) throw failure.error;
+		})();
+		return closing;
+	};
+	const exitCodes = { SIGINT: 130, SIGTERM: 143, SIGHUP: 129 } as const;
+	const onSignal = (signal: keyof typeof exitCodes): void => {
+		if (interrupted) return;
+		abort.abort(new Error(`wiki generation interrupted by ${signal}`));
+		interrupted = (async () => {
+			const completed = await runWithBudget(close, 2000, (error) => {
+				writeShutdownNotice(`clio-coder context wiki: shutdown failed: ${String(error)}`);
+			});
+			if (!completed) writeShutdownNotice("clio-coder context wiki: shutdown exceeded 2000ms budget");
+			process.exit(exitCodes[signal]);
+		})();
+	};
+	for (const signal of Object.keys(exitCodes) as Array<keyof typeof exitCodes>) process.on(signal, onSignal);
+	let failure: { error: unknown } | null = null;
+	try {
+		await generate(abort.signal);
+	} catch (error) {
+		failure = { error };
+	}
+	try {
+		if (interrupted) await interrupted;
+		else await close();
+	} catch (error) {
+		if (failure) writeShutdownNotice(`clio-coder context wiki: cleanup failed: ${String(error)}`);
+		else failure = { error };
+	} finally {
+		for (const signal of Object.keys(exitCodes) as Array<keyof typeof exitCodes>) process.off(signal, onSignal);
+	}
+	if (failure) throw failure.error;
+}
+
 export function modelWikiGenerate(options: ModelWikiGenerateOptions = {}): WikiGenerate {
 	return async (input) => {
-		let loaded: LoadResult | null = null;
-		try {
-			if (options.dispatch) {
-				await generateWikiWithDocumenter(options.dispatch, input, options.route, options.runBudgetMs);
-				return;
-			}
-			const lazy = await loadWikiDispatch();
-			loaded = lazy.loaded;
-			await generateWikiWithDocumenter(lazy.dispatch, input, options.route, options.runBudgetMs);
-		} finally {
-			if (loaded) await loaded.stop();
+		const deadline = explicitWikiDeadline(options);
+		if (options.dispatch) {
+			await generateWikiWithDocumenter(options.dispatch, input, options.route, deadline);
+			return;
 		}
+		const { dispatch, loaded } = await loadWikiDispatch();
+		await withWikiDispatchLifecycle({ dispatch, stop: () => loaded.stop() }, (signal) =>
+			generateWikiWithDocumenter(dispatch, input, options.route, deadline, signal),
+		);
 	};
 }

package/src/core/bash-exec.ts

@@ -1,5 +1,6 @@
 import { spawn } from "node:child_process";
 import { StringDecoder } from "node:string_decoder";
+import { isSecretArgKey } from "../domains/safety/redaction.js";
 import { AI_AGENT_NAME } from "./agent-environment.js";
 import {
 	gitCommitAttributionEnabled,
@@ -18,7 +19,7 @@ export { clampTimerDelayMs as clampTimeoutMs } from "./timers.js";
 // (failing assertion, compiler error, exit summary) must survive.
 export const BASH_HARD_CAP_BYTES = 16 * 1024 * 1024;
 
-const CLIO_CONTROL_ENV_KEYS = ["CLIO_CODER_INTERACTIVE"] as const;
+const CLIO_CONTROL_ENV_KEYS = ["CLIO_CODER_INTERACTIVE", "BASH_ENV", "ENV"] as const;
 
 export interface BashCommandResult {
 	error: NodeJS.ErrnoException | null;
@@ -175,8 +176,10 @@ export function createBashOutputProgressController(
 	};
 }
 
-function buildToolEnv(): NodeJS.ProcessEnv {
-	const env = { ...process.env };
+function buildToolEnv(source: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+	const env = { ...source };
+	for (const key of Object.keys(env))
+		if (isSecretArgKey(key) || key.startsWith("BASH_FUNC_")) Reflect.deleteProperty(env, key);
 	env.AI_AGENT = AI_AGENT_NAME;
 	for (const key of CLIO_CONTROL_ENV_KEYS) {
 		Reflect.deleteProperty(env, key);
@@ -192,7 +195,7 @@ function buildToolEnv(): NodeJS.ProcessEnv {
 // call still gets a fresh shell — only the env composition is cached, so
 // there is no state bleed and cancellation semantics are untouched. When the
 // capture fails (profile error, timeout, no PATH), every call falls back to
-// the historical per-call `-lc`.
+// the filtered non-login environment; failed capture must not source secrets again.
 const LOGIN_ENV_CAPTURE_TIMEOUT_MS = 10_000;
 
 let loginEnvCapture: Promise<NodeJS.ProcessEnv | null> | null = null;
@@ -243,15 +246,11 @@ interface BashSpawnPlan {
 async function bashSpawnPlan(): Promise<BashSpawnPlan> {
 	loginEnvCapture ??= captureLoginEnv();
 	const captured = await loginEnvCapture;
-	if (captured === null) return { mode: "-lc", env: buildToolEnv() };
+	if (captured === null) return { mode: "-c", env: buildToolEnv() };
 	// Captured (login-transformed) values win; keys added to process.env after
 	// the capture still flow through; the CLIO control keys are re-stripped
 	// last so they never reach the child from either source.
-	const env: NodeJS.ProcessEnv = { ...process.env, ...captured };
-	env.AI_AGENT = AI_AGENT_NAME;
-	for (const key of CLIO_CONTROL_ENV_KEYS) {
-		Reflect.deleteProperty(env, key);
-	}
+	const env = buildToolEnv({ ...process.env, ...captured });
 	return { mode: "-c", env };
 }
 
@@ -275,6 +274,7 @@ export async function runBashCommand(command: string, options: RunBashCommandOpt
 		let timeoutId: ReturnType<typeof setTimeout> | null = null;
 		let killGraceTimer: ReturnType<typeof setTimeout> | null = null;
 		let killSent = false;
+		let pendingClose: (() => void) | null = null;
 		const output = createBashOutputProgressController(options.onUpdate);
 
 		const child = spawn("/bin/bash", [plan.mode, command], {
@@ -305,12 +305,42 @@ export async function runBashCommand(command: string, options: RunBashCommandOpt
 			child.kill(signalName);
 		};
 
+		const hasOwnedProcesses = (): boolean => {
+			const pid = child.pid;
+			if (pid === undefined) return false;
+			if (process.platform !== "win32") {
+				try {
+					process.kill(-pid, 0);
+					return true;
+				} catch (error) {
+					if ((error as NodeJS.ErrnoException).code === "EPERM") return true;
+				}
+			}
+			return child.exitCode === null && child.signalCode === null;
+		};
+
+		const resolveAfterCancellation = (result: BashCommandResult): void => {
+			// A TERM handler can exit while a same-group child ignores TERM and
+			// holds no pipes. Keep the original result, but do not let close discard
+			// the escalation that still owns that child's cancellation.
+			if (killGraceTimer !== null && hasOwnedProcesses()) {
+				pendingClose = () => resolve(result);
+				return;
+			}
+			clearKillGraceTimer();
+			resolve(result);
+		};
+
 		const killChild = (): void => {
 			if (killSent) return;
 			killSent = true;
 			sendSignal("SIGTERM");
 			killGraceTimer = setTimeout(() => {
-				sendSignal("SIGKILL");
+				killGraceTimer = null;
+				if (hasOwnedProcesses()) sendSignal("SIGKILL");
+				const finish = pendingClose;
+				pendingClose = null;
+				finish?.();
 			}, 5000);
 		};
 
@@ -342,10 +372,9 @@ export async function runBashCommand(command: string, options: RunBashCommandOpt
 			if (settled) return;
 			settled = true;
 			if (timeoutId) clearTimeout(timeoutId);
-			clearKillGraceTimer();
 			const finalOutput = output.settle();
 			options.signal?.removeEventListener("abort", onAbort);
-			resolve({
+			resolveAfterCancellation({
 				error: error as NodeJS.ErrnoException,
 				...finalOutput,
 				exitCode: null,
@@ -358,7 +387,6 @@ export async function runBashCommand(command: string, options: RunBashCommandOpt
 			if (settled) return;
 			settled = true;
 			if (timeoutId) clearTimeout(timeoutId);
-			clearKillGraceTimer();
 			const finalOutput = output.settle();
 			options.signal?.removeEventListener("abort", onAbort);
 			const error =
@@ -370,7 +398,7 @@ export async function runBashCommand(command: string, options: RunBashCommandOpt
 							code: code ?? undefined,
 							signal: signalName ?? undefined,
 						} as NodeJS.ErrnoException);
-			resolve({
+			resolveAfterCancellation({
 				error,
 				...finalOutput,
 				exitCode: code,