@iowarp/clio-coder 0.4.7 → 0.4.9

package/src/domains/providers/runtimes/local-native/llamacpp-embed.ts

@@ -54,27 +54,6 @@ function flattenNativeEmbedding(entry: NativeEmbeddingItem): number[] {
 	return value as number[];
 }
 
-async function postJson<T>(
-	url: string,
-	body: unknown,
-	signal: AbortSignal | undefined,
-): Promise<{ status: number; data: T | null }> {
-	const init: RequestInit = {
-		method: "POST",
-		headers: { "content-type": "application/json" },
-		body: JSON.stringify(body),
-	};
-	if (signal) init.signal = signal;
-	const response = await fetch(url, init);
-	if (!response.ok) return { status: response.status, data: null };
-	try {
-		const data = (await response.json()) as T;
-		return { status: response.status, data };
-	} catch {
-		return { status: response.status, data: null };
-	}
-}
-
 const llamacppEmbedRuntime: RuntimeDescriptor = {
 	id: "llamacpp-embed",
 	displayName: "llama.cpp (embeddings)",
@@ -90,16 +69,16 @@ const llamacppEmbedRuntime: RuntimeDescriptor = {
 		const healthOpts = { url: `${base}/health`, timeoutMs: ctx.httpTimeoutMs } as const;
 		const health = await (ctx.signal ? probeHttp({ ...healthOpts, signal: ctx.signal }) : probeHttp(healthOpts));
 		if (!health.ok) return health;
-		const probeResponse = await fetch(`${base}/embedding`, {
+		const probeResponse = await probeHttp({
+			url: `${base}/embedding`,
 			method: "POST",
+			timeoutMs: ctx.httpTimeoutMs,
 			headers: { "content-type": "application/json" },
 			body: JSON.stringify({ content: "probe" }),
 			...(ctx.signal ? { signal: ctx.signal } : {}),
-		}).catch((err) => {
-			return new Response(null, { status: 599, statusText: String(err) });
 		});
 		if (!probeResponse.ok) {
-			return { ok: false, error: `/embedding not available: HTTP ${probeResponse.status}` };
+			return { ok: false, error: `/embedding not available: ${probeResponse.error}` };
 		}
 		const props = await probeLlamaCppProps(base, ctx, target.defaultModel);
 		const result: ProbeResult = { ok: true };
@@ -129,12 +108,15 @@ const llamacppEmbedRuntime: RuntimeDescriptor = {
 		if (!base) throw new Error("target has no url");
 		const modelId = target.defaultModel ?? "default";
 		const inputs = Array.isArray(input) ? input : [input];
-		const oai = await postJson<OaiEmbeddingResponse>(
-			`${base}/v1/embeddings`,
-			{ input: inputs, model: modelId, encoding_format: "float" },
-			ctx.signal,
-		);
-		if (oai.data && Array.isArray(oai.data.data)) {
+		const oai = await probeJson<OaiEmbeddingResponse>({
+			url: `${base}/v1/embeddings`,
+			method: "POST",
+			timeoutMs: ctx.httpTimeoutMs,
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify({ input: inputs, model: modelId, encoding_format: "float" }),
+			...(ctx.signal ? { signal: ctx.signal } : {}),
+		});
+		if (oai.ok && oai.data && Array.isArray(oai.data.data)) {
 			const rows = oai.data.data;
 			const sorted = [...rows].sort((a, b) => (a.index ?? 0) - (b.index ?? 0));
 			const vectors = sorted.map((row) => row.embedding ?? []);
@@ -148,6 +130,13 @@ const llamacppEmbedRuntime: RuntimeDescriptor = {
 			if (tokens !== undefined) result.tokensUsed = tokens;
 			return result;
 		}
+		// Only endpoint-unavailable responses permit trying the native route.
+		// Cancellation, transport failures and malformed successes must not
+		// submit a second inference request.
+		if (oai.status === undefined || ![404, 405, 501].includes(oai.status)) {
+			throw new Error(`llama.cpp embedding failed: ${oai.error ?? "invalid OAI embedding response"}`);
+		}
+		if (ctx.signal?.aborted) throw new Error("llama.cpp embedding failed: aborted by caller");
 		const probeOpts = { url: `${base}/embedding`, timeoutMs: ctx.httpTimeoutMs } as const;
 		const native = await (ctx.signal
 			? probeJson<NativeEmbeddingItem[]>({

package/src/domains/providers/runtimes/local-native/llamacpp-rerank.ts

@@ -51,14 +51,19 @@ const llamacppRerankRuntime: RuntimeDescriptor = {
 		const health = await (ctx.signal ? probeHttp({ ...healthOpts, signal: ctx.signal }) : probeHttp(healthOpts));
 		if (!health.ok) return health;
 		const modelId = target.defaultModel ?? "default";
-		const probeResponse = await fetch(`${base}/reranking`, {
+		const probeResponse = await probeHttp({
+			url: `${base}/reranking`,
 			method: "POST",
+			timeoutMs: ctx.httpTimeoutMs,
 			headers: { "content-type": "application/json" },
 			body: JSON.stringify({ query: "probe", documents: ["a"], model: modelId }),
 			...(ctx.signal ? { signal: ctx.signal } : {}),
-		}).catch((err) => new Response(null, { status: 599, statusText: String(err) }));
-		if (!(probeResponse.status === 200 || probeResponse.status === 202)) {
-			return { ok: false, error: `/reranking not available: HTTP ${probeResponse.status}` };
+		});
+		if (!probeResponse.ok || !(probeResponse.status === 200 || probeResponse.status === 202)) {
+			return {
+				ok: false,
+				error: `/reranking not available: ${probeResponse.error ?? `HTTP ${probeResponse.status}`}`,
+			};
 		}
 		const props = await probeLlamaCppProps(base, ctx, target.defaultModel);
 		const result: ProbeResult = { ok: true };

package/src/domains/providers/types/target-descriptor.ts

@@ -14,6 +14,22 @@ export interface TargetPricing {
 	cacheWrite?: number;
 }
 
+/** Request policy interpreted by the selected Pi API; it does not authorize cache administration or paid warming. */
+export interface TargetCacheSettings {
+	retention?: "none" | "short" | "long";
+	/** Explicit read-only deployment binding; never grants administrative authority. */
+	deployment?: {
+		backend: "llamacpp" | "vllm";
+		controlUrl: string;
+		model: string;
+		build: string;
+		/** Required for a gateway binding; compared with its current route inventory. */
+		gatewayDeploymentId?: string;
+	};
+	/** Local warm bounds. Paid routes remain ineligible. */
+	warm?: { maxInputTokens?: number; maxDurationMs?: number; cooldownMs?: number };
+}
+
 // Canonical persisted lifecycle name. Readers temporarily normalize the
 // released `clio-managed` spelling at the settings boundary.
 export type TargetLifecycle = "user-managed" | "clio-coder-managed";
@@ -74,6 +90,7 @@ export interface TargetDescriptor {
 	lifecycle?: TargetLifecycle;
 	gateway?: boolean;
 	pricing?: TargetPricing;
+	cache?: TargetCacheSettings;
 	lmstudio?: LmStudioTargetSettings;
 	litellm?: LiteLLMTargetSettings;
 	/** Explicit request-slot limit for this inference endpoint. It overrides live discovery. */

package/src/domains/safety/action-classifier.ts

@@ -6,7 +6,7 @@ import { extractCommandCdTargets, extractCommandWriteTargets } from "./protected
 
 /**
  * Deterministic action classifier for tool calls. Pure function, no I/O, no
- * state. Slice 3 wires it into dispatch admission and audit. This module only
+ * state. Dispatch admission and tool audit consume it. This module only
  * owns the mapping from (tool, args) to an ActionClass.
  */
 
@@ -89,10 +89,22 @@ function baseClassify(tool: string): ActionClass | null {
 		case ToolNames.Grep:
 		case ToolNames.Find:
 		case ToolNames.Ls:
+		// web_read is the GET-only half of the web split: no method, headers,
+		// or body can make it outward, so it is read class unconditionally.
+		case ToolNames.WebRead:
 		case ToolNames.WebFetch:
 		case ToolNames.Git:
 		case ToolNames.CodeNav:
 		case ToolNames.Context:
+		// clio_docs and clio_library read Clio's bundled documentation and the
+		// recipe catalog; data streams structured files. None writes.
+		case ToolNames.ClioDocs:
+		case ToolNames.ClioLibrary:
+		case ToolNames.Data:
+		// gateway lists and describes capabilities on its own; a call carries
+		// the capability's own class through a nested admission, so the outer
+		// call stays read class.
+		case ToolNames.Gateway:
 		case ToolNames.Monitor:
 		case ToolNames.AskUser:
 		case ToolNames.CredentialPresent:
@@ -124,6 +136,10 @@ function baseClassify(tool: string): ActionClass | null {
 			return "write";
 		case ToolNames.Bash:
 		case ToolNames.Verify:
+		// run_script runs an interpreter over a workspace script; its
+		// safetyCall projects the exact argv to a bash command so the policy
+		// engine applies the shell rules to it.
+		case ToolNames.RunScript:
 			return "execute";
 		case ToolNames.Dispatch:
 		case ToolNames.Steer:

package/src/domains/safety/call-target.ts

@@ -130,12 +130,20 @@ const CALL_ACTION_VOCABULARY: Readonly<Record<string, { verb: string; field: str
 	bash: { verb: "running", field: "command" },
 	grep: { verb: "searching", field: "pattern" },
 	find: { verb: "finding", field: "pattern" },
+	web_read: { verb: "reading", field: "url" },
 	web_fetch: { verb: "fetching", field: "url" },
 	git: { verb: "git", field: "op" },
 	verify: { verb: "verifying", field: "check" },
+	run_script: { verb: "running", field: "script" },
 	code_nav: { verb: "navigating", field: "query" },
 	context: { verb: "context", field: "scope" },
+	clio_docs: { verb: "searching", field: "query" },
+	clio_library: { verb: "searching", field: "query" },
+	data: { verb: "inspecting", field: "path" },
 	artifact: { verb: "writing", field: "kind" },
+	// The gateway's descriptor names the capability it reaches, so worker
+	// telemetry and receipts read "gateway git" rather than an opaque call.
+	gateway: { verb: "gateway", field: "capability" },
 	monitor: { verb: "monitoring", field: "run_id" },
 	steer: { verb: "steering", field: "run_id" },
 	tasks: { verb: "tasks", field: "action" },
@@ -193,9 +201,15 @@ const CALL_TARGET_FIELDS: Readonly<Record<string, ReadonlyArray<string>>> = {
 	steer: ["run_id", "action"],
 	tasks: ["action", "id"],
 	ledger: ["action", "kind", "path", "line", "target", "passed", "since"],
+	web_read: ["url", "timeout_ms", "max_bytes", "format"],
 	web_fetch: ["url", "method", "timeout_ms", "max_bytes", "format"],
+	run_script: ["interpreter", "script", "args", "interpreter_args", "cwd", "timeout_ms", "inputs", "outputs"],
+	clio_docs: ["query", "limit"],
+	clio_library: ["query", "kind", "ref", "limit", "offset"],
+	data: ["op", "path", "format", "offset", "limit", "columns", "pointer", "sample_rows", "max_rows"],
 	ask_user: ["action", "mode", "max_rounds", "exposure"],
 	artifact: ["kind", "path", "title"],
+	gateway: ["op", "capability", "query"],
 	// ACP tool kinds use only fields whose meaning the protocol defines.
 	execute: ["command", "cwd"],
 	search: ["query", "path"],

package/src/domains/safety/contract.ts

@@ -45,7 +45,7 @@ export interface SafetyContract {
 		readonly confirmed: ScopeSpec;
 	};
 
-	/** Subset check used by dispatch admission (Phase 6). */
+	/** Subset check used by dispatch admission. */
 	isSubset(worker: ScopeSpec, orchestrator: ScopeSpec): boolean;
 
 	/** Immutable safety policy metadata for receipts, audit, and replay. */

package/src/domains/safety/finish-contract.ts

@@ -1,6 +1,7 @@
 import { resolve } from "node:path";
 import { ToolNames } from "../../core/tool-names.js";
 import { isProjectVerifierCheckId, isVerificationScriptName } from "../../core/verification-scripts.js";
+import { effectiveToolCall } from "../../tools/surface.js";
 import { type DeclaredCheckSourceRef, PROJECT_VERIFIER_CATALOG_RELATIVE_PATH } from "../../tools/verify/catalog.js";
 import type { UserTaskAcceptance } from "../user-tasks/acceptance.js";
 import {
@@ -295,9 +296,14 @@ function mutatingToolCall(entry: unknown): MutationCandidate | null {
 	if (record?.kind !== "message" || record.role !== "tool_call") return null;
 	const payload = asRecord(record.payload);
 	if (payload === null) return null;
-	const toolName = stringFromFirst(payload, ["name", "toolName", "tool"]);
-	if (toolName === null) return null;
-	const args = asRecord(payload.args ?? payload.arguments ?? payload.input) ?? undefined;
+	const recordedTool = stringFromFirst(payload, ["name", "toolName", "tool"]);
+	if (recordedTool === null) return null;
+	// An artifact written through the gateway mutates the same path a direct
+	// artifact call would, so the call unwraps to the capability first.
+	const { toolName, args } = effectiveToolCall(
+		recordedTool,
+		asRecord(payload.args ?? payload.arguments ?? payload.input) ?? undefined,
+	);
 	const paths = mutationPathsForTool(toolName, args);
 	if (paths.length === 0) return null;
 	const toolCallId = stringFromFirst(payload, ["toolCallId", "tool_call_id", "id"]) ?? turnIdOf(entry);

package/src/domains/safety/loop-detector.ts

@@ -1,6 +1,6 @@
 /**
  * Simple sliding-window loop detector. Pure logic; the caller owns state
- * storage. Slice 3 hands this an identity key composed of tool name + canonical
+ * storage. Callers provide an identity key composed of tool name + canonical
  * arg hash and a `Date.now()` reading so runaway workers can be caught before
  * their audit trail floods disk. `hashToolCall` builds that identity key and
  * lives here, beside the detector, so every observer (the registry's hook

package/src/domains/safety/policy-engine.ts

@@ -162,6 +162,7 @@ const EXECUTION_TOOLS = new Set<string>([ToolNames.Bash, ToolNames.Verify]);
 export const WRITE_ROOT_REFUSED_TOOLS: ReadonlySet<string> = new Set<string>([
 	ToolNames.Bash,
 	ToolNames.Verify,
+	ToolNames.RunScript,
 	ToolNames.Dispatch,
 ]);
 
@@ -634,6 +635,12 @@ function pathPolicyTargets(call: ClassifierCall): Array<{ operation: PathPolicyO
 			const target = pathArg(args) ?? ".";
 			return [{ operation: "read", path: target }];
 		}
+		case ToolNames.Data: {
+			// data streams one named file; a zero-access path is refused here,
+			// before the reader opens it, exactly as a read of the same path.
+			const target = pathArg(args);
+			return target === null ? [] : [{ operation: "read", path: target }];
+		}
 		case ToolNames.Write:
 		case ToolNames.Edit: {
 			const target = pathArg(args);

package/src/domains/safety/protected-artifacts.ts

@@ -62,10 +62,9 @@ export type ValidationCommandDetection = { kind: "validation"; matched: string }
  * `npx vitest`, `tsc --noEmit`). Its consumer, dispatch validation grounding,
  * spends a match on nothing. An unmatched claim there is reported and never
  * downgrades a quality label, so the cost of a miss is noise in the receipt
- * rather than a gate opening. Observed live this session: S3 workers claimed
- * "git diff verification" and grounded 0/1, and a slice-2 coder verified its
- * own fix with `node -e "import(...)"`. Both are real work the strict set
- * cannot name.
+ * rather than a gate opening. Commands such as `git diff` and
+ * `node -e "import(...)"` can ground inspection claims even when they do not
+ * satisfy the strict validation vocabulary.
  */
 export type ValidationCommandScope = "finish-contract" | "grounding";
 

package/src/domains/safety/rejection-feedback.ts

@@ -1,6 +1,6 @@
 /**
  * Human-readable rejection messages for blocked tool calls. The registry
- * (slice 6) renders `short` in the UI footer, attaches `detail` to the audit
+ * renders `short` in the UI footer, attaches `detail` to the audit
  * record, and surfaces `hints` to the worker so the next turn can recover
  * without another round-trip.
  */

package/src/domains/safety/scope.ts

@@ -3,9 +3,8 @@ import { asDirectoryPathBoundary, pathBoundaryEntryCovers, resolvePathBoundary }
 import type { ActionClass } from "./action-classifier.js";
 
 /**
- * Scope rules for worker-vs-orchestrator privilege checks. Phase 2 ships the
- * shapes and the subset predicate. Phase 6 consumes isSubset at dispatch
- * admission so a worker scope never escalates past the orchestrator.
+ * Scope rules for worker-vs-orchestrator privilege checks. Dispatch admission
+ * consumes isSubset so a worker scope never escalates past the orchestrator.
  */
 
 export interface ScopeSpec {

package/src/domains/safety/validation-contract.ts

@@ -3,6 +3,7 @@ import path from "node:path";
 import { parseDocument } from "yaml";
 import { resolveSafeCwd } from "../../core/safe-exec.js";
 import { byteLength } from "../../tools/truncate-utf8.js";
+import { MAX_ULP_TOLERANCE } from "../../tools/verify/numeric.js";
 import { compareCodepoints } from "../evidence/ordering.js";
 
 /**
@@ -215,8 +216,8 @@ function validateTolerances(value: unknown, location: string): ValidationNumeric
 	}
 	if (Object.hasOwn(value, "ulp")) {
 		const ulp = value.ulp;
-		if (typeof ulp !== "number" || !Number.isInteger(ulp) || ulp < 0) {
-			return new Error(`${location}.ulp must be a non-negative integer`);
+		if (typeof ulp !== "number" || !Number.isInteger(ulp) || ulp < 0 || ulp > MAX_ULP_TOLERANCE) {
+			return new Error(`${location}.ulp must be a non-negative integer no greater than ${MAX_ULP_TOLERANCE}`);
 		}
 		tolerances.ulp = ulp;
 	}

package/src/domains/scheduling/budget.ts

@@ -1,7 +1,9 @@
 /**
- * Session budget state. checkCeiling reports whether the current spend is at
- * or above the ceiling; dispatch admission stays informational for v0.1 per
- * the Phase 10 scope, so the caller decides whether to enforce.
+ * Session budget state. checkCeiling reports whether current spend is under,
+ * at, or over the ceiling. Scheduling preflight exposes that spend and ceiling
+ * to dispatch reservations for accounting; the allocator does not enforce this
+ * session ceiling. Dispatch separately enforces an explicit per-request intent
+ * cost ceiling against the route estimate.
  */
 
 export type BudgetVerdict = "under" | "at" | "over";

package/src/domains/scheduling/contract.ts

@@ -15,7 +15,8 @@ export interface SchedulingContract {
 	 * Evaluate the running session cost against the ceiling. Scheduling owns the
 	 * observability lookup so callers (notably dispatch) don't need to import it.
 	 * Verdict is "under" when spend is below the ceiling, "at" when equal, "over"
-	 * when above. Dispatch treats "at" and "over" as admission failures.
+	 * when above. Dispatch records this session budget without denying reservations
+	 * from the verdict; explicit request cost ceilings have a separate route check.
 	 */
 	preflight(): BudgetPreflight;
 	/** Configured global worker capacity; durable leases own active usage. */

package/src/domains/scheduling/extension.ts

@@ -1,9 +1,9 @@
 /**
  * Scheduling domain wire-up. Seeds budget + concurrency state from settings and
  * listens to dispatch.enqueued so it can fire budget.alert events when session
- * spend meets or crosses the ceiling. Dispatch admission preflights this state
- * and denies new dispatches at or over the ceiling; the alert is the TUI's
- * explanation of those denials.
+ * spend meets or crosses the ceiling. Dispatch preflight reads this state for
+ * accounting. Session-cost alerts are advisory; explicit per-request intent
+ * cost ceilings are enforced separately by dispatch route admission.
  */
 
 import { type BudgetAlertPayload, BusChannels } from "../../core/bus-events.js";

package/src/domains/session/compaction/branch-summary.ts

@@ -1,5 +1,5 @@
 /**
- * Branch summary builders (Phase 12 slice 12c).
+ * Branch summary builders.
  *
  * Deterministic text assembly for the compaction prompt. The summarization
  * model is asked to read a serialized conversation and emit a structured

package/src/domains/session/compaction/compact.ts

@@ -1,5 +1,5 @@
 /**
- * Compaction orchestration (Phase 12 slice 12c).
+ * Compaction orchestration.
  *
  * Given a list of session entries, finds the cut point, summarizes the
  * history portion via the supplied model, and returns the trimmed entry
@@ -252,6 +252,29 @@ function findTurnStartForProtection(
 	return -1;
 }
 
+/**
+ * The ledger chains entries linearly, so a result's parent is its own call only
+ * when that call was alone in its batch. In a parallel batch the parent chain
+ * runs back through sibling calls, results and activation receipts. The load is
+ * still verifiable when that chain reaches the call without crossing another
+ * assistant or user message, which would make it a different exchange.
+ */
+function resultFollowsCallInBatch(
+	turn: ReadonlyArray<SessionEntry>,
+	resultEntry: SessionEntry,
+	call: SessionEntry,
+): boolean {
+	let parent = resultEntry.parentTurnId;
+	for (let hops = 0; hops < turn.length && parent; hops++) {
+		if (parent === call.turnId) return true;
+		const link = turn.find((candidate) => candidate.turnId === parent);
+		if (!link) return false;
+		if (link.kind === "message" && link.role !== "tool_call" && link.role !== "tool_result") return false;
+		parent = link.parentTurnId;
+	}
+	return false;
+}
+
 /** Recover only complete, uniquely paired historical main-agent loads. Never consult current disk. */
 export function captureSkillContext(
 	entries: ReadonlyArray<SessionEntry>,
@@ -337,7 +360,7 @@ export function captureSkillContext(
 			results.length !== 1 ||
 			resultEntry?.kind !== "message" ||
 			!turn.includes(resultEntry) ||
-			resultEntry.parentTurnId !== call.turnId ||
+			!resultFollowsCallInBatch(turn, resultEntry, call) ||
 			entry.parentTurnId !== request.turnId
 		)
 			return undefined;
@@ -593,6 +616,9 @@ function addCompactionUsage(total: CompactionUsage | undefined, raw: unknown): C
 		output: base.output + output,
 		cacheRead: base.cacheRead + cacheRead,
 		cacheWrite: base.cacheWrite + cacheWrite,
+		...(base.cacheWrite1h === undefined && usage.cacheWrite1h === undefined
+			? {}
+			: { cacheWrite1h: (base.cacheWrite1h ?? 0) + numberOrZero(usage.cacheWrite1h) }),
 		reasoning: base.reasoning + numberOrZero(usage.reasoning),
 		totalTokens: base.totalTokens + totalTokens,
 		cost: { total: base.cost.total + numberOrZero(usage.cost?.total) },
@@ -605,7 +631,7 @@ function retainReportedUsage(previous: Record<string, unknown>, raw: unknown): R
 	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return previous;
 	const usage = raw as Record<string, unknown>;
 	const known = { ...previous };
-	for (const field of ["input", "output", "cacheRead", "cacheWrite", "totalTokens"]) {
+	for (const field of ["input", "output", "cacheRead", "cacheWrite", "cacheWrite1h", "totalTokens"]) {
 		const value = numberOrZero(usage[field]);
 		if (value > 0) known[field] = value;
 	}

package/src/domains/session/compaction/cut-point.ts

@@ -1,5 +1,5 @@
 /**
- * Cut-point detection for compaction (Phase 12 slice 12c).
+ * Cut-point detection for compaction.
  *
  * Walks an entry list newest-to-oldest, accumulating estimated tokens, and
  * reports where to slice so the suffix carries at least `keepRecentTokens`

package/src/domains/session/compaction/tokens.ts

@@ -1,16 +1,11 @@
 /**
- * Token estimation for session entries (Phase 12 slice 12c).
+ * Token estimation for session entries.
  *
- * Ports pi-coding-agent's chars/4 heuristic verbatim (reference:
- * pi-mono/packages/coding-agent/src/core/compaction/compaction.ts:232
- * `estimateTokens`). Pure functions, no I/O.
+ * Uses shared context-accounting estimates for messages and character-based
+ * estimates for other context-bearing entries. Provider usage anchors measured
+ * prefixes when available. These estimates are approximate, not token ceilings.
+ * Pure functions, no I/O.
  *
- * Rationale for the heuristic (plan §3):
- *   - Conservative by design: over-estimating trips compaction earlier,
- *     never later. Missing a trigger and hitting provider overflow is
- *     expensive; running a compaction on 80k when actual was 95k is cheap.
- *   - pi-coding-agent ships it at scale, so we adopt the
- *     known ceiling rather than introduce a new numeric contract.
  *   - Exact per-provider counts (Anthropic /count_tokens, tiktoken) are
  *     parked. The `TokenEstimator` interface below keeps them a drop-in
  *     swap for a later phase.

package/src/domains/session/contract.ts

@@ -92,7 +92,7 @@ export interface SessionContract {
 	append(turn: TurnInput): ClioTurnRecord;
 	/**
 	 * Append a rich SessionEntry to the current session. Complements
-	 * `append(turn)` for Phase 12+ entry kinds (compactionSummary,
+	 * `append(turn)` for structured entry kinds (compactionSummary,
 	 * branchSummary, modelChange, etc.). Old callers keep using `append`.
 	 */
 	appendEntry(entry: SessionEntryInput): SessionEntry;

package/src/domains/session/cwd-fallback.ts

@@ -1,5 +1,5 @@
 /**
- * Session cwd fallback resolver (Phase 12 slice 12d).
+ * Session cwd fallback resolver.
  *
  * Pure guard used by the interactive layer when a session is resumed.
  * `meta.cwd` is captured at session creation time; by the time the user
@@ -37,7 +37,7 @@ export const defaultFsProbe: FsProbe = {
 /**
  * Discriminated result the overlay layer branches on.
  *   - `no-cwd`: the meta record has no cwd field or it is blank after
- *     trimming. Pre-Phase-12 sessions occasionally land here.
+ *     trimming. Incomplete legacy metadata can produce this result.
  *   - `missing`: cwd string is set but the directory does not exist on
  *     disk (fsProbe.exists returned false).
  *   - `not-a-directory`: the path exists but resolves to a file or a

package/src/domains/session/entries.ts

@@ -114,6 +114,7 @@ export interface CompactionUsage {
 	output: number;
 	cacheRead: number;
 	cacheWrite: number;
+	cacheWrite1h?: number;
 	reasoning: number;
 	totalTokens: number;
 	cost: { total: number };

package/src/domains/session/handoff.ts

@@ -22,6 +22,7 @@
  */
 
 import { isAbsolute, normalize, relative, resolve } from "node:path";
+import { effectiveToolCall } from "../../tools/surface.js";
 import { decisionRationale } from "./decision-board.js";
 import type { DecisionLedgerEntry, SessionEntry } from "./entries.js";
 import { filterEntriesToActivePath } from "./tree/active-path.js";
@@ -369,7 +370,10 @@ function stringField(record: Record<string, unknown> | null, ...keys: string[]):
 	return null;
 }
 
-function pathFromCall(toolName: string, args: unknown, cwd: string | null, into: Set<string>): void {
+function pathFromCall(recordedTool: string, recordedArgs: unknown, cwd: string | null, into: Set<string>): void {
+	// A gateway call is the capability it reached: an artifact written through
+	// the gateway touched the same path a direct artifact call would have.
+	const { toolName, args } = effectiveToolCall(recordedTool, recordedArgs);
 	if (!READ_LEDGER_TOOLS.has(toolName)) return;
 	const record = isRecord(args) ? args : null;
 	const named = stringField(record, "path", "file_path", "filePath");

package/src/domains/session/history.ts

@@ -95,6 +95,12 @@ function extractMessageText(payload: unknown): string | null {
  * operator-authored remains, so the caller moves on to the next turn.
  */
 function operatorTextOfUserPayload(payload: unknown): string | null {
+	// An expansion (prompt template, command) replaced the typed input. The
+	// typed input is the title; the expansion starts with generated scaffolding.
+	if (payload && typeof payload === "object" && typeof (payload as { displayText?: unknown }).displayText === "string") {
+		const typed = collapseWhitespace((payload as { displayText: string }).displayText);
+		if (typed.length > 0) return typed;
+	}
 	if (
 		payload &&
 		typeof payload === "object" &&

package/src/domains/session/manager.ts

@@ -6,10 +6,12 @@ import {
 	type ClioTurnRecord,
 	createSession as engineCreateSession,
 	resumeSession as engineResumeSession,
+	openSession,
 	readSessionMeta,
 	type SessionTreeNode,
 	sessionPaths,
 } from "../../engine/session.js";
+import { collectSessionEntries } from "./compaction/session-entries.js";
 import type { SessionEntryInput, SessionMeta, TurnInput } from "./contract.js";
 import { isSessionEntry, type SessionEntry } from "./entries.js";
 import { runMigrations } from "./migrations/index.js";
@@ -71,14 +73,19 @@ export function resumeSessionState(sessionId: string): {
 	const persistedMeta = readSessionMeta(sessionId) as SessionMeta;
 	const paths = sessionPaths(persistedMeta);
 	const migration = runMigrations(persistedMeta, paths.meta);
-	const { meta, writer, tree } = engineResumeSession(sessionId);
+	const candidate = openSession(sessionId);
+	// Use the replay schema before engineResumeSession clears endedAt or
+	// the domain caller parks its current writer. The engine reader retains
+	// its established tolerance for interrupted JSONL fragments.
+	collectSessionEntries(candidate.turns(), paths.current);
+	// The ledger needed no transformation; only the stamp moves, so the next
+	// reader does not re-run the same no-op. It lands in the same metadata
+	// publication that reopens the session.
+	const { meta, writer, tree } = engineResumeSession(
+		sessionId,
+		migration.migrated ? { sessionFormatVersion: migration.to } : {},
+	);
 	const state: SessionManagerState = { meta: meta as SessionMeta, writer };
-	if (migration.migrated) {
-		// The ledger needed no transformation; only the stamp moves, so the next
-		// reader does not re-run the same no-op.
-		state.meta.sessionFormatVersion = migration.to;
-		persistSessionMeta(state);
-	}
 	return { state, nodes: tree };
 }
 

package/src/domains/session/retry.ts

@@ -1,5 +1,5 @@
 /**
- * Retry settings and countdown helper (Phase 12 / Phase 22 seam).
+ * Retry settings and countdown helper.
  *
  * pi-agent-core surfaces provider failures as a terminal assistant message
  * with `stopReason: "error"` + `errorMessage: <provider text>`. It does not
@@ -42,6 +42,7 @@ export const DEFAULT_RETRY_SETTINGS: RetrySettings = {
 	baseDelayMs: 2000,
 	maxDelayMs: 60000,
 	streamStallMs: 180000,
+	firstTokenStallMs: 600000,
 };
 
 /**