@iowarp/clio-coder 0.4.4 → 0.4.5

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

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import type { AskUserToolPolicy } from "../../tools/registry.js";
 import type { AutonomyExposure } from "../safety/autonomy.js";
-import { type DecisionLedgerEntry, type DecisionRecord, decisionRef } from "./entries.js";
+import { type DecisionLedgerEntry, type DecisionRecord, type DecisionSource, decisionRef } from "./entries.js";
 
 export interface DecisionLedgerEntryFields {
 	kind: "decisionLedger";
@@ -187,6 +187,46 @@ export function createDecisionBoardStore(deps: DecisionBoardStoreDeps = {}): Dec
 		dirty = true;
 	};
 
+	const revise = (
+		interviewId: string,
+		key: string,
+		revisionSource: DecisionSource,
+		correction?: string,
+	): DecisionLedgerEntryFields => {
+		syncToSession();
+		const interview = interviews.find((candidate) => candidate.interviewId === interviewId);
+		if (!interview) throw new Error(`decision board: interview ${interviewId} was not found on the active branch`);
+		const selected = interview.decisions.find((decision) => decision.key === key);
+		if (!selected) throw new Error(`decision board: decision ${key} was not found in interview ${interviewId}`);
+		const revisedAt = (deps.now?.() ?? new Date()).toISOString();
+		const normalizedCorrection = correction?.trim();
+		const entries = deps.readEntries?.() ?? [];
+		const parentTurnId = deps.getActiveLeafTurnId?.() ?? activeLeafFromEntries(entries);
+		if (!parentTurnId) throw new Error("decision board: no active branch leaf is available for the revision");
+		const revision: DecisionLedgerEntryFields = {
+			kind: "decisionLedger",
+			parentTurnId,
+			...(interview.origin !== undefined ? { origin: interview.origin } : {}),
+			interviewId: interview.interviewId,
+			interviewStatus: interview.interviewStatus,
+			startedAt: interview.startedAt,
+			endedAt: interview.endedAt,
+			roundCount: interview.roundCount,
+			...(interview.summary ? { summary: interview.summary } : {}),
+			...(interview.transcriptPath ? { transcriptPath: interview.transcriptPath } : {}),
+			...(interview.exposure ? { exposure: interview.exposure } : {}),
+			decisions: interview.decisions.map((decision) => {
+				if (decision.key !== selected.key) return { ...decision };
+				const next: DecisionRecord = { ...decision, status: "superseded", revisedAt, revisionSource };
+				if (normalizedCorrection) next.correction = normalizedCorrection;
+				else delete next.correction;
+				return next;
+			}),
+		};
+		append(revision);
+		return revision;
+	};
+
 	const store: DecisionBoardStore = {
 		snapshot(): ReadonlyArray<DecisionLedgerEntry> {
 			syncToSession();
@@ -212,7 +252,7 @@ export function createDecisionBoardStore(deps: DecisionBoardStoreDeps = {}): Dec
 				superseded = { interviewId: interview.interviewId, key: prior.key };
 				break;
 			}
-			if (superseded !== null) store.supersede(superseded.interviewId, superseded.key, input.rationale);
+			if (superseded !== null) revise(superseded.interviewId, superseded.key, "agent", input.rationale);
 			const now = (deps.now?.() ?? new Date()).toISOString();
 			const entries = deps.readEntries?.() ?? [];
 			const parentTurnId = deps.getActiveLeafTurnId?.() ?? activeLeafFromEntries(entries);
@@ -244,37 +284,7 @@ export function createDecisionBoardStore(deps: DecisionBoardStoreDeps = {}): Dec
 			return { entry, superseded };
 		},
 		supersede(interviewId: string, key: string, correction?: string): DecisionLedgerEntryFields {
-			syncToSession();
-			const interview = interviews.find((candidate) => candidate.interviewId === interviewId);
-			if (!interview) throw new Error(`decision board: interview ${interviewId} was not found on the active branch`);
-			const selected = interview.decisions.find((decision) => decision.key === key);
-			if (!selected) throw new Error(`decision board: decision ${key} was not found in interview ${interviewId}`);
-			const revisedAt = (deps.now?.() ?? new Date()).toISOString();
-			const normalizedCorrection = correction?.trim();
-			const entries = deps.readEntries?.() ?? [];
-			const parentTurnId = deps.getActiveLeafTurnId?.() ?? activeLeafFromEntries(entries);
-			if (!parentTurnId) throw new Error("decision board: no active branch leaf is available for the revision");
-			const revision: DecisionLedgerEntryFields = {
-				kind: "decisionLedger",
-				parentTurnId,
-				interviewId: interview.interviewId,
-				interviewStatus: interview.interviewStatus,
-				startedAt: interview.startedAt,
-				endedAt: interview.endedAt,
-				roundCount: interview.roundCount,
-				...(interview.summary ? { summary: interview.summary } : {}),
-				...(interview.transcriptPath ? { transcriptPath: interview.transcriptPath } : {}),
-				...(interview.exposure ? { exposure: interview.exposure } : {}),
-				decisions: interview.decisions.map((decision) => {
-					if (decision.key !== selected.key) return { ...decision };
-					const next: DecisionRecord = { ...decision, status: "superseded", revisedAt };
-					if (normalizedCorrection) next.correction = normalizedCorrection;
-					else delete next.correction;
-					return next;
-				}),
-			};
-			append(revision);
-			return revision;
+			return revise(interviewId, key, "operator", correction);
 		},
 		invalidate(): void {
 			dirty = true;

package/src/domains/session/entries.ts

@@ -14,7 +14,9 @@
  *     evidence builders but has no in-tree producer.
  */
 
-import { isSkillActivation, type SkillActivation } from "../../core/skill-activation.js";
+import { createHash } from "node:crypto";
+
+import { isSkillActivation, type PendingSkillToolPolicy, type SkillActivation } from "../../core/skill-activation.js";
 import type { ClioTurnRecord } from "../../engine/session.js";
 import { AUTONOMY_EXPOSURES, type AutonomyExposure } from "../safety/autonomy.js";
 
@@ -119,8 +121,159 @@ export interface CompactionUsage {
 	apiCalls: number;
 }
 
+/** Exact historical skill context, independent of generated checkpoint prose. */
+export interface PreservedSkillContext {
+	activationRef: string;
+	requestRef: string;
+	callRef: string;
+	resultRef: string;
+	activation: SkillActivation;
+	requestText: string;
+	content: Array<{ type: "text"; text: string }>;
+	/** Hash of the captured rendered text blocks, not the raw SKILL.md hash. */
+	contentHash: string;
+}
+
+export interface SkillContextCheckpoint {
+	version: 1;
+	skills: PreservedSkillContext[];
+}
+
+export const SKILL_CONTEXT_STATE = "skillContextState";
+export interface SkillContextState {
+	version: 1;
+	/** Empty is an explicit off/replacement; absence is unknown legacy state. */
+	activationRefs: string[];
+	unknown?: true;
+}
+
+export function skillContextContentHash(content: PreservedSkillContext["content"]): string {
+	return createHash("sha256").update(JSON.stringify(content)).digest("hex");
+}
+
+function isSkillContextState(value: unknown): value is SkillContextState {
+	return (
+		isRecord(value) &&
+		value.version === 1 &&
+		(value.unknown === undefined || value.unknown === true) &&
+		Array.isArray(value.activationRefs) &&
+		value.activationRefs.every((ref) => typeof ref === "string")
+	);
+}
+
+/** Ledger validation is structural; bad evidence must not make the session unreadable. */
+function isSkillContextCheckpoint(value: unknown): value is SkillContextCheckpoint {
+	return (
+		isRecord(value) &&
+		value.version === 1 &&
+		Array.isArray(value.skills) &&
+		value.skills.every(
+			(skill: unknown) =>
+				isRecord(skill) &&
+				[skill.activationRef, skill.requestRef, skill.callRef, skill.resultRef, skill.requestText, skill.contentHash].every(
+					isString,
+				) &&
+				isSkillActivation(skill.activation) &&
+				Array.isArray(skill.content) &&
+				skill.content.every((block: unknown) => isRecord(block) && block.type === "text" && typeof block.text === "string"),
+		)
+	);
+}
+
+export function verifiedSkillContextCheckpoint(value: unknown): value is SkillContextCheckpoint {
+	if (!isSkillContextCheckpoint(value)) return false;
+	const refs = new Set<string>();
+	const names = new Set<string>();
+	return value.skills.every((skill) => {
+		const activation = skill.activation;
+		if (
+			![skill.activationRef, skill.requestRef, skill.callRef, skill.resultRef].every((ref) => ref.length > 0) ||
+			activation.runId !== undefined ||
+			activation.triggeredBy !== "tool" ||
+			activation.turnId !== skill.requestRef ||
+			!activation.name ||
+			!activation.filePath ||
+			!activation.source ||
+			!activation.sourceOrigin ||
+			!/^[a-f0-9]{64}$/.test(activation.hash) ||
+			(activation.drift !== undefined && activation.drift !== "match") ||
+			skill.content.length === 0 ||
+			skill.content.every((block) => block.text.length === 0) ||
+			skill.contentHash !== skillContextContentHash(skill.content) ||
+			refs.has(skill.activationRef) ||
+			names.has(activation.name)
+		)
+			return false;
+		refs.add(skill.activationRef);
+		names.add(activation.name);
+		return true;
+	});
+}
+
+export interface PreservedUserContext {
+	turnId: string;
+	text: string;
+}
+function isPreservedUserContext(value: unknown): value is PreservedUserContext {
+	return isRecord(value) && isString(value.turnId) && isString(value.text);
+}
+
+/** Undefined means no live policy; null explicitly forbids reuse during an uncertain replacement. */
+export function mainSkillContextState(
+	entries: ReadonlyArray<SessionEntry>,
+	policy: PendingSkillToolPolicy | undefined,
+): SkillContextState | null | undefined {
+	if (!policy) return latestSkillContextState(entries);
+	// A cold turn may grant optional model activation without selecting or
+	// replacing any skill. Keep the recorded selection, including explicit off.
+	// This preserves historical content; it does not reconstruct tool authority.
+	if (
+		policy.modelActivation === true &&
+		policy.carriedSurface !== true &&
+		policy.requests.length === 0 &&
+		policy.loadedSkillNames.size === 0 &&
+		policy.loadedSkillPolicies.size === 0
+	)
+		return latestSkillContextState(entries);
+	if (policy.requests.some((request) => !policy.loadedSkillNames.has(request.name))) return null;
+	const names = [...policy.loadedSkillNames];
+	if (names.length === 0) return null;
+	const activationRefs: string[] = [];
+	for (const name of names) {
+		const entry = [...entries]
+			.reverse()
+			.find(
+				(candidate) =>
+					candidate.kind === "skillActivation" &&
+					candidate.activation.runId === undefined &&
+					candidate.activation.name === name,
+			);
+		if (!entry) return null;
+		activationRefs.push(entry.turnId);
+	}
+	return { version: 1, activationRefs };
+}
+
+/** Caller supplies an already selected branch. Never infer active skills from audit metadata. */
+export function latestSkillContextState(entries: ReadonlyArray<SessionEntry>): SkillContextState | undefined {
+	for (let index = entries.length - 1; index >= 0; index--) {
+		const entry = entries[index];
+		if (entry?.kind === "custom" && entry.customType === SKILL_CONTEXT_STATE) {
+			return isSkillContextState(entry.data) ? entry.data : undefined;
+		}
+		if (entry?.kind === "compactionSummary" && entry.skillContext !== undefined) {
+			return verifiedSkillContextCheckpoint(entry.skillContext)
+				? { version: 1, activationRefs: entry.skillContext.skills.map((skill) => skill.activationRef) }
+				: undefined;
+		}
+	}
+	return undefined;
+}
+
 export interface CompactionSummaryEntry extends BaseSessionEntry {
 	kind: "compactionSummary";
+	skillContext?: SkillContextCheckpoint;
+	userContext?: PreservedUserContext;
 	summary: string;
 	tokensBefore: number;
 	firstKeptTurnId: string;
@@ -232,6 +385,8 @@ export interface DecisionRecord {
 	status: DecisionStatus;
 	decidedAt: string;
 	revisedAt?: string;
+	/** Who made this revision, independently of the original decision source. Absent on legacy revisions. */
+	revisionSource?: DecisionSource;
 	correction?: string;
 	source?: DecisionSource;
 	/** Options considered and not taken. Only agent decisions carry these. */
@@ -350,6 +505,8 @@ export interface WorkingSetRef {
 }
 
 export interface EvictedItem {
+	/** Stable session-local recall alias; absent on legacy ledger records. */
+	alias?: string;
 	ref: WorkingSetRef;
 	reason: EvictionReason;
 	/** Estimated tokens the projection removes for this item (marker cost already subtracted). */
@@ -542,12 +699,13 @@ export function isDecisionRecord(value: unknown): value is DecisionRecord {
 	if (!isString(value.value) || !isOneOf(value.status, DECISION_STATUSES) || !isString(value.decidedAt)) return false;
 	if (!isOptionalString(value.label) || !isOptionalString(value.source_question)) return false;
 	if (value.source !== undefined && !isOneOf(value.source, ["operator", "agent"])) return false;
+	if (value.revisionSource !== undefined && !isOneOf(value.revisionSource, ["operator", "agent"])) return false;
 	if (value.alternatives !== undefined && !isStringArray(value.alternatives)) return false;
 	if (!isOptionalString(value.rationale)) return false;
 	if (!isOptionalString(value.revisedAt) || !isOptionalString(value.correction)) return false;
 	return value.status === "superseded"
 		? isString(value.revisedAt)
-		: value.revisedAt === undefined && value.correction === undefined;
+		: value.revisedAt === undefined && value.revisionSource === undefined && value.correction === undefined;
 }
 
 function isOptionalCompactionUsage(value: unknown): boolean {
@@ -605,6 +763,7 @@ function isEvictedItem(value: unknown): value is EvictedItem {
 		isOneOf(value.reason, EVICTION_REASONS) &&
 		isNumber(value.tokensFreed) &&
 		isString(value.marker) &&
+		(value.alias === undefined || (typeof value.alias === "string" && /^r[1-9]\d*$/.test(value.alias))) &&
 		isOptionalString(value.by)
 	);
 }
@@ -628,7 +787,11 @@ export function isSessionEntry(value: unknown): value is SessionEntry {
 				isOptionalBoolean(v.excludeFromContext)
 			);
 		case "custom":
-			return isString(v.customType) && isOptionalBoolean(v.display);
+			return (
+				isString(v.customType) &&
+				isOptionalBoolean(v.display) &&
+				(v.customType !== SKILL_CONTEXT_STATE || isSkillContextState(v.data))
+			);
 		case "modelChange":
 			return isString(v.provider) && isString(v.modelId) && isOptionalString(v.target);
 		case "thinkingLevelChange":
@@ -648,7 +811,9 @@ export function isSessionEntry(value: unknown): value is SessionEntry {
 				(v.trigger === undefined || isOneOf(v.trigger, COMPACTION_TRIGGERS)) &&
 				isOptionalNumber(v.tokensAfter) &&
 				isOptionalNumber(v.messagesSummarized) &&
-				isOptionalBoolean(v.isSplitTurn)
+				isOptionalBoolean(v.isSplitTurn) &&
+				(v.skillContext === undefined || isSkillContextCheckpoint(v.skillContext)) &&
+				(v.userContext === undefined || isPreservedUserContext(v.userContext))
 			);
 		case "sessionInfo":
 			return isOptionalString(v.name) && isOptionalString(v.targetTurnId) && isOptionalString(v.label);

package/src/domains/session/prompt-manifest.ts

@@ -115,15 +115,54 @@ function isPromptManifestFragment(value: unknown): value is PromptManifestFragme
 	);
 }
 
-function isProjectPreloadClass(value: unknown): value is ProjectPreloadClass {
-	if (!isRecord(value)) return false;
+/** Validate additive accounting when present, while accepting historical manifests. */
+export function isProjectPreloadClass(value: unknown): value is ProjectPreloadClass {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+	const row = value as Record<string, unknown>;
+	const integer = (item: unknown): item is number => typeof item === "number" && Number.isInteger(item) && item >= 0;
+	const optionalInteger = (item: unknown): boolean => item === undefined || integer(item);
+	const range = (item: unknown): boolean =>
+		item === null ||
+		(Array.isArray(item) &&
+			item.length === 2 &&
+			integer(item[0]) &&
+			item[0] >= 1 &&
+			integer(item[1]) &&
+			item[1] >= item[0]);
 	return (
-		(value.mode === "full" || value.mode === "synopsis" || value.mode === "none") &&
-		isNonNegativeInteger(value.chars) &&
-		isNonNegativeInteger(value.lines) &&
-		(value.reason === null || value.reason === "size" || value.reason === "lines" || value.reason === "no-clio-md") &&
-		typeof value.nearLimit === "boolean" &&
-		typeof value.label === "string"
+		typeof row.mode === "string" &&
+		["full", "partial", "synopsis", "none"].includes(row.mode) &&
+		integer(row.chars) &&
+		integer(row.lines) &&
+		(row.reason === null || (typeof row.reason === "string" && ["size", "lines", "no-clio-md"].includes(row.reason))) &&
+		typeof row.nearLimit === "boolean" &&
+		typeof row.label === "string" &&
+		optionalInteger(row.includedChars) &&
+		optionalInteger(row.includedLines) &&
+		optionalInteger(row.omittedSupportFragments) &&
+		(row.providerSupportsTools === undefined ||
+			row.providerSupportsTools === null ||
+			typeof row.providerSupportsTools === "boolean") &&
+		(row.sources === undefined ||
+			(Array.isArray(row.sources) &&
+				row.sources.every((source: unknown) => {
+					if (source === null || typeof source !== "object" || Array.isArray(source)) return false;
+					const s = source as Record<string, unknown>;
+					return (
+						typeof s.path === "string" &&
+						typeof s.contentHash === "string" &&
+						/^[a-f0-9]{64}$/.test(s.contentHash) &&
+						integer(s.availableChars) &&
+						integer(s.availableLines) &&
+						integer(s.includedChars) &&
+						integer(s.includedLines) &&
+						s.includedChars <= s.availableChars &&
+						s.includedLines <= s.availableLines &&
+						range(s.includedRange) &&
+						range(s.omittedRange) &&
+						(s.omissionReason === null || s.omissionReason === "budget")
+					);
+				})))
 	);
 }
 

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

@@ -29,6 +29,7 @@ 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;
@@ -286,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[];
@@ -311,7 +329,7 @@ function toEntryView(entry: {
 			};
 			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((item) => ({ ...item }));
+			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;
@@ -397,9 +415,9 @@ function applyMutation(
 		if (mutation.verification && mutation.verification.length > 0) {
 			picked.requiredValidationEvidence = mutation.verification.map((item, index) => ({
 				id: `${picked.id}.acceptance.${index}`,
-				description: `Operator acceptance: ${item.check}`,
+				description: acceptanceRequirementDescription(item.check),
 				command: item.check,
-				status: "pending",
+				status: "required",
 				notes: `timeoutMs=${item.timeoutMs}`,
 			}));
 		}

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/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";
@@ -136,6 +137,7 @@ function flattenPrompt(input: AcpDelegationRunInput): string {
 
 export function emptyUsage(): AcpDelegationUsage {
 	return {
+		tokensReported: false,
 		inputTokens: 0,
 		outputTokens: 0,
 		cacheReadTokens: 0,
@@ -150,14 +152,33 @@ function finite(value: unknown): number {
 	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
 }
 
-/** Same field the ACP server side and `sumRunUsage` read for a dollar figure; cost is never re-derived here. */
-function costTotal(raw: Record<string, unknown>): number {
-	const cost = raw.cost;
-	return isRecord(cost) ? finite(cost.total) : 0;
+/** 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;
+	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);
@@ -167,12 +188,23 @@ export function mergeUsage(into: AcpDelegationUsage, raw: unknown): void {
 	into.cacheReadTokens += cacheRead;
 	into.cacheWriteTokens += cacheWrite;
 	into.reasoningTokens += finite(raw.reasoning) + finite(raw.reasoningTokens) + finite(raw.reasoning_tokens);
-	// Same rule as the ACP server accumulator: prefer the peer's explicit total,
+	// 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 = finite(raw.totalTokens) + finite(raw.total_tokens);
-	into.totalTokens += explicitTotal > 0 ? explicitTotal : input + output + cacheRead + cacheWrite;
-	into.costUsd += costTotal(raw);
+	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 {
@@ -195,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;
@@ -322,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

@@ -268,6 +268,7 @@ const ACP_ADMISSION_REASONS = new Set([
 	"model-not-configured",
 	"chat-unsupported",
 	"streaming-unsupported",
+	"context-window-exceeded",
 	"admission-failed",
 ]);
 

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, {

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,6 +190,8 @@ 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;
@@ -196,8 +199,10 @@ export interface AcpDelegationUsage {
 	reasoningTokens: number;
 	/** Peer-reported total when present, otherwise input+output+cacheRead+cacheWrite, matching the ACP server side. */
 	totalTokens: number;
-	/** Sum of the peer's `usage.cost.total`; stays 0 when the peer reports no cost. */
+	/** 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 {