@iowarp/clio-coder 0.4.1 → 0.4.2

package/src/domains/observability/trace-store.ts

@@ -341,6 +341,8 @@ export interface TraceRunRow {
 	ended_at: string | null;
 	total_tokens: number | null;
 	total_cost_usd: number | null;
+	/** 'dispatch' for a worker run, 'session' for an interactive chat-loop turn. */
+	source: "dispatch" | "session";
 }
 
 export interface TracePhaseRow {
@@ -423,7 +425,8 @@ CREATE TABLE runs (
   started_at TEXT NOT NULL,
   ended_at TEXT,
   total_tokens INTEGER,
-  total_cost_usd REAL
+  total_cost_usd REAL,
+  source TEXT NOT NULL DEFAULT 'dispatch' CHECK(source IN ('dispatch','session'))
 );
 
 CREATE TABLE phases (
@@ -524,6 +527,23 @@ function ensureProcessOwnerColumns(db: DatabaseSync): void {
 	db.exec("ALTER TABLE processes ADD COLUMN host TEXT; ALTER TABLE processes ADD COLUMN birth_token TEXT;");
 }
 
+/**
+ * Additive discriminator between a dispatched run and an interactive session
+ * turn; older version-1 databases gain it in place. `runs`/`phases` held both
+ * kinds under one undocumented schema before this column existed, distinguishable
+ * only by the sentinel `assignment_id = SESSION_TRACE_ASSIGNMENT_ID` a session
+ * turn's row carries (recordSessionTurn's startSessionTurn) versus a real
+ * dispatch assignment id (upsertRun). The backfill reads that existing
+ * sentinel once; every row written after this migration sets `source`
+ * directly instead of relying on it.
+ */
+function ensureRunSourceColumn(db: DatabaseSync): void {
+	const columns = db.prepare("PRAGMA table_info(runs)").all() as { name: string }[];
+	if (columns.some((column) => column.name === "source")) return;
+	db.exec("ALTER TABLE runs ADD COLUMN source TEXT NOT NULL DEFAULT 'dispatch';");
+	db.prepare("UPDATE runs SET source = 'session' WHERE assignment_id = ?").run(SESSION_TRACE_ASSIGNMENT_ID);
+}
+
 /**
  * Finalize `running` rows whose recorded owner is on this host and provably
  * dead (pid gone, or alive under a different birth token, i.e. reused). Rows
@@ -570,6 +590,7 @@ export class TraceStore {
 		else if (version !== TRACE_SCHEMA_VERSION) throw new TraceSchemaVersionError(version);
 		this.transaction(() => {
 			ensureProcessOwnerColumns(this.db);
+			ensureRunSourceColumn(this.db);
 			reconcileAbandonedRuns(this.db);
 		});
 	}
@@ -673,8 +694,8 @@ export class TraceStore {
 		this.transaction(() => {
 			this.db
 				.prepare(`INSERT INTO runs
-          (run_id, assignment_id, request, status, agent, target, model, runtime, node, started_at)
-          VALUES (?, ?, ?, 'queued', ?, ?, ?, ?, ?, ?)
+          (run_id, assignment_id, request, status, agent, target, model, runtime, node, started_at, source)
+          VALUES (?, ?, ?, 'queued', ?, ?, ?, ?, ?, ?, 'dispatch')
           ON CONFLICT(run_id) DO UPDATE SET request=excluded.request, agent=excluded.agent,
             target=excluded.target, model=excluded.model, runtime=excluded.runtime, node=excluded.node`)
 				.run(
@@ -1046,8 +1067,8 @@ export class TraceStore {
 		this.transaction(() => {
 			this.db
 				.prepare(`INSERT INTO runs
-          (run_id, assignment_id, request, status, agent, target, model, runtime, node, started_at)
-          VALUES (?, ?, ?, 'running', ?, ?, ?, ?, NULL, ?)
+          (run_id, assignment_id, request, status, agent, target, model, runtime, node, started_at, source)
+          VALUES (?, ?, ?, 'running', ?, ?, ?, ?, NULL, ?, 'session')
           ON CONFLICT(run_id) DO NOTHING`)
 				.run(
 					input.runId,
@@ -1167,6 +1188,15 @@ function traceDatabaseFootprintBytes(path: string): number {
 
 export class TraceReader {
 	readonly db: DatabaseSync;
+	/**
+	 * `runs.source` is an additive column (see ensureRunSourceColumn) a
+	 * TraceStore writer backfills in place. A read-only reader can open a
+	 * database no writer has touched since before the column existed — the
+	 * trace viewer opening a dormant install's trace.sqlite fresh is the
+	 * realistic case — and cannot ALTER TABLE to fix that itself, so it
+	 * derives the same value the migration would have written instead.
+	 */
+	private readonly runsSourceExpr: string;
 
 	constructor(readonly path: string) {
 		this.db = new (databaseSyncConstructor())(path, { readOnly: true });
@@ -1177,6 +1207,10 @@ export class TraceReader {
 		const mode = this.db.prepare("PRAGMA journal_mode").get() as { journal_mode: string };
 		if (mode.journal_mode.toLowerCase() !== "wal")
 			throw new Error(`trace database journal mode is ${mode.journal_mode}, expected WAL`);
+		const runColumns = this.db.prepare("PRAGMA table_info(runs)").all() as { name: string }[];
+		this.runsSourceExpr = runColumns.some((column) => column.name === "source")
+			? "*"
+			: `*, CASE WHEN assignment_id = '${SESSION_TRACE_ASSIGNMENT_ID}' THEN 'session' ELSE 'dispatch' END AS source`;
 	}
 
 	close(): void {
@@ -1185,13 +1219,15 @@ export class TraceReader {
 
 	runs(limit = 50): TraceRunRow[] {
 		return this.db
-			.prepare("SELECT * FROM runs ORDER BY started_at DESC LIMIT ?")
+			.prepare(`SELECT ${this.runsSourceExpr} FROM runs ORDER BY started_at DESC LIMIT ?`)
 			.all(clampInt(limit, 1, 500)) as unknown as TraceRunRow[];
 	}
 
 	run(runId: string): TraceRunRow | null {
 		return (
-			(this.db.prepare("SELECT * FROM runs WHERE run_id=?").get(runId) as unknown as TraceRunRow | undefined) ?? null
+			(this.db.prepare(`SELECT ${this.runsSourceExpr} FROM runs WHERE run_id=?`).get(runId) as unknown as
+				| TraceRunRow
+				| undefined) ?? null
 		);
 	}
 

package/src/domains/prompts/compiler.ts

@@ -1,6 +1,8 @@
 import { join } from "node:path";
 import { resolvePackageRoot } from "../../core/package-root.js";
+import { normalizePromptHint } from "../../core/prompt-hint.js";
 import type { ToolName } from "../../core/tool-names.js";
+import { resolveClioDirs } from "../../core/xdg.js";
 import type { AutonomyLevel } from "../safety/autonomy.js";
 import { ceilChars } from "../session/context-accounting.js";
 import type { FragmentTable, LoadedFragment } from "./fragment-loader.js";
@@ -147,13 +149,6 @@ export interface CompiledSessionPrompt {
 	operatorProfileApplied?: boolean;
 }
 
-export const FLEET_ROUTING_GUIDANCE_MAX_BYTES = 320;
-// Points at the Fleet section rather than describing routing in the abstract:
-// `agent:"auto"` baselines by task shape and can still land on a worker whose
-// capability class is wrong for the job, so a pinned id is the reliable path.
-export const FLEET_ROUTING_GUIDANCE =
-	'Fleet routing: pin the `agent` id from the Fleet section; agent:"auto" baselines from the task text and is a fallback, not a router.';
-
 /**
  * Worker-side mirror of the parent's `SPOT_CHECK_GUIDANCE`. The parent sentence
  * demonstrably works: in the E19 drive it is what caught a verifier reporting a
@@ -234,7 +229,7 @@ function renderRuntimeBlock(inputs: SessionPromptInputs): string {
  */
 function sessionCanDispatch(inputs: SessionPromptInputs): boolean {
 	if (inputs.providerSupportsTools === false) return false;
-	return toolSurfaceHasTool(inputs.toolNames, inputs.toolPromptHints, "dispatch");
+	return toolSurfaceHasTool(inputs.toolNames, "dispatch");
 }
 
 /**
@@ -245,18 +240,38 @@ function sessionCanDispatch(inputs: SessionPromptInputs): boolean {
  */
 function sessionHasContext(inputs: SessionPromptInputs): boolean {
 	if (inputs.providerSupportsTools === false) return false;
-	return toolSurfaceHasTool(inputs.toolNames, inputs.toolPromptHints, "context");
+	return toolSurfaceHasTool(inputs.toolNames, "context");
 }
 
-/** One lookup for every "is this tool on the surface" predicate, over names and hints alike. */
-function toolSurfaceHasTool(
-	toolNames: ReadonlyArray<string> | undefined,
-	toolPromptHints: ReadonlyArray<ToolPromptHint> | undefined,
-	tool: string,
-): boolean {
+/** Tool names come from attached schemas; hints never manufacture a surface. */
+function toolSurfaceHasTool(toolNames: ReadonlyArray<string> | undefined, tool: string): boolean {
 	const names = new Set((toolNames ?? []).map((name) => name.trim()));
-	const hinted = new Set((toolPromptHints ?? []).map((entry) => entry.tool.trim()));
-	return names.has(tool) || hinted.has(tool);
+	return names.has(tool);
+}
+
+/** Normalize, sort, and exact-deduplicate caller-provided tool guidance. */
+function canonicalToolPromptHints(
+	entries: ReadonlyArray<ToolPromptHint>,
+	admitted: ReadonlySet<string>,
+): Array<{ tool: string; hint: string }> {
+	const normalized = entries
+		.map((entry) => ({
+			tool: entry.tool.trim(),
+			hint: normalizePromptHint(entry.hint) ?? "",
+		}))
+		.filter((entry) => admitted.has(entry.tool) && entry.hint.length > 0)
+		.sort((a, b) => {
+			if (a.tool !== b.tool) return a.tool < b.tool ? -1 : 1;
+			return a.hint < b.hint ? -1 : a.hint > b.hint ? 1 : 0;
+		});
+	const seenTools = new Set<string>();
+	const seenHints = new Set<string>();
+	return normalized.filter((entry) => {
+		if (seenTools.has(entry.tool) || seenHints.has(entry.hint)) return false;
+		seenTools.add(entry.tool);
+		seenHints.add(entry.hint);
+		return true;
+	});
 }
 
 function renderFleetBlock(inputs: SessionPromptInputs): string {
@@ -277,44 +292,55 @@ function renderToolContractBlock(inputs: SessionPromptInputs): string {
 	].sort();
 	const canDispatch = sessionCanDispatch(inputs);
 	const canListSkills = sessionHasContext(inputs);
+	// Asked twice in one session which tools it had, a live model gave two
+	// different answers and invented `web_find`. The authoritative list is one
+	// line above; pointing at it beats letting the model recall the schemas.
+	const admitted = new Set(names);
 	const inventoryGuidance = [
-		// Asked twice in one session which tools it had, a live model gave two
-		// different answers and invented `web_find`. The authoritative list is one
-		// line above; pointing at it beats letting the model recall the schemas.
-		"When answering capability-inventory questions, copy the Direct tools line above verbatim rather than recalling the attached schemas, and make no calls",
-		...(canDispatch ? ["add dispatch(list:true) only if agents or the fleet are requested"] : []),
-		...(canListSkills
-			? ['add context(scope="skills") only if skills are requested (it lists installed and marketplace skills)']
+		"When asked what tools you have, copy the Direct tools line verbatim and call nothing",
+		...(canDispatch
+			? [
+					"dispatch(list:true) answers a question about agents, the fleet, or which target and model run this session and its workers",
+				]
 			: []),
+		...(canListSkills ? ['context(scope="skills") answers only a question about skills'] : []),
 	].join("; ");
+	const capabilityKinds = [
+		"direct tools are attached schemas",
+		...(canDispatch ? ["fleet agents are workers behind dispatch"] : []),
+		...(canListSkills ? ["skills are operator-activated workflows reached through context"] : []),
+	];
+	const orientationTools = ["context", "code_nav", "grep", "read"].filter((name) => admitted.has(name));
+	const validationTools = ["verify", "git"].filter((name) => admitted.has(name));
 	const lines = [
 		"# Tool Contract",
 		"The attached schemas are the session's complete direct-tool surface; follow each schema exactly.",
 		...(names.length > 0 ? [`Direct tools: ${names.map((name) => `\`${name}\``).join(", ")}.`] : []),
-		"Harness model: direct tools are attached schemas; fleet agents are workers behind dispatch; skills are operator-activated workflows reached through context. Keep these capability sets distinct.",
+		`Harness model: ${capabilityKinds.join("; ")}. Keep these capability sets distinct.`,
 		`${inventoryGuidance}.`,
-		"Call tools only for concrete inspection or changes the task requires. If the user asks for a tool-free answer, simply answer without calling tools.",
+		"Call tools only for concrete inspection or changes the task requires; a tool-free question gets a tool-free answer.",
 		// The tool-specific instantiation of the operating contract's "narrow
 		// work: inspect directly" rule; the contract cannot name tools.
 		// Delegation, the tasks board, and skills are not restated here: the
-		// Delegation and Skills passages and the registry hints carry them, and
-		// each renders exactly when its tool does.
-		'For narrow file or symbol orientation, prefer context(scope="workspace"), code_nav, grep, and read instead of assuming source-tree details were preloaded.',
-		"Validate with verify or git diff before final claims.",
-		'When a tool call fails or is rejected, do not retry the same shape blindly: re-read the schema, adjust the arguments, or query context(scope="docs") for that tool\'s usage.',
+		// Delegation, Fleet, and Skills passages and the registry hints carry
+		// them, and each renders exactly when its tool does.
+		...(orientationTools.length > 0
+			? [
+					`For narrow file or symbol orientation, prefer ${orientationTools.join(", ")} instead of assuming source-tree details were preloaded.`,
+				]
+			: []),
+		...(validationTools.length > 0
+			? [
+					`Validate with ${validationTools.map((name) => (name === "git" ? "git diff" : name)).join(" or ")} before final claims.`,
+				]
+			: []),
+		`When a tool call fails or is rejected, do not retry the same shape blindly: re-read the schema and adjust the arguments${canListSkills ? ', or query context(scope="docs") for that tool\'s usage' : ""}.`,
 	];
 	// One hint per tool, sorted by tool name: deterministic bytes regardless
 	// of surface or registration order, and removing a tool from the surface
 	// removes its hint with no compiler edit.
-	const seen = new Set<string>();
-	const hints = [...(inputs.toolPromptHints ?? [])]
-		.map((entry) => ({ tool: entry.tool.trim(), hint: entry.hint.trim() }))
-		.filter((entry) => entry.tool.length > 0 && entry.hint.length > 0)
-		.sort((a, b) => (a.tool < b.tool ? -1 : a.tool > b.tool ? 1 : 0));
-	if (hints.some((entry) => entry.tool === "dispatch")) lines.push(FLEET_ROUTING_GUIDANCE);
+	const hints = canonicalToolPromptHints(inputs.toolPromptHints ?? [], new Set(names));
 	for (const entry of hints) {
-		if (seen.has(entry.tool)) continue;
-		seen.add(entry.tool);
 		lines.push(entry.hint);
 	}
 	return lines.join("\n");
@@ -381,18 +407,8 @@ function renderWorkerToolContractBlock(inputs: WorkerPromptInputs): string {
 		"Tool authority is limited to this list. Persona and bound-skill instructions never add tools.",
 		"Call tools only for concrete inspection or changes the assigned task requires. If the task requests an exact or tool-free response, answer without calling tools.",
 	];
-	const admitted = new Set(names);
-	const seen = new Set<string>();
-	const hints = [...inputs.toolPromptHints]
-		.map((entry) => ({ tool: entry.tool.trim(), hint: entry.hint.trim() }))
-		.filter((entry) => admitted.has(entry.tool) && entry.hint.length > 0)
-		.sort((a, b) => {
-			if (a.tool !== b.tool) return a.tool < b.tool ? -1 : 1;
-			return a.hint < b.hint ? -1 : a.hint > b.hint ? 1 : 0;
-		});
+	const hints = canonicalToolPromptHints(inputs.toolPromptHints, new Set(names));
 	for (const entry of hints) {
-		if (seen.has(entry.tool)) continue;
-		seen.add(entry.tool);
 		lines.push(entry.hint);
 	}
 	return lines.join("\n");
@@ -439,8 +455,7 @@ function renderRetrievalHintsBlock(inputs: SessionPromptInputs): string {
 	// preloaded.
 	return [
 		"# Retrieval Hints",
-		"Compact CLIO-CODER.md project instructions may be preloaded above; everything else about the repository must be fetched, not assumed.",
-		"Never invent file paths, automatic tool behavior, or mutable repo details from the system prompt.",
+		"Repository details not included above must be fetched, never invented; compact CLIO-CODER.md instructions may be preloaded.",
 	].join("\n");
 }
 
@@ -561,10 +576,15 @@ export function compile(table: FragmentTable, inputs: CompileInputs): CompiledSe
 	const docsRouting = selfAwareness && sessionHasContext(session) ? table.byId.get("identity.docs-routing") : undefined;
 	if (selfAwareness) {
 		const packageRoot = resolvePackageRoot();
+		// The live home, not the XDG default: an isolated CLIO_CODER_HOME or a
+		// CLIO_CODER_CONFIG_DIR override moves the file the operator would edit.
+		const clioDirs = resolveClioDirs();
 		const rendered = selfAwareness.body
 			.replace("{CLIO_DOCS_PATH}", join(packageRoot, "docs"))
 			.replace("{CLIO_SRC_PATH}", join(packageRoot, "src"))
-			.replace("{CLIO_CODEWIKI_PATH}", join(packageRoot, "dist", "assets", "codewiki.json"));
+			.replace("{CLIO_CODEWIKI_PATH}", join(packageRoot, "dist", "assets", "codewiki.json"))
+			.replace("{CLIO_SETTINGS_PATH}", join(clioDirs.config, "settings.yaml"))
+			.replace("{CLIO_STATE_PATH}", clioDirs.state);
 		identityBody = [identity.body.trim(), rendered.trim(), ...(docsRouting ? [docsRouting.body.trim()] : [])].join(
 			"\n\n",
 		);

package/src/domains/prompts/contract.ts

@@ -1,6 +1,8 @@
 import type { CompiledSessionPrompt, SessionPromptInputs, WorkerPromptInputs } from "./compiler.js";
 
 export interface CompileSessionPromptInput {
+	/** Stable session identity that owns the compiler's frozen disk-input snapshot. */
+	sessionId: string;
 	sessionInputs: SessionPromptInputs;
 	autonomy?: string;
 	cwd?: string;
@@ -23,11 +25,21 @@ export interface CompileWorkerPromptInput extends WorkerPromptInputs {
 }
 
 export interface PromptsContract {
+	/**
+	 * Revision of compiler-owned inputs. Fragment, agent-catalog, and
+	 * session-source invalidation components advance independently and are
+	 * combined without loss. Project handbooks, rules, operator profile, and
+	 * repo awareness are frozen in a real per-session snapshot until a config
+	 * invalidation or a new session.
+	 */
+	inputEpoch(): string;
+
 	/**
 	 * Compile the session system prompt. Called once per session (and again
 	 * only on explicit, logged events: model/target change, autonomy-level
-	 * change, fragment reload, session switch). Inputs must be constant for
-	 * the session's lifetime.
+	 * change, fragment reload, session switch). Compiler-owned disk inputs are
+	 * selected from the session snapshot even when another identity input causes
+	 * a recompile.
 	 */
 	compileSessionPrompt(input: CompileSessionPromptInput): Promise<CompiledSessionPrompt>;
 
@@ -39,6 +51,6 @@ export interface PromptsContract {
 	 */
 	compileWorkerPrompt(input: CompileWorkerPromptInput): Promise<CompiledSessionPrompt>;
 
-	/** Reload fragment table (triggered by config.hotReload). */
+	/** Reload fragment table and advance `inputEpoch` after a successful load. */
 	reload(): void;
 }

package/src/domains/prompts/extension.ts

@@ -8,9 +8,11 @@ import type { AgentsContract } from "../agents/contract.js";
 import type { ConfigContract } from "../config/contract.js";
 import {
 	type ContextContract,
+	type LoadedOperatorProfile,
 	loadOperatorProfile,
 	loadProjectRules,
 	type ProjectPromptContext,
+	type ProjectRulesLoad,
 	renderOperatorProfile,
 	selectActiveRules,
 } from "../context/index.js";
@@ -28,11 +30,26 @@ export interface PromptsBundleOptions {
 const CLIO_REPO_AWARENESS_ID = "context.clio-repo-awareness";
 const WORKSPACE_ROOT_ID = "context.workspace-root";
 
+interface CustomizationSourceSnapshot {
+	rules: ProjectRulesLoad["rules"];
+	operatorProfile: LoadedOperatorProfile | null;
+}
+
+interface SessionPromptSourceSnapshot {
+	projectContext: ProjectPromptContext | null;
+	customization: CustomizationSourceSnapshot;
+	workspaceRoot: RenderedPromptFragment[];
+	clioRepoAwareness: RenderedPromptFragment[];
+}
+
 export function createPromptsBundle(
 	context: DomainContext,
 	options: PromptsBundleOptions = {},
 ): DomainBundle<PromptsContract> {
 	let table: FragmentTable | null = null;
+	let fragmentEpoch = 0;
+	let sessionSourceEpoch = 0;
+	const sessionSourceSnapshots = new Map<string, SessionPromptSourceSnapshot>();
 	const suppressContextFiles = options.noContextFiles === true;
 
 	function config(): ConfigContract | undefined {
@@ -60,6 +77,7 @@ export function createPromptsBundle(
 	function reload(): void {
 		try {
 			table = loadFragments();
+			fragmentEpoch += 1;
 		} catch (err) {
 			const msg = err instanceof Error ? err.message : String(err);
 			process.stderr.write(`[clio-coder:prompts] reload failed: ${msg}\n`);
@@ -73,7 +91,42 @@ export function createPromptsBundle(
 		return false;
 	}
 
+	function sessionSourceKey(sessionId: string, cwd: string): string {
+		return `${sessionId}\0${cwd}`;
+	}
+
+	function captureSessionSourceSnapshot(cwd: string): SessionPromptSourceSnapshot {
+		let projectContext: ProjectPromptContext | null = null;
+		if (!suppressContextFiles) {
+			projectContext = contextDomain()?.renderPromptContext(cwd) ?? null;
+			for (const warning of projectContext?.warnings ?? []) process.stderr.write(`${warning}\n`);
+		}
+		return {
+			projectContext,
+			customization: captureCustomizationSources(cwd),
+			workspaceRoot: workspaceRootFragment(cwd),
+			clioRepoAwareness: clioRepoAwarenessFragments(cwd),
+		};
+	}
+
+	function sessionSourceSnapshot(sessionId: string, cwd: string): SessionPromptSourceSnapshot {
+		const key = sessionSourceKey(sessionId, cwd);
+		const existing = sessionSourceSnapshots.get(key);
+		if (existing) return existing;
+		const captured = captureSessionSourceSnapshot(cwd);
+		sessionSourceSnapshots.set(key, captured);
+		return captured;
+	}
+
+	function invalidateSessionSources(): void {
+		sessionSourceSnapshots.clear();
+		sessionSourceEpoch += 1;
+	}
+
 	const contract: PromptsContract = {
+		inputEpoch() {
+			return `${fragmentEpoch}:${agentsDomain()?.revision() ?? 0}:${sessionSourceEpoch}`;
+		},
 		async compileSessionPrompt(input: CompileSessionPromptInput) {
 			if (!table) throw new Error("prompts domain not started");
 			if (table.byId.size === 0) {
@@ -83,11 +136,12 @@ export function createPromptsBundle(
 			const settings: Readonly<ClioSettings> | undefined = configContract?.get();
 			const safety = input.autonomy ?? settings?.safety.autonomy ?? "auto-edit";
 			const cwd = input.cwd ?? process.cwd();
+			const sources = sessionSourceSnapshot(input.sessionId, cwd);
 			let contextFiles = "";
 			let projectPreload: ProjectPreloadClass | null = null;
 			let projectHandbookFiles: string[] = [];
 			if (!suppressContextFiles) {
-				const projectContext = contextDomain()?.renderPromptContext(cwd);
+				const projectContext = sources.projectContext;
 				contextFiles = projectContext
 					? selectProjectContext(projectContext, input.sessionInputs.providerSupportsTools ?? null)
 					: "";
@@ -98,7 +152,6 @@ export function createPromptsBundle(
 					});
 					projectHandbookFiles = projectContext.handbookFiles;
 				}
-				for (const warning of projectContext?.warnings ?? []) process.stderr.write(`${warning}\n`);
 			}
 			const roster = fleetRoster();
 			const sessionInputs = {
@@ -112,9 +165,9 @@ export function createPromptsBundle(
 				safety: `safety.${safety}`,
 				sessionInputs,
 				additionalFragments: [
-					...workspaceRootFragment(cwd),
-					...clioRepoAwarenessFragments(cwd),
-					...customizationFragments(cwd, input.workingContextPaths ?? []).fragments,
+					...sources.workspaceRoot,
+					...sources.clioRepoAwareness,
+					...renderCustomizationFragments(sources.customization, cwd, input.workingContextPaths ?? []).fragments,
 				],
 			});
 			return { ...compiled, projectPreload, projectHandbookFiles };
@@ -141,25 +194,38 @@ export function createPromptsBundle(
 	};
 
 	let unsubscribeHotReload: (() => void) | null = null;
+	let unsubscribeExtensionsReload: (() => void) | null = null;
 	const extension: DomainExtension = {
 		async start() {
 			try {
 				table = loadFragments();
+				fragmentEpoch += 1;
 			} catch (err) {
 				const msg = err instanceof Error ? err.message : String(err);
 				process.stderr.write(`[clio-coder:prompts] initial load failed: ${msg}\n`);
 				table = { byId: new Map(), rootDir: "" };
 			}
 			unsubscribeHotReload = context.bus.on(BusChannels.ConfigHotReload, (payload: unknown) => {
+				invalidateSessionSources();
 				const diff = (payload as { diff?: { hotReload?: string[] } } | undefined)?.diff;
 				const paths = diff?.hotReload ?? [];
 				if (!diffTouchesFragments(paths)) return;
 				reload();
 			});
+			// Extension prompt and skill roots feed fragments through the
+			// resources domain; a committed generation with new content means
+			// the table must be rebuilt from the new roots.
+			unsubscribeExtensionsReload = context.bus.on(BusChannels.ExtensionsReloaded, (payload: unknown) => {
+				if ((payload as { changed?: unknown } | undefined)?.changed !== true) return;
+				reload();
+			});
 		},
 		async stop() {
 			unsubscribeHotReload?.();
 			unsubscribeHotReload = null;
+			unsubscribeExtensionsReload?.();
+			unsubscribeExtensionsReload = null;
+			sessionSourceSnapshots.clear();
 		},
 	};
 
@@ -189,13 +255,36 @@ export interface CustomizationFragmentsResult {
 export function customizationFragments(
 	cwd: string,
 	workingContextPaths: ReadonlyArray<string>,
+): CustomizationFragmentsResult {
+	return renderCustomizationFragments(captureCustomizationSources(cwd), cwd, workingContextPaths);
+}
+
+function captureCustomizationSources(cwd: string): CustomizationSourceSnapshot {
+	let rules: ProjectRulesLoad["rules"] = [];
+	let operatorProfile: LoadedOperatorProfile | null = null;
+	try {
+		rules = loadProjectRules(cwd).rules;
+	} catch {
+		// Project rules are best-effort; a load failure freezes an empty set.
+	}
+	try {
+		operatorProfile = loadOperatorProfile(cwd);
+	} catch {
+		// The operator profile is best-effort; a load failure freezes no profile.
+	}
+	return { rules, operatorProfile };
+}
+
+function renderCustomizationFragments(
+	sources: CustomizationSourceSnapshot,
+	cwd: string,
+	workingContextPaths: ReadonlyArray<string>,
 ): CustomizationFragmentsResult {
 	const fragments: RenderedPromptFragment[] = [];
 	let activeRuleIds: string[] = [];
 	let operatorProfileApplied = false;
 	try {
-		const loaded = loadProjectRules(cwd);
-		const active = selectActiveRules(loaded.rules, normalizeWorkingContextPaths(cwd, workingContextPaths));
+		const active = selectActiveRules(sources.rules, normalizeWorkingContextPaths(cwd, workingContextPaths));
 		if (active.length > 0) {
 			const body = ["# Project rules", ...active.map((rule) => rule.body)].join("\n\n");
 			fragments.push({
@@ -211,8 +300,7 @@ export function customizationFragments(
 		// Project rules are best-effort; a load failure must not block compilation.
 	}
 	try {
-		const profile = loadOperatorProfile(cwd);
-		const rendered = renderOperatorProfile(profile.profile);
+		const rendered = renderOperatorProfile(sources.operatorProfile?.profile ?? {});
 		if (rendered.text.length > 0) {
 			fragments.push({
 				id: "context.operator-profile",

package/src/domains/prompts/fragments/identity/clio-worker.md

@@ -6,6 +6,4 @@ description: Identity for a bounded Clio fleet worker
 
 # Identity
 
-You are Clio, IOWarp's coding agent, running as one bounded worker in a Clio fleet.
-Complete only the assigned task within the admitted tool and autonomy contracts, then return a concise handoff to the coordinating session.
-You do not coordinate the fleet unless an admitted tool and the assigned task explicitly authorize delegation.
+You are Clio, IOWarp's coding agent, running as one bounded worker in a Clio fleet. Return a concise handoff to the coordinating session; do not coordinate the fleet unless the assigned task and an admitted tool explicitly authorize it.

package/src/domains/prompts/fragments/identity/clio.md

@@ -1,25 +1,19 @@
 ---
 id: identity.clio
 version: 1
-budgetTokens: 200
 description: Clio identity and persona block
 ---
 
 # Clio identity
 
 You are Clio, the coding agent in IOWarp's CLIO ecosystem of agentic
-science (NSF-funded, iowarp.ai). CLIO stands for Context Layer for
-Input/Output. You are the first female agentic coder, named for the
-Greek muse of history who proclaimed and made famous the great
-deeds of the past. Developed by the Gnosis Research Center
-at Illinois Tech (github.com/grc-iit, @grc-iit) and the IOWarp
-team, you focus on HPC and scientific-software engineering for
-researchers and developers.
+science (Context Layer for Input/Output), developed by the Gnosis
+Research Center at Illinois Tech for HPC and scientific-software
+engineering.
 
-Whichever weights run you, your name and persona are Clio. You are
-not Claude, GPT, Qwen, Gemini, Llama, Mistral, or any other vendor's
-assistant, and you do not claim to be from Anthropic, OpenAI,
-Alibaba, Google, Meta, or any other model vendor.
+Whichever weights run you, your name and persona are Clio: not Claude,
+GPT, Qwen, Gemini, Llama, Mistral, or any other vendor's assistant, and
+you claim no model vendor.
 
 You do not invent capabilities, and you do not bypass confirmations,
 privilege limits, or git safety rails.

package/src/domains/prompts/fragments/identity/docs-routing.md

@@ -1,10 +1,9 @@
 ---
 id: identity.docs-routing
 version: 1
-budgetTokens: 120
 description: Directive to route questions about Clio herself through context(scope="docs"); rendered only when context is on the surface
 ---
 
 # Clio documentation routing
 
-When the user asks about Clio herself, her commands, configuration, targets, fleet, dispatch, extensions, skills, safety model, or any other Clio behavior, call context (scope="docs", query=<the question>) before answering and before any grep, find, or read: Clio's documentation ships with the package, not in the working tree, so searching the workspace for it finds nothing. Every response lists the whole corpus alongside the ranked sections, so one call routes the question to its document; then read that document completely from the installed documentation path above.
+For a question about Clio herself, call context (scope="docs", query=<the question>) before answering and before any workspace search, then read the document it names from the installed documentation path above.

package/src/domains/prompts/fragments/identity/self-awareness.md

@@ -1,19 +1,11 @@
 ---
 id: identity.self-awareness
 version: 1
-budgetTokens: 260
 description: Clio self-awareness, installed documentation, and harness configuration paths
 ---
 
 # Clio's own harness
 
-Read these only when the user asks about Clio herself, her configuration, targets, fleet, extensions, skills, dispatch, or safety model; never for ordinary coding work.
-
-Installed documentation: {CLIO_DOCS_PATH}
-Installed source: {CLIO_SRC_PATH}
-Code map: {CLIO_CODEWIKI_PATH} (a structural index of Clio's own files, symbols, and import edges; paths are POSIX-relative to the installed source root)
-When reading Clio documentation, resolve docs/... there, not in the current working directory.
-Documentation routes, code decides: when precision matters, verify against the installed source, because code outranks docs.
-
-User configuration lives in ~/.config/clio-coder/settings.yaml and machine-produced session state lives in the XDG state directory (~/.local/state/clio-coder on Linux, ~/Library/Application Support/clio-coder/state on macOS, %LOCALAPPDATA%/clio-coder/state on Windows). Extension and skill authoring is documented in docs/extensions-and-sharing.md and docs/skills-marketplace.md.
-Always read Clio .md documentation files completely and follow cross-references before acting.
+Only for questions about Clio herself (her commands, configuration, targets, fleet, dispatch, extensions, skills, or safety model), never for ordinary coding work.
+Her documentation and source ship with the package, not in the workspace: documentation at {CLIO_DOCS_PATH}, source at {CLIO_SRC_PATH}. Code outranks docs when precision matters.
+User settings live in {CLIO_SETTINGS_PATH}; session state lives in {CLIO_STATE_PATH}.