@iowarp/clio-coder 0.3.0 → 0.3.2

package/src/core/git-commit-attribution.ts

@@ -0,0 +1,362 @@
+import { execFileSync } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { AI_AGENT_NAME } from "./agent-environment.js";
+import { CLIO_COMMIT_TRAILERS, type CommitAttributionEvidence } from "./commit-attribution.js";
+import { clioStateDir } from "./xdg.js";
+
+/** Effective `attribution.gitCommits` for child-process seams. Internal state, not an operator override. */
+export const CLIO_GIT_COMMITS_ENABLED_ENV = "CLIO_CODER_GIT_COMMITS_ENABLED";
+const ASSISTED_ENV = "CLIO_CODER_COMMIT_ASSISTED";
+const AUTHORED_ENV = "CLIO_CODER_COMMIT_AUTHORED";
+/** Present iff this environment carries Clio's command-scope core.hooksPath pair; holds the count below it. */
+const CONFIG_BASE_COUNT_ENV = "CLIO_CODER_GIT_CONFIG_BASE_COUNT";
+const DEFAULT_HOOKS_EQUIVALENT_ENV = "CLIO_CODER_GIT_DEFAULT_HOOKS_EQUIVALENT";
+const MANAGED_HOOK_VERSION = 2;
+const DIAGNOSTIC_MAX_CHARS = 300;
+const COUNT = /^(?:0|[1-9][0-9]*)$/u;
+const reportedDiagnostics = new Set<string>();
+/**
+ * How long one repository probe (inside a work tree, effective core.hooksPath)
+ * is reused for the same cwd and Git environment. Each probe costs two `git`
+ * subprocesses, about 9 ms on a warm machine, and seams such as the verify
+ * tool's per-file `node --check` spawn in bursts. The window is short so a
+ * `git init` or a `core.hooksPath` change made during a session is seen on the
+ * next spawn after it rather than for the rest of the session.
+ */
+const PROBE_CACHE_TTL_MS = 10_000;
+const PROBE_CACHE_MAX_ENTRIES = 32;
+
+type RepositoryProbe =
+	| { kind: "outside" }
+	| { kind: "custom"; hooksPath: string }
+	| { kind: "default"; declaredDefault: boolean };
+
+const probeCache = new Map<string, { at: number; probe: RepositoryProbe }>();
+let installedHooksDirectory: string | null = null;
+
+const PER_SPAWN_ENV_NAMES = [ASSISTED_ENV, AUTHORED_ENV, CONFIG_BASE_COUNT_ENV, DEFAULT_HOOKS_EQUIVALENT_ENV] as const;
+
+export interface ManagedCommitAttributionOptions {
+	cwd?: string;
+	enabled?: boolean;
+	evidence?: Readonly<CommitAttributionEvidence>;
+}
+
+export interface ManagedCommitAttributionEnvironment {
+	env: NodeJS.ProcessEnv;
+	/** Bounded, nonfatal reason the managed hook could not be composed. */
+	diagnostic: string | null;
+}
+
+/** Report a bounded fail-open reason once without changing child command output. */
+export function reportCommitAttributionDiagnostic(diagnostic: string | null): void {
+	if (diagnostic === null || reportedDiagnostics.has(diagnostic)) return;
+	reportedDiagnostics.add(diagnostic);
+	process.stderr.write(`[clio:attribution] ${diagnostic}\n`);
+}
+
+export function setGitCommitAttributionEnabled(enabled: boolean): void {
+	process.env[CLIO_GIT_COMMITS_ENABLED_ENV] = enabled ? "1" : "0";
+}
+
+export function gitCommitAttributionEnabled(source: NodeJS.ProcessEnv = process.env): boolean {
+	return source[CLIO_GIT_COMMITS_ENABLED_ENV] !== "0";
+}
+
+/** Forget cached repository probes and the installed managed hooks directory. */
+export function resetGitCommitAttributionCachesForTests(): void {
+	probeCache.clear();
+	installedHooksDirectory = null;
+}
+
+function boundedDiagnostic(message: string): string {
+	const folded = message.replace(/\s+/gu, " ").trim();
+	return folded.length <= DIAGNOSTIC_MAX_CHARS ? folded : `${folded.slice(0, DIAGNOSTIC_MAX_CHARS - 3)}...`;
+}
+
+/**
+ * Remove the command-scope config pair a parent Clio process installed, so a
+ * nested seam starts from the operator's own GIT_CONFIG_* entries.
+ */
+function withoutManagedGitConfig(source: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+	const env = { ...source };
+	const baseRaw = env[CONFIG_BASE_COUNT_ENV];
+	const currentRaw = env.GIT_CONFIG_COUNT;
+	if (baseRaw !== undefined && COUNT.test(baseRaw) && currentRaw !== undefined && COUNT.test(currentRaw)) {
+		const base = Number(baseRaw);
+		for (let index = base; index < Number(currentRaw); index += 1) {
+			Reflect.deleteProperty(env, `GIT_CONFIG_KEY_${index}`);
+			Reflect.deleteProperty(env, `GIT_CONFIG_VALUE_${index}`);
+		}
+		if (base === 0) Reflect.deleteProperty(env, "GIT_CONFIG_COUNT");
+		else env.GIT_CONFIG_COUNT = String(base);
+	}
+	for (const name of PER_SPAWN_ENV_NAMES) Reflect.deleteProperty(env, name);
+	return env;
+}
+
+function gitOutput(cwd: string, env: NodeJS.ProcessEnv, args: ReadonlyArray<string>): string | null {
+	try {
+		return execFileSync("git", [...args], {
+			cwd,
+			env,
+			encoding: "utf8",
+			stdio: ["ignore", "pipe", "ignore"],
+			timeout: 5_000,
+		}).trim();
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Every hook name Git resolves through core.hooksPath. Pointing core.hooksPath
+ * at the managed directory would otherwise silently disable each repository
+ * hook that is not prepare-commit-msg, so each name gets a chaining wrapper.
+ */
+const MANAGED_HOOK_NAMES = [
+	"applypatch-msg",
+	"pre-applypatch",
+	"post-applypatch",
+	"pre-commit",
+	"pre-merge-commit",
+	"prepare-commit-msg",
+	"commit-msg",
+	"post-commit",
+	"pre-rebase",
+	"post-checkout",
+	"post-merge",
+	"pre-push",
+	"pre-receive",
+	"update",
+	"proc-receive",
+	"post-receive",
+	"post-update",
+	"reference-transaction",
+	"push-to-checkout",
+	"pre-auto-gc",
+	"post-rewrite",
+	"sendemail-validate",
+	"post-index-change",
+] as const;
+
+/**
+ * One script serves every hook name. It restores the Git configuration the
+ * command would have had without Clio, chains the repository's own hook of the
+ * same name with the original exit status, and, for prepare-commit-msg only,
+ * appends the assistance and authorship trailers this spawn was given.
+ *
+ * Testing, review, and receipt trailers never cross the environment. The fleet
+ * seam writes them into the message in process from coordinator-owned facts;
+ * an environment channel could be forged by exporting a variable before
+ * `git commit`.
+ */
+const MANAGED_HOOK_SCRIPT = `#!/bin/sh
+# Clio Coder managed Git hook v${MANAGED_HOOK_VERSION}. Selected only through
+# command-scope configuration in Clio child-process environments.
+
+hook_name=$(basename "$0")
+
+base_count=$${CONFIG_BASE_COUNT_ENV}
+case "$base_count" in
+  '' | *[!0-9]*)
+    printf '%s\\n' '[clio:attribution] invalid managed hook environment' >&2
+    exit 0
+    ;;
+  0) unset GIT_CONFIG_COUNT ;;
+  *)
+    GIT_CONFIG_COUNT=$base_count
+    export GIT_CONFIG_COUNT
+    ;;
+esac
+
+# A command may have moved into a different repository after Clio prepared the
+# environment. A repository with its own core.hooksPath gets its hook run and
+# is never attributed; composing an unknown setup is not attempted.
+if [ "$${DEFAULT_HOOKS_EQUIVALENT_ENV}" != '1' ] && git config --get core.hooksPath >/dev/null 2>&1; then
+  custom_hooks=$(git config --path --get core.hooksPath 2>/dev/null || true)
+  case "$custom_hooks" in
+    '') ;;
+    /*) custom_hook=$custom_hooks/$hook_name ;;
+    *) custom_hook=$PWD/$custom_hooks/$hook_name ;;
+  esac
+  if [ -n "$custom_hooks" ] && [ -x "$custom_hook" ]; then exec "$custom_hook" "$@"; fi
+  exit 0
+fi
+
+common_dir=$(git rev-parse --git-common-dir 2>/dev/null || true)
+case "$common_dir" in
+  '') default_hook= ;;
+  /*) default_hook=$common_dir/hooks/$hook_name ;;
+  *) default_hook=$PWD/$common_dir/hooks/$hook_name ;;
+esac
+
+if [ "$hook_name" != 'prepare-commit-msg' ]; then
+  if [ -n "$default_hook" ] && [ -x "$default_hook" ]; then exec "$default_hook" "$@"; fi
+  exit 0
+fi
+
+message_file=$1
+message_source=$2
+
+if [ -n "$default_hook" ] && [ -x "$default_hook" ]; then
+  "$default_hook" "$@" || exit $?
+fi
+
+# The repository's own hook semantics are settled. Everything below is
+# fail-open and applies only to Clio-spawned commits with attribution enabled.
+if [ "$AI_AGENT" != '${AI_AGENT_NAME}' ] || [ "$${CLIO_GIT_COMMITS_ENABLED_ENV}" != '1' ]; then exit 0; fi
+
+# Only a message supplied up front (-m, -F, or a merge) is attributed. --amend,
+# -c/-C, squash, and template sources reuse or lack a real message, and an
+# editor session starts from an all-comment template where added trailers
+# would turn an abandoned editor into a commit whose whole message is trailers.
+case "$message_source" in message|merge) ;; *) exit 0 ;; esac
+for marker in CHERRY_PICK_HEAD REVERT_HEAD rebase-apply rebase-merge sequencer; do
+  marker_path=$(git rev-parse --git-path "$marker" 2>/dev/null || true)
+  if [ -n "$marker_path" ] && [ -e "$marker_path" ]; then exit 0; fi
+done
+
+# Case-insensitive presence check on the whole message, so a human-written
+# variant of a Clio trailer is respected rather than duplicated.
+has_trailer() {
+  awk -v wanted="$(printf '%s' "$1" | tr '[:upper:]' '[:lower:]')" '
+    { line=$0; gsub(/[ \\t]+/, " ", line); sub(/ $/, "", line); if (tolower(line) == wanted) found=1 }
+    END { exit found ? 0 : 1 }' "$message_file"
+}
+
+append_trailer() {
+  if has_trailer "$1"; then return 0; fi
+  git interpret-trailers --in-place --if-exists=addIfDifferent --trailer "$1" "$message_file" ||
+    printf '%s\\n' '[clio:attribution] git interpret-trailers failed; commit left as written' >&2
+}
+
+if [ "$${ASSISTED_ENV}" = '1' ] || [ "$${AUTHORED_ENV}" = '1' ]; then
+  append_trailer '${CLIO_COMMIT_TRAILERS.assisted}'
+fi
+if [ "$${AUTHORED_ENV}" = '1' ]; then append_trailer '${CLIO_COMMIT_TRAILERS.coAuthored}'; fi
+exit 0
+`;
+
+function installManagedHook(directory: string, name: string): void {
+	const hook = join(directory, name);
+	try {
+		if (existsSync(hook) && readFileSync(hook, "utf8") === MANAGED_HOOK_SCRIPT) {
+			chmodSync(hook, 0o755);
+			return;
+		}
+	} catch {
+		// Unreadable content is replaced below; the path is Clio-owned.
+	}
+	const temporary = `${hook}.tmp-${process.pid}-${Date.now()}`;
+	try {
+		writeFileSync(temporary, MANAGED_HOOK_SCRIPT, { encoding: "utf8", mode: 0o755 });
+		renameSync(temporary, hook);
+	} finally {
+		rmSync(temporary, { force: true });
+	}
+}
+
+function managedHooksDirectory(): string {
+	const directory = join(clioStateDir(), "git-hooks", `v${MANAGED_HOOK_VERSION}`);
+	// Installed once per process; one stat afterwards confirms the Clio-owned
+	// directory is still there rather than re-reading all of its wrappers.
+	if (installedHooksDirectory === directory && existsSync(join(directory, "prepare-commit-msg"))) return directory;
+	mkdirSync(directory, { recursive: true, mode: 0o700 });
+	for (const name of MANAGED_HOOK_NAMES) installManagedHook(directory, name);
+	installedHooksDirectory = directory;
+	return directory;
+}
+
+/** The environment entries that change what `git` resolves for a cwd. */
+function gitEnvironmentFingerprint(env: NodeJS.ProcessEnv): string {
+	const parts: string[] = [];
+	for (const key of Object.keys(env)) {
+		if (key.startsWith("GIT_") || key === "HOME" || key === "XDG_CONFIG_HOME") parts.push(`${key}=${env[key] ?? ""}`);
+	}
+	return parts.sort().join("\0");
+}
+
+function probeRepositoryUncached(cwd: string, env: NodeJS.ProcessEnv): RepositoryProbe {
+	if (gitOutput(cwd, env, ["rev-parse", "--is-inside-work-tree"]) !== "true") return { kind: "outside" };
+	const customHooksPath = gitOutput(cwd, env, ["config", "--path", "--get", "core.hooksPath"]);
+	if (customHooksPath === null) return { kind: "default", declaredDefault: false };
+	const commonDirectory = gitOutput(cwd, env, ["rev-parse", "--git-common-dir"]);
+	const defaultHooksPath = commonDirectory === null ? null : resolve(cwd, commonDirectory, "hooks");
+	if (customHooksPath.length === 0 || resolve(cwd, customHooksPath) !== defaultHooksPath) {
+		return { kind: "custom", hooksPath: customHooksPath };
+	}
+	return { kind: "default", declaredDefault: true };
+}
+
+function probeRepository(cwd: string, env: NodeJS.ProcessEnv, now = Date.now()): RepositoryProbe {
+	const key = `${cwd}\0${gitEnvironmentFingerprint(env)}`;
+	const cached = probeCache.get(key);
+	if (cached !== undefined && now - cached.at < PROBE_CACHE_TTL_MS && now >= cached.at) return cached.probe;
+	const probe = probeRepositoryUncached(cwd, env);
+	if (cached === undefined && probeCache.size >= PROBE_CACHE_MAX_ENTRIES) {
+		const oldest = probeCache.keys().next().value;
+		if (oldest !== undefined) probeCache.delete(oldest);
+	}
+	probeCache.delete(key);
+	probeCache.set(key, { at: now, probe });
+	return probe;
+}
+
+/**
+ * Build a child environment that selects Clio's managed hooks directory through
+ * command-scope Git configuration. Repository and user configuration are never
+ * written. An effective core.hooksPath that is not the repository's default
+ * hooks directory is left alone: attribution fails open with a diagnostic.
+ *
+ * The repository probe behind this is cached per cwd and Git environment for
+ * `PROBE_CACHE_TTL_MS`, and the managed hooks directory is installed once per
+ * process, so a burst of spawns pays the git subprocesses once.
+ */
+export function withManagedGitCommitAttributionEnvironment(
+	source: NodeJS.ProcessEnv,
+	options: ManagedCommitAttributionOptions = {},
+): ManagedCommitAttributionEnvironment {
+	const env = withoutManagedGitConfig(source);
+	env.AI_AGENT = AI_AGENT_NAME;
+	const enabled = options.enabled ?? gitCommitAttributionEnabled(source);
+	env[CLIO_GIT_COMMITS_ENABLED_ENV] = enabled ? "1" : "0";
+	if (!enabled) return { env, diagnostic: null };
+
+	const evidence = options.evidence ?? { materiallyAssisted: true, materiallyAuthored: true };
+	env[ASSISTED_ENV] = evidence.materiallyAssisted === true ? "1" : "0";
+	env[AUTHORED_ENV] = evidence.materiallyAuthored === true ? "1" : "0";
+
+	const countRaw = env.GIT_CONFIG_COUNT;
+	const count = countRaw === undefined ? 0 : COUNT.test(countRaw) ? Number(countRaw) : Number.NaN;
+	if (!Number.isSafeInteger(count) || count > 1_024) {
+		return { env, diagnostic: boundedDiagnostic("GIT_CONFIG_COUNT is invalid; Clio commit attribution skipped") };
+	}
+	const cwd = resolve(options.cwd ?? process.cwd());
+	const probe = probeRepository(cwd, env);
+	if (probe.kind === "outside") return { env, diagnostic: null };
+	if (probe.kind === "custom") {
+		return {
+			env,
+			diagnostic: boundedDiagnostic(`core.hooksPath is set to '${probe.hooksPath}'; Clio commit attribution skipped`),
+		};
+	}
+	if (probe.declaredDefault) env[DEFAULT_HOOKS_EQUIVALENT_ENV] = "1";
+
+	let hooksDirectory: string;
+	try {
+		hooksDirectory = managedHooksDirectory();
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		return {
+			env,
+			diagnostic: boundedDiagnostic(`managed hooks unavailable; Clio commit attribution skipped (${reason})`),
+		};
+	}
+	env[CONFIG_BASE_COUNT_ENV] = String(count);
+	env.GIT_CONFIG_COUNT = String(count + 1);
+	env[`GIT_CONFIG_KEY_${count}`] = "core.hooksPath";
+	env[`GIT_CONFIG_VALUE_${count}`] = hooksDirectory;
+	return { env, diagnostic: null };
+}

package/src/core/guardrails.ts

@@ -0,0 +1,185 @@
+/**
+ * Guardrail policy values: the numeric backstops that bound runaway agent
+ * behavior (tool-call budgets, tool output byte caps, dispatch ledger size).
+ *
+ * These are durable operator policy, the same species as
+ * `compaction.threshold`, so their primary home is the `guardrails:` section
+ * of settings.yaml. The composition roots (orchestrator entry and worker
+ * runtime) wire that section in via {@link configureGuardrails}; consumers
+ * resolve values through {@link resolveGuardrail}, which layers a per-process
+ * env override on top for CI and one-off experiments:
+ *
+ *   env var  >  settings.yaml guardrails  >  built-in default
+ *
+ * Every value is a positive safe integer; invalid overrides fall through to
+ * the next layer rather than erroring.
+ */
+
+export interface GuardrailValues {
+	/**
+	 * Orchestrator per-turn soft tool-call budget. Crossing it blocks every
+	 * further call in the turn with a stop-and-summarize directive; the hard
+	 * interrupt ceiling sits a fixed margin above it (see engine/loop-guard.ts).
+	 * Sized as a backstop against a model spraying distinct unproductive calls,
+	 * not as a routine ceiling: verbatim retry spirals are the identical-call
+	 * detector's job, and legitimate deep work (a repo-wide audit) runs dozens
+	 * of productive calls in one turn.
+	 */
+	turnToolCallBudget: number;
+	/**
+	 * Lifetime cap on tool calls a dispatched worker may execute. It bounds
+	 * admitted calls, not attempts: a call the harness refuses (a reserve-window
+	 * steering block, a synthesis-lockout denial) never ran and never spends the
+	 * cap, because a worker must not be killed by the harness's own refusals.
+	 * Attempts stay bounded by the loop-block budget and the synthesis backstop.
+	 *
+	 * Sized so a recipe's declared budget is what actually binds. A writer that
+	 * produces a dozen files spends a call per file before a single grounding
+	 * read, so a ceiling tuned for a reporting agent silently made whole classes
+	 * of work impossible: `min(declared, cap)` in dispatch means the smaller of
+	 * the two always wins, and only the recipe knows the shape of its job.
+	 */
+	workerToolCallCap: number;
+	/** Dispatch run-ledger retention cap. */
+	maxDispatchRuns: number;
+	/** Per-call byte cap for the read tool (clamped to a 1KB floor at use). */
+	readMaxBytes: number;
+	/** Shared per-turn byte pool across all observation-producing tools. */
+	observationTurnBudgetBytes: number;
+	/**
+	 * Wall-clock cap in milliseconds for one internal generator dispatch (the
+	 * wiki documenter and the bootstrap scout). Backstop for a degenerate model
+	 * that keeps streaming without finishing: continuous output satisfies the
+	 * heartbeat watchdog, and a run mid-generation spends no tool calls, so
+	 * neither existing guard ends it. Healthy runs finish in minutes; this is
+	 * not a routine ceiling.
+	 */
+	internalDispatchTimeoutMs: number;
+}
+
+export const GUARDRAIL_DEFAULTS: GuardrailValues = {
+	turnToolCallBudget: 60,
+	workerToolCallCap: 150,
+	maxDispatchRuns: 1000,
+	readMaxBytes: 50 * 1024,
+	observationTurnBudgetBytes: 192 * 1024,
+	internalDispatchTimeoutMs: 15 * 60 * 1000,
+};
+
+/** Per-process env overrides, one per guardrail. */
+export const GUARDRAIL_ENV_VARS: Readonly<Record<keyof GuardrailValues, string>> = {
+	turnToolCallBudget: "CLIO_CODER_TURN_TOOL_CALL_BUDGET",
+	workerToolCallCap: "CLIO_CODER_WORKER_TOOL_CALL_CAP",
+	maxDispatchRuns: "CLIO_CODER_MAX_DISPATCH_RUNS",
+	readMaxBytes: "CLIO_CODER_READ_MAX_BYTES",
+	observationTurnBudgetBytes: "CLIO_CODER_OBSERVATION_TURN_BUDGET_BYTES",
+	internalDispatchTimeoutMs: "CLIO_CODER_INTERNAL_DISPATCH_TIMEOUT_MS",
+};
+
+/**
+ * Older env spellings that still read. `CLIO_CODER_MAX_RUNS` was the only
+ * guardrail whose variable was not the SCREAMING_SNAKE of its key, and CI
+ * environments already set it, so it keeps working behind the canonical name.
+ */
+const GUARDRAIL_ENV_ALIASES: Readonly<Partial<Record<keyof GuardrailValues, string>>> = {
+	maxDispatchRuns: "CLIO_CODER_MAX_RUNS",
+};
+
+/**
+ * One-shot annotation attached to the first tool result inside the reserve
+ * window. Advisory: the call that carried it still ran; only subsequent
+ * non-read calls are blocked.
+ */
+export function workerSynthesisReserveDirective(remaining: number, cap: number): string {
+	return (
+		`budget reserve: only ${remaining} of your ${cap} tool calls remain, and they are reserved for verification ` +
+		"reads and synthesis. Stop broad exploration now: re-read the locations you will cite, then answer in prose. " +
+		"Calls that are not reads will be blocked."
+	);
+}
+
+/**
+ * Block reason for a non-read call inside the reserve window. Deliberately
+ * does NOT start with the `workerToolCallCap reached (` machine prefix:
+ * reserve blocks are steering, not cap exhaustion, and must never trip
+ * {@link mentionsWorkerToolCallCap} or the worker abort predicates.
+ */
+export function workerSynthesisReserveBlockReason(tool: string, remaining: number, cap: number): string {
+	return (
+		`workerToolCallReserve: only ${remaining} of ${cap} tool calls remain and they are reserved for verification ` +
+		`reads and synthesis; ${tool} is not a read. Re-read any locations you will cite, then answer in prose from ` +
+		"what you have gathered."
+	);
+}
+
+export function isWorkerSynthesisReserveBlockReason(reason: string): boolean {
+	return /^workerToolCallReserve: only [1-9]\d* of [1-9]\d* tool calls remain/.test(reason);
+}
+
+export function workerToolCallCapExceededReason(cap: number): string {
+	return `workerToolCallCap reached (${cap}); abort run`;
+}
+
+export function isWorkerToolCallCapExceededReason(reason: string): boolean {
+	return /^workerToolCallCap reached \([1-9]\d*\); abort run$/.test(reason);
+}
+
+/**
+ * Cap-exhaustion synthesis directive. Emitted instead of the abort reason when
+ * the loop guard runs with the synthesis lockout (dispatched workers): the run
+ * gets one bounded text-only opportunity to report from what it gathered
+ * before the backstop ends it. The prefix keeps the cap telemetry recognizable
+ * in receipts and stderr diagnostics.
+ */
+export function workerToolCallCapSynthesisReason(cap: number): string {
+	return (
+		`workerToolCallCap reached (${cap}); tool calls are now disabled for the rest of this run. ` +
+		"Everything you retrieved is already in the conversation above. Answer the operator now, in plain prose, " +
+		"from what you have gathered. Do not write tool-call markup such as <tool_call> blocks; tool calls are " +
+		"disabled and will not run."
+	);
+}
+
+export function isWorkerToolCallCapSynthesisReason(reason: string): boolean {
+	return /^workerToolCallCap reached \([1-9]\d*\); tool calls are now disabled/.test(reason);
+}
+
+/**
+ * True when a receipt diagnostic (failureMessage/outcomeDetail) embeds the
+ * cap telemetry prefix. Unlike the anchored predicates above this matches
+ * anywhere in the text, because worker diagnostics merge the reason into a
+ * larger machine-written string. It is deliberately keyed on the guard's own
+ * prefix, never on free-form worker prose.
+ */
+export function mentionsWorkerToolCallCap(text: string | null | undefined): boolean {
+	return typeof text === "string" && /workerToolCallCap reached \([1-9]\d*\)/.test(text);
+}
+
+let configured: Partial<GuardrailValues> = {};
+
+/**
+ * Install the settings.yaml `guardrails:` section. Called once per process by
+ * the composition roots; later calls replace the whole layer (used by tests).
+ */
+export function configureGuardrails(values: Partial<GuardrailValues> | undefined): void {
+	configured = { ...(values ?? {}) };
+}
+
+function parsePositiveSafeInt(raw: string | undefined): number | undefined {
+	if (raw === undefined) return undefined;
+	const normalized = raw.trim();
+	if (!/^[1-9]\d*$/.test(normalized)) return undefined;
+	const parsed = Number(normalized);
+	return Number.isSafeInteger(parsed) ? parsed : undefined;
+}
+
+/** Resolve one guardrail: env override > configured settings > default. */
+export function resolveGuardrail(key: keyof GuardrailValues, env: NodeJS.ProcessEnv = process.env): number {
+	const alias = GUARDRAIL_ENV_ALIASES[key];
+	return (
+		parsePositiveSafeInt(env[GUARDRAIL_ENV_VARS[key]]) ??
+		(alias ? parsePositiveSafeInt(env[alias]) : undefined) ??
+		configured[key] ??
+		GUARDRAIL_DEFAULTS[key]
+	);
+}

package/src/core/headless-permission.ts

@@ -0,0 +1,21 @@
+/**
+ * What a headless run answers a tool call that needs an approval nobody can
+ * give. There is no operator on the other end of `clio-coder run`, so every ask-rail
+ * call below `full-auto` is denied with this sentence.
+ *
+ * It lives here rather than inline at the deny site because two surfaces read
+ * it: the orchestrator writes it, and the skill-eval harness recognizes it in
+ * an arm transcript to tell "the skill did not do the work" apart from "the
+ * harness never let it try". A recognizer holding its own copy of the sentence
+ * would silently stop matching the day the wording changed.
+ */
+export const HEADLESS_PERMISSION_DENIED_REASON =
+	"clio-coder run cannot confirm permission requests; rerun interactively to approve this action.";
+
+/**
+ * The stable clause of that sentence, for matching against transcripts where
+ * the remedy half may have been truncated by a preview or elision budget.
+ * `HEADLESS_PERMISSION_DENIED_REASON` starts with it, which a contract test
+ * pins.
+ */
+export const HEADLESS_PERMISSION_DENIED_MARKER = "clio-coder run cannot confirm permission requests";

package/src/core/incomplete-installation.ts

@@ -0,0 +1,45 @@
+import { isAbsolute, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolvePackageRoot } from "./package-root.js";
+
+function missingModulePath(message: string): string | null {
+	const specifier = /Cannot find (?:module|package) ['"]([^'"]+)['"]/.exec(message)?.[1];
+	if (!specifier) return null;
+	if (specifier.startsWith("file:")) {
+		try {
+			return fileURLToPath(specifier);
+		} catch {
+			return null;
+		}
+	}
+	return isAbsolute(specifier) ? specifier : null;
+}
+
+/**
+ * Turn a missing Clio-owned lazy chunk into an actionable reinstall message.
+ * Errors for user extensions, hooks, or any module outside this installation's
+ * generated `dist` directory remain untouched.
+ */
+export function incompleteInstallationAdvice(err: unknown): string | null {
+	if ((err as NodeJS.ErrnoException | undefined)?.code !== "ERR_MODULE_NOT_FOUND") return null;
+	const message = err instanceof Error ? err.message : String(err);
+	let outputDir: string;
+	try {
+		outputDir = join(resolvePackageRoot(), "dist");
+	} catch {
+		return null;
+	}
+	const missing = missingModulePath(message);
+	if (!missing) return null;
+	const fromOutput = relative(outputDir, missing);
+	if (fromOutput === "" || fromOutput.startsWith("..") || isAbsolute(fromOutput)) return null;
+	return [
+		`${message}`,
+		"",
+		"This Clio Coder installation is incomplete: the command's own module is missing from",
+		`${outputDir}`,
+		"Reinstall to restore it, using the line that matches how you installed:",
+		"  npm install -g @iowarp/clio-coder    # npm install",
+		"  npm run install:local                # source checkout",
+	].join("\n");
+}