@iowarp/clio-coder 0.4.0 → 0.4.2

package/src/core/session-routing.ts

@@ -18,7 +18,7 @@
 
 import type { ClioSettings } from "./config.js";
 
-type SessionThinkingLevel = ClioSettings["orchestrator"]["thinkingLevel"];
+type SessionThinkingLevel = ClioSettings["chat"]["thinkingLevel"];
 
 export interface SessionRoutingTarget {
 	target: string | null;
@@ -28,7 +28,7 @@ export interface SessionRoutingTarget {
 
 export interface SessionRoutingState {
 	orchestrator: SessionRoutingTarget;
-	background: SessionRoutingTarget;
+	background: Pick<SessionRoutingTarget, "target" | "model">;
 	workersDefault: SessionRoutingTarget;
 	scope: string[];
 }
@@ -40,7 +40,7 @@ export interface SessionRoutingState {
  */
 export interface RoutingPatch {
 	orchestrator?: Partial<SessionRoutingTarget>;
-	background?: Partial<SessionRoutingTarget>;
+	background?: Partial<Pick<SessionRoutingTarget, "target" | "model">>;
 	workersDefault?: Partial<SessionRoutingTarget>;
 	scope?: string[];
 }
@@ -59,10 +59,10 @@ function targetFrom(source: {
 
 export function seedSessionRouting(saved: Readonly<ClioSettings>): SessionRoutingState {
 	return {
-		orchestrator: targetFrom(saved.orchestrator),
-		background: targetFrom(saved.background),
-		workersDefault: targetFrom(saved.workers.default),
-		scope: [...(saved.scope ?? [])],
+		orchestrator: targetFrom(saved.chat),
+		background: { target: saved.context.memory.target, model: saved.context.memory.model },
+		workersDefault: targetFrom(saved.fleet.default),
+		scope: [...saved.chat.modelPicker.cycleSet],
 	};
 }
 
@@ -73,16 +73,15 @@ export function seedSessionRouting(saved: Readonly<ClioSettings>): SessionRoutin
  */
 export function applySessionRouting(saved: Readonly<ClioSettings>, routing: SessionRoutingState): ClioSettings {
 	const view = structuredClone(saved) as ClioSettings;
-	view.orchestrator.target = routing.orchestrator.target;
-	view.orchestrator.model = routing.orchestrator.model;
-	view.orchestrator.thinkingLevel = routing.orchestrator.thinkingLevel;
-	view.background.target = routing.background.target;
-	view.background.model = routing.background.model;
-	view.background.thinkingLevel = routing.background.thinkingLevel;
-	view.workers.default.target = routing.workersDefault.target;
-	view.workers.default.model = routing.workersDefault.model;
-	view.workers.default.thinkingLevel = routing.workersDefault.thinkingLevel;
-	view.scope = [...routing.scope];
+	view.chat.target = routing.orchestrator.target;
+	view.chat.model = routing.orchestrator.model;
+	view.chat.thinkingLevel = routing.orchestrator.thinkingLevel;
+	view.context.memory.target = routing.background.target;
+	view.context.memory.model = routing.background.model;
+	view.fleet.default.target = routing.workersDefault.target;
+	view.fleet.default.model = routing.workersDefault.model;
+	view.fleet.default.thinkingLevel = routing.workersDefault.thinkingLevel;
+	view.chat.modelPicker.cycleSet = [...routing.scope];
 	return view;
 }
 
@@ -107,14 +106,21 @@ export type SessionOverrides = Map<string, unknown>;
 
 /** True for the dotted paths owned by the session routing state (never overrides). */
 export function isRoutingPath(path: string): boolean {
-	return (
-		path === "scope" ||
-		path.startsWith("orchestrator.") ||
-		path.startsWith("background.") ||
-		path.startsWith("workers.default.")
-	);
+	return ROUTING_PATHS.has(path);
 }
 
+const ROUTING_PATHS = new Set<string>([
+	"chat.target",
+	"chat.model",
+	"chat.thinkingLevel",
+	"context.memory.target",
+	"context.memory.model",
+	"fleet.default.target",
+	"fleet.default.model",
+	"fleet.default.thinkingLevel",
+	"chat.modelPicker.cycleSet",
+]);
+
 /** Read a leaf from a settings blob by dotted object path. Missing ⇒ undefined. */
 export function getAtPath(source: Readonly<ClioSettings>, path: string): unknown {
 	let cursor: unknown = source;
@@ -159,10 +165,10 @@ export function applyOverrides(base: Readonly<ClioSettings>, overrides: SessionO
 
 /** Write-through of a routing patch onto a (cloned) saved-settings blob. */
 export function mergeRoutingPatchIntoSettings(settings: ClioSettings, patch: RoutingPatch): void {
-	if (patch.orchestrator) Object.assign(settings.orchestrator, patch.orchestrator);
-	if (patch.background) Object.assign(settings.background, patch.background);
-	if (patch.workersDefault) Object.assign(settings.workers.default, patch.workersDefault);
-	if (patch.scope) settings.scope = [...patch.scope];
+	if (patch.orchestrator) Object.assign(settings.chat, patch.orchestrator);
+	if (patch.background) Object.assign(settings.context.memory, patch.background);
+	if (patch.workersDefault) Object.assign(settings.fleet.default, patch.workersDefault);
+	if (patch.scope) settings.chat.modelPicker.cycleSet = [...patch.scope];
 }
 
 /**
@@ -176,26 +182,24 @@ export function mergeRoutingPatchIntoSettings(settings: ClioSettings, patch: Rou
  */
 export function routingPatchForId(path: string, settings: Readonly<ClioSettings>): RoutingPatch | null {
 	switch (path) {
-		case "orchestrator.target":
-			return { orchestrator: { target: settings.orchestrator.target, model: settings.orchestrator.model } };
-		case "orchestrator.model":
-			return { orchestrator: { model: settings.orchestrator.model } };
-		case "orchestrator.thinkingLevel":
-			return { orchestrator: { thinkingLevel: settings.orchestrator.thinkingLevel } };
-		case "background.target":
-			return { background: { target: settings.background.target, model: settings.background.model } };
-		case "background.model":
-			return { background: { model: settings.background.model } };
-		case "background.thinkingLevel":
-			return { background: { thinkingLevel: settings.background.thinkingLevel } };
-		case "workers.default.target":
-			return { workersDefault: { target: settings.workers.default.target, model: settings.workers.default.model } };
-		case "workers.default.model":
-			return { workersDefault: { model: settings.workers.default.model } };
-		case "workers.default.thinkingLevel":
-			return { workersDefault: { thinkingLevel: settings.workers.default.thinkingLevel } };
-		case "scope":
-			return { scope: [...(settings.scope ?? [])] };
+		case "chat.target":
+			return { orchestrator: { target: settings.chat.target, model: settings.chat.model } };
+		case "chat.model":
+			return { orchestrator: { model: settings.chat.model } };
+		case "chat.thinkingLevel":
+			return { orchestrator: { thinkingLevel: settings.chat.thinkingLevel } };
+		case "context.memory.target":
+			return { background: { target: settings.context.memory.target, model: settings.context.memory.model } };
+		case "context.memory.model":
+			return { background: { model: settings.context.memory.model } };
+		case "fleet.default.target":
+			return { workersDefault: { target: settings.fleet.default.target, model: settings.fleet.default.model } };
+		case "fleet.default.model":
+			return { workersDefault: { model: settings.fleet.default.model } };
+		case "fleet.default.thinkingLevel":
+			return { workersDefault: { thinkingLevel: settings.fleet.default.thinkingLevel } };
+		case "chat.modelPicker.cycleSet":
+			return { scope: [...settings.chat.modelPicker.cycleSet] };
 		default:
 			return null;
 	}
@@ -224,13 +228,17 @@ function scopeEquals(a: ReadonlyArray<string>, b: ReadonlyArray<string>): boolea
  */
 export function diffRouting(prev: Readonly<ClioSettings>, next: Readonly<ClioSettings>): RoutingPatch | null {
 	const patch: RoutingPatch = {};
-	const orchestrator = diffTarget(prev.orchestrator, next.orchestrator);
+	const orchestrator = diffTarget(prev.chat, next.chat);
 	if (orchestrator) patch.orchestrator = orchestrator;
-	const background = diffTarget(prev.background, next.background);
+	const background = diffTarget(
+		{ ...prev.context.memory, thinkingLevel: "off" },
+		{ ...next.context.memory, thinkingLevel: "off" },
+	);
 	if (background) patch.background = background;
-	const workersDefault = diffTarget(prev.workers.default, next.workers.default);
+	const workersDefault = diffTarget(prev.fleet.default, next.fleet.default);
 	if (workersDefault) patch.workersDefault = workersDefault;
-	if (!scopeEquals(prev.scope ?? [], next.scope ?? [])) patch.scope = [...(next.scope ?? [])];
+	if (!scopeEquals(prev.chat.modelPicker.cycleSet, next.chat.modelPicker.cycleSet))
+		patch.scope = [...next.chat.modelPicker.cycleSet];
 	return Object.keys(patch).length > 0 ? patch : null;
 }
 
@@ -241,16 +249,15 @@ export function diffRouting(prev: Readonly<ClioSettings>, next: Readonly<ClioSet
  * saved routing defaults with this session's live routing.
  */
 export function restoreRoutingFields(target: ClioSettings, source: Readonly<ClioSettings>): void {
-	target.orchestrator.target = source.orchestrator.target;
-	target.orchestrator.model = source.orchestrator.model;
-	target.orchestrator.thinkingLevel = source.orchestrator.thinkingLevel;
-	target.background.target = source.background.target;
-	target.background.model = source.background.model;
-	target.background.thinkingLevel = source.background.thinkingLevel;
-	target.workers.default.target = source.workers.default.target;
-	target.workers.default.model = source.workers.default.model;
-	target.workers.default.thinkingLevel = source.workers.default.thinkingLevel;
-	target.scope = [...(source.scope ?? [])];
+	target.chat.target = source.chat.target;
+	target.chat.model = source.chat.model;
+	target.chat.thinkingLevel = source.chat.thinkingLevel;
+	target.context.memory.target = source.context.memory.target;
+	target.context.memory.model = source.context.memory.model;
+	target.fleet.default.target = source.fleet.default.target;
+	target.fleet.default.model = source.fleet.default.model;
+	target.fleet.default.thinkingLevel = source.fleet.default.thinkingLevel;
+	target.chat.modelPicker.cycleSet = [...source.chat.modelPicker.cycleSet];
 }
 
 const ROUTING_FIELD_LABELS: ReadonlyArray<{
@@ -258,20 +265,23 @@ const ROUTING_FIELD_LABELS: ReadonlyArray<{
 	label: string;
 	read: (settings: Readonly<ClioSettings>) => unknown;
 }> = [
-	{ field: "orchestrator.target", label: "chat target", read: (s) => s.orchestrator.target ?? null },
-	{ field: "orchestrator.model", label: "chat model", read: (s) => s.orchestrator.model ?? null },
-	{ field: "orchestrator.thinkingLevel", label: "chat thinking", read: (s) => s.orchestrator.thinkingLevel ?? "off" },
-	{ field: "background.target", label: "background target", read: (s) => s.background.target ?? null },
-	{ field: "background.model", label: "background model", read: (s) => s.background.model ?? null },
-	{ field: "background.thinkingLevel", label: "background thinking", read: (s) => s.background.thinkingLevel ?? "off" },
-	{ field: "workers.default.target", label: "fleet target", read: (s) => s.workers.default.target ?? null },
-	{ field: "workers.default.model", label: "fleet model", read: (s) => s.workers.default.model ?? null },
+	{ field: "chat.target", label: "chat target", read: (s) => s.chat.target ?? null },
+	{ field: "chat.model", label: "chat model", read: (s) => s.chat.model ?? null },
+	{ field: "chat.thinkingLevel", label: "chat thinking", read: (s) => s.chat.thinkingLevel ?? "off" },
+	{ field: "context.memory.target", label: "memory target", read: (s) => s.context.memory.target ?? null },
+	{ field: "context.memory.model", label: "memory model", read: (s) => s.context.memory.model ?? null },
+	{ field: "fleet.default.target", label: "fleet target", read: (s) => s.fleet.default.target ?? null },
+	{ field: "fleet.default.model", label: "fleet model", read: (s) => s.fleet.default.model ?? null },
 	{
-		field: "workers.default.thinkingLevel",
+		field: "fleet.default.thinkingLevel",
 		label: "fleet thinking",
-		read: (s) => s.workers.default.thinkingLevel ?? "off",
+		read: (s) => s.fleet.default.thinkingLevel ?? "off",
+	},
+	{
+		field: "chat.modelPicker.cycleSet",
+		label: "Alt+J/Alt+K cycle set",
+		read: (s) => s.chat.modelPicker.cycleSet.join(","),
 	},
-	{ field: "scope", label: "Alt+J/Alt+K scope", read: (s) => (s.scope ?? []).join(",") },
 ];
 
 /**
@@ -282,7 +292,7 @@ const ROUTING_FIELD_LABELS: ReadonlyArray<{
  * writer — a second session, the CLI, or a manual edit — moved the defaults
  * out from under this session.
  */
-export function externalRoutingDivergence(
+function externalRoutingDivergence(
 	changedPaths: ReadonlyArray<string>,
 	saved: Readonly<ClioSettings>,
 	effective: Readonly<ClioSettings>,
@@ -325,7 +335,7 @@ export function routingChangeNotices(
 			text: `settings.yaml changed (${diverged.join(", ")}). This session keeps its routing; new sessions use the saved defaults.${hint}`,
 		});
 	}
-	const activeTarget = effective.orchestrator.target;
+	const activeTarget = effective.chat.target;
 	const targetsTouched = changedPaths.some((path) => path === "targets" || path.startsWith("targets."));
 	if (activeTarget && targetsTouched && !saved.targets.some((entry) => entry.id === activeTarget)) {
 		const hint = options?.commandHints ? " (/model)" : "";

package/src/core/skill-activation.ts

@@ -19,6 +19,24 @@ export const SKILL_SUGGESTION_ANCHOR = "Suggested skill: /skill <name>";
  */
 export const SKILL_SUGGESTION_PREFIX = SKILL_SUGGESTION_ANCHOR.slice(0, SKILL_SUGGESTION_ANCHOR.indexOf("<name>"));
 
+/**
+ * The four fixed answer labels of a marketplace install offer. Every surface
+ * that teaches or reads the offer (the marketplace-offer middleware, the
+ * skills fragment, the context listing footer) cites these exact strings, so
+ * the after_tool observer that records declines and runs consented installs
+ * recognizes the operator's choice by label identity, never by paraphrase.
+ */
+export const SKILL_INSTALL_OFFER_OPTION_PROJECT = "Install for this project";
+export const SKILL_INSTALL_OFFER_OPTION_USER = "Install globally";
+export const SKILL_INSTALL_OFFER_OPTION_NOT_NOW = "Not now";
+export const SKILL_INSTALL_OFFER_OPTION_NEVER = "Never offer this skill";
+export const SKILL_INSTALL_OFFER_OPTIONS = [
+	SKILL_INSTALL_OFFER_OPTION_PROJECT,
+	SKILL_INSTALL_OFFER_OPTION_USER,
+	SKILL_INSTALL_OFFER_OPTION_NOT_NOW,
+	SKILL_INSTALL_OFFER_OPTION_NEVER,
+] as const;
+
 export interface PendingSkillRequest {
 	name: string;
 	args: string;

package/src/core/termination.ts

@@ -37,7 +37,7 @@ const SIGNAL_EXIT_CODES: Partial<Record<NodeJS.Signals, number>> = {
  * Break `text` into lines no wider than `width` columns, at spaces where
  * possible and mid-word when a single token is wider than the terminal.
  */
-export function wrapToWidth(text: string, width: number): string[] {
+function wrapToWidth(text: string, width: number): string[] {
 	if (!Number.isFinite(width) || width < 1) return [text];
 	const lines: string[] = [];
 	let current = "";
@@ -156,7 +156,7 @@ class TerminationCoordinator {
 		const log = (msg: string): void => {
 			if (!debug) return;
 			const ms = Number(process.hrtime.bigint() - mark) / 1e6;
-			process.stderr.write(`[clio:shutdown] +${ms.toFixed(1)}ms ${msg}\n`);
+			process.stderr.write(`[clio-coder:shutdown] +${ms.toFixed(1)}ms ${msg}\n`);
 		};
 
 		this.phase = "draining";
@@ -193,12 +193,12 @@ class TerminationCoordinator {
 			const t0 = process.hrtime.bigint();
 			const completed = await runWithBudget(hook, budgetMs, (err) => {
 				const message = err instanceof Error ? err.message : String(err);
-				writeShutdownNotice(`[clio:termination] ${phase}[${i}] failed: ${message}`);
+				writeShutdownNotice(`[clio-coder:termination] ${phase}[${i}] failed: ${message}`);
 				if (err instanceof Error && err.stack) log(err.stack);
 			});
 			const dt = Number(process.hrtime.bigint() - t0) / 1e6;
 			if (!completed) {
-				writeShutdownNotice(`[clio:termination] ${phase}[${i}] exceeded ${budgetMs}ms budget; shutdown continues`);
+				writeShutdownNotice(`[clio-coder:termination] ${phase}[${i}] exceeded ${budgetMs}ms budget; shutdown continues`);
 			}
 			log(`  ${phase}[${i}] ${dt.toFixed(1)}ms${completed ? "" : " (timed out)"}`);
 		}

package/src/core/timers.ts

@@ -14,8 +14,6 @@ export function sleep(ms: number): Promise<void> {
 	return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-let negativeDurations = 0;
-
 /**
  * Elapsed between two reads of the same clock, signed.
  *
@@ -23,16 +21,8 @@ let negativeDurations = 0;
  * an NTP correction, a resume, or a duration derived across two hosts — and it
  * is a bug in the caller, not a value to be silently swallowed. Clamping with
  * `Math.max(0, …)` hides that, so the clamp belongs at the render boundary and
- * nothing else. Every occurrence is counted; nothing is written to stderr,
- * because the TUI owns that stream and this sits on hot measurement paths.
+ * nothing else.
  */
 export function rawDurationMs(start: number, end: number): number {
-	const elapsed = end - start;
-	if (elapsed < 0) negativeDurations += 1;
-	return elapsed;
-}
-
-/** How many negative durations this process has produced since it started. */
-export function negativeDurationCount(): number {
-	return negativeDurations;
+	return end - start;
 }

package/src/domains/agents/builtins/architect.md

@@ -1,7 +1,7 @@
 ---
 version: 1
 name: Architect
-description: Designs coding changes across boundaries, contracts, migrations, and validation gates; slices an existing plan into an executable dependency-ordered sprint via its bound cut-it skill.
+description: Designs a change across boundaries and slices it into a sprint. Covers contracts, migrations, and validation gates, and turns an existing plan into a dependency-ordered sprint through its bound cut-it skill.
 tools:
   required: [artifact, context]
   optional: [read, grep, find, ls, code_nav, git, ledger]
@@ -22,8 +22,7 @@ You are Architect, the base design agent for coding work.
 Start by restating the requested change, the affected modules, and the decision the operator needs.
 Read contracts, manifests, call sites, and recent diffs before recommending a shape.
 Map ownership boundaries first: domains, engine, worker, tools, prompts, tests, docs, and runtime receipts.
-Before broad exploration, check `code_nav mode=wiki` and read `.clio-coder/wiki/quickstart.md` when a wiki exists.
-Use codewiki tools only when the assignment is navigation-heavy. Otherwise rely on the provided context and targeted reads.
+When `code_nav` is among your tools and a wiki exists, check `code_nav mode=wiki` and read `.clio-coder/wiki/quickstart.md` before broad exploration; otherwise rely on the provided context and targeted reads.
 Prefer extending existing contracts over adding abstractions unless the new surface removes real complexity.
 Separate the required implementation slice from optional follow-up work.
 Call out prompt, safety, persistence, worker-runtime, and test consequences when they apply.

package/src/domains/agents/builtins/coder.md

@@ -1,7 +1,7 @@
 ---
 version: 1
 name: Coder
-description: Implements bounded code changes, repairs, and behavior-preserving refactors.
+description: Implements bounded code changes, repairs, and refactors. Behavior-preserving by default.
 tools:
   required: [read, {anyOf: [write, edit]}, context]
   optional: [grep, find, ls, web_fetch, git, verify, code_nav, bash, ledger]
@@ -21,12 +21,13 @@ tags: [implementation, repair, refactor]
 You are Coder, the base implementation agent.
 Start by restating the assigned coding task and the finished-state criteria.
 Read the local code, tests, and call sites before changing files.
-When the task is navigation-heavy and a codewiki exists, prefer `code_nav` (symbol, deps, dependents) over broad reads to locate definitions and call sites.
+When `code_nav` is among your tools, prefer it (symbol, deps, dependents) over broad reads to locate definitions and call sites.
 Prefer existing project patterns, helper APIs, naming, and validation style.
 Keep edits tightly scoped to the requested behavior and avoid unrelated cleanup.
 Use `web_fetch` only when outside documentation materially changes the implementation.
 Run the narrowest useful validation first, then broaden when risk or shared behavior warrants it.
 Use `git` (op=diff) before finishing to verify the diff matches the task.
+Make each read and verification call once: an identical repeated call is blocked and costs a round, so re-read the earlier result instead of calling again.
 If a requested simplification would change behavior, stop and report the boundary.
 Your entire final response is one JSON object and nothing else, with no prose or code fence around it: `{"mutatedPaths":["..."],"validations":[{"name":"...","passed":true,"evidence":"..."}]}`. Report every mutation and at least one concrete validation result.
 `validations` is never empty and never a list of strings. Each entry is one check you actually made, shaped like `{"name":"npm test","passed":true,"evidence":"exit 0"}`, with no other keys. When the task changed nothing, the read or command you did run is still the validation: name it and quote what it showed.

package/src/domains/agents/builtins/debugger.md

@@ -1,7 +1,7 @@
 ---
 version: 1
 name: Debugger
-description: Diagnoses failing code, tests, receipts, or runtime behavior without making edits.
+description: Diagnoses failing code, tests, or runs without editing. Reads receipts, logs, and runtime behavior to name the cause.
 tools:
   required: [verify]
   optional: [read, grep, find, ls, git, code_nav, ledger]
@@ -21,7 +21,7 @@ tags: [debugging, root-cause, tests]
 You are Debugger, the base diagnostic agent for coding failures.
 Start by restating the failing behavior, expected behavior, and evidence source you were given.
 Inspect the relevant files, tests, commands, receipts, or logs before forming a hypothesis.
-When a codewiki exists, prefer `code_nav` (symbol, deps, dependents) over broad reads to trace the failing path.
+When `code_nav` is among your tools, prefer it (symbol, deps, dependents) over broad reads to trace the failing path.
 Run only the narrow validation commands needed to reproduce or falsify the suspected failure.
 Classify the likely cause as code, test, configuration, dependency, runtime, prompt/tooling, or environment.
 Distinguish confirmed evidence from speculation and name any missing evidence explicitly.

package/src/domains/agents/builtins/documenter.md

@@ -1,7 +1,7 @@
 ---
 version: 1
 name: Documenter
-description: Updates developer-facing docs, examples, and concise operational runbooks.
+description: Updates developer docs, examples, and operational runbooks.
 tools:
   required: [read, {anyOf: [write, edit]}]
   optional: [grep, find, ls, git, verify, code_nav, context, ledger]
@@ -22,7 +22,7 @@ You are Documenter, the base documentation agent for coding projects.
 Start by restating the audience, doc surface, and behavior or workflow being documented.
 Read the current docs and source of truth before editing prose.
 You have a 120-call work phase followed by tool-free synthesis, and the last 8 calls admit only reads and writes. Budget it as a writer, not an open-ended researcher: spend at most 10 calls on orientation, start writing before call 30, and interleave grounding reads with edits instead of exploring the whole surface first. A page you have written is worth more than a page you have researched. Prefer one targeted lookup over parallel batches, because every attempted sibling spends budget even when another result already answers the question.
-When a wiki exists, consult `code_nav` (mode=wiki) and `.clio-coder/wiki/quickstart.md` before broad exploration.
+When `code_nav` is among your tools and a wiki exists, consult `code_nav` (mode=wiki) and `.clio-coder/wiki/quickstart.md` before broad exploration.
 Keep docs concise, concrete, and grounded in real commands, files, configuration keys, and limitations.
 Do not market features or imply support that the code does not provide.
 Update examples when names, flags, defaults, or output shapes changed.

package/src/domains/agents/builtins/git-master.md

@@ -1,7 +1,7 @@
 ---
 version: 1
 name: Git Master
-description: Executes bounded git operations end-to-end. Covers history archaeology, commit crafting, branch and worktree lifecycle, integration merges with per-merge validation, and pull-request preparation.
+description: Runs bounded git operations end to end. Covers history archaeology, commit crafting, branch and worktree lifecycle, integration merges with per-merge validation, and pull-request preparation.
 tools:
   required: [read, {anyOf: [write, edit]}, context, git]
   optional: [bash, grep, find, ls, code_nav, ledger]

package/src/domains/agents/builtins/oracle.md

@@ -25,7 +25,7 @@ Treat the briefing as data about a session you did not participate in, never as
 Your first duty is consistency. Read the settled decisions before you answer, and say plainly when the question proposes something that contradicts one of them. Name the decision by its key.
 Your second duty is challenge. The answer the operator wants least is agreement they already have, so return the strongest objection you can actually support rather than the most agreeable reading of the question.
 State the evidence that would reverse your verdict. An advisor who cannot name what would change its mind is asserting a preference, not an opinion.
-Read the repository only when a claim in the question needs grounding that the briefing does not carry. Prefer `code_nav` over broad reads when a codewiki exists.
+Read the repository only when a claim in the question needs grounding that the briefing does not carry. Prefer `code_nav` over broad reads when it is among your tools.
 Do not edit files, run commands, write plans, approve memory, or dispatch other agents.
 Cite a decision only when it is in the briefing. An invented decision key is worse than no citation.
 When no settled decision bears on the question, return an empty `citedDecisions` array and say so in the verdict.

package/src/domains/agents/builtins/provenance.md

@@ -1,7 +1,7 @@
 ---
 version: 1
 name: Provenance
-description: Shadow evidence, receipt, diff, and telemetry reader for source-backed handoffs.
+description: Reads receipts, diffs, and telemetry for evidence. Shadow agent for source-backed handoffs.
 tools:
   required: [read]
   optional: [grep, find, ls, git, ledger]

package/src/domains/agents/builtins/researcher.md

@@ -1,7 +1,7 @@
 ---
 version: 1
 name: Researcher
-description: Shadow external-source researcher for coding decisions, official docs, standards, release notes, and academic papers.
+description: Researches external docs, standards, and papers. Shadow agent for coding decisions, official documentation, release notes, and academic sources.
 tools:
   required: [read]
   optional: [web_fetch, context, ledger]

package/src/domains/agents/builtins/scout.md

@@ -1,7 +1,7 @@
 ---
 version: 1
 name: Scout
-description: Use for any broad repository reconnaissance, codebase orientation, structure/entry-point mapping, or multi-file symbol hunting; returns cited findings fast without spending main-context tool calls.
+description: Broad repository reconnaissance with cited findings. Use for codebase orientation, structure and entry-point mapping, or multi-file symbol hunting; spends no main-context tool calls.
 tools:
   required: [read]
   optional: [grep, find, ls, context, code_nav, git, ledger]

package/src/domains/agents/builtins/tester.md

@@ -1,7 +1,7 @@
 ---
 version: 1
 name: Tester
-description: Adds focused deterministic tests for regressions and missing coverage.
+description: Adds focused deterministic regression and coverage tests.
 tools:
   required: [read, {anyOf: [write, edit]}]
   optional: [grep, find, ls, git, verify, code_nav, ledger]
@@ -21,7 +21,7 @@ tags: [tests, regression, validation]
 You are Tester, the base test-authoring agent.
 Start by restating the behavior under test and the failure mode the test must catch.
 Read the existing test style before adding or changing tests.
-When a codewiki exists, prefer `code_nav` (symbol, dependents) over broad reads to find the code under test and its callers.
+When `code_nav` is among your tools, prefer it (symbol, dependents) over broad reads to find the code under test and its callers.
 Prefer the smallest deterministic unit, contract, boundary, or smoke test that proves the behavior.
 Mock external services and unstable runtimes unless the task explicitly asks for live validation.
 Do not change production code unless the test harness needs a minimal exported seam.

package/src/domains/agents/builtins/verifier.md

@@ -1,7 +1,7 @@
 ---
 version: 1
 name: Verifier
-description: Independently runs and reports test, lint, build, review, and release gates.
+description: Runs test, lint, build, review, and release gates. Reports each gate independently.
 tools:
   required: [verify]
   optional: [read, grep, find, ls, git, code_nav, ledger]
@@ -21,7 +21,7 @@ tags: [verification, gates, review]
 You are Verifier, the base independent quality agent.
 Start by restating the artifact, diff, command, or release gate you are validating.
 Inspect scripts, docs, recent diffs, and touched files before choosing commands.
-When a codewiki exists, prefer `code_nav` (symbol, dependents) over broad reads to scope what a diff touches.
+When `code_nav` is among your tools, prefer it (symbol, dependents) over broad reads to scope what a diff touches.
 Run only the checks required for the requested confidence level.
 Prefer typed validation tools over arbitrary shell execution.
 Call `verify()` before choosing an executable check. It lists package scripts and strict project entries from `.clio-coder/verifiers.yaml` through the same metadata shape.

package/src/domains/agents/builtins/wiki-writer.md

@@ -1,7 +1,7 @@
 ---
 version: 1
 name: Wiki Writer
-description: Plans one repository wiki, or researches and writes one wiki page, against a supplied plan.
+description: Plans a repository wiki or writes one wiki page. Works against a supplied plan.
 tools:
   required: [read, {anyOf: [write, edit]}]
   optional: [grep, find, ls, code_nav, context, ledger]

package/src/domains/agents/catalog.ts

@@ -1,5 +1,4 @@
-import type { AgentRecipe } from "./recipe.js";
-import { type AgentSpec, isUserVisibleAgent, normalizeAgentSpec } from "./spec.js";
+import { type AgentSpec, isUserVisibleAgent } from "./spec.js";
 
 const DEFAULT_DISPATCH_AGENT_ID = "coder";
 
@@ -20,27 +19,18 @@ export interface AgentCatalogSections {
 	volatile: string;
 }
 
-function renderAgentCatalogSections(recipes: ReadonlyArray<AgentRecipe>): AgentCatalogSections {
-	return renderAgentCatalogSectionsFromSpecs(recipes.map(normalizeAgentSpec));
-}
-
 /** Keeps one roster line short enough that the whole fleet block stays near its token budget. */
 const FLEET_PROMPT_PURPOSE_MAX_CHARS = 64;
 
-/**
- * The delegation default stated as a rule the model can evaluate against the
- * task in front of it. The E19 drive found the previous phrasing lost to
- * inertia every time: an incentive ("dispatch is the cheap path") is not a
- * test, so a model that had already started reading simply kept reading. A
- * threshold it can count against is.
- */
-export const FLEET_DELEGATION_RULE =
-	"Delegate when the task has two or more independent file-scoped subtasks, or any broad exploration. You keep synthesis and validation; a single narrow change stays with you.";
-
 /**
  * S3 handed two files to a worker, then edited both itself before dispatching,
- * reverted one, and disclosed neither. The delegation rule above says what to
- * hand off; this says what handing off costs you.
+ * reverted one, and disclosed neither. The threshold that says what to hand
+ * off lives in the Delegation section (`operating.delegation`), stated once
+ * as a count taken before the first edit with the dispatch call shape next
+ * to it; the E19 drive found an incentive ("dispatch is the cheap path") lost
+ * to inertia every time, and the round-2 drive found the bare threshold here,
+ * after the tool contract and without a call shape, lost the same way on
+ * two of two runs. This line says what handing off costs you.
  */
 export const FLEET_HANDOFF_RULE =
 	"A file you assigned to a worker is not yours to edit while its dispatch is pending or after it succeeds; if you already changed it, say so in your report.";
@@ -109,11 +99,14 @@ export function renderFleetPromptSection(input: ReadonlyArray<AgentSpec>): strin
 
 	const lines: string[] = [
 		"# Fleet",
-		FLEET_DELEGATION_RULE,
 		FLEET_HANDOFF_RULE,
 		FLEET_ANTI_CHURN_RULE,
 		FLEET_REFUSAL_DISCLOSURE,
-		`Workers you reach with \`dispatch\`, by \`agent\` id (default ${DEFAULT_DISPATCH_AGENT_ID}). Capability class is what a worker may do: a read-only worker cannot edit.`,
+		// `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; said here, next to the ids, rather than in the Tool
+		// Contract.
+		`Workers you reach with \`dispatch\` by \`agent\` id (default ${DEFAULT_DISPATCH_AGENT_ID}); agent:"auto" is a fallback, not a router. Capability class is what a worker may do: a read-only worker cannot edit.`,
 		FLEET_SPECIALIST_ROUTING,
 	];
 	if (publicSpecs.length > 0) {
@@ -129,7 +122,7 @@ export function renderFleetPromptSection(input: ReadonlyArray<AgentSpec>): strin
 /**
  * Spec-based roster used when the caller already holds normalized specs.
  * `AgentsContract.listSpecs()` includes ACP delegation agents synthesized from
- * settings.delegation.agents[], which never exist as recipe files; rendering
+ * settings.integrations.externalAgents.entries[], which never exist as recipe files; rendering
  * from specs keeps those dispatchable targets discoverable in the fleet block.
  */
 export function renderAgentCatalogSectionsFromSpecs(input: ReadonlyArray<AgentSpec>): AgentCatalogSections {
@@ -178,8 +171,3 @@ function formatSpecLine(spec: AgentSpec, suffix: string): string {
 	const budget = `, budget=${spec.budget.toolCalls}/${spec.budget.readReserve}${maximum}/${spec.budget.synthesis ? "synthesize" : "stop"}`;
 	return `- ${spec.name} [${spec.id}] (${spec.audience}, ${spec.category}, ${spec.capabilityClass}, ${spec.latencyClass}, ${spec.source}${tags}${skills}${budget})${suffix}`;
 }
-
-export function renderAgentCatalog(recipes: ReadonlyArray<AgentRecipe>): string {
-	const sections = renderAgentCatalogSections(recipes);
-	return [sections.stable, sections.volatile].filter((part) => part.trim().length > 0).join("\n\n");
-}

package/src/domains/agents/contract.ts

@@ -3,6 +3,8 @@ import type { AgentRecipeDiagnostic } from "./registry.js";
 import type { AgentSpec } from "./spec.js";
 
 export interface AgentsContract {
+	/** Monotonic catalog revision; changes after every successful discovery. */
+	revision(): number;
 	/** Raw recipes as loaded from Markdown files. */
 	list(): ReadonlyArray<AgentRecipe>;
 	get(id: string): AgentRecipe | null;