@iowarp/clio-coder 0.3.1 → 0.3.3

package/src/domains/dispatch/orphan-recovery.ts

@@ -28,6 +28,8 @@ export interface OrphanRecoverySummary {
 	skipped: number;
 	/** Non-terminal rows whose worker process no longer exists, closed as stalled. */
 	abandoned: number;
+	/** Non-terminal rows whose worker process is gone but whose own receipt verified, sealed from it. */
+	sealed: number;
 }
 
 /**
@@ -128,12 +130,40 @@ function isProcessAlive(pid: number | null): boolean {
 
 const NON_TERMINAL_STATUSES: ReadonlySet<string> = new Set(["queued", "running", "stale", "dead"]);
 
+/**
+ * The sealed receipt for a row that never made it to a persisted terminal
+ * state, or null when there is no receipt or it does not verify against a
+ * reconstructable envelope. A run writes its receipt before it persists the
+ * ledger, so this window is exactly where a crash or a clobbered persist leaves
+ * the truth on disk in the receipt and a lie in the row.
+ */
+function sealedEnvelopeFor(runId: string): RunEnvelope | null {
+	const path = join(receiptsDir(), `${runId}.json`);
+	if (!existsSync(path)) return null;
+	let receipt: RunReceipt;
+	try {
+		receipt = JSON.parse(readFileSync(path, "utf8")) as RunReceipt;
+	} catch {
+		return null;
+	}
+	if (receipt?.runId !== runId) return null;
+	if (!isReceiptIntegrity(receipt.integrity)) return null;
+	if (receipt.reproducibility?.cwd === undefined) return null;
+	return verifyOrphan(receipt, path);
+}
+
 /**
  * Close abandoned ledger rows: a non-terminal row whose recorded worker pid
- * no longer exists belongs to an orchestrator that died mid-run. There is no
- * receipt to seal (the run never finalized), so the row is closed in place
- * with outcome "stalled" rather than left as a permanent ghost in status
- * output.
+ * no longer exists belongs to an orchestrator that died mid-run.
+ *
+ * Such a row may still have a sealed receipt on disk. A run writes its receipt
+ * before it persists the settled row, so a crash or a clobbered persist in that
+ * window leaves a receipt saying `succeeded`/0 next to a row that still says
+ * `running`. Stamping the row dead without looking was how a finished dispatch
+ * came to be recorded as a failure, and the receipt pass below could not repair
+ * it afterwards because it only adopts receipts with no row at all. So the
+ * receipt decides when it verifies, and only a row with nothing to seal is
+ * closed as "stalled" rather than left as a permanent ghost in status output.
  *
  * `endedAt` is the last instant the run was observed alive, not the instant
  * recovery noticed it was gone. Stamping recovery time made every phase
@@ -142,8 +172,9 @@ const NON_TERMINAL_STATUSES: ReadonlySet<string> = new Set(["queued", "running",
  * last heartbeat is the honest bound; a row that never heartbeat has only its
  * own start, which reads as a zero-length run rather than an invented one.
  */
