@iowarp/clio-coder 0.4.3 → 0.4.5

package/src/domains/session/task-board.ts

@@ -29,6 +29,8 @@ export interface TaskBoardTask {
 	status: TaskLedgerStatus;
 	origin?: "agent" | "user";
 	userTaskId?: string;
+	/** Operator requirements are declarations, not projected verifier execution results. */
+	requiredValidationEvidence?: TaskLedgerValidationEvidence[];
 	/** Block or drop reason; empty for pending/active/completed tasks. */
 	reason?: string;
 	/** Evidence note recorded when the task was completed. */
@@ -64,7 +66,7 @@ export interface TaskBoardCounts {
 export type TaskBoardMutation =
 	| { op: "plan"; title: string; tasks: ReadonlyArray<string> }
 	| { op: "add"; tasks: ReadonlyArray<string> }
-	| { op: "pick"; title: string; userTaskId: string }
+	| { op: "pick"; title: string; userTaskId: string; verification?: ReadonlyArray<{ check: string; timeoutMs: number }> }
 	| { op: "start"; id: string }
 	| { op: "done"; id: string; evidence: string }
 	| { op: "block"; id: string; reason: string }
@@ -179,6 +181,7 @@ function boardStatus(tasks: ReadonlyArray<TaskBoardTask>): TaskLedgerStatus {
 export function toTaskLedgerEntryFields(board: TaskBoardSnapshot, now: Date): TaskLedgerEntryFields {
 	const evidence: TaskLedgerValidationEvidence[] = [];
 	const subgoals: TaskLedgerGoal[] = board.tasks.map((task) => {
+		evidence.push(...(task.requiredValidationEvidence ?? []).map((item) => ({ ...item })));
 		if (task.status === "completed" && task.evidence) {
 			evidence.push({
 				id: `${task.id}.evidence`,
@@ -284,6 +287,23 @@ export function foldSessionTaskHistory(entries: ReadonlyArray<unknown>): Session
 		.map(({ lastIndex: _lastIndex, tasks, ...board }) => ({ ...board, tasks: [...tasks.values()] }));
 }
 
+function acceptanceRequirementDescription(check: string): string {
+	return `Operator acceptance requirement: ${check} (declaration only; see verification receipts for execution status)`;
+}
+
+/** Old pickup snapshots used pending for declarations; preserve any actual observations. */
+function acceptanceRequirement(item: TaskLedgerValidationEvidence): TaskLedgerValidationEvidence {
+	if (
+		item.status === "pending" &&
+		item.command &&
+		item.description === `Operator acceptance: ${item.command}` &&
+		item.observedAt === undefined
+	) {
+		return { ...item, status: "required", description: acceptanceRequirementDescription(item.command) };
+	}
+	return { ...item };
+}
+
 function toEntryView(entry: {
 	boardId?: string;
 	goals: TaskLedgerGoal[];
@@ -308,6 +328,8 @@ function toEntryView(entry: {
 				origin: goal.origin ?? "agent",
 			};
 			if (goal.userTaskId) task.userTaskId = goal.userTaskId;
+			const required = entry.requiredValidationEvidence.filter((item) => item.id.startsWith(`${goal.id}.acceptance.`));
+			if (required.length > 0) task.requiredValidationEvidence = required.map(acceptanceRequirement);
 			if (goal.description) task.reason = goal.description;
 			const evidence = evidenceByTask.get(goal.id);
 			if (evidence) task.evidence = evidence;
@@ -390,6 +412,15 @@ function applyMutation(
 			origin: "user",
 			userTaskId: mutation.userTaskId,
 		};
+		if (mutation.verification && mutation.verification.length > 0) {
+			picked.requiredValidationEvidence = mutation.verification.map((item, index) => ({
+				id: `${picked.id}.acceptance.${index}`,
+				description: acceptanceRequirementDescription(item.check),
+				command: item.check,
+				status: "required",
+				notes: `timeoutMs=${item.timeoutMs}`,
+			}));
+		}
 		return {
 			board: {
 				boardId: board?.boardId ?? "",

package/src/domains/session/tree/fork.ts

@@ -14,8 +14,7 @@ import { entryBelongsToPath } from "./active-path.js";
  * install it as current.
  *
  * Used by SessionContract.fork (current session) and the /fork message
- * picker path that lands in slice 12b-3. Kept out of extension.ts so the
- * bundle wiring stays thin.
+ * picker overlay. Kept out of extension.ts so the bundle wiring stays thin.
  */
 export interface ForkInput {
 	/** The state we are forking from. Must carry a live writer. */

package/src/domains/session/tree/navigator.ts

@@ -6,7 +6,7 @@ import type { ResolvedLabel } from "./manager.js";
  * Purely functional tree-walk helpers. Given the raw SessionTreeNode[] that
  * the engine persists plus a label map and a leaf pointer, produce a
  * render-friendly snapshot. No I/O. Used by SessionContract.tree() to
- * deliver a serializable structure to overlay renderers in slice 12b-2.
+ * deliver a serializable structure to the /tree overlay renderer.
  */
 
 /**

package/src/domains/user-tasks/acceptance.ts

@@ -0,0 +1,56 @@
+import {
+	DISPATCH_INTENT_TIMEOUT_MIN_MS,
+	type DispatchIntentCheckBound,
+	type DispatchIntentVerification,
+	normalizeIntentExpectedOutputs,
+	normalizeIntentVerification,
+} from "../dispatch/intent.js";
+
+export interface UserTaskAcceptance {
+	expectedOutputs: string[];
+	verification: DispatchIntentVerification[];
+}
+
+/** Validate stored acceptance without consulting a catalog that may have changed. */
+export function normalizeUserTaskAcceptance(raw: unknown): UserTaskAcceptance {
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+		throw new Error("acceptance must be an object");
+	}
+	const value = raw as Record<string, unknown>;
+	if (Object.keys(value).some((key) => key !== "expectedOutputs" && key !== "verification")) {
+		throw new Error("acceptance contains an unknown field");
+	}
+	if (!Array.isArray(value.expectedOutputs) || !Array.isArray(value.verification)) {
+		throw new Error("acceptance requires expectedOutputs and verification arrays");
+	}
+	const checks = new Map<string, DispatchIntentCheckBound>();
+	const rawVerification = value.verification.map((entry: unknown) => {
+		if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+			throw new Error("acceptance verification must contain check and timeoutMs");
+		}
+		const item = entry as Record<string, unknown>;
+		if (Object.keys(item).some((key) => key !== "check" && key !== "timeoutMs")) {
+			throw new Error("acceptance verification contains an unknown field");
+		}
+		if (
+			typeof item.check !== "string" ||
+			typeof item.timeoutMs !== "number" ||
+			!Number.isSafeInteger(item.timeoutMs) ||
+			item.timeoutMs <= 0
+		) {
+			throw new Error("acceptance verification requires a check and a positive integer timeoutMs");
+		}
+		checks.set(item.check.trim(), {
+			id: item.check.trim(),
+			timeoutMs: Math.max(DISPATCH_INTENT_TIMEOUT_MIN_MS, item.timeoutMs, checks.get(item.check.trim())?.timeoutMs ?? 0),
+		});
+		return { check: item.check, timeout_ms: item.timeoutMs };
+	});
+	const expectedOutputs = normalizeIntentExpectedOutputs(value.expectedOutputs);
+	if (!Array.isArray(expectedOutputs))
+		throw new Error(expectedOutputs.ok ? "invalid acceptance outputs" : expectedOutputs.message);
+	const verification = normalizeIntentVerification(rawVerification, checks);
+	if (!Array.isArray(verification))
+		throw new Error(verification.ok ? "invalid acceptance verification" : verification.message);
+	return { expectedOutputs, verification };
+}

package/src/domains/user-tasks/active-acceptance.ts

@@ -0,0 +1,40 @@
+import { isSessionEntry } from "../session/entries.js";
+import type { TaskBoardSnapshot } from "../session/task-board.js";
+import type { UserTaskAcceptance } from "./acceptance.js";
+import type { UserTask } from "./store.js";
+
+/** Keep a task's acceptance through the turn that finishes or blocks its board row. */
+export function activeUserTaskAcceptance(
+	tasks: ReadonlyArray<UserTask>,
+	board: TaskBoardSnapshot | null,
+	sessionId: string | null,
+	window: ReadonlyArray<unknown>,
+): UserTaskAcceptance | undefined {
+	if (!board || !sessionId) return undefined;
+	const touched = new Set<string>();
+	for (const entry of window) {
+		if (!isSessionEntry(entry) || entry.kind !== "message" || entry.role !== "tool_call") continue;
+		if (!entry.payload || typeof entry.payload !== "object") continue;
+		const payload = entry.payload as { name?: string; toolName?: string; args?: { action?: string; id?: string } };
+		if (
+			(payload.name ?? payload.toolName) === "tasks" &&
+			payload.args?.id &&
+			["done", "block", "drop"].includes(payload.args.action ?? "")
+		)
+			touched.add(payload.args.id);
+	}
+	const linked = new Set(
+		board.tasks
+			.filter((task) => task.status === "pending" || task.status === "active" || touched.has(task.id))
+			.map((task) => task.userTaskId),
+	);
+	const acceptance = tasks
+		.filter((task) => task.handedSessionId === sessionId && linked.has(task.id))
+		.flatMap((task) => (task.acceptance ? [task.acceptance] : []));
+	return acceptance.length > 0
+		? {
+				expectedOutputs: [...new Set(acceptance.flatMap((item) => item.expectedOutputs))],
+				verification: acceptance.flatMap((item) => item.verification),
+			}
+		: undefined;
+}

package/src/domains/user-tasks/handoff.ts

@@ -0,0 +1,16 @@
+import type { UserTask } from "./store.js";
+
+/** The operator-authored pickup turn shared by CLI, slash, and overlay handoffs. */
+export function formatUserTaskHandoff(task: Pick<UserTask, "id" | "title" | "note" | "acceptance">): string {
+	const note = task.note ? ` ${task.note}.` : "";
+	const acceptance = task.acceptance ? ` Acceptance: ${JSON.stringify(task.acceptance)}.` : "";
+	return (
+		`Operator task ${task.id}: ${task.title}.${note}${acceptance} ` +
+		`Before working this task, call tasks action="pick" id="${task.id}" and confirm its durable session/board link. ` +
+		"Use the returned linked tN for start and done; do not replace the pickup with a self-created plan or pick unrelated inbox tasks. " +
+		"Respect the task's authorized scope, including proposal-only limits. If pickup fails, report the actual state and stop this task's work. " +
+		"After work and required verification, call tasks done on that linked tN with concrete evidence, then tasks list. " +
+		`Claim ${task.id} completed only if the linked board row is completed and the durable operator task is done with the same session/board link. ` +
+		"Report the IDs, actual state, and verification results or limitations; an unpicked or still-handed task is not done."
+	);
+}

package/src/domains/user-tasks/store.ts

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { CLIO_PROJECT_DIR } from "../../core/artifact-paths.js";
 import { atomicWrite } from "../../engine/session.js";
+import { normalizeUserTaskAcceptance, type UserTaskAcceptance } from "./acceptance.js";
 
 export const USER_TASKS_FILE_VERSION = 1 as const;
 export const USER_TASKS_RELATIVE_PATH = `${CLIO_PROJECT_DIR}/user-tasks.json`;
@@ -12,6 +13,7 @@ export interface UserTask {
 	id: string;
 	title: string;
 	note?: string;
+	acceptance?: UserTaskAcceptance;
 	status: UserTaskStatus;
 	createdAt: string;
 	updatedAt: string;
@@ -37,7 +39,8 @@ export interface UserTasksStore {
 	readonly path: string;
 	snapshot(): ReadonlyArray<UserTask>;
 	get(id: string): UserTask | null;
-	add(title: string, note?: string): UserTask;
+	add(title: string, note?: string, acceptance?: UserTaskAcceptance): UserTask;
+	setAcceptance(id: string, acceptance: UserTaskAcceptance): UserTask;
 	hand(id: string, sessionId?: string): UserTask;
 	done(id: string): UserTask;
 	drop(id: string): UserTask;
@@ -65,6 +68,7 @@ const TASK_KEYS = new Set([
 	"id",
 	"title",
 	"note",
+	"acceptance",
 	"status",
 	"createdAt",
 	"updatedAt",
@@ -86,6 +90,13 @@ function isOptionalString(value: unknown): boolean {
 
 function isUserTask(value: unknown): value is UserTask {
 	if (!isRecord(value) || !hasOnlyKeys(value, TASK_KEYS)) return false;
+	if (value.acceptance !== undefined) {
+		try {
+			normalizeUserTaskAcceptance(value.acceptance);
+		} catch {
+			return false;
+		}
+	}
 	return (
 		typeof value.id === "string" &&
 		/^u[1-9]\d*$/.test(value.id) &&
@@ -138,7 +149,7 @@ function parseFile(body: string, path: string): UserTasksFile {
 }
 
 function copyTask(task: UserTask): UserTask {
-	return { ...task };
+	return { ...task, ...(task.acceptance ? { acceptance: normalizeUserTaskAcceptance(task.acceptance) } : {}) };
 }
 
 function initialFile(): UserTasksFile {
@@ -219,7 +230,8 @@ export function createUserTasksStore(deps: UserTasksStoreDeps): UserTasksStore {
 			const task = load().tasks.find((candidate) => candidate.id === id);
 			return task ? copyTask(task) : null;
 		},
-		add(title: string, note?: string): UserTask {
+		add(title: string, note?: string, acceptance?: UserTaskAcceptance): UserTask {
+			const normalizedAcceptance = acceptance === undefined ? undefined : normalizeAcceptance(acceptance);
 			const normalizedTitle = title.trim();
 			if (normalizedTitle.length === 0) throw new UserTasksStoreError("operator task title cannot be empty");
 			const normalizedNote = note?.trim();
@@ -229,6 +241,7 @@ export function createUserTasksStore(deps: UserTasksStoreDeps): UserTasksStore {
 				id: `u${file.nextId}`,
 				title: normalizedTitle,
 				...(normalizedNote ? { note: normalizedNote } : {}),
+				...(normalizedAcceptance ? { acceptance: normalizedAcceptance } : {}),
 				status: "open",
 				createdAt: timestamp,
 				updatedAt: timestamp,
@@ -238,6 +251,16 @@ export function createUserTasksStore(deps: UserTasksStoreDeps): UserTasksStore {
 			save(file);
 			return copyTask(task);
 		},
+		setAcceptance(id: string, acceptance: UserTaskAcceptance): UserTask {
+			const normalized = normalizeAcceptance(acceptance);
+			const file = load();
+			const task = file.tasks.find((item) => item.id === id);
+			if (!task) throw new UserTasksStoreError(`operator task ${id} was not found`);
+			task.acceptance = normalized;
+			task.updatedAt = now();
+			save(file);
+			return copyTask(task);
+		},
 		hand(id: string, sessionId?: string): UserTask {
 			return mutate(id, ["open"], "handed", sessionId);
 		},
@@ -295,3 +318,11 @@ export function createUserTasksStore(deps: UserTasksStoreDeps): UserTasksStore {
 		},
 	};
 }
+
+function normalizeAcceptance(raw: unknown): UserTaskAcceptance {
+	try {
+		return normalizeUserTaskAcceptance(raw);
+	} catch (error) {
+		throw new UserTasksStoreError(error instanceof Error ? error.message : String(error), { cause: error });
+	}
+}

package/src/engine/acp/adapter.ts

@@ -5,6 +5,7 @@ import {
 	type DelegationAgentConfig,
 } from "../../core/defaults.js";
 import type { HeartbeatStamp } from "../../domains/dispatch/heartbeat.js";
+import { resolveCostProvenance } from "../../domains/providers/types/cost-provenance.js";
 import type { AutonomyLevel } from "../../domains/safety/autonomy.js";
 import type { SafetyContract } from "../../domains/safety/contract.js";
 import type { AgentEvent } from "../types.js";
@@ -134,13 +135,16 @@ function flattenPrompt(input: AcpDelegationRunInput): string {
 	return parts.join("\n\n");
 }
 
-function emptyUsage(): AcpDelegationUsage {
+export function emptyUsage(): AcpDelegationUsage {
 	return {
+		tokensReported: false,
 		inputTokens: 0,
 		outputTokens: 0,
 		cacheReadTokens: 0,
 		cacheWriteTokens: 0,
 		reasoningTokens: 0,
+		totalTokens: 0,
+		costUsd: 0,
 	};
 }
 
@@ -148,13 +152,59 @@ function finite(value: unknown): number {
 	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
 }
 
-function mergeUsage(into: AcpDelegationUsage, raw: unknown): void {
+/** Presence matters: an explicit zero must not fall back to another observation. */
+function nonnegative(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+
+export function mergeUsage(into: AcpDelegationUsage, raw: unknown): void {
 	if (!isRecord(raw)) return;
-	into.inputTokens += finite(raw.input) + finite(raw.inputTokens) + finite(raw.input_tokens);
-	into.outputTokens += finite(raw.output) + finite(raw.outputTokens) + finite(raw.output_tokens);
-	into.cacheReadTokens += finite(raw.cacheRead) + finite(raw.cacheReadTokens) + finite(raw.cache_read_tokens);
-	into.cacheWriteTokens += finite(raw.cacheWrite) + finite(raw.cacheWriteTokens) + finite(raw.cache_write_tokens);
+	const tokensReported = [
+		raw.input,
+		raw.inputTokens,
+		raw.input_tokens,
+		raw.output,
+		raw.outputTokens,
+		raw.output_tokens,
+		raw.cacheRead,
+		raw.cacheReadTokens,
+		raw.cache_read_tokens,
+		raw.cacheWrite,
+		raw.cacheWriteTokens,
+		raw.cache_write_tokens,
+		raw.reasoning,
+		raw.reasoningTokens,
+		raw.reasoning_tokens,
+		raw.totalTokens,
+		raw.total_tokens,
+	].some((value) => nonnegative(value) !== undefined);
+	into.tokensReported ||= tokensReported;
+	const input = finite(raw.input) + finite(raw.inputTokens) + finite(raw.input_tokens);
+	const output = finite(raw.output) + finite(raw.outputTokens) + finite(raw.output_tokens);
+	const cacheRead = finite(raw.cacheRead) + finite(raw.cacheReadTokens) + finite(raw.cache_read_tokens);
+	const cacheWrite = finite(raw.cacheWrite) + finite(raw.cacheWriteTokens) + finite(raw.cache_write_tokens);
+	into.inputTokens += input;
+	into.outputTokens += output;
+	into.cacheReadTokens += cacheRead;
+	into.cacheWriteTokens += cacheWrite;
 	into.reasoningTokens += finite(raw.reasoning) + finite(raw.reasoningTokens) + finite(raw.reasoning_tokens);
+	// Prefer the peer's explicit total, including zero,
+	// otherwise sum the four billed categories (reasoning excluded, since a peer
+	// that reports it separately still counts it inside output).
+	const explicitTotal = nonnegative(raw.totalTokens) ?? nonnegative(raw.total_tokens);
+	into.totalTokens += explicitTotal ?? input + output + cacheRead + cacheWrite;
+	// Clio metadata uses costUsd; legacy message usage uses cost.total. These
+	// are alternate representations of one amount, never additive sources.
+	const cost = (isRecord(raw.cost) ? nonnegative(raw.cost.total) : undefined) ?? nonnegative(raw.costUsd);
+	into.costUsd += cost ?? 0;
+	if (tokensReported || cost !== undefined) {
+		const provenance = cost === undefined ? "unknown" : resolveCostProvenance(raw.costProvenance, "unknown");
+		const previous = into.costProvenance;
+		if (previous === undefined || previous === provenance) into.costProvenance = provenance;
+		else if (previous === "unknown" || provenance === "unknown") into.costProvenance = "unknown";
+		else if (previous === "estimated" || provenance === "estimated") into.costProvenance = "estimated";
+		else into.costProvenance = "known";
+	}
 }
 
 function errorMessage(value: unknown): string {
@@ -177,9 +227,9 @@ function errorEvents(messageText: string): AgentEvent[] {
 }
 
 export function startAcpDelegationRun(input: AcpDelegationRunInput): AcpDelegationRunHandle {
-	// Validated settings always populate these values. Keep the public runtime
-	// boundary safe for direct callers too: omission must not turn a silent ACP
-	// peer into an unbounded request.
+	// Connection faults stay bounded. Elapsed turn time is not a progress signal;
+	// only an explicit positive timeout stops a healthy turn. Dispatch owns its
+	// event-inactivity watchdog and cancellation/process cleanup.
 	const connectTimeoutMs = input.agent.connectTimeoutMs ?? DEFAULT_DELEGATION_CONNECT_TIMEOUT_MS;
 	const turnTimeoutMs = input.agent.turnTimeoutMs ?? DEFAULT_DELEGATION_TURN_TIMEOUT_MS;
 	const now = input.now ?? Date.now;
@@ -304,7 +354,7 @@ export function startAcpDelegationRun(input: AcpDelegationRunInput): AcpDelegati
 					sessionId,
 					prompt: [{ type: "text", text: flattenPrompt(input) }],
 				},
-				turnTimeoutMs,
+				turnTimeoutMs === 0 ? undefined : turnTimeoutMs,
 			);
 			// ACP v1 has no usage field on PromptResponse. Clio servers report it in
 			// _meta; other agents (Copilot/Codex/OpenCode) report nothing here, so usage

package/src/engine/acp/server.ts

@@ -60,7 +60,7 @@ export interface AcpServerChat {
 	onEvent(handler: (event: AcpServerEvent) => void): () => void;
 	isStreaming(): boolean;
 	getSessionId(): string | null;
-	/** Replace provider context and the next persisted parent after session/load. */
+	/** Replace provider context and the next persisted parent for a new or loaded session. */
 	resetForSession?(leafTurnId: string | null, replayMessages?: ReadonlyArray<AgentMessage>): void;
 	dispose?(): void;
 }
@@ -268,6 +268,7 @@ const ACP_ADMISSION_REASONS = new Set([
 	"model-not-configured",
 	"chat-unsupported",
 	"streaming-unsupported",
+	"context-window-exceeded",
 	"admission-failed",
 ]);
 
@@ -1406,6 +1407,7 @@ function installPermissionBridge(input: {
 	toolCallSnapshot: (wireId: string) => AcpToolCallSnapshot | null;
 	permissionTimeoutMs: number;
 	expireActivePrompt: () => void;
+	cancelActivePrompt: (reason: string) => void;
 }): AcpPermissionBridge {
 	if (!input.toolRegistry) return { unregister: () => {}, cancelPending: () => {} };
 	let pendingCancel: ((reason: string) => void) | null = null;
@@ -1573,6 +1575,17 @@ function installPermissionBridge(input: {
 					// client mint `allow-always` and get a grant this server never
 					// offered as an option.
 					const answer = outcome.response.outcome;
+					if (answer.outcome === "cancelled") {
+						const reason = "ACP client cancelled permission";
+						// Abort before releasing the parked tools so their results cannot
+						// start another model request while session/cancel is in flight.
+						input.cancelActivePrompt(reason);
+						emitResolution({ status: "denied", decidedBy: "cancelled", reason });
+						queuedRequestIds.clear();
+						queuedRequestDetails.clear();
+						input.toolRegistry?.cancelParkedCalls(reason);
+						return;
+					}
 					if (answer.outcome === "selected" && answer.optionId === "allow-once") {
 						emitResolution({ status: "granted", decidedBy: "acp-client" });
 						await input.toolRegistry?.resumeParkedCalls({
@@ -1695,6 +1708,10 @@ export async function serveClioAcpAgent(options: ClioAcpServerOptions): Promise<
 			activePromptState.permissionExpired = true;
 			options.chat.cancel();
 		},
+		cancelActivePrompt: (reason) => {
+			const session = activeSessionId === null ? undefined : sessions.get(activeSessionId);
+			if (session) cancelSession(session, reason);
+		},
 	});
 	/**
 	 * Sends one frame of the opt-in stream. Every forwarded channel goes through
@@ -2128,9 +2145,8 @@ export async function serveClioAcpAgent(options: ClioAcpServerOptions): Promise<
 
 	options.transport.onRequest("session/new", (params) => {
 		requireInitialized();
-		// One chat instance, one provider context, one ledger ancestry. A second
-		// session id over the same process would share all three with the first,
-		// so the honest answer is to refuse and let the client start a process.
+		// The chat instance can bind only one session at a time. Closing that
+		// session releases the slot; the next creation resets its conversation.
 		if (sessionCreated) {
 			throw new AcpRequestError(-32000, "this server hosts one session per process", { code: "session_limit" });
 		}
@@ -2144,6 +2160,7 @@ export async function serveClioAcpAgent(options: ClioAcpServerOptions): Promise<
 		if (safeStoredIdentifier(id, ACP_MAX_SESSION_ID_BYTES) === null) {
 			throw new AcpRequestError(-32000, "session creation failed", { code: "internal_error" });
 		}
+		options.chat.resetForSession?.(null);
 		const autonomy = options.autonomy?.() ?? DEFAULT_AUTONOMY_LEVEL;
 		const boundTarget = safeConfiguredIdentifier(meta?.target ?? route.target, ACP_MAX_TARGET_ID_BYTES);
 		const boundModel = safeConfiguredIdentifier(meta?.model ?? route.model, ACP_MAX_MODEL_ID_BYTES);
@@ -2529,6 +2546,7 @@ export async function serveClioAcpAgent(options: ClioAcpServerOptions): Promise<
 		if (options.session?.current()?.id === session.id) await options.session.close();
 		sessions.delete(session.id);
 		if (boundSessionId === session.id) boundSessionId = null;
+		sessionCreated = false;
 		closedSessionIds.add(session.id);
 		return {};
 	});

package/src/engine/acp/transport.ts

@@ -6,6 +6,7 @@ import {
 	reportCommitAttributionDiagnostic,
 	withManagedGitCommitAttributionEnvironment,
 } from "../../core/git-commit-attribution.js";
+import { buildSafeToolEnv } from "../../core/safe-exec.js";
 import { MAX_TIMER_DELAY_MS } from "../../core/timers.js";
 import {
 	ACP_INTERNAL_ERROR_MESSAGE,
@@ -207,7 +208,7 @@ class StdioJsonRpcTransport implements AcpJsonRpcTransport {
 		this.childClosePromise = new Promise((resolve) => {
 			this.resolveChildClose = resolve;
 		});
-		const childEnvironment = options.env ? { ...process.env, ...options.env } : process.env;
+		const childEnvironment = buildSafeToolEnv(options.env);
 		// A delegated external harness authors its own commits. Clio only
 		// assisted by delegating, so no Co-authored-by is claimed for it.
 		const attribution = withManagedGitCommitAttributionEnvironment(childEnvironment, {
@@ -534,6 +535,10 @@ export function createStdioTransport(
 }
 
 class StreamJsonRpcPeerTransport implements AcpJsonRpcPeerTransport {
+	private outputPaused = false;
+	private queuedOutputBytes = 0;
+	private sinkOutputBytes = 0;
+	private readonly outputQueue: string[] = [];
 	private nextId = 1;
 	private buffer = "";
 	/** True while the bytes of an oversized line are being dropped up to its terminating newline. */
@@ -626,18 +631,56 @@ class StreamJsonRpcPeerTransport implements AcpJsonRpcPeerTransport {
 	}
 
 	private write(message: AcpJsonRpcMessage): void {
+		if (this.closed) return;
 		const line = `${JSON.stringify(message)}\n`;
-		if (this.writeOverride) {
-			this.writeOverride(line);
-			return;
+		if (this.outputPaused) {
+			const bytes = Buffer.byteLength(line, "utf8");
+			// Include bytes already held by the sink in the existing frame budget.
+			if (this.queuedOutputBytes + this.sinkOutputBytes + bytes > ACP_MAX_INPUT_LINE_BYTES) {
+				this.markClosed(new AcpProcessError("ACP output buffer exceeded byte limit"));
+				return;
+			}
 		}
-		// A `false` return means the stream buffered rather than flushed. Honoring
-		// it means pausing frame production, which changes turn timing, so the
-		// decision to keep writing is deferred rather than forgotten (CONTRACT
-		// C001 §6 leaves stdout backpressure out of this profile).
-		this.output.write(line);
+		this.outputQueue.push(line);
+		this.queuedOutputBytes += Buffer.byteLength(line, "utf8");
+		if (!this.outputPaused) this.flushOutput();
 	}
 
+	private readonly flushOutput = (): void => {
+		this.outputPaused = false;
+		while (!this.closed && !this.outputPaused && this.outputQueue.length > 0) {
+			const line = this.outputQueue.shift();
+			if (line === undefined) break;
+			this.queuedOutputBytes -= Buffer.byteLength(line, "utf8");
+			try {
+				// Stdout can count buffered strings in UTF-16 units rather than bytes.
+				// Retain their byte count until drain, bounding earlier writes by at
+				// most three UTF-8 bytes per unit still held by the sink.
+				this.sinkOutputBytes = Math.min(this.sinkOutputBytes, this.output.writableLength * 3);
+				let ready: boolean;
+				if (this.writeOverride) {
+					this.writeOverride(line);
+					// The stdout guard writes to this sink but does not return write's boolean.
+					ready = !this.output.writableNeedDrain;
+				} else {
+					ready = this.output.write(line);
+				}
+				this.sinkOutputBytes =
+					this.output.writableLength === 0 ? 0 : this.sinkOutputBytes + Buffer.byteLength(line, "utf8");
+				if (!ready && !this.closed) {
+					if (this.queuedOutputBytes + this.sinkOutputBytes > ACP_MAX_INPUT_LINE_BYTES) {
+						this.markClosed(new AcpProcessError("ACP output buffer exceeded byte limit"));
+						return;
+					}
+					this.outputPaused = true;
+					this.output.once("drain", this.flushOutput);
+				}
+			} catch (err) {
+				this.markClosed(new AcpProcessError(`ACP output write failed: ${errorMessage(err)}`));
+			}
+		}
+	};
+
 	private consume(chunk: string): void {
 		this.buffer += chunk;
 		for (;;) {
@@ -757,6 +800,9 @@ class StreamJsonRpcPeerTransport implements AcpJsonRpcPeerTransport {
 	private markClosed(reason: unknown): void {
 		if (this.isClosed) return;
 		this.isClosed = true;
+		this.output.removeListener("drain", this.flushOutput);
+		this.outputQueue.length = 0;
+		this.queuedOutputBytes = 0;
 		this.failAll(reason);
 		for (const handler of this.closeHandlers) handler();
 	}

package/src/engine/acp/types.ts

@@ -1,3 +1,4 @@
+import type { CostProvenance } from "../../domains/providers/types/cost-provenance.js";
 import type { AgentMessage } from "../types.js";
 
 /**
@@ -189,11 +190,19 @@ export interface AcpPromptResponse {
 }
 
 export interface AcpDelegationUsage {
+	/** A valid peer token field was present, including an explicit zero. */
+	tokensReported: boolean;
 	inputTokens: number;
 	outputTokens: number;
 	cacheReadTokens: number;
 	cacheWriteTokens: number;
 	reasoningTokens: number;
+	/** Peer-reported total when present, otherwise input+output+cacheRead+cacheWrite, matching the ACP server side. */
+	totalTokens: number;
+	/** Sum of peer cost.total (legacy) or costUsd (Clio metadata); never re-priced. */
+	costUsd: number;
+	/** Absent until usage is reported; missing or unsupported pricing provenance stays unknown. */
+	costProvenance?: CostProvenance;
 }
 
 export interface AcpDelegationResult {