@iowarp/clio-coder 0.4.8 → 0.4.9

package/src/interactive/theme/labels.ts

@@ -1,29 +1,50 @@
-/**
- * Abbreviate a wire model id for chips and dashboards without amputating a
- * meaningful placement prefix or version suffix. `dynamo/qwen3.8-27b` remains
- * visible as selected; only the leaf is shortened when the complete route is
- * wider than 24 characters.
- */
-export function abbreviateModelId(modelId: string | null | undefined): string {
-	const segments = (modelId ?? "").trim().split("/").filter(Boolean);
-	const base = segments.pop() ?? "";
-	if (base.length === 0) return "model";
-	const prefix = segments[0];
-	const maxLeaf = prefix ? Math.max(8, 24 - prefix.length - 1) : 18;
-	const parts = base.split("-").filter((part) => part.length > 0);
-	let leaf: string;
-	if (parts.length <= 1) leaf = base.length > maxLeaf ? base.slice(0, maxLeaf) : base;
-	else {
-		const kept: string[] = [];
-		for (const part of parts) {
-			const next = [...kept, part].join("-");
-			if (kept.length > 0 && next.length > maxLeaf) break;
-			kept.push(part);
-		}
-		const joined = kept.join("-");
-		leaf = joined.length > maxLeaf ? joined.slice(0, maxLeaf) : joined;
+import { sanitizeCallTargetText } from "../../domains/safety/call-target.js";
+import { stripTerminalSequences, truncateToWidth, visibleWidth } from "../../engine/tui.js";
+
+const identitySegments = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+
+/** Keep both placement and the distinguishing suffix when an identity must fit. */
+export function fitIdentityLabel(value: string, width: number): string {
+	value = sanitizeCallTargetText(value);
+	const room = Math.max(0, Math.floor(width));
+	if (visibleWidth(value) <= room) return value;
+	if (room <= 1) return room === 1 ? "…" : "";
+	const tailBudget = Math.ceil((room - 1) / 2);
+	let tail = "";
+	for (const { segment } of [...identitySegments.segment(value)].reverse()) {
+		if (visibleWidth(segment + tail) > tailBudget) break;
+		tail = segment + tail;
+	}
+	const headBudget = room - 1 - visibleWidth(tail);
+	let head = "";
+	for (const { segment } of identitySegments.segment(value)) {
+		if (visibleWidth(head + segment) > headBudget) break;
+		head += segment;
 	}
-	return prefix ? `${prefix}/${leaf}` : leaf;
+	return `${head}…${tail}`;
+}
+
+/** Compact wire identity with explicit omission and its version/quantization suffix. */
+export function abbreviateModelId(modelId: string | null | undefined): string {
+	const value = sanitizeCallTargetText(modelId ?? "");
+	if (value.length === 0) return "model";
+	if (visibleWidth(value) <= 24) return value;
+	const slash = value.lastIndexOf("/");
+	if (slash < 0) return fitIdentityLabel(value, 24);
+	const placement = value.slice(0, slash);
+	const model = value.slice(slash + 1);
+	const modelBudget = Math.min(18, visibleWidth(model));
+	return `${fitIdentityPrefix(placement, 23 - modelBudget)}/${fitIdentityLabel(model, modelBudget)}`;
+}
+
+/** Raw route fields stay separate until the surface knows its terminal-cell budget. */
+export interface TargetIdentity {
+	targetId: string | null | undefined;
+	modelId: string | null | undefined;
+}
+
+function fitIdentityPrefix(value: string, width: number): string {
+	return stripTerminalSequences(truncateToWidth(value, Math.max(0, width), "…", false));
 }
 
 export interface TargetLabelOptions {
@@ -31,6 +52,8 @@ export interface TargetLabelOptions {
 	separator?: string;
 	/** Off for surfaces with room for the whole wire id. */
 	abbreviate?: boolean;
+	/** Fit raw target/model fields once, preserving family and suffix before placement. */
+	width?: number;
 }
 
 /**
@@ -53,12 +76,25 @@ export function formatTargetLabel(
 	modelId: string | null | undefined,
 	options: TargetLabelOptions = {},
 ): string {
-	const target = (targetId ?? "").trim();
-	const model = (modelId ?? "").trim();
-	if (target.length === 0 && model.length === 0) return "not configured";
+	const target = sanitizeCallTargetText(targetId ?? "");
+	const model = sanitizeCallTargetText(modelId ?? "");
+	const fit = (label: string): string => (options.width === undefined ? label : fitIdentityLabel(label, options.width));
+	if (target.length === 0 && model.length === 0) return fit("not configured");
+	if (options.width !== undefined && target.length > 0 && model.length > 0) {
+		const width = Math.max(0, Math.floor(options.width));
+		const separator = options.separator ?? " · ";
+		const full = `${target}${separator}${model}`;
+		if (visibleWidth(full) <= width) return full;
+		const leaf = model.slice(model.lastIndexOf("/") + 1);
+		const available = width - visibleWidth(separator);
+		if (available < 9) return fitIdentityLabel(leaf, width);
+		const modelBudget = Math.min(visibleWidth(leaf), Math.max(8, Math.ceil(available * 0.7)));
+		const targetBudget = Math.min(visibleWidth(target), available - modelBudget);
+		return `${fitIdentityPrefix(target, targetBudget)}${separator}${fitIdentityLabel(leaf, available - targetBudget)}`;
+	}
 	const shown = options.abbreviate === false ? model : abbreviateModelId(model);
-	if (target.length === 0) return `no target · ${shown}`;
-	if (model.length === 0) return `${target} · no model`;
+	if (target.length === 0) return fit(`no target · ${shown}`);
+	if (model.length === 0) return fit(`${target} · no model`);
 	return `${target}${options.separator ?? " · "}${shown}`;
 }
 

package/src/interactive/turn-persistence.ts

@@ -78,6 +78,9 @@ export interface TurnPersistence {
 	 * (reminder block, skill preamble, handoff, then the operator's words);
 	 * `operatorText`, when it differs, is what the operator actually typed and
 	 * is what a transcript replay renders under the operator marker.
+	 * `displayText` is the literal editor input when an expansion (a prompt
+	 * template or command) replaced it; the session picker and replay show it,
+	 * while compaction keeps reasserting the expanded `operatorText`.
 	 */
 	appendSubmittedUserTurn(
 		agentRuntime: AgentRuntime,
@@ -85,6 +88,7 @@ export interface TurnPersistence {
 		images: ReadonlyArray<unknown> | undefined,
 		synthetic: boolean,
 		operatorText?: string,
+		displayText?: string,
 	): string | null;
 	appendRetryStatus(status: RetryStatusPayload): void;
 	appendModelChangeEntry(target: ChatLoopTarget): void;
@@ -404,7 +408,7 @@ export function createTurnPersistence(deps: TurnPersistenceDeps): TurnPersistenc
 			finishTracedTurn("success", null);
 		},
 
-		appendSubmittedUserTurn(agentRuntime, text, images, synthetic, operatorText): string | null {
+		appendSubmittedUserTurn(agentRuntime, text, images, synthetic, operatorText, displayText): string | null {
 			if (!deps.session) return null;
 			if (!deps.session.current()) {
 				deps.session.create({
@@ -415,6 +419,7 @@ export function createTurnPersistence(deps: TurnPersistenceDeps): TurnPersistenc
 			}
 			const payload: Record<string, unknown> = images ? { content: [{ type: "text", text }, ...images] } : { text };
 			if (operatorText !== undefined && operatorText !== text) payload.operatorText = operatorText;
+			if (displayText !== undefined && displayText !== (operatorText ?? text)) payload.displayText = displayText;
 			if (synthetic) {
 				payload.synthetic = true;
 				payload.source = "middleware_request_continuation";

package/src/interactive/turn-recovery.ts

@@ -275,7 +275,8 @@ export function createTurnRecovery(deps: TurnRecoveryDeps): TurnRecovery {
 						maxAttempts: settings.maxRetries,
 						errorMessage: message,
 					});
-					deps.emitNotice(message);
+					// The exhausted status already exposes this failure and retains its full
+					// diagnostic. A second raw notice bypasses bounded error presentation.
 					pruneFailedAssistantFromContext(agentRuntime.agent);
 					return true;
 				}

package/src/interactive/turn-runtime.ts

@@ -571,20 +571,30 @@ export function createTurnRuntime(deps: TurnRuntimeDeps): TurnRuntime {
 			stallTimer = setTimeout(
 				() => {
 					stallTimer = null;
-					const stallMs = deps.retrySettings().streamStallMs;
+					const retry = deps.retrySettings();
 					// Zero disables the escalation; an operator who wants a stream to
 					// hang forever keeps that by setting `retry.streamStallMs: 0`.
-					if (stallMs <= 0) return;
+					if (retry.streamStallMs <= 0) return;
 					if (stallSuspendDepth > 0 || toolsInFlight > 0) {
-						armStallTimer(stallMs);
+						armStallTimer(retry.streamStallMs);
+						return;
+					}
+					// Silence before a call's first delta is not silence mid-stream. A
+					// local server that slept reloads the model and prefills cold before
+					// it can emit anything, which is minutes of healthy quiet; a stream
+					// that already produced output and stops is a wedged slot.
+					const awaitingFirstToken = apiCallStartedAt !== null && apiCallFirstDeltaAt === null;
+					if (awaitingFirstToken && retry.firstTokenStallMs <= 0) {
+						armStallTimer(retry.streamStallMs);
 						return;
 					}
+					const stallMs = awaitingFirstToken ? Math.max(retry.firstTokenStallMs, retry.streamStallMs) : retry.streamStallMs;
 					const idleMs = performance.now() - lastActivityAt;
 					if (idleMs < stallMs) {
 						armStallTimer(stallMs - idleMs);
 						return;
 					}
-					state.streamStallReason = `stream stalled: no output from ${localRuntime.targetId} for ${Math.round(idleMs / 1000)}s, aborting (stream timeout)`;
+					state.streamStallReason = `stream stalled: no ${awaitingFirstToken ? "first token" : "output"} from ${localRuntime.targetId} for ${Math.round(idleMs / 1000)}s, aborting (stream timeout)`;
 					localRuntime.agent.abort();
 				},
 				Math.max(1, delayMs),
@@ -767,7 +777,14 @@ export function createTurnRuntime(deps: TurnRuntimeDeps): TurnRuntime {
 						typeof assistantEvent.delta === "string" &&
 						assistantEvent.delta.length > 0);
 				if (hasDelta && firstAssistantDeltaAt === null) firstAssistantDeltaAt = eventClock;
-				if (hasDelta && apiCallFirstDeltaAt === null) apiCallFirstDeltaAt = eventClock;
+				if (hasDelta && apiCallFirstDeltaAt === null) {
+					apiCallFirstDeltaAt = eventClock;
+					// The timer may be armed for the longer first-token window; the
+					// stream is live now, so the mid-stream window applies from here.
+					const stallMs = deps.retrySettings().streamStallMs;
+					clearStallTimer();
+					if (stallMs > 0) armStallTimer(stallMs);
+				}
 			}
 			if (enrichedEvent.type === "agent_end") {
 				context.noteRunCacheSummary(enrichedEvent.messages, runFirstCallVerdict);

package/src/interactive/view/artifacts.ts

@@ -1125,11 +1125,12 @@ export class WorkspaceArtifactProvider implements ArtifactProvider {
 				{
 					id: `workspace:${path}`,
 					category: this.category,
-					title: safeTitle(`${artifact.path} · ${artifact.tool}${kind}`, artifact.path),
+					title: safeTitle(`${basename(path)} · ${relative(workspace, path)} · ${artifact.tool}${kind}`, basename(path)),
 					timestamp: parseTime(artifact.timestamp),
 					sizeBytes: maybeSizeBytes(path),
 					path,
-					description: `${artifact.tool}${kind} · ${overwriteLabel}`,
+					description: `${artifact.tool}${kind} · ${overwriteLabel} · Workspace: ${workspace} · Turn: ${artifact.turnId}`,
+					...(this.deps.sessionMeta ? { sessionId: this.deps.sessionMeta.id } : {}),
 					toolName: artifact.tool,
 					searchText: [
 						artifact.path,

package/src/interactive/view/view-overlay.ts

@@ -1,6 +1,6 @@
+import { sanitizeCallTargetText } from "../../domains/safety/call-target.js";
 import {
 	type Component,
-	fuzzyFilter,
 	Input,
 	Markdown,
 	matchesKey,
@@ -168,10 +168,6 @@ function isNonEmptySearchValue(value: string | undefined): value is string {
 	return typeof value === "string" && value.trim().length > 0;
 }
 
-function broadFilterText(artifact: ViewArtifact): string {
-	return `${artifact.id} ${artifact.category} ${artifact.title}`;
-}
-
 function artifactSearchValues(artifact: ViewArtifact): string[] {
 	return [
 		artifact.id,
@@ -188,8 +184,12 @@ function artifactSearchValues(artifact: ViewArtifact): string[] {
 	].filter(isNonEmptySearchValue);
 }
 
-function categoryFilterText(artifact: ViewArtifact): string {
-	return artifactSearchValues(artifact).join(" ");
+function matchesFilterText(artifact: ViewArtifact, query: string): boolean {
+	const values = artifactSearchValues(artifact).map((value) => value.toLocaleLowerCase());
+	return query
+		.toLocaleLowerCase()
+		.split(/\s+/u)
+		.every((token) => values.some((value) => value.includes(token)));
 }
 
 function matchesExactArtifactValue(artifact: ViewArtifact, value: string): boolean {
@@ -225,10 +225,10 @@ function filterViewArtifacts(artifacts: ReadonlyArray<ViewArtifact>, query: stri
 	if (parsed.kind === "category") {
 		const categoryArtifacts = artifacts.filter((artifact) => artifact.category === parsed.category);
 		if (parsed.value.length === 0) return categoryArtifacts;
-		return fuzzyFilter(categoryArtifacts, parsed.value, categoryFilterText);
+		return categoryArtifacts.filter((artifact) => matchesFilterText(artifact, parsed.value));
 	}
 	if (parsed.text.length === 0) return [...artifacts];
-	return fuzzyFilter([...artifacts], parsed.text, broadFilterText);
+	return artifacts.filter((artifact) => matchesFilterText(artifact, parsed.text));
 }
 
 function artifactsInCategoryOrder(artifacts: ReadonlyArray<ViewArtifact>): ViewArtifact[] {
@@ -418,6 +418,7 @@ function viewFooterHint(focus: ViewPaneFocus, canVerify: boolean, innerWidth?: n
 			{ key: "PgUp/PgDn", verb: "page" },
 			{ key: "g/G", verb: "top/bottom" },
 			...(canVerify ? [{ key: "v", verb: "verify" }] : []),
+			{ key: "i", verb: "info" },
 			{ key: "o", verb: "path" },
 		],
 		"back",
@@ -446,31 +447,44 @@ export class ViewOverlayView implements Component {
 	private artifactError: string | null = null;
 	private content: LoadedContent | null = null;
 	private loadToken = 0;
+	private refreshToken = 0;
+	private showProvenance = false;
 	private lastContentWidth = 80;
 	private lastContentBodyHeight = 1;
 	private readonly verifications = new Map<string, ViewVerificationState>();
 
 	constructor(private readonly options: ViewOverlayOptions) {
 		this.filterText = options.initialFilter ?? "";
-		this.filterInput.setValue(this.filterText);
+		this.filterInput.handleInput(`\x1b[200~${this.filterText}\x1b[201~`);
 	}
 
 	refresh(): void {
+		const refreshToken = ++this.refreshToken;
+		const selected = this.selectedArtifact();
+		this.loadToken += 1;
 		this.loadingArtifacts = true;
 		this.artifactError = null;
 		this.options.requestRender?.();
 		void (async () => {
 			try {
-				this.artifacts = await listViewArtifacts(this.options.providers);
-				this.selectedIndex = initialViewSelection(this.artifacts, this.filterText);
+				const artifacts = await listViewArtifacts(this.options.providers);
+				if (refreshToken !== this.refreshToken) return;
+				this.artifacts = artifacts;
+				const retainedIndex = selected
+					? this.filteredArtifacts().findIndex((artifact) => artifactKey(artifact) === artifactKey(selected))
+					: -1;
+				this.selectedIndex = retainedIndex >= 0 ? retainedIndex : initialViewSelection(this.artifacts, this.filterText);
 				this.contentScrollOffset = 0;
 				this.content = null;
 			} catch (err) {
+				if (refreshToken !== this.refreshToken) return;
 				this.artifactError = err instanceof Error ? err.message : String(err);
 				this.artifacts = [];
 			} finally {
-				this.loadingArtifacts = false;
-				this.options.requestRender?.();
+				if (refreshToken === this.refreshToken) {
+					this.loadingArtifacts = false;
+					this.options.requestRender?.();
+				}
 			}
 		})();
 	}
@@ -490,6 +504,8 @@ export class ViewOverlayView implements Component {
 	}
 
 	private selectIndex(next: number): void {
+		this.loadToken += 1;
+		this.showProvenance = false;
 		const filtered = this.filteredArtifacts();
 		if (filtered.length === 0) {
 			this.selectedIndex = 0;
@@ -513,14 +529,17 @@ export class ViewOverlayView implements Component {
 	}
 
 	private ensureContentLoaded(artifact: ViewArtifact | undefined): void {
-		if (!artifact) return;
+		if (!artifact) {
+			this.content = null;
+			return;
+		}
 		const key = artifactKey(artifact);
 		if (this.content?.key === key) return;
 		const token = ++this.loadToken;
 		this.content = { key, status: "loading", lines: [clioTheme().fg("dim", "loading artifact…")], format: "text" };
 		void (async () => {
 			try {
-				const loaded = await artifact.load();
+				const loaded = await Promise.resolve().then(() => artifact.load());
 				if (token !== this.loadToken) return;
 				this.content = { key, status: "loaded", lines: loaded.lines, format: loaded.format };
 			} catch (err) {
@@ -540,6 +559,20 @@ export class ViewOverlayView implements Component {
 	}
 
 	private renderedContentLines(width: number): string[] {
+		if (this.showProvenance) {
+			const artifact = this.selectedArtifact();
+			if (!artifact) return [];
+			return [
+				`Title: ${artifact.title}`,
+				`Category: ${artifact.category}`,
+				`ID: ${artifact.id}`,
+				`Path: ${artifact.path ?? "No backing path"}`,
+				...(artifact.sessionId ? [`Session: ${artifact.sessionId}`] : []),
+				...(artifact.runId ? [`Run: ${artifact.runId}`] : []),
+				...(artifact.correlationId ? [`Correlation: ${artifact.correlationId}`] : []),
+				...(artifact.description ? [`Details: ${artifact.description}`] : []),
+			].flatMap((line) => wrapTextWithAnsi(sanitizeCallTargetText(line), Math.max(1, width)));
+		}
 		const content = this.content;
 		if (!content) return [];
 		if (content.status === "error") return content.lines.flatMap((line) => wrapTextWithAnsi(line, Math.max(1, width)));
@@ -572,10 +605,30 @@ export class ViewOverlayView implements Component {
 		}
 
 		const filtered = this.filteredArtifacts();
-		if (filtered.length === 0) return this.fixedLines([...lines, theme.fg("dim", "No matching details.")], width, height);
+		lines.push(
+			padAnsi(
+				theme.fg(
+					this.focus === "list" ? "accent" : "dim",
+					`List · ${filtered.length}/${this.artifacts.length} · ←→ category`,
+				),
+				width,
+				ELLIPSIS,
+			),
+		);
+		if (filtered.length === 0)
+			return this.fixedLines(
+				[
+					...lines,
+					theme.fg("dim", "No matching details."),
+					theme.fg("muted", "Ctrl+U clears the filter."),
+					theme.fg("dim", "Try workspace: or receipt:"),
+				],
+				width,
+				height,
+			);
 		const rows = groupedViewRows(filtered);
 		const selectedRow = rows.findIndex((row) => row.type === "item" && row.itemIndex === this.selectedIndex);
-		const rowHeight = Math.max(1, height - 1);
+		const rowHeight = Math.max(1, height - lines.length);
 		if (selectedRow >= 0) {
 			if (selectedRow < this.listScrollOffset) this.listScrollOffset = selectedRow;
 			if (selectedRow >= this.listScrollOffset + rowHeight) this.listScrollOffset = selectedRow - rowHeight + 1;
@@ -614,7 +667,21 @@ export class ViewOverlayView implements Component {
 		this.ensureContentLoaded(artifact);
 		this.lastContentWidth = width;
 		const verification = artifact ? this.verifications.get(artifactKey(artifact)) : undefined;
-		const header = buildArtifactHeaderLines(artifact, verification, width);
+		const header = [
+			padAnsi(
+				clioTheme().fg(
+					this.focus === "content" ? "accent" : "dim",
+					this.showProvenance
+						? "Provenance · i preview · Esc list"
+						: this.focus === "content"
+							? "Preview · i info · Esc list"
+							: "Preview · Enter/Tab focus",
+				),
+				width,
+				ELLIPSIS,
+			),
+			...buildArtifactHeaderLines(artifact, verification, width),
+		];
 		const bodyHeight = Math.max(0, height - header.length);
 		this.lastContentBodyHeight = Math.max(1, bodyHeight);
 		const body = this.renderedContentLines(width);
@@ -657,6 +724,7 @@ export class ViewOverlayView implements Component {
 			matchesKey(data, "shift+tab") ||
 			(this.focus === "list" && matchesKey(data, "enter"))
 		) {
+			if (this.focus === "list" && !this.selectedArtifact()) return;
 			this.focus = this.focus === "list" ? "content" : "list";
 			this.options.requestRender?.();
 			return;
@@ -669,6 +737,12 @@ export class ViewOverlayView implements Component {
 			this.selectCategory(1);
 			return;
 		}
+		if (this.focus === "content" && data === "i") {
+			this.showProvenance = !this.showProvenance;
+			this.contentScrollOffset = 0;
+			this.options.requestRender?.();
+			return;
+		}
 		if (this.focus === "content" && data === "v") {
 			this.verifySelected();
 			return;
@@ -704,7 +778,9 @@ export class ViewOverlayView implements Component {
 			return true;
 		}
 		const previous = this.filterText;
-		this.filterInput.handleInput(data);
+		if (matchesKey(data, "ctrl+u")) {
+			this.filterInput.applyEdit("clear");
+		} else this.filterInput.handleInput(data);
 		this.filterText = this.filterInput.getValue();
 		if (previous !== this.filterText) {
 			this.selectInitialFilterMatch();

package/src/tools/agent-tools.ts

@@ -30,6 +30,7 @@ import type { AgentTool, AgentToolResult, AgentToolUpdateCallback } from "../eng
 import { applyToolProfile, type ToolProfileName } from "./profiles.js";
 import type { ToolInvokeOptions, ToolRegistry, ToolResult, ToolSpec } from "./registry.js";
 import { isDispositionedToolResultError, toolResultContextText } from "./result-disposition.js";
+import { toolSpecPlacement, withGatewayForCapabilities } from "./surface.js";
 
 /**
  * Lightweight per-call observability hook. Default no-op so unused
@@ -308,9 +309,10 @@ function errorMessage(err: unknown): string {
  * (`Value.Check` answers identically with and without), so the copy handed
  * to the agent loop drops every `~`-prefixed key. Symbol keys are copied
  * through untouched because pi-ai picks its coercion path by the TypeBox
- * kind symbol on the root schema.
+ * kind symbol on the root schema. Exported for the gateway's describe, which
+ * hands a capability's schema to the model through a result the same way.
  */
-function wireParameterSchema<T>(schema: T): T {
+export function wireParameterSchema<T>(schema: T): T {
 	if (Array.isArray(schema)) return schema.map((entry) => wireParameterSchema(entry)) as T;
 	if (typeof schema !== "object" || schema === null) return schema;
 	const source = schema as Record<PropertyKey, unknown>;
@@ -374,30 +376,41 @@ function toAgentTool(
  *   1. tools registered on the supplied registry
  *   2. tools whose id appears in `allowedTools`
  *
- * When `allowedTools` is undefined, step 3 is skipped.
+ * projected onto the direct surface: a gateway-placed capability on the
+ * effective list is reachable through the attached `gateway` tool, never as
+ * a schema of its own. When `allowedTools` is undefined, step 2 is skipped.
  */
 export function resolveAgentTools(input: ResolveAgentToolsInput): AgentTool[] {
 	const specs: ToolSpec[] = [];
 	for (const name of effectiveToolNames(input)) {
 		const spec = input.registry.get(name);
-		if (spec) specs.push(spec);
+		if (spec && toolSpecPlacement(spec) === "direct") specs.push(spec);
 	}
 	specs.sort((a, b) => a.name.localeCompare(b.name));
 	return specs.map((spec) => toAgentTool(spec, input.registry, input.telemetry, input.invokeOptions));
 }
 
 /**
- * The effective tool surface for one worker run, as names. This is the single
+ * The effective capability surface for one run, as names. This is the single
  * narrowing used both to build the executable tool set and to compute the
  * signature the worker attests, so an attested identity can never describe a
  * different surface than the one the agent actually gets.
+ *
+ * The list names capabilities, whatever their placement: a recipe that admits
+ * `git` keeps `git` here, and because `git` sits behind the gateway the list
+ * gains `gateway` as well (the same rule dispatch admission applies to the
+ * list it approves, so the two signatures agree). `resolveAgentTools` then
+ * attaches only the direct-placed names, and the gateway enforces this list
+ * on every call it makes on the run's behalf.
  */
 export function effectiveToolNames(input: Omit<ResolveAgentToolsInput, "telemetry" | "invokeOptions">): ToolName[] {
 	const profileContext = {
 		...(input.agentId !== undefined ? { agentId: input.agentId } : {}),
 		...(input.task !== undefined ? { task: input.task } : {}),
 	};
-	const toolIds = applyToolProfile(input.registry.listRegistered(), input.toolProfile, profileContext);
+	const gatewayNames = input.registry.listGateway().map((spec) => spec.name);
+	const registered = [...input.registry.listRegistered(), ...gatewayNames];
+	const toolIds = applyToolProfile(registered, input.toolProfile, profileContext);
 	const allowed = input.allowedTools ? new Set<string>(input.allowedTools) : null;
 	const includeInteractiveTools = input.includeInteractiveTools !== false;
 	const names: ToolName[] = [];
@@ -408,7 +421,8 @@ export function effectiveToolNames(input: Omit<ResolveAgentToolsInput, "telemetr
 		if (allowed && !allowed.has(name)) continue;
 		names.push(name);
 	}
-	return names;
+	if (input.registry.get(ToolNames.Gateway) === undefined) return names;
+	return withGatewayForCapabilities(names);
 }
 
 /**

package/src/tools/artifact.ts

@@ -1,10 +1,9 @@
-import { mkdirSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { Type } from "typebox";
 import { artifactDefaultPath, CLIO_ARTIFACT_DIR } from "../core/artifact-paths.js";
 import { ToolNames } from "../core/tool-names.js";
 import { StringEnum } from "../engine/ai.js";
-import { withFileMutationQueue } from "./file-mutation-queue.js";
+import { type AtomicPublishResult, publishFileAtomically, withFileMutationQueue } from "./file-mutation-queue.js";
 import { resolveToCwd } from "./path-utils.js";
 import type { ToolResult, ToolSpec } from "./registry.js";
 
@@ -14,6 +13,12 @@ import type { ToolResult, ToolSpec } from "./registry.js";
  * answer, so pi-agent-core skips the follow-up LLM call that would only
  * summarize it.
  *
+ * Placement: gateway. The terminal contract survives the indirection because
+ * the gateway propagates `terminate`, `details.kind`, and `details.paths`
+ * from this result unchanged, so the turn still ends and `/view` still lists
+ * the document. The write is an atomic publish (temp file, fsync, rename) so
+ * a failed write never leaves a half-written artifact behind.
+ *
  * A pathless call lands under `.clio-coder/artifacts/`, not in the repo working
  * tree. A turn nobody asked for a file from used to drop REPORT.md into the
  * project root, which the operator then had to notice and delete; the working
@@ -58,11 +63,9 @@ async function writeTerminalArtifact(
 	}
 	const title = typeof args.title === "string" ? args.title.trim() : "";
 	const body = title.length > 0 && !content.trimStart().startsWith("#") ? `# ${title}\n\n${content}` : content;
+	let published: AtomicPublishResult;
 	try {
-		await withFileMutationQueue(target, async () => {
-			mkdirSync(path.dirname(target), { recursive: true });
-			writeFileSync(target, body, "utf8");
-		});
+		published = await withFileMutationQueue(target, () => publishFileAtomically(target, body));
 	} catch (err) {
 		return { kind: "error", message: `artifact: ${err instanceof Error ? err.message : String(err)}` };
 	}
@@ -70,10 +73,15 @@ async function writeTerminalArtifact(
 	const bytes = Buffer.byteLength(body, "utf8");
 	return {
 		kind: "ok",
-		output: `wrote ${kind} artifact (${bytes}B) to ${rel}`,
+		output: `wrote ${kind} artifact (${bytes}B) to ${rel}${published.durabilityWarning ? `\n${published.durabilityWarning}` : ""}`,
 		// shownBytes is the artifact's real size; the ledger otherwise measures
 		// this confirmation sentence (a 4753B plan rendered as "60B", #76).
-		details: { kind, paths: [target], observation: { shownBytes: bytes } },
+		details: {
+			kind,
+			paths: [target],
+			observation: { shownBytes: bytes },
+			file: { before: published.before, after: published.after },
+		},
 		// Writing the artifact is the whole turn; terminate skips the follow-up
 		// LLM call that would only restate what was just written.
 		terminate: true,