-function closeAbandonedRows(ledger: Ledger): number {
+function closeAbandonedRows(ledger: Ledger): { closed: number; sealed: number } {
 	let closed = 0;
+	let sealed = 0;
 	const localHost = hostname();
 	for (const row of ledger.list()) {
 		if (row.endedAt !== null || !NON_TERMINAL_STATUSES.has(row.status)) continue;
@@ -155,6 +186,15 @@ function closeAbandonedRows(ledger: Ledger): number {
 		// for that host's own recovery pass.
 		if (row.identity !== undefined && row.identity.host !== localHost) continue;
 		if (isProcessAlive(row.pid)) continue;
+		const envelope = sealedEnvelopeFor(row.id);
+		if (envelope !== null) {
+			// Patch rather than replace: the row carries phase timings and lineage
+			// the receipt does not, and pid/heartbeatAt are this row's own history.
+			const { id: _id, pid: _pid, heartbeatAt: _heartbeatAt, ...settled } = envelope;
+			ledger.update(row.id, settled);
+			sealed += 1;
+			continue;
+		}
 		ledger.update(row.id, {
 			status: "dead",
 			outcome: "stalled",
@@ -164,12 +204,14 @@ function closeAbandonedRows(ledger: Ledger): number {
 		});
 		closed += 1;
 	}
-	return closed;
+	return { closed, sealed };
 }
 
 export function recoverOrphanReceipts(ledger: Ledger): OrphanRecoverySummary {
-	const summary: OrphanRecoverySummary = { recovered: 0, corrupt: 0, skipped: 0, abandoned: 0 };
-	summary.abandoned = closeAbandonedRows(ledger);
+	const summary: OrphanRecoverySummary = { recovered: 0, corrupt: 0, skipped: 0, abandoned: 0, sealed: 0 };
+	const abandoned = closeAbandonedRows(ledger);
+	summary.abandoned = abandoned.closed;
+	summary.sealed = abandoned.sealed;
 	const dir = receiptsDir();
 	if (!existsSync(dir)) return summary;
 	// Retention horizon: the ledger is a bounded ring, so a receipt older than

package/src/domains/dispatch/receipt-integrity.ts

@@ -94,6 +94,11 @@ export const RECEIPT_INTEGRITY_FIELD_COVERAGE = {
 	plan: true,
 	personaOverride: true,
 	projectContext: true,
+	// Always set on receipts written after #104 landed; absent only on older
+	// receipts, which digest exactly as they did before these fields existed,
+	// so the integrity version stays where it is.
+	rulesApplied: true,
+	operatorProfileApplied: true,
 	exitCode: true,
 	failureMessage: true,
 	tokenCount: true,

package/src/domains/dispatch/state.ts

@@ -106,13 +106,23 @@ function cloneEnvelope(envelope: RunEnvelope): RunEnvelope {
 	return structuredClone(envelope);
 }
 
-function mergeRunsById(disk: RunEnvelope[], memory: RunEnvelope[]): RunEnvelope[] {
-	// In-memory writes represent newer state (we just updated them in this process),
-	// so they win on id conflict. Disk-only entries are preserved so sibling
-	// processes' runs survive this process's persist().
+/**
+ * Only a row this process actually wrote is newer than disk. The mirror also
+ * holds rows read at open time that belong to sibling processes, and letting
+ * those win reverted a sibling's settled run to the snapshot this process
+ * happened to read: a dispatch that finished `completed`/0 reappeared as
+ * `running` with a null receiptPath, and the next recovery pass then sealed it
+ * `dead`/1. So memory wins only for `dirty` ids; every other id takes the disk
+ * copy. A non-dirty mirror row absent from disk was evicted by a sibling's ring
+ * cap and stays evicted rather than being resurrected on every persist.
+ */
+function mergeRunsById(disk: RunEnvelope[], memory: RunEnvelope[], dirty: ReadonlySet<string>): RunEnvelope[] {
 	const merged = new Map<string, RunEnvelope>();
 	for (const r of disk) merged.set(r.id, r);
-	for (const r of memory) merged.set(r.id, r);
+	for (const r of memory) {
+		if (!dirty.has(r.id)) continue;
+		merged.set(r.id, r);
+	}
 	const all = Array.from(merged.values());
 	all.sort((a, b) => (a.startedAt < b.startedAt ? 1 : a.startedAt > b.startedAt ? -1 : 0));
 	return all;
@@ -147,6 +157,10 @@ function capRuns(all: RunEnvelope[], maxRuns: number): RunEnvelope[] {
 export function openLedger(opts?: LedgerOptions): Ledger {
 	const maxRuns = resolveMaxRuns(opts?.maxRuns);
 	let runs: RunEnvelope[] = readRuns();
+	// Ids this process has written since the last successful persist. See
+	// mergeRunsById: this is what separates our writes from a sibling's rows we
+	// merely read at open time.
+	const dirty = new Set<string>();
 
 	function findIndex(id: string): number {
 		return runs.findIndex((r) => r.id === id);
@@ -187,6 +201,7 @@ export function openLedger(opts?: LedgerOptions): Ledger {
 				costUsd: 0,
 			};
 			runs.unshift(envelope);
+			dirty.add(envelope.id);
 			return cloneEnvelope(envelope);
 		},
 
@@ -197,6 +212,7 @@ export function openLedger(opts?: LedgerOptions): Ledger {
 			if (!current) return null;
 			const next = applyPatch(current, patch);
 			runs[idx] = next;
+			dirty.add(id);
 			return cloneEnvelope(next);
 		},
 
@@ -244,6 +260,7 @@ export function openLedger(opts?: LedgerOptions): Ledger {
 			if (stateRootRemoved()) return receiptWithIntegrity;
 			atomicWrite(target, JSON.stringify(receiptWithIntegrity, null, 2));
 			runs[idx] = { ...current, receiptPath: target };
+			dirty.add(id);
 			return receiptWithIntegrity;
 		},
 
@@ -251,6 +268,7 @@ export function openLedger(opts?: LedgerOptions): Ledger {
 			if (findIndex(envelope.id) !== -1) return false;
 			runs.push(cloneEnvelope(envelope));
 			runs.sort((a, b) => (a.startedAt < b.startedAt ? 1 : a.startedAt > b.startedAt ? -1 : 0));
+			dirty.add(envelope.id);
 			return true;
 		},
 
@@ -263,15 +281,22 @@ export function openLedger(opts?: LedgerOptions): Ledger {
 			await withStateFileLock(target, () => {
 				if (stateRootRemoved()) return;
 				const diskRuns = readRuns();
-				const merged = mergeRunsById(diskRuns, runs);
+				const merged = mergeRunsById(diskRuns, runs, dirty);
 				const capped = capRuns(merged, maxRuns);
 				runs = capped;
 				atomicWrite(target, JSON.stringify(capped, null, 2));
+				// Everything this process claimed is now on disk, so the mirror holds
+				// no newer state until the next write. Clearing here is what stops a
+				// long-lived process from re-asserting an old snapshot of its own rows
+				// over a sibling's later update to them.
+				dirty.clear();
 			});
 		},
 
 		reload(): void {
 			runs = readRuns();
+			// The mirror was just replaced wholesale, so any unpersisted claim is gone.
+			dirty.clear();
 		},
 	};
 }

package/src/domains/dispatch/transport.ts

@@ -22,6 +22,7 @@
  */
 
 import { spawn } from "node:child_process";
+import { AI_AGENT_NAME } from "../../core/agent-environment.js";
 import { shellQuote } from "../../core/shell-quote.js";
 import type { WorkerSpec } from "../../worker/spec-contract.js";
 import type { RunNodeIdentity } from "./types.js";
@@ -122,7 +123,7 @@ function remoteEnvAssignments(node: SshNodeEndpoint): string {
 	// is the group an abort must signal.
 	const labels = (node.labels ?? []).map((label) => label.trim()).filter((label) => label.length > 0);
 	const labelAssignment = labels.length > 0 ? ` CLIO_CODER_WORKER_LABELS=${shellQuote(labels.join(","))}` : "";
-	return `CLIO_CODER_RESIDENCY=${residency} CLIO_CODER_WORKER_PGID=$$${labelAssignment}`;
+	return `AI_AGENT=${AI_AGENT_NAME} CLIO_CODER_RESIDENCY=${residency} CLIO_CODER_WORKER_PGID=$$${labelAssignment}`;
 }
 
 export function buildRemoteWorkerCommand(node: SshNodeEndpoint, cwd: string): string {

package/src/domains/dispatch/types.ts

@@ -713,6 +713,20 @@ export interface RunReceipt {
 	personaOverride?: RunPersonaOverride;
 	/** Effective project-context tier for this run; absent on receipts written before this field landed. */
 	projectContext?: RunProjectContextProvenance;
+	/**
+	 * Repo-relative `.clio-coder/rules/**` ids selected into this run's worker
+	 * prompt, in load order; `[]` when the run had none. Always present on
+	 * receipts written after this field landed (#104); absent on older
+	 * receipts, which readers must treat as unknown, never as "no rules".
+	 */
+	rulesApplied?: string[];
+	/**
+	 * Whether the operator profile rendered non-empty content into this run's
+	 * worker prompt. Always present on receipts written after this field
+	 * landed (#104); absent on older receipts, which readers must treat as
+	 * unknown, never as false.
+	 */
+	operatorProfileApplied?: boolean;
 	exitCode: number;
 	failureMessage?: string;
 	tokenCount: number;

package/src/domains/dispatch/worker-spawn.ts

@@ -26,6 +26,8 @@
 
 import { type ChildProcess, spawn } from "node:child_process";
 import { join } from "node:path";
+import { withClioAgentEnvironment } from "../../core/agent-environment.js";
+import { enableClioCompileCache, workerCompileCacheEnvironment } from "../../core/compile-cache.js";
 import { resolvePackageRoot } from "../../core/package-root.js";
 import type { WorkerSpec } from "../../worker/spec-contract.js";
 import {
@@ -184,7 +186,7 @@ export function spawnWorkerProcess(
 	const child: ChildProcess = spawn(command, [...args], {
 		stdio: ["pipe", "pipe", "pipe"],
 		cwd: opts?.cwd,
-		env: opts?.env ?? process.env,
+		env: withClioAgentEnvironment(opts?.env ?? process.env),
 		// The worker leads its own process group so abort escalation covers the
 		// descendants a runtime spawned, not only the immediate child.
 		detached: true,
@@ -561,6 +563,23 @@ export function spawnNativeWorker(spec: WorkerSpec, opts?: SpawnOptions): Spawne
 	const { workerEntryPath: _entryPath, ...processOptions } = opts ?? {};
 	return spawnWorkerProcess(process.execPath, ["--disable-warning=ExperimentalWarning", workerEntry], spec, {
 		...processOptions,
-		env: opts?.env ?? process.env,
+		env: withCompileCacheEnvironment(opts?.env ?? process.env),
 	});
 }
+
+/**
+ * Hand a native worker the parent's compile-cache directory. The worker's
+ * whole static graph resolves before its first application statement, so an
+ * in-process enableCompileCache() call there is too late; NODE_COMPILE_CACHE
+ * is the only control Node reads early enough. Spawning a worker writes state
+ * by definition, so the cache is established here when no boot entrypoint did
+ * it earlier (a direct `fleet run` reaches this line with the cache still
+ * unsettled); the enable is settle-once, root-gated, and operator-controlled
+ * like everywhere else. Operator settings win, stale markers are normalized
+ * away, and the worker entry consumes the injected pair from its own
+ * process.env right after Node reads it, so the cache serves Clio's own
+ * entry graph and never the user's node processes.
+ */
+function withCompileCacheEnvironment(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+	return workerCompileCacheEnvironment(env, enableClioCompileCache());
+}

package/src/domains/eval/metrics/context.ts

@@ -1,6 +1,6 @@
 import { enumerateWorkspaceFiles } from "../../../core/workspace-files.js";
+import { readCodewiki, structuralCodewikiHash } from "../../context/codewiki/artifact.js";
 import { renderCodewikiDigest } from "../../context/codewiki/digest.js";
-import { readCodewiki, structuralCodewikiHash } from "../../context/codewiki/indexer.js";
 import { detectProjectProfile } from "../../session/workspace/project-type.js";
 
 export function collectContextMetrics(cwd: string): Record<string, number | string | null> {

package/src/domains/eval/types.ts

@@ -1,5 +1,4 @@
 export const EVAL_TASK_FILE_VERSION = 1;
-export const EVAL_ARTIFACT_VERSION = 1;
 
 export type EvalCommandPhase = "setup" | "verifier";
 

package/src/domains/evidence/build.ts

@@ -53,6 +53,7 @@ import {
 const MAX_TASK_CHARS = 500;
 const TRANSCRIPT_TEXT_MAX_CHARS = 500;
 const TOOL_PREVIEW_MAX_CHARS = 240;
+const TASK_LEDGER_ROW_LIMIT = 200;
 
 export interface BuildEvidenceOptions {
 	/** Evidence bundles are written under <dataDir>/evidence/. */
@@ -1321,8 +1322,47 @@ function renderSessionTranscriptEntry(linked: LinkedSessionEntry): string[] {
 		];
 	}
 	if (entry.kind === "taskLedger") {
+		const userLinks = entry.subgoals
+			.filter((goal) => goal.origin === "user" && goal.userTaskId)
+			.map((goal) => `${goal.id}:${goal.userTaskId}`)
+			.join(",");
+		const boardId = entry.boardId ?? "legacy";
+		const provenance = userLinks ? ` userLinks=${userLinks}` : "";
+		const evidenceByTaskId = new Map(
+			entry.requiredValidationEvidence.map((item) => [
+				item.id.endsWith(".evidence") ? item.id.slice(0, -".evidence".length) : item.id,
+				item.description,
+			]),
+		);
+		const rows = entry.subgoals.slice(0, TASK_LEDGER_ROW_LIMIT).map((goal) => {
+			const userTaskId = goal.userTaskId ?? "none";
+			const reason = goal.description === undefined ? "none" : previewUnknown(goal.description);
+			const evidence = evidenceByTaskId.has(goal.id) ? previewUnknown(evidenceByTaskId.get(goal.id)) : "none";
+			return `  task board=${boardId} id=${goal.id} title=${previewUnknown(goal.title)} status=${goal.status} origin=${goal.origin ?? "agent"} userTaskId=${userTaskId} reason=${reason} evidence=${evidence}`;
+		});
+		if (entry.subgoals.length > TASK_LEDGER_ROW_LIMIT) {
+			rows.push(`  task rows omitted=${entry.subgoals.length - TASK_LEDGER_ROW_LIMIT}`);
+		}
+		return [
+			`${prefix} taskLedger goals=${entry.goals.length} subgoals=${entry.subgoals.length} activeRuns=${entry.activeRunIds.length} evidence=${entry.requiredValidationEvidence.length} board=${boardId}${provenance}`,
+			...rows,
+		];
+	}
+	if (entry.kind === "decisionLedger") {
+		const summary = entry.summary === undefined ? "" : ` summary=${previewUnknown(entry.summary)}`;
 		return [
-			`${prefix} taskLedger goals=${entry.goals.length} subgoals=${entry.subgoals.length} activeRuns=${entry.activeRunIds.length} evidence=${entry.requiredValidationEvidence.length}`,
+			`${prefix} decisionLedger anchor=${entry.parentTurnId ?? "none"} interview=${entry.interviewId} status=${entry.interviewStatus} startedAt=${entry.startedAt} endedAt=${entry.endedAt} rounds=${entry.roundCount} decisions=${entry.decisions.length}${summary}`,
+			...entry.decisions.map((decision) => {
+				const label = decision.label === undefined ? "" : ` label=${previewUnknown(decision.label)}`;
+				const sourceQuestion =
+					decision.source_question === undefined ? "" : ` sourceQuestion=${previewUnknown(decision.source_question)}`;
+				const revision = decision.revisedAt === undefined ? "" : ` revisedAt=${decision.revisedAt} revisionSource=operator`;
+				const correction =
+					decision.correction === undefined
+						? ""
+						: ` correctionSource=operator correction=${previewUnknown(decision.correction)}`;
+				return `  decision key=${decision.key} status=${decision.status} decidedAt=${decision.decidedAt}${revision}${label}${sourceQuestion} value=${previewUnknown(decision.value)}${correction}`;
+			}),
 		];
 	}
 	if (entry.kind === "workerRun") {

package/src/domains/lifecycle/migrations/2026-08-18-lmstudio-runtime-id.ts

@@ -0,0 +1,52 @@
+import { existsSync } from "node:fs";
+
+import { readSettings, settingsPath, updateSettings } from "../../../core/config.js";
+import { authStoragePath } from "../../providers/auth/backend-file.js";
+import { openAuthStorage } from "../../providers/auth/index.js";
+import type { Migration } from "./index.js";
+
+function normalizeLmStudioUrl(url: string | undefined): string | undefined {
+	if (!url) return url;
+	if (url.startsWith("ws://")) return `http://${url.slice("ws://".length)}`;
+	if (url.startsWith("wss://")) return `https://${url.slice("wss://".length)}`;
+	return url;
+}
+
+const migration: Migration = {
+	id: "2026-08-18-lmstudio-runtime-id",
+	async up(): Promise<void> {
+		let keepLegacyCredential = false;
+		if (existsSync(settingsPath())) {
+			const current = readSettings();
+			keepLegacyCredential = current.targets.some((target) => target.auth?.apiKeyRef === "lmstudio-native");
+			const needsSettingsRewrite = current.targets.some(
+				(target) =>
+					target.runtime === "lmstudio-native" ||
+					((target.runtime === "lmstudio" || target.runtime === "lmstudio-native") &&
+						normalizeLmStudioUrl(target.url) !== target.url),
+			);
+			if (needsSettingsRewrite) {
+				updateSettings((settings) => {
+					for (const target of settings.targets) {
+						if (target.runtime !== "lmstudio-native" && target.runtime !== "lmstudio") continue;
+						target.runtime = "lmstudio";
+						const url = normalizeLmStudioUrl(target.url);
+						if (url !== undefined) target.url = url;
+					}
+				});
+			}
+		}
+		if (!existsSync(authStoragePath())) return;
+		// Only reach for the rename when a legacy credential is actually stored.
+		// Most homes this migration runs on never held one, and asking the store
+		// to rename nothing is work that can only fail: it takes the credentials
+		// lock and, before this guard existed, refused outright on a file the
+		// parser could not fully read, which failed every later `clio-coder
+		// upgrade` on that machine.
+		const storage = openAuthStorage();
+		if (!storage.hasStored("lmstudio-native")) return;
+		storage.renameProvider("lmstudio-native", "lmstudio", { keepSource: keepLegacyCredential });
+	},
+};
+
+export default migration;

package/src/domains/lifecycle/migrations/index.ts

@@ -25,6 +25,8 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
+import lmStudioRuntimeId from "./2026-08-18-lmstudio-runtime-id.js";
+
 export interface Migration {
 	id: string;
 	up(stateDir: string): Promise<void>;
@@ -43,7 +45,7 @@ export interface MigrationRunResult {
 	available: string[];
 }
 
-const REGISTRY: ReadonlyArray<Migration> = Object.freeze([]);
+const REGISTRY: ReadonlyArray<Migration> = Object.freeze([lmStudioRuntimeId]);
 
 export function listMigrations(): ReadonlyArray<Migration> {
 	return REGISTRY;
@@ -72,23 +74,41 @@ function writeManifest(path: string, manifest: MigrationManifest): void {
 	writeFileSync(path, `${JSON.stringify(manifest, null, 2)}\n`, { encoding: "utf8", mode: 0o644 });
 }
 
-export async function runPending(stateDir: string): Promise<MigrationRunResult> {
+/**
+ * Apply every registered migration this state tree has not recorded yet.
+ *
+ * `migrations` defaults to the compiled registry and exists so the ordering
+ * guarantee below can be exercised against a failing migration; production
+ * callers pass one argument.
+ */
+export async function runPending(
+	stateDir: string,
+	migrations: ReadonlyArray<Migration> = REGISTRY,
+): Promise<MigrationRunResult> {
 	mkdirSync(stateDir, { recursive: true });
 	const path = manifestPath(stateDir);
 	const manifest = readManifest(path);
 	const applied = new Set(manifest.applied);
 	const newlyApplied: string[] = [];
-	for (const m of REGISTRY) {
+	// The manifest is written after each `up()` rather than once at the end. A
+	// throw from a later migration used to discard the record of the earlier ones
+	// that had already succeeded, so they re-ran on the next upgrade against a
+	// tree they had already changed. That breaks the at-most-once guarantee this
+	// module's contract states.
+	for (const m of migrations) {
 		if (applied.has(m.id)) continue;
 		await m.up(stateDir);
 		applied.add(m.id);
 		newlyApplied.push(m.id);
+		writeManifest(path, { applied: [...applied] });
 	}
 	const allApplied = [...applied];
+	// Nothing pending still rewrites the manifest, so a home whose file was
+	// missing or unparseable gains a well-formed one.
 	writeManifest(path, { applied: allApplied });
 	return {
 		applied: newlyApplied,
 		allApplied,
-		available: REGISTRY.map((m) => m.id),
+		available: migrations.map((m) => m.id),
 	};
 }

package/src/domains/middleware/hooks-io.ts

@@ -15,6 +15,10 @@ import { spawnSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { parse as parseYaml } from "yaml";
+import {
+	reportCommitAttributionDiagnostic,
+	withManagedGitCommitAttributionEnvironment,
+} from "../../core/git-commit-attribution.js";
 import {
 	type HookReceiptSink,
 	loadUserHooks,
@@ -156,12 +160,20 @@ export function installUserHooks(options: InstallUserHooksOptions): InstallUserH
 export function spawnSyncCommandRunner(): UserHookCommandRunner {
 	return (argv, options): UserHookCommandResult => {
 		const [command, ...args] = argv;
+		// A user hook is operator automation, not Clio work: the environment is
+		// normalized so a nested seam sees consistent state, but no role is claimed.
+		const attribution = withManagedGitCommitAttributionEnvironment(process.env, {
+			cwd: options.cwd ?? process.cwd(),
+			evidence: {},
+		});
+		reportCommitAttributionDiagnostic(attribution.diagnostic);
 		const result = spawnSync(command ?? "", args, {
 			...(options.cwd !== undefined ? { cwd: options.cwd } : {}),
 			timeout: options.timeoutMs,
 			maxBuffer: COMMAND_OUTPUT_MAX_BYTES,
 			encoding: "utf8",
 			shell: false,
+			env: attribution.env,
 		});
 		const timedOut = result.error !== undefined && (result.error as NodeJS.ErrnoException).code === "ETIMEDOUT";
 		return {

package/src/domains/middleware/skills-reminder.ts

@@ -7,35 +7,48 @@ import { type MiddlewareEffect, metadataNumber } from "./types.js";
  * models read and ignore every ambient prompt channel but comply with the
  * identical instruction when it is visible user-message text, and
  * middleware reminders are the sanctioned mechanism for that text. Once
- * per session, on the first substantive task turn, when model-visible
- * skills exist, this registration injects one compact line teaching the
- * same reply protocol as the context(scope="skills") listing footer.
- * Reminder text only: loading stays operator-gated (`pendingSkillPolicy`
- * untouched), and a turn that already carries a pending skill request gets
- * no reminder because the operator has already chosen.
+ * per session, on the first substantive task turn, when model-visible or
+ * installable skills exist, this registration injects one compact line
+ * teaching the same reply protocol as the context(scope="skills") listing
+ * footer. Installable skills count because a fresh install has none
+ * installed and a marketplace full of them: gating on installed alone meant
+ * the one channel these models act on never fired for the operator who
+ * needed it most. Reminder text only: loading stays operator-gated
+ * (`pendingSkillPolicy` untouched), and a turn that already carries a
+ * pending skill request gets no reminder because the operator has already
+ * chosen.
  */
 
 export const SKILLS_REMINDER_REGISTRATION_ID = "observer.skills-reminder";
 
 export { SKILL_SUGGESTION_ANCHOR };
 
-export function skillsReminderMessage(count: number): string {
+export function skillsReminderMessage(installed: number, installable = 0): string {
 	// Unconditional imperative, deliberately: the skill-mastery batteries
 	// showed literal local models comply with "list and check" but never act
 	// on wording that first asks them to classify the task as skill-shaped.
 	// One listing call on the session's first turn is the accepted price.
+	const counts =
+		installable > 0
+			? `${installed} installed, ${installable} installable from the marketplace`
+			: `${installed} installed`;
 	return (
-		`[Skills] ${count} installed. Start this task by listing them with context(scope="skills") ` +
+		`[Skills] ${counts}. Start this task by listing them with context(scope="skills") ` +
 		"and checking for a match; if one matches, open your reply with the line " +
 		`\`${SKILL_SUGGESTION_ANCHOR}\` (a comma-separated sequence, in order, when several compose) ` +
-		"and wait for the operator; load only on operator request. If none match, do not mention " +
-		"skills and continue with the task."
+		"and wait for the operator; load only on operator request, and a marketplace skill is offered for " +
+		"install when the operator runs it. If none match, do not mention skills and continue with the task."
 	);
 }
 
 export interface SkillsReminderDeps {
-	/** Count of skills the model may see and suggest; 0 disables the reminder. */
+	/** Count of installed skills the model may see and suggest. */
 	countModelVisibleSkills(): number;
+	/**
+	 * Count of marketplace skills not yet installed. Optional; absent reads as
+	 * zero. Either count above zero arms the reminder.
+	 */
+	countInstallableSkills?(): number;
 }
 
 const NO_EFFECTS: ReadonlyArray<MiddlewareEffect> = [];
@@ -174,14 +187,16 @@ export function createSkillsReminderRegistration(deps: SkillsReminderDeps): Midd
 			// suggesting one would only add noise.
 			const pendingSkillRequests = metadataNumber(input, "pendingSkillRequests");
 			if (pendingSkillRequests !== null && pendingSkillRequests > 0) return NO_EFFECTS;
-			let count = 0;
+			let installed = 0;
+			let installable = 0;
 			try {
-				count = deps.countModelVisibleSkills();
+				installed = deps.countModelVisibleSkills();
+				installable = deps.countInstallableSkills?.() ?? 0;
 			} catch {
 				return NO_EFFECTS;
 			}
-			if (count <= 0) return NO_EFFECTS;
-			return [{ kind: "inject_reminder", severity: "info", message: skillsReminderMessage(count) }];
+			if (installed <= 0 && installable <= 0) return NO_EFFECTS;
+			return [{ kind: "inject_reminder", severity: "info", message: skillsReminderMessage(installed, installable) }];
 		},
 	};
 }