@skein-code/cli 0.3.24 → 0.3.26

package/dist/cli.js

@@ -220,7 +220,7 @@ function isSqliteBusy(error) {
 // package.json
 var package_default = {
   name: "@skein-code/cli",
-  version: "0.3.24",
+  version: "0.3.26",
   description: "A context-first, model-agnostic coding agent with an auditable terminal workspace.",
   type: "module",
   license: "MIT",
@@ -236,6 +236,17 @@ var package_default = {
   },
   skein: {
     releaseNotes: [
+      "First-run setup now states that the primary agent needs API credentials and that provider subscriptions or signed-in coding CLIs are separate delegated tools",
+      "Permission prompts show the policy reason, redacted target, working directory, category risk, and explicit once, session, deny, and stop choices",
+      "The Recovery Center joins last-run state, failure repair hints, changed files, checkpoints, diff, audit, rollback, retry, and safe session resume",
+      "Read-only review commands pin working-tree, commit, or branch scope and inject a content-free redacted evidence bundle without storing it in the user transcript",
+      "JSON and JSONL terminal records now follow the published headless v1 schema with stable completed, verification, input, blocked, cancellation, turn, token, and error exit codes",
+      "Short terminal viewports clip long lists without overflow and pending clarifications cannot be consumed by recovery commands",
+      "Durable sessions now separate a 250k-token context epoch from a 1m-token lifetime ceiling without changing the session id or deleting transcript history",
+      "Content-free epoch handoffs preserve Task Contract criteria, unresolved failure circuits, changed files, and verification receipts across long runs",
+      "Intent Sufficiency routes clear requests to execution, repository-inferable gaps to inspection, and genuine product choices to one persisted clarification",
+      "TUI and headless output expose epoch, lifetime, and needs-input state; queued follow-ups pause and resume after keyboard clarification instead of becoming accidental answers",
+      "Successful identical tool calls clear matching historical failure signatures from later epoch handoffs",
       "Context compaction now rebuilds authoritative task, working-state, verification, permission, failure, and artifact facts outside generated narrative",
       "Automatic compaction runs only when three predicted prompt reuses produce positive net token savings while explicit compact commands remain available",
       "Compaction provider usage is included in session totals with separate content-free actual or estimated receipts",
@@ -1993,6 +2004,7 @@ var partialConfigSchema = z2.object({
   }).partial().optional(),
   agent: z2.object({
     maxTurns: z2.number().int().positive().optional(),
+    maxEpochTokens: z2.number().int().positive().optional(),
     maxSessionTokens: z2.number().int().positive().optional(),
     autoVerify: z2.boolean().optional(),
     verifyCommands: z2.array(z2.string()).optional(),
@@ -2072,7 +2084,8 @@ function defaultConfig(workspace = process.cwd()) {
     hooks: {},
     agent: {
       maxTurns: 24,
-      maxSessionTokens: 25e4,
+      maxEpochTokens: 25e4,
+      maxSessionTokens: 1e6,
       autoVerify: true,
       verifyCommands: [],
       checkpointBeforeWrite: true
@@ -2436,6 +2449,7 @@ function configSummary(config) {
     workspaceRoots: config.workspaceRoots,
     permissions: config.permissions,
     maxTurns: config.agent.maxTurns,
+    maxEpochTokens: config.agent.maxEpochTokens,
     maxSessionTokens: config.agent.maxSessionTokens,
     autoVerify: config.agent.autoVerify,
     skills: config.skills ? {
@@ -4720,10 +4734,127 @@ function formatContextHits(hits, roots) {
 }
 
 // src/agent/runner.ts
-import { randomUUID as randomUUID13 } from "node:crypto";
+import { randomUUID as randomUUID15 } from "node:crypto";
 
 // src/context/manager.ts
+import { randomUUID as randomUUID5 } from "node:crypto";
+
+// src/context/epochs.ts
 import { randomUUID as randomUUID4 } from "node:crypto";
+var MAX_EPOCHS = 64;
+var MAX_HANDOFF_FAILURES = 16;
+function activeContextEpoch(session) {
+  return ensureContextEpoch(session);
+}
+function ensureContextEpoch(session) {
+  const epochs = session.contextEpochs ?? (session.contextEpochs = []);
+  const active = epochs.at(-1);
+  if (active && active.finishedAt === void 0) return active;
+  const next = createEpoch((active?.index ?? 0) + 1);
+  epochs.push(next);
+  trimEpochs(epochs);
+  return next;
+}
+function recordContextEpochUsage(session, inputTokens, outputTokens) {
+  const epoch = ensureContextEpoch(session);
+  epoch.usage.inputTokens += boundedTokens(inputTokens);
+  epoch.usage.outputTokens += boundedTokens(outputTokens);
+  return epoch;
+}
+function contextEpochTokens(session) {
+  const epoch = ensureContextEpoch(session);
+  return epoch.usage.inputTokens + epoch.usage.outputTokens;
+}
+function rotateContextEpoch(session, reason, compaction) {
+  const previous = ensureContextEpoch(session);
+  const createdAt = (/* @__PURE__ */ new Date()).toISOString();
+  const handoff = buildEpochHandoff(session, reason, createdAt, compaction);
+  previous.finishedAt = createdAt;
+  previous.handoff = handoff;
+  const current = createEpoch(previous.index + 1, createdAt);
+  const epochs = session.contextEpochs ?? (session.contextEpochs = []);
+  epochs.push(current);
+  trimEpochs(epochs);
+  return { previous, current, handoff };
+}
+function buildEpochHandoff(session, reason, createdAt, compaction) {
+  const failures = unresolvedFailureReceipts(session);
+  const contract = session.taskContract;
+  return {
+    reason,
+    createdAt,
+    ...compaction ? { compactionReceiptId: compaction.id } : {},
+    ...session.compactedThroughMessageId ? { compactedThroughMessageId: session.compactedThroughMessageId } : {},
+    ...contract ? {
+      contract: {
+        state: contract.state,
+        required: contract.acceptanceCriteria.filter((criterion2) => criterion2.required).map((criterion2) => ({
+          id: criterion2.id,
+          status: criterion2.status,
+          evidenceRefs: [...criterion2.evidenceRefs]
+        }))
+      }
+    } : {},
+    unresolvedFailures: failures,
+    changedFiles: [...new Set(session.changedFiles)].slice(-256),
+    checks: session.lastRun?.checks.map((check) => ({ ...check })) ?? []
+  };
+}
+function unresolvedFailureReceipts(session) {
+  const unresolved2 = /* @__PURE__ */ new Map();
+  for (const event of session.audit ?? []) {
+    if (event.type !== "tool") continue;
+    if (event.outcome === "failure") {
+      const receipt = failureReceipt(event.metadata?.failure);
+      if (receipt) unresolved2.set(receipt.signature, receipt);
+      continue;
+    }
+    const resolved = event.metadata?.resolvedFailureSignatures;
+    if (!Array.isArray(resolved)) continue;
+    for (const signature of resolved) {
+      if (typeof signature === "string") unresolved2.delete(signature);
+    }
+  }
+  return [...unresolved2.values()].slice(-MAX_HANDOFF_FAILURES);
+}
+function failureReceipt(value) {
+  if (!value || typeof value !== "object") return;
+  const candidate = value;
+  const classes = /* @__PURE__ */ new Set([
+    "schema_input",
+    "unknown_tool",
+    "permission_denied",
+    "command_exit",
+    "timeout",
+    "cancelled",
+    "hook",
+    "execution",
+    "no_progress",
+    "contract_required"
+  ]);
+  if (typeof candidate.signature !== "string" || !candidate.signature || typeof candidate.class !== "string" || !classes.has(candidate.class) || typeof candidate.circuitOpen !== "boolean") return;
+  return {
+    signature: candidate.signature.slice(0, 256),
+    class: candidate.class,
+    circuitOpen: candidate.circuitOpen
+  };
+}
+function createEpoch(index, startedAt = (/* @__PURE__ */ new Date()).toISOString()) {
+  return {
+    id: randomUUID4(),
+    index,
+    startedAt,
+    usage: { inputTokens: 0, outputTokens: 0 }
+  };
+}
+function trimEpochs(epochs) {
+  if (epochs.length > MAX_EPOCHS) epochs.splice(0, epochs.length - MAX_EPOCHS);
+}
+function boundedTokens(value) {
+  return Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+}
+
+// src/context/manager.ts
 var RECENT_TURN_RESERVE = 3;
 var COMPACTION_HIGH_WATER = 0.78;
 var TOOL_PRESSURE_WATER = 0.28;
@@ -4776,13 +4907,21 @@ var ContextManager = class {
       modelContextTokens ?? Math.min(1e5, this.config.context.maxTokens * 3)
     );
     const compactedMessages = session.compactedThroughMessageId ? Math.max(0, session.messages.findIndex((message2) => message2.id === session.compactedThroughMessageId) + 1) : 0;
+    const epoch = activeContextEpoch(session);
+    const epochBudget = this.config.agent.maxEpochTokens ?? this.config.agent.maxSessionTokens;
     return {
       activeTokens,
       summaryTokens,
       toolTokens: toolTokenCount,
       messageCount: active.length,
       compactedMessages,
-      pressure: Math.min(1, (activeTokens + summaryTokens) / contextLimit)
+      pressure: Math.min(1, (activeTokens + summaryTokens) / contextLimit),
+      epochIndex: epoch.index,
+      epochCount: epoch.index,
+      epochTokens: epoch.usage.inputTokens + epoch.usage.outputTokens,
+      epochBudget,
+      lifetimeTokens: session.usage.inputTokens + session.usage.outputTokens,
+      lifetimeBudget: this.config.agent.maxSessionTokens
     };
   }
   shouldCompact(session, tokenBudget) {
@@ -4891,7 +5030,7 @@ function compactionEstimate(session, older, facts, request) {
 }
 function skippedCompaction(session, mode, reason, estimate = emptyCompactionEstimate(session)) {
   const receipt = {
-    id: randomUUID4(),
+    id: randomUUID5(),
     recordedAt: (/* @__PURE__ */ new Date()).toISOString(),
     mode,
     status: "skipped",
@@ -4928,7 +5067,7 @@ function emptyCompactionEstimate(session) {
 function completedCompactionReceipt(mode, omittedMessages, compactedThroughMessageId, estimated, response, summary) {
   const actual = actualUsage(response.usage);
   return {
-    id: randomUUID4(),
+    id: randomUUID5(),
     recordedAt: (/* @__PURE__ */ new Date()).toISOString(),
     mode,
     status: "compacted",
@@ -4967,6 +5106,7 @@ function buildCompactionFactsEnvelope(session, throughMessageId) {
   const memory = session.workingMemory;
   const contract = session.taskContract;
   const lastRun = session.lastRun;
+  const epoch = activeContextEpoch(session);
   const directives = olderUserDirectives(session, throughMessageId ?? session.compactedThroughMessageId);
   const permissions = recentPermissionFacts(session.audit ?? []);
   const failures = recentFailureFacts(session.audit ?? []);
@@ -5019,6 +5159,11 @@ ${factList(memory?.relevantFiles ?? [])}
 Session changed files:
 ${factList(session.changedFiles)}
 
+Context epoch ledger:
+- Current epoch: ${epoch.index}
+- Current epoch usage: input=${epoch.usage.inputTokens}; output=${epoch.usage.outputTokens}
+- Lifetime usage: input=${session.usage.inputTokens}; output=${session.usage.outputTokens}
+
 Last-run verification and residual state:
 ${lastRunLines}
 
@@ -5462,7 +5607,7 @@ function normalizeForMatch(value) {
 }
 
 // src/providers/anthropic.ts
-import { randomUUID as randomUUID5 } from "node:crypto";
+import { randomUUID as randomUUID6 } from "node:crypto";
 
 // src/providers/provider.ts
 var ProviderError = class extends Error {
@@ -5587,7 +5732,7 @@ var AnthropicProvider = class {
     return {
       content: blocks.filter((block) => block.type === "text").map((block) => block.text ?? "").join("\n"),
       toolCalls: blocks.filter((block) => block.type === "tool_use").map((block) => ({
-        id: block.id ?? randomUUID5(),
+        id: block.id ?? randomUUID6(),
         name: block.name ?? "unknown",
         arguments: safeJsonArguments(block.input)
       })),
@@ -5661,7 +5806,7 @@ var AnthropicProvider = class {
       }
       if (chunk.type === "content_block_start" && chunk.content_block?.type === "tool_use") {
         calls.set(index, {
-          id: chunk.content_block.id ?? randomUUID5(),
+          id: chunk.content_block.id ?? randomUUID6(),
           name: chunk.content_block.name ?? "unknown",
           input: chunk.content_block.input,
           partialJson: ""
@@ -5672,7 +5817,7 @@ var AnthropicProvider = class {
         yield { type: "text_delta", content: chunk.delta.text };
       }
       if (chunk.type === "content_block_delta" && chunk.delta?.type === "input_json_delta") {
-        const call = calls.get(index) ?? { id: randomUUID5(), name: "unknown", input: void 0, partialJson: "" };
+        const call = calls.get(index) ?? { id: randomUUID6(), name: "unknown", input: void 0, partialJson: "" };
         call.partialJson += chunk.delta.partial_json ?? "";
         calls.set(index, call);
       }
@@ -5702,7 +5847,7 @@ function normalizeAnthropicResponse(data) {
   return {
     content: blocks.filter((block) => block.type === "text").map((block) => block.text ?? "").join("\n"),
     toolCalls: blocks.filter((block) => block.type === "tool_use").map((block) => ({
-      id: block.id ?? randomUUID5(),
+      id: block.id ?? randomUUID6(),
       name: block.name ?? "unknown",
       arguments: safeJsonArguments(block.input)
     })),
@@ -5747,7 +5892,7 @@ function toAnthropicMessage(message2) {
 }
 
 // src/providers/gemini.ts
-import { randomUUID as randomUUID6 } from "node:crypto";
+import { randomUUID as randomUUID7 } from "node:crypto";
 var GeminiProvider = class {
   constructor(config) {
     this.config = config;
@@ -5787,7 +5932,7 @@ var GeminiProvider = class {
     return {
       content: parts.map((part) => part.text ?? "").filter(Boolean).join("\n"),
       toolCalls: parts.filter((part) => part.functionCall).map((part) => ({
-        id: randomUUID6(),
+        id: randomUUID7(),
         name: part.functionCall?.name ?? "unknown",
         arguments: safeJsonArguments(part.functionCall?.args)
       })),
@@ -5859,7 +6004,7 @@ var GeminiProvider = class {
         }
         if (part.functionCall) {
           toolCalls.push({
-            id: randomUUID6(),
+            id: randomUUID7(),
             name: part.functionCall.name ?? "unknown",
             arguments: safeJsonArguments(part.functionCall.args)
           });
@@ -5888,7 +6033,7 @@ function normalizeGeminiResponse(data) {
   return {
     content: parts.map((part) => part.text ?? "").filter(Boolean).join("\n"),
     toolCalls: parts.filter((part) => part.functionCall).map((part) => ({
-      id: randomUUID6(),
+      id: randomUUID7(),
       name: part.functionCall?.name ?? "unknown",
       arguments: safeJsonArguments(part.functionCall?.args)
     })),
@@ -5932,7 +6077,7 @@ function toGeminiMessage(message2) {
 }
 
 // src/providers/openai.ts
-import { randomUUID as randomUUID7 } from "node:crypto";
+import { randomUUID as randomUUID8 } from "node:crypto";
 var OpenAIProvider = class {
   constructor(config) {
     this.config = config;
@@ -6055,7 +6200,7 @@ var OpenAIProvider = class {
       }
       for (const fragment of delta?.tool_calls ?? []) {
         const index = fragment.index ?? 0;
-        const current = calls.get(index) ?? { id: randomUUID7(), name: "", arguments: "" };
+        const current = calls.get(index) ?? { id: randomUUID8(), name: "", arguments: "" };
         if (fragment.id) current.id = fragment.id;
         if (fragment.function?.name) current.name += fragment.function.name;
         if (fragment.function?.arguments) current.arguments += fragment.function.arguments;
@@ -6089,7 +6234,7 @@ function normalizeOpenAIResponse(data) {
   return {
     content: message2.content ?? "",
     toolCalls: (message2.tool_calls ?? []).map((call) => ({
-      id: call.id ?? randomUUID7(),
+      id: call.id ?? randomUUID8(),
       name: call.function?.name ?? "unknown",
       arguments: safeJsonArguments(call.function?.arguments)
     })),
@@ -6145,7 +6290,7 @@ function createProvider(config) {
 }
 
 // src/checkpoint/store.ts
-import { createHash as createHash8, randomUUID as randomUUID8 } from "node:crypto";
+import { createHash as createHash8, randomUUID as randomUUID9 } from "node:crypto";
 import { lstat as lstat10, mkdir as mkdir7, readFile as readFile5, readdir as readdir2, unlink as unlink2 } from "node:fs/promises";
 import { basename as basename6, dirname as dirname8, join as join9, relative as relative6, resolve as resolve12 } from "node:path";
 import { z as z4 } from "zod";
@@ -6181,7 +6326,7 @@ var CheckpointStore = class {
     return this.withManagedLease(() => this.captureUnlocked(sessionId, unique3, options));
   }
   async captureUnlocked(sessionId, unique3, options) {
-    const id = `${Date.now().toString(36)}-${randomUUID8()}`;
+    const id = `${Date.now().toString(36)}-${randomUUID9()}`;
     const target = join9(this.directory, sessionId, id);
     const blobDirectory = join9(target, "blobs");
     await this.ensureDirectory();
@@ -6457,7 +6602,7 @@ var HookRunner = class {
 };
 
 // src/session/store.ts
-import { randomUUID as randomUUID9 } from "node:crypto";
+import { randomUUID as randomUUID10 } from "node:crypto";
 import { constants as constants4 } from "node:fs";
 import {
   chmod as chmod6,
@@ -6683,6 +6828,76 @@ var contextCompactionReceiptSchema = z5.object({
   outputSource: z5.enum(["actual", "estimated", "none"]),
   narrative: z5.enum(["present", "empty", "not-requested"])
 }).strict();
+var contextEpochSchema = z5.object({
+  id: z5.string().uuid(),
+  index: z5.number().int().positive(),
+  startedAt: z5.string().datetime(),
+  finishedAt: z5.string().datetime().optional(),
+  usage: z5.object({
+    inputTokens: z5.number().int().nonnegative(),
+    outputTokens: z5.number().int().nonnegative()
+  }).strict(),
+  handoff: z5.object({
+    reason: z5.enum(["token_budget", "context_pressure", "manual"]),
+    createdAt: z5.string().datetime(),
+    compactionReceiptId: z5.string().uuid().optional(),
+    compactedThroughMessageId: z5.string().optional(),
+    contract: z5.object({
+      state: z5.enum(["draft", "active", "satisfied", "blocked"]),
+      required: z5.array(z5.object({
+        id: z5.string().min(1).max(128),
+        status: z5.enum(["pending", "satisfied", "blocked"]),
+        evidenceRefs: z5.array(z5.string().min(1).max(256)).max(64)
+      }).strict()).max(64)
+    }).strict().optional(),
+    unresolvedFailures: z5.array(z5.object({
+      signature: z5.string().min(1).max(256),
+      class: z5.enum([
+        "schema_input",
+        "unknown_tool",
+        "permission_denied",
+        "command_exit",
+        "timeout",
+        "cancelled",
+        "hook",
+        "execution",
+        "no_progress",
+        "contract_required"
+      ]),
+      circuitOpen: z5.boolean()
+    }).strict()).max(16),
+    changedFiles: z5.array(z5.string().max(4096)).max(256),
+    checks: z5.array(verificationEvidenceSchema).max(64)
+  }).strict().optional()
+}).strict();
+var intentAssessmentSchema = z5.object({
+  version: z5.literal(1),
+  route: z5.enum(["direct_execute", "inspect_then_execute", "needs_input", "permission_required"]),
+  reasons: z5.array(z5.enum([
+    "simple_explicit_request",
+    "workspace_inference_available",
+    "explicit_user_choice_missing",
+    "public_api_compatibility_missing",
+    "runtime_permission_separate",
+    "clarification_resolved"
+  ])).min(1).max(8),
+  assessedAt: z5.string().datetime(),
+  retrievalHits: z5.number().int().nonnegative()
+}).strict();
+var pendingInputSchema = z5.object({
+  id: z5.string().uuid(),
+  runId: z5.string().uuid(),
+  createdAt: z5.string().datetime(),
+  originalRequest: z5.string().min(1).max(12e4),
+  question: z5.string().min(1).max(2e3),
+  options: z5.array(z5.object({
+    id: z5.string().regex(/^[a-z][a-z0-9_-]{0,63}$/u),
+    label: z5.string().min(1).max(160),
+    impact: z5.string().min(1).max(500),
+    recommended: z5.boolean()
+  }).strict()).min(2).max(3),
+  reason: z5.enum(["explicit_user_choice_missing", "public_api_compatibility_missing"])
+}).strict();
 var sessionSchema = z5.object({
   id: sessionIdSchema,
   title: z5.string(),
@@ -6699,6 +6914,9 @@ var sessionSchema = z5.object({
   contextCompactions: z5.number().int().nonnegative().optional(),
   compactedThroughMessageId: z5.string().optional(),
   contextCompactionReceipts: z5.array(contextCompactionReceiptSchema).max(64).optional(),
+  contextEpochs: z5.array(contextEpochSchema).max(64).optional(),
+  intentAssessment: intentAssessmentSchema.optional(),
+  pendingInput: pendingInputSchema.optional(),
   workingMemory: workingMemorySchema.optional(),
   contextSources: z5.array(contextSourceSchema).max(64).optional(),
   toolArtifacts: z5.array(toolArtifactSchema).max(200).optional(),
@@ -6849,7 +7067,7 @@ var SessionStore = class {
     const backup = this.backupPathFor(session.id);
     await this.assertManagedFile(target);
     await this.assertManagedFile(backup);
-    const temporary = join10(this.directory, `.${session.id}.${randomUUID9()}.tmp`);
+    const temporary = join10(this.directory, `.${session.id}.${randomUUID10()}.tmp`);
     const data = `${JSON.stringify(session, null, 2)}
 `;
     const handle = await open2(temporary, "wx", 384);
@@ -6867,7 +7085,7 @@ var SessionStore = class {
     }
   }
   async copyBackup(source, target) {
-    const temporary = join10(this.directory, `.${basename7(target)}.${randomUUID9()}.tmp`);
+    const temporary = join10(this.directory, `.${basename7(target)}.${randomUUID10()}.tmp`);
     try {
       await copyFile(source, temporary, constants4.COPYFILE_EXCL);
       await chmod6(temporary, 384);
@@ -6956,7 +7174,7 @@ var SessionStore = class {
   }
 };
 function createSession(options) {
-  const id = options.id ?? randomUUID9();
+  const id = options.id ?? randomUUID10();
   validateId(id);
   const now = (/* @__PURE__ */ new Date()).toISOString();
   return {
@@ -6971,6 +7189,12 @@ function createSession(options) {
     tasks: [],
     changedFiles: [],
     audit: [],
+    contextEpochs: [{
+      id: randomUUID10(),
+      index: 1,
+      startedAt: now,
+      usage: { inputTokens: 0, outputTokens: 0 }
+    }],
     usage: { inputTokens: 0, outputTokens: 0 }
   };
 }
@@ -8063,7 +8287,7 @@ function isUnsafeGitOption(argument) {
     "--exclude-from",
     "--output",
     "--directory"
-  ].some((option) => argument === option || argument.startsWith(`${option}=`));
+  ].some((option2) => argument === option2 || argument.startsWith(`${option2}=`));
 }
 function firstGitCommand(args) {
   for (const argument of args) {
@@ -8811,7 +9035,7 @@ async function discoverSnapshotFiles(root) {
 }
 
 // src/tools/task.ts
-import { randomUUID as randomUUID10 } from "node:crypto";
+import { randomUUID as randomUUID11 } from "node:crypto";
 import { z as z14 } from "zod";
 var taskSchema2 = z14.object({
   id: z14.string().min(1).optional(),
@@ -8860,7 +9084,7 @@ var taskTool = {
       case "list":
         break;
       case "add":
-        tasks.push({ id: randomUUID10(), title: input2.title, status: input2.status ?? "pending" });
+        tasks.push({ id: randomUUID11(), title: input2.title, status: input2.status ?? "pending" });
         break;
       case "update": {
         const task = tasks.find((item) => item.id === input2.id);
@@ -8877,7 +9101,7 @@ var taskTool = {
       }
       case "replace":
         tasks.splice(0, tasks.length, ...input2.tasks.map((task) => ({
-          id: task.id ?? randomUUID10(),
+          id: task.id ?? randomUUID11(),
           title: task.title,
           status: task.status
         })));
@@ -8891,11 +9115,11 @@ var taskTool = {
 };
 
 // src/tools/task-contract.ts
-import { randomUUID as randomUUID12 } from "node:crypto";
+import { randomUUID as randomUUID13 } from "node:crypto";
 import { z as z15 } from "zod";
 
 // src/agent/task-contract.ts
-import { randomUUID as randomUUID11 } from "node:crypto";
+import { randomUUID as randomUUID12 } from "node:crypto";
 var EXECUTABLE_INTENTS = /* @__PURE__ */ new Set(["debug", "refactor", "test", "implement"]);
 function shouldUseTaskContract(request, intent, existing) {
   if (existing && existing.state !== "satisfied") return true;
@@ -8961,7 +9185,7 @@ function refreshTaskContractState(contract) {
 }
 function criterion(id, description) {
   return {
-    id: `${id}-${randomUUID11().slice(0, 8)}`,
+    id: `${id}-${randomUUID12().slice(0, 8)}`,
     description,
     required: true,
     status: "pending",
@@ -9515,7 +9739,7 @@ var taskContractTool = {
       }
       const now = (/* @__PURE__ */ new Date()).toISOString();
       const criteria = input2.acceptance_criteria.map((item) => ({
-        id: item.id ?? `criterion-${randomUUID12().slice(0, 8)}`,
+        id: item.id ?? `criterion-${randomUUID13().slice(0, 8)}`,
         description: item.description,
         required: item.required ?? true,
         status: "pending",
@@ -9983,6 +10207,118 @@ function escapeAttribute3(value) {
   })[character] ?? character);
 }
 
+// src/agent/intent-sufficiency.ts
+import { randomUUID as randomUUID14 } from "node:crypto";
+function assessIntentSufficiency(request, intent, context) {
+  const assessedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const uiChoice = explicitUiChoice(request);
+  if (uiChoice) {
+    const pending = clarification(
+      request,
+      assessedAt,
+      "explicit_user_choice_missing",
+      isChinese(request) ? "\u8FD9\u4E2A\u754C\u9762\u884C\u4E3A\u9700\u8981\u4F60\u7684\u4EA7\u54C1\u504F\u597D\uFF0C\u5E94\u91C7\u7528\u54EA\u4E00\u79CD\uFF1F" : "This UI behavior depends on your product preference. Which should be used?",
+      uiChoice
+    );
+    return {
+      assessment: assessment("needs_input", "explicit_user_choice_missing", assessedAt, context.retrievalHits),
+      pending,
+      directive: "Pause before mutation and ask the single recorded clarification question."
+    };
+  }
+  if (publicApiCompatibilityMissing(request)) {
+    const chinese = isChinese(request);
+    const pending = clarification(
+      request,
+      assessedAt,
+      "public_api_compatibility_missing",
+      chinese ? "\u516C\u5171 API \u7684\u517C\u5BB9\u7B56\u7565\u5C1A\u672A\u6307\u5B9A\uFF0C\u5E94\u8BE5\u91C7\u7528\u54EA\u4E00\u79CD\uFF1F" : "The public API compatibility policy is unspecified. Which policy should be used?",
+      chinese ? [
+        option("backward_compatible", "\u4FDD\u6301\u5411\u540E\u517C\u5BB9", "\u4FDD\u7559\u65E7\u63A5\u53E3\u5E76\u63D0\u4F9B\u5F03\u7528\u6216\u8FC1\u79FB\u8DEF\u5F84\uFF1B\u6539\u52A8\u66F4\u7A33\u59A5\u4F46\u5B9E\u73B0\u8303\u56F4\u8F83\u5927\u3002", true),
+        option("breaking_change", "\u5141\u8BB8\u7834\u574F\u6027\u53D8\u66F4", "\u76F4\u63A5\u91C7\u7528\u65B0\u63A5\u53E3\uFF1B\u8303\u56F4\u66F4\u5C0F\uFF0C\u4F46\u8C03\u7528\u65B9\u5FC5\u987B\u540C\u6B65\u8FC1\u79FB\u3002", false)
+      ] : [
+        option("backward_compatible", "Preserve compatibility", "Keep the old API with a deprecation or migration path; safer but broader.", true),
+        option("breaking_change", "Allow breaking change", "Adopt the new API directly; smaller change but callers must migrate.", false)
+      ]
+    );
+    return {
+      assessment: assessment("needs_input", "public_api_compatibility_missing", assessedAt, context.retrievalHits),
+      pending,
+      directive: "Pause before mutation and ask the single recorded clarification question."
+    };
+  }
+  if (requiresRuntimePermission(request)) {
+    return {
+      assessment: assessment("permission_required", "runtime_permission_separate", assessedAt, context.retrievalHits),
+      directive: "The objective is sufficiently clear. Continue, but keep runtime permission approval separate from clarification."
+    };
+  }
+  if (context.complex && shouldInspectWorkspace(request, intent)) {
+    return {
+      assessment: assessment("inspect_then_execute", "workspace_inference_available", assessedAt, context.retrievalHits),
+      directive: "Do not ask the user for repository facts. Inspect the workspace and current evidence before the first mutation."
+    };
+  }
+  return {
+    assessment: assessment("direct_execute", "simple_explicit_request", assessedAt, context.retrievalHits),
+    directive: "The request is sufficiently clear. Execute without an extra clarification turn."
+  };
+}
+function resolvePendingInput(pending, answer) {
+  const normalized = answer.trim();
+  const byIndex = /^([1-3])(?:[.)、:]|$)/u.exec(normalized)?.[1];
+  const selected = pending.options.find((candidate) => candidate.id.toLocaleLowerCase() === normalized.toLocaleLowerCase() || candidate.label.toLocaleLowerCase() === normalized.toLocaleLowerCase()) ?? (byIndex ? pending.options[Number(byIndex) - 1] : void 0);
+  const decision = selected ? `${selected.label}: ${selected.impact}` : compact2(normalized, 2e3);
+  return { answer: compact2(normalized, 2e3), decision };
+}
+function assessment(route, reason, assessedAt, retrievalHits) {
+  return { version: 1, route, reasons: [reason], assessedAt, retrievalHits };
+}
+function clarification(originalRequest, createdAt, reason, question2, options) {
+  return {
+    id: randomUUID14(),
+    runId: randomUUID14(),
+    createdAt,
+    originalRequest: originalRequest.slice(0, 12e4),
+    question: question2,
+    options,
+    reason
+  };
+}
+function explicitUiChoice(value) {
+  const terms = "modal|dialog|drawer|popover|inline|new page|side panel|\u5F39\u7A97|\u6A21\u6001\u6846|\u62BD\u5C49|\u6D6E\u5C42|\u5185\u8054|\u9875\u9762\u5185|\u4FA7\u8FB9\u680F|\u65B0\u9875\u9762";
+  const match = value.match(new RegExp(`\\b(${terms})\\b\\s*(?:or|versus|vs\\.?)\\s*\\b(${terms})\\b`, "iu")) ?? value.match(new RegExp(`(${terms})[\uFF0C\u3001\\s]*(?:\u8FD8\u662F|\u6216\u8005|\u6216)[\uFF0C\u3001\\s]*(${terms})`, "iu"));
+  if (!match?.[1] || !match[2] || match[1].toLocaleLowerCase() === match[2].toLocaleLowerCase()) return;
+  const chinese = isChinese(value);
+  return [
+    option("choice_1", compact2(match[1], 80), chinese ? "\u91C7\u7528\u8BF7\u6C42\u4E2D\u5217\u51FA\u7684\u7B2C\u4E00\u79CD\u4EA4\u4E92\u65B9\u5F0F\u3002" : "Use the first interaction named in the request.", true),
+    option("choice_2", compact2(match[2], 80), chinese ? "\u91C7\u7528\u8BF7\u6C42\u4E2D\u5217\u51FA\u7684\u7B2C\u4E8C\u79CD\u4EA4\u4E92\u65B9\u5F0F\u3002" : "Use the second interaction named in the request.", false)
+  ];
+}
+function publicApiCompatibilityMissing(value) {
+  const api = /\b(?:public|external|exported)\s+(?:api|interface|contract)\b|公共\s*(?:api|接口)|公开\s*(?:api|接口)|对外接口/iu;
+  const change = /\b(?:change|replace|remove|rename|migrate|redesign|refactor)\b|修改|替换|删除|移除|重命名|迁移|重构/iu;
+  const policy = /\b(?:backward compatible|backwards compatible|breaking change|semver major|deprecat|compatibility shim|migration path)\b|向后兼容|保持兼容|允许破坏|破坏性变更|主版本|弃用|迁移路径/iu;
+  return api.test(value) && change.test(value) && !policy.test(value);
+}
+function requiresRuntimePermission(value) {
+  return /\b(?:push|publish|deploy|release|delete|drop|reset|force[- ]push|send|upload)\b|推送|发布|部署|删除|清空|重置|发送|上传/iu.test(value);
+}
+function shouldInspectWorkspace(value, intent) {
+  if (intent === "debug" || intent === "refactor" || intent === "review") return true;
+  const hasConcreteTarget = /(?:^|\s)(?:[\w.-]+\/)+[\w.-]+|`[^`]+`|\b[A-Za-z_$][\w$]*(?:\(\))?\b/u.test(value);
+  return !hasConcreteTarget || /\b(?:existing|current|relevant|appropriate|best)\b|现有|当前|相关|合适|最适合|这个|那个/iu.test(value);
+}
+function option(id, label, impact, recommended) {
+  return { id, label, impact, recommended };
+}
+function isChinese(value) {
+  return /[\u3400-\u9fff]/u.test(value);
+}
+function compact2(value, limit) {
+  return value.trim().replace(/\s+/gu, " ").slice(0, limit);
+}
+
 // src/agent/tool-recovery.ts
 import { createHash as createHash13 } from "node:crypto";
 var RETRY_BUDGET = {
@@ -9997,6 +10333,7 @@ var RETRY_BUDGET = {
   no_progress: 0,
   contract_required: 2
 };
+var FAILURE_CLASSES = Object.keys(RETRY_BUDGET);
 var REPAIR_HINT = {
   schema_input: "Correct the arguments to match the tool schema.",
   unknown_tool: "Choose a tool exposed for this turn.",
@@ -10098,6 +10435,9 @@ function classifyToolFailure(result, fallback = "execution") {
 function formatFailureReceipt(receipt) {
   return `Failure: ${receipt.class}; attempt ${receipt.attempt}; ${receipt.remaining} retries remain; circuit ${receipt.circuitOpen ? "open" : "closed"}. Repair: ${receipt.repairHint}`;
 }
+function resolvableFailureSignatures(call) {
+  return FAILURE_CLASSES.map((failureClass) => failureSignature(call, failureClass));
+}
 function isRetryable(failureClass) {
   return RETRY_BUDGET[failureClass] > 0;
 }
@@ -10915,16 +11255,35 @@ var AgentRunner = class {
   }
   async run(input2, options = {}) {
     if (this.running) throw new Error("This AgentRunner is already processing a turn.");
-    const request = input2.trim();
-    if (!request) throw new Error("User input cannot be empty.");
-    if (request.length > 12e4) {
+    const submittedRequest = input2.trim();
+    if (!submittedRequest) throw new Error("User input cannot be empty.");
+    if (submittedRequest.length > 12e4) {
       throw new Error("User input is too large; pass a focused request or attach files with @path.");
     }
+    let request = submittedRequest;
     this.running = true;
     this.contextEngine.resetDiagnostics?.();
     const emit = async (event) => {
       await options.onEvent?.(event);
     };
+    const pendingAtStart = this.session.pendingInput;
+    const resolvedInput = pendingAtStart ? resolvePendingInput(pendingAtStart, submittedRequest) : void 0;
+    if (pendingAtStart && resolvedInput) {
+      request = `${pendingAtStart.originalRequest}
+
+<user-clarification-decision source="explicit-user-input">
+${resolvedInput.decision}
+</user-clarification-decision>`;
+      delete this.session.pendingInput;
+      const constraint = `User clarification (${pendingAtStart.id}): ${resolvedInput.decision}`;
+      if (this.session.taskContract && !this.session.taskContract.constraints.includes(constraint)) {
+        this.session.taskContract.constraints.push(constraint);
+        if (this.session.taskContract.constraints.length > 64) {
+          this.session.taskContract.constraints.splice(0, this.session.taskContract.constraints.length - 64);
+        }
+        this.session.taskContract.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+      }
+    }
     const changeSequenceAtStart = this.changeSequence;
     const runStartedAt = (/* @__PURE__ */ new Date()).toISOString();
     const loadedProgressiveTools = /* @__PURE__ */ new Set();
@@ -10992,11 +11351,12 @@ var AgentRunner = class {
     try {
       throwIfAborted(options.signal);
       await this.reconcileToolArtifacts();
+      ensureContextEpoch(this.session);
       if (this.session.messages.length === 0 && this.session.title === "New session") {
         this.session.title = titleFromInput(request);
       }
       this.contextManager.startTurn(this.session, request);
-      const userMessage = message("user", request);
+      const userMessage = message("user", submittedRequest);
       this.activeReuseGate = { requestId: userMessage.id, request, attempted: false };
       this.session.messages.push(userMessage);
       await this.persist();
@@ -11004,11 +11364,48 @@ var AgentRunner = class {
       const turnDirective = buildTurnDirective(request, {
         agents: Boolean(this.config.agents?.enabled)
       });
+      const contractEnabled = shouldUseTaskContract(
+        request,
+        turnDirective.intent,
+        this.session.taskContract
+      );
       const packed = trivialTurn ? emptyPackedContext(selectContextBudget(request, this.config, {
         intent: turnDirective.intent,
         trivial: true
       })) : await this.packContext(request, { intent: turnDirective.intent });
       if (!trivialTurn) await emit({ type: "context", packed });
+      if (contractEnabled && (!this.session.taskContract || this.session.taskContract.state === "satisfied")) {
+        this.session.taskContract = createDraftTaskContract(request, this.session.audit?.at(-1)?.id);
+        await this.persist();
+        await emit({ type: "contract", contract: structuredClone(this.session.taskContract) });
+      }
+      let intentDirective;
+      if (pendingAtStart && resolvedInput) {
+        this.session.intentAssessment = {
+          version: 1,
+          route: "direct_execute",
+          reasons: ["clarification_resolved"],
+          assessedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          retrievalHits: packed.hits.length
+        };
+        intentDirective = "The user resolved the recorded clarification. Continue the same logical run and apply that decision without asking again.";
+        await emit({ type: "input_resolved", pendingId: pendingAtStart.id, runId: pendingAtStart.runId, answer: resolvedInput.answer });
+        await emit({ type: "intent", assessment: this.session.intentAssessment });
+      } else {
+        const intent = assessIntentSufficiency(request, turnDirective.intent, {
+          retrievalHits: packed.hits.length,
+          complex: contractEnabled
+        });
+        this.session.intentAssessment = intent.assessment;
+        intentDirective = intent.directive;
+        await emit({ type: "intent", assessment: intent.assessment });
+        if (intent.pending) {
+          this.session.pendingInput = intent.pending;
+          await this.persist();
+          await emit({ type: "needs_input", pending: intent.pending });
+          return finishRun("needs_input");
+        }
+      }
       const mentions = await this.packMentions(request);
       const retrievedContext = trivialTurn && !mentions.length ? "" : buildRetrievedContext(
         packed,
@@ -11036,19 +11433,10 @@ var AgentRunner = class {
           scope: augmentation.memoryScope ?? "session"
         });
       }
-      const contractEnabled = shouldUseTaskContract(
-        request,
-        turnDirective.intent,
-        this.session.taskContract
-      );
-      if (contractEnabled && (!this.session.taskContract || this.session.taskContract.state === "satisfied")) {
-        this.session.taskContract = createDraftTaskContract(request, this.session.audit?.at(-1)?.id);
-        await this.persist();
-        await emit({ type: "contract", contract: structuredClone(this.session.taskContract) });
-      }
       activeRunContract = contractEnabled ? this.session.taskContract : void 0;
       let verificationAttempted = false;
       const maxTurns = options.maxTurns ?? this.config.agent.maxTurns;
+      const epochTokenBudget = this.config.agent.maxEpochTokens ?? this.config.agent.maxSessionTokens;
       const contextBudget = Math.max(24e3, Math.min(1e5, this.config.context.maxTokens * 3));
       if (this.contextManager.shouldCompact(this.session, contextBudget)) {
         const compacted = await this.compactContext(void 0, options.signal, "automatic");
@@ -11074,11 +11462,15 @@ var AgentRunner = class {
         if (this.session.usage.inputTokens + this.session.usage.outputTokens >= this.config.agent.maxSessionTokens) {
           return finishRun("token_budget");
         }
+        if (contextEpochTokens(this.session) >= epochTokenBudget) {
+          await this.rollContextEpoch("token_budget", options.signal, emit);
+        }
         this.applySteering();
         await emit({ type: "thinking", turn });
         const dynamicPrompt = [
           buildSessionStatePrompt(this.session),
           turnDirective.text,
+          `<intent-sufficiency route="${this.session.intentAssessment?.route ?? "direct_execute"}">${intentDirective}</intent-sufficiency>`,
           this.contextManager.buildShortTermPrompt(this.session),
           pinnedContext,
           options.turnInstructions ?? "",
@@ -11091,7 +11483,9 @@ var AgentRunner = class {
           activeMessages(this.session),
           contextBudget
         );
-        const availableTokens = this.config.agent.maxSessionTokens - (this.session.usage.inputTokens + this.session.usage.outputTokens);
+        const availableLifetimeTokens = this.config.agent.maxSessionTokens - (this.session.usage.inputTokens + this.session.usage.outputTokens);
+        const availableEpochTokens = epochTokenBudget - contextEpochTokens(this.session);
+        const availableTokens = Math.min(availableLifetimeTokens, availableEpochTokens);
         const visibleTools = visibleToolDefinitions(
           this.tools,
           options.askMode === true,
@@ -11105,9 +11499,15 @@ var AgentRunner = class {
           loadedProgressiveTools
         );
         const estimatedInputTokens = estimateMessages2(messages) + estimateToolDefinitions(visibleTools);
-        if (availableTokens <= 0 || estimatedInputTokens >= availableTokens) {
+        if (estimatedInputTokens >= availableLifetimeTokens) {
           return finishRun("token_budget");
         }
+        if (availableTokens <= 0 || estimatedInputTokens >= availableEpochTokens) {
+          if (contextEpochTokens(this.session) === 0) return finishRun("token_budget");
+          await this.rollContextEpoch("token_budget", options.signal, emit);
+          turn -= 1;
+          continue;
+        }
         const maxOutputTokens = Math.max(1, Math.min(
           this.config.model.maxTokens ?? 8192,
           availableTokens - estimatedInputTokens
@@ -11129,7 +11529,7 @@ var AgentRunner = class {
             breakdown
           });
         }
-        const assistantId = randomUUID13();
+        const assistantId = randomUUID15();
         const response = await this.completeModel(
           messages,
           visibleTools,
@@ -11509,6 +11909,9 @@ ${completeContent}`;
         metadata.failure = receipt;
       } else {
         recovery.recordSuccess(call);
+        const historicalFailures = new Set((this.session.audit ?? []).filter((event) => event.type === "tool" && event.outcome === "failure").map((event) => failureSignatureFromMetadata(event.metadata?.failure)).filter((signature) => signature !== void 0));
+        const resolvedFailureSignatures = resolvableFailureSignatures(call).filter((signature) => historicalFailures.has(signature));
+        if (resolvedFailureSignatures.length) metadata.resolvedFailureSignatures = resolvedFailureSignatures;
       }
       const evidenceProgress = recovery.recordEvidence(call, {
         toolCallId: call.id,
@@ -11578,13 +11981,13 @@ ${completeContent}`;
       this.recordPermission(call, category, "allow", "Approved for this session.");
       return true;
     }
-    await emit({ type: "permission", call, category });
+    await emit({ type: "permission", call, category, reason: decision.reason });
     if (!options.requestPermission) {
       this.recordPermission(call, category, "deny", "No permission handler was available.");
       return false;
     }
     try {
-      const grant = await options.requestPermission(call, category);
+      const grant = await options.requestPermission(call, category, decision.reason);
       const allowed = grant === true || grant === "session";
       if (grant === "session") this.sessionApprovals.add(approvalKey);
       this.recordPermission(
@@ -11599,13 +12002,13 @@ ${completeContent}`;
       return false;
     }
   }
-  recordPermission(call, category, outcome, reason) {
+  recordPermission(call, category, outcome2, reason) {
     this.appendAudit({
       type: "permission",
       toolCallId: call.id,
       tool: call.name,
       category,
-      outcome,
+      outcome: outcome2,
       reason
     });
   }
@@ -11622,7 +12025,7 @@ ${completeContent}`;
   }
   appendAudit(event) {
     const audit = this.session.audit ?? (this.session.audit = []);
-    audit.push({ id: randomUUID13(), createdAt: (/* @__PURE__ */ new Date()).toISOString(), ...event });
+    audit.push({ id: randomUUID15(), createdAt: (/* @__PURE__ */ new Date()).toISOString(), ...event });
     if (audit.length > 5e3) audit.splice(0, audit.length - 5e3);
   }
   async acceptChangedFiles(paths) {
@@ -11643,7 +12046,7 @@ ${completeContent}`;
     const results = [];
     for (const command2 of this.config.agent.verifyCommands) {
       const call = {
-        id: `verify-${randomUUID13()}`,
+        id: `verify-${randomUUID15()}`,
         name: "shell",
         arguments: { command: command2, cwd: this.workspace.primaryRoot }
       };
@@ -11691,6 +12094,30 @@ ${completeContent}`;
     await this.persist();
     return result;
   }
+  async rollContextEpoch(reason, signal, emit) {
+    let receipt;
+    const contextBudget = Math.max(24e3, Math.min(1e5, this.config.context.maxTokens * 3));
+    if (this.contextManager.shouldCompact(this.session, contextBudget)) {
+      const compacted = await this.compactContext(
+        "Create a boundary handoff for the next bounded context epoch.",
+        signal,
+        "automatic"
+      );
+      receipt = compacted.receipt;
+      if (compacted.status === "compacted") await emit({ type: "context_compacted", ...compacted });
+    }
+    const rotated = rotateContextEpoch(this.session, reason, receipt);
+    await this.persist();
+    await emit({
+      type: "context_epoch",
+      index: rotated.current.index,
+      previousIndex: rotated.previous.index,
+      reason,
+      inputTokens: rotated.previous.usage.inputTokens,
+      outputTokens: rotated.previous.usage.outputTokens,
+      handoff: rotated.handoff
+    });
+  }
   getContextStatus() {
     return this.contextManager.status(this.session);
   }
@@ -11722,8 +12149,14 @@ ${completeContent}`;
   toolOutputBudget() {
     const contextWindowTokens = Math.max(24e3, Math.min(1e5, this.config.context.maxTokens * 3));
     const activeContextTokens = this.contextManager.status(this.session, contextWindowTokens).activeTokens;
-    const remainingSessionTokens = this.config.agent.maxSessionTokens - (this.session.usage.inputTokens + this.session.usage.outputTokens);
-    return dynamicToolOutputBudget(contextWindowTokens, activeContextTokens, remainingSessionTokens);
+    const remainingLifetimeTokens = this.config.agent.maxSessionTokens - (this.session.usage.inputTokens + this.session.usage.outputTokens);
+    const epochBudget = this.config.agent.maxEpochTokens ?? this.config.agent.maxSessionTokens;
+    const remainingEpochTokens = epochBudget - contextEpochTokens(this.session);
+    return dynamicToolOutputBudget(
+      contextWindowTokens,
+      activeContextTokens,
+      Math.min(remainingLifetimeTokens, remainingEpochTokens)
+    );
   }
   async protectToolResult(result) {
     const metadata = { ...result.metadata ?? {} };
@@ -11779,7 +12212,7 @@ ${completeContent}`;
 };
 function message(role, content, extra = {}) {
   return {
-    id: randomUUID13(),
+    id: randomUUID15(),
     role,
     content,
     createdAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -11894,6 +12327,7 @@ function recordTokenUsage(session, providerUsage, estimatedInputTokens, estimate
   const outputTokens = outputActual ?? estimatedOutputTokens;
   session.usage.inputTokens += inputTokens;
   session.usage.outputTokens += outputTokens;
+  recordContextEpochUsage(session, inputTokens, outputTokens);
   if (inputActual !== void 0) {
     session.usage.actualInputTokens = (session.usage.actualInputTokens ?? 0) + inputActual;
   } else {
@@ -11969,6 +12403,11 @@ ${content}` : content,
     ...failure ? { metadata: { failure } } : {}
   };
 }
+function failureSignatureFromMetadata(value) {
+  if (!value || typeof value !== "object") return;
+  const signature = value.signature;
+  return typeof signature === "string" && signature ? signature : void 0;
+}
 function visibleToolDefinitions(tools, askMode, contractEnabled, artifactReadAvailable, duplicationAvailable, request, loadedProgressiveTools) {
   const eligible = tools.definitions().filter(
     (tool) => (!askMode || tool.category === "read") && (contractEnabled || tool.name !== "task_contract") && (artifactReadAvailable || tool.name !== "read_tool_artifact") && (duplicationAvailable || tool.name !== "duplication_audit")
@@ -12176,7 +12615,7 @@ function integer(value, fallback, min, max) {
 }
 
 // src/agent/delegation.ts
-import { randomUUID as randomUUID15 } from "node:crypto";
+import { randomUUID as randomUUID17 } from "node:crypto";
 import { join as join18 } from "node:path";
 import { z as z19 } from "zod";
 
@@ -12305,7 +12744,7 @@ function numeric(...values) {
 }
 
 // src/agent/team-store.ts
-import { createHash as createHash16, randomUUID as randomUUID14 } from "node:crypto";
+import { createHash as createHash16, randomUUID as randomUUID16 } from "node:crypto";
 import { lstat as lstat18, readFile as readFile17, readdir as readdir7, rm as rm3 } from "node:fs/promises";
 import { join as join16, resolve as resolve18 } from "node:path";
 import { z as z18 } from "zod";
@@ -12399,7 +12838,7 @@ var TeamRunStore = class {
     const now = (/* @__PURE__ */ new Date()).toISOString();
     const manifest = manifestSchema2.parse({
       version: 2,
-      id: randomUUID14(),
+      id: randomUUID16(),
       workspace: this.workspace,
       objective: input2.objective,
       reviewer: input2.reviewer,
@@ -13205,7 +13644,7 @@ var DelegationManager = class {
         maxReviewRounds: 0
       });
       await emit?.({ type: "team_start", id: board.id, objective: task });
-      const writerId = randomUUID15();
+      const writerId = randomUUID17();
       await emit?.({ type: "agent_queued", id: writerId, profile: profile.name, task, phase: "write" });
       const draft = await this.writerLane.createDraft(
         Math.min(this.team.maxWriterPatchBytes ?? 6e4, 12e4),
@@ -13216,18 +13655,18 @@ var DelegationManager = class {
       await this.recordAgent(board.id, writer, "write");
       const writerFailed = !writer.ok || !draft.patch || !draft.worktreeCleaned || signal?.aborted;
       if (writerFailed) {
-        const outcome = writer.termination === "cancelled" || signal?.aborted ? "cancelled" : "failed";
+        const outcome2 = writer.termination === "cancelled" || signal?.aborted ? "cancelled" : "failed";
         await this.teamStore.recordWriterLane(board.id, {
           profile: profile.name,
           reviewer: reviewer.name,
           baseCommit: draft.baseCommit,
-          outcome,
+          outcome: outcome2,
           patch: draft.patch,
           files: draft.files,
           worktreeCleaned: draft.worktreeCleaned
         });
         await this.teamStore.complete(board.id, { accepted: false, reviewRounds: 0, failed: true });
-        const status2 = outcome === "cancelled" ? "cancelled" : "failed";
+        const status2 = outcome2 === "cancelled" ? "cancelled" : "failed";
         const detail2 = !draft.worktreeCleaned ? "Writer worktree cleanup could not be verified; integration is blocked." : !draft.patch ? "Writer returned no patch." : writer.summary;
         await emit?.({ type: "writer_lane", id: board.id, status: status2, detail: detail2, files: draft.files });
         await emit?.({ type: "team_done", id: board.id, accepted: false, reviewRounds: 0 });
@@ -13575,7 +14014,7 @@ You are the only writer inside a disposable worktree. Make only the bounded requ
     const reviewer = reviewerOverride ?? this.team.reviewerProfile ?? "reviewer";
     const rounds = Math.max(0, this.team.maxReviewRounds ?? 1);
     const board = await this.teamStore?.create({ objective, reviewer, maxReviewRounds: rounds });
-    const runId = board?.id ?? randomUUID15();
+    const runId = board?.id ?? randomUUID17();
     await emit?.({ type: "team_start", id: runId, objective });
     try {
       let results = await this.runBatch(board?.id, tasks, "work", emit, signal);
@@ -13633,7 +14072,7 @@ ${review.summary}`,
     }
   }
   async runBatch(runId, tasks, phase, emit, signal) {
-    const scheduled = tasks.map((task) => ({ id: randomUUID15(), task }));
+    const scheduled = tasks.map((task) => ({ id: randomUUID17(), task }));
     for (const item of scheduled) {
       await emit?.({ type: "agent_queued", id: item.id, profile: item.task.profile, task: item.task.task, phase });
     }
@@ -13742,12 +14181,12 @@ Start the response with exactly VERDICT: ACCEPT when the evidence is sufficient,
     });
   }
   async peerMessage(runId, from, to, content, emit) {
-    const id = randomUUID15();
+    const id = randomUUID17();
     if (runId) await this.teamStore?.recordMessage(runId, { id, from, to, content });
     await emit?.({ type: "agent_message", id, from, to, content });
   }
   async runOne(task, phase, emit, signal, retryOf, scheduledId) {
-    const id = scheduledId ?? randomUUID15();
+    const id = scheduledId ?? randomUUID17();
     const profile = this.options.profiles.get(task.profile);
     const configuredRoute = this.team.routes?.[task.profile];
     const budgetMode = configuredRoute?.budgetMode ?? this.team.budgetMode ?? "observe";
@@ -14576,6 +15015,61 @@ function keyEnvironmentName(provider) {
 // src/cli/output.ts
 import { createInterface } from "node:readline/promises";
 import chalk2, { Chalk } from "chalk";
+
+// src/cli/headless-contract.ts
+var HEADLESS_SCHEMA_VERSION = 1;
+var HEADLESS_EXIT_CODES = {
+  completed: 0,
+  error: 1,
+  needsInput: 2,
+  unverified: 3,
+  verificationFailed: 4,
+  blocked: 5,
+  cancelled: 6,
+  maxTurns: 7,
+  tokenBudget: 8
+};
+function resolveHeadlessOutcome(input2) {
+  if (input2.error !== void 0 || input2.reason === "error") {
+    return outcome("error", HEADLESS_EXIT_CODES.error, input2.reason ?? "error");
+  }
+  if (input2.reason === "needs_input") {
+    return outcome("needs_input", HEADLESS_EXIT_CODES.needsInput, input2.reason);
+  }
+  if (input2.reason === "blocked" || input2.completion?.acceptance?.state === "blocked") {
+    return outcome("blocked", HEADLESS_EXIT_CODES.blocked, input2.reason ?? "blocked");
+  }
+  if (input2.reason === "aborted" || input2.reason === "cancelled") {
+    return outcome("cancelled", HEADLESS_EXIT_CODES.cancelled, input2.reason);
+  }
+  if (input2.reason === "max_turns") {
+    return outcome("max_turns", HEADLESS_EXIT_CODES.maxTurns, input2.reason);
+  }
+  if (input2.reason === "token_budget") {
+    return outcome("token_budget", HEADLESS_EXIT_CODES.tokenBudget, input2.reason);
+  }
+  if (input2.reason === "verification_failed" || input2.completion?.status === "verification_failed") {
+    return outcome("verification_failed", HEADLESS_EXIT_CODES.verificationFailed, input2.reason ?? "verification_failed");
+  }
+  if (input2.reason === "unverified" || input2.completion?.status === "unverified") {
+    return outcome("unverified", HEADLESS_EXIT_CODES.unverified, input2.reason ?? "unverified");
+  }
+  if (input2.completion?.status === "verified") {
+    return outcome("verified", HEADLESS_EXIT_CODES.completed, input2.reason ?? "completed");
+  }
+  return outcome("completed", HEADLESS_EXIT_CODES.completed, input2.reason ?? "completed");
+}
+function outcome(status, exitCode, reason) {
+  return {
+    schemaVersion: HEADLESS_SCHEMA_VERSION,
+    ok: exitCode === HEADLESS_EXIT_CODES.completed,
+    status,
+    exitCode,
+    reason
+  };
+}
+
+// src/cli/output.ts
 var HeadlessReporter = class {
   constructor(options) {
     this.options = options;
@@ -14585,7 +15079,6 @@ var HeadlessReporter = class {
   options;
   finalResponse = "";
   tools = [];
-  eventError;
   context;
   streamedAssistant = false;
   completion;
@@ -14595,7 +15088,6 @@ var HeadlessReporter = class {
   onEvent = (event) => {
     if (event.type === "assistant") this.finalResponse = event.content;
     if (event.type === "tool_result") this.tools.push(event.result);
-    if (event.type === "error") this.eventError = event.error.message;
     if (event.type === "done") {
       this.doneReason = event.reason;
       this.completion = event.completion;
@@ -14613,26 +15105,33 @@ var HeadlessReporter = class {
     this.printText(event);
   };
   finish(session) {
+    const completion = this.completion ?? session.lastRun;
+    const reason = this.doneReason ?? session.lastRun?.reason;
+    const outcome2 = resolveHeadlessOutcome({
+      ...reason ? { reason } : {},
+      ...completion ? { completion } : {}
+    });
     if (this.options.format === "stream-json") {
       process.stdout.write(`${JSON.stringify({
         type: "session",
+        ...outcome2,
         session: sessionSummary(session)
       })}
 `);
-      return;
+      return outcome2;
     }
     if (this.options.format === "json") {
       process.stdout.write(`${JSON.stringify({
-        ok: this.doneReason === void 0 || this.doneReason === "completed" && this.completion?.status !== "verification_failed",
+        type: "result",
+        ...outcome2,
         response: this.finalResponse,
         session: sessionSummary(session),
-        ...this.doneReason ? { reason: this.doneReason } : {},
-        ...this.completion ? { completion: this.completion } : {},
+        ...completion ? { completion } : {},
         ...this.context ? { context: this.context } : {},
         tools: this.tools
       }, null, 2)}
 `);
-      return;
+      return outcome2;
     }
     if (this.options.quiet && this.finalResponse.trim()) {
       process.stdout.write(`${this.finalResponse.trim()}
@@ -14647,24 +15146,41 @@ ${this.glyphs.meta} ${session.changedFiles.length} changed files ${this.glyphs.s
 `
       ));
     }
+    return outcome2;
   }
-  fail(error) {
+  fail(error, session) {
     const message2 = error instanceof Error ? error.message : String(error);
-    if (this.options.format === "stream-json" && this.eventError === message2) return;
-    if (this.options.format === "json" || this.options.format === "stream-json") {
-      process.stdout.write(`${JSON.stringify({ type: "error", ok: false, error: message2 })}
+    const outcome2 = resolveHeadlessOutcome({ reason: "error", error });
+    if (this.options.format === "stream-json") {
+      process.stdout.write(`${JSON.stringify({
+        type: "final",
+        ...outcome2,
+        error: message2,
+        ...session ? { session: sessionSummary(session) } : {}
+      })}
 `);
-      return;
+      return outcome2;
+    }
+    if (this.options.format === "json") {
+      process.stdout.write(`${JSON.stringify({
+        type: "result",
+        ...outcome2,
+        error: message2,
+        ...session ? { session: sessionSummary(session) } : {}
+      }, null, 2)}
+`);
+      return outcome2;
     }
     process.stderr.write(`${this.paint.red(this.glyphs.error)} ${message2}
 `);
+    return outcome2;
   }
   printText(event) {
-    const { quiet, compact: compact2 } = this.options;
-    if (quiet) return;
+    const { quiet, compact: compact3 } = this.options;
+    if (quiet && event.type !== "needs_input") return;
     switch (event.type) {
       case "thinking":
-        if (!compact2) process.stderr.write(this.paint.dim(`${this.glyphs.meta} reasoning ${this.glyphs.separator} turn ${event.turn}
+        if (!compact3) process.stderr.write(this.paint.dim(`${this.glyphs.meta} reasoning ${this.glyphs.separator} turn ${event.turn}
 `));
         break;
       case "context": {
@@ -14676,7 +15192,7 @@ ${this.glyphs.meta} ${session.changedFiles.length} changed files ${this.glyphs.s
         break;
       }
       case "prompt":
-        if (!compact2) {
+        if (!compact3) {
           const partition = event.breakdown ? ` ${this.glyphs.separator} stable ${event.breakdown.stableTokens} ${this.glyphs.separator} dynamic ${event.breakdown.dynamicTokens} ${this.glyphs.separator} history ${event.breakdown.conversationTokens} ${this.glyphs.separator} tool results ${event.breakdown.toolResultTokens} ${this.glyphs.separator} retrieved ${event.breakdown.retrievedTokens} ${this.glyphs.separator} tools ${event.breakdown.toolSchemaTokens} ${this.glyphs.separator} output cap ${event.breakdown.outputAllowanceTokens}` : "";
           process.stderr.write(this.paint.dim(
             `${this.glyphs.meta} prompt ${this.glyphs.separator} ${event.intent} ${this.glyphs.separator} ~${event.estimatedTokens} estimated tokens${partition}
@@ -14712,7 +15228,7 @@ ${this.glyphs.meta} ${session.changedFiles.length} changed files ${this.glyphs.s
         }
         break;
       case "tasks":
-        if (!compact2) {
+        if (!compact3) {
           const completed = event.tasks.filter((task) => task.status === "completed").length;
           process.stderr.write(this.paint.dim(`${this.glyphs.meta} plan ${this.glyphs.separator} ${completed}/${event.tasks.length} complete
 `));
@@ -14733,6 +15249,22 @@ ${this.glyphs.meta} ${session.changedFiles.length} changed files ${this.glyphs.s
 `
         );
         break;
+      case "needs_input":
+        process.stderr.write(this.paint.yellow(`${this.glyphs.meta} ${event.pending.question}
+`));
+        event.pending.options.forEach((option2, index) => {
+          process.stderr.write(this.paint.dim(
+            `  ${index + 1}. ${option2.label}${option2.recommended ? " (recommended)" : ""} ${this.glyphs.separator} ${option2.impact}
+`
+          ));
+        });
+        break;
+      case "input_resolved":
+        process.stderr.write(this.paint.dim(
+          `${this.glyphs.meta} clarification resolved ${this.glyphs.separator} ${event.answer}
+`
+        ));
+        break;
       case "usage":
       case "permission":
       case "skill":
@@ -14743,9 +15275,12 @@ ${this.glyphs.meta} ${session.changedFiles.length} changed files ${this.glyphs.s
       case "agent_done":
       case "workflow":
       case "context_compacted":
+      case "context_epoch":
+      case "intent":
         break;
       case "done":
         this.printCompletion(event.completion);
+        this.printStopReason(event.reason);
         break;
       case "error":
         break;
@@ -14776,8 +15311,20 @@ ${this.glyphs.meta} ${session.changedFiles.length} changed files ${this.glyphs.s
 `
     ));
   }
+  printStopReason(reason) {
+    if (reason === "aborted") {
+      process.stderr.write(this.paint.yellow(`${this.glyphs.warning} cancelled ${this.glyphs.separator} resume with --resume after inspecting the saved session
+`));
+    } else if (reason === "max_turns") {
+      process.stderr.write(this.paint.yellow(`${this.glyphs.warning} turn limit reached ${this.glyphs.separator} resume with --resume and a larger --max-turns value
+`));
+    } else if (reason === "token_budget") {
+      process.stderr.write(this.paint.yellow(`${this.glyphs.warning} token budget reached ${this.glyphs.separator} inspect the saved session before resuming with a larger --token-budget
+`));
+    }
+  }
 };
-async function askConsolePermission(call, category, color = !process.env.NO_COLOR) {
+async function askConsolePermission(call, category, color = !process.env.NO_COLOR, reason = `${category} tools require approval.`) {
   if (!process.stdin.isTTY || !process.stderr.isTTY) return false;
   const paint = color ? chalk2 : new Chalk({ level: 0 });
   const glyphs = resolveCliGlyphs();
@@ -14785,6 +15332,10 @@ async function askConsolePermission(call, category, color = !process.env.NO_COLO
 ${paint.yellow("Permission required")} ${paint.dim(`(${category})`)}
 `);
   process.stderr.write(`${paint.bold(call.name)}${formatToolDetail(call, paint)}
+`);
+  process.stderr.write(`${paint.dim(`Reason: ${reason}`)}
+`);
+  process.stderr.write(`${paint.yellow(`Risk: ${permissionRisk(category)}`)}
 `);
   const readline = createInterface({ input: process.stdin, output: process.stderr });
   try {
@@ -14794,6 +15345,13 @@ ${paint.yellow("Permission required")} ${paint.dim(`(${category})`)}
     readline.close();
   }
 }
+function permissionRisk(category) {
+  if (category === "read") return "workspace content may enter model context";
+  if (category === "write") return "workspace files may be created, replaced, or deleted";
+  if (category === "shell") return "a local process may read or change workspace state";
+  if (category === "git") return "repository state or remotes may change";
+  return "data may leave this machine or remote state may change";
+}
 function eventToJson(event) {
   if (event.type === "error") {
     return { type: event.type, error: event.error.message };
@@ -14815,6 +15373,9 @@ function sessionSummary(session) {
     ...session.lastRun ? { lastRun: session.lastRun } : {},
     ...session.tokenLedger?.length ? { tokenLedger: session.tokenLedger } : {},
     ...session.contextCompactionReceipts?.length ? { contextCompactionReceipts: session.contextCompactionReceipts } : {},
+    ...session.contextEpochs?.length ? { contextEpochs: session.contextEpochs } : {},
+    ...session.intentAssessment ? { intentAssessment: session.intentAssessment } : {},
+    ...session.pendingInput ? { pendingInput: session.pendingInput } : {},
     usage: session.usage
   };
 }
@@ -14896,7 +15457,7 @@ function commandNames(command2) {
 // src/ui/tui.tsx
 import { useCallback, useEffect as useEffect2, useMemo, useRef as useRef2, useState as useState2 } from "react";
 import { Box as Box2, render as render2, Text as Text3, useApp, useInput as useInput2, useWindowSize } from "ink";
-import { relative as relative9 } from "node:path";
+import { relative as relative10 } from "node:path";
 
 // src/ui/components.tsx
 import React2 from "react";
@@ -14920,6 +15481,8 @@ var commandDefinitions = [
   command("permissions", "Inspect the active permission policy"),
   command("changes", "List files changed in the active session"),
   command("diff", "Open the current workspace diff in the transcript"),
+  command("review", "Run a read-only review with a fixed, redacted scope", "/review [working-tree|commit <ref>|branch <base-ref>]"),
+  command("recover", "Open recovery actions for the last incomplete run", "/recover [retry|resume|diff|rollback|audit]"),
   command("checkpoints", "List recoverable pre-mutation snapshots"),
   command("audit", "Review the hash-chained tool and permission timeline"),
   command("rollback", "Restore workspace files from a checkpoint", "/rollback [checkpoint-id]"),
@@ -14976,6 +15539,28 @@ function commandSuggestions(input2, options = {}) {
       description: "Show the secure shared-connection setup command"
     }].filter((item) => item.label.includes(argument.trim().toLocaleLowerCase()));
   }
+  if (firstSpace >= 0 && commandName === "review") {
+    const query = argument.trim().toLocaleLowerCase();
+    return [
+      { value: "/review working-tree", label: "working-tree", description: "Review only the current working tree" },
+      { value: "/review commit ", label: "commit", description: "Review exactly one Git commit" },
+      { value: "/review branch ", label: "branch", description: "Review the current branch against one base ref" }
+    ].filter((item) => item.label.includes(query) || item.value.slice("/review ".length).startsWith(query));
+  }
+  if (firstSpace >= 0 && commandName === "recover") {
+    const query = argument.trim().toLocaleLowerCase();
+    return [
+      { name: "retry", description: "Repair and retry the latest failed operation once" },
+      { name: "resume", description: "Continue the most recent incomplete logical run" },
+      { name: "diff", description: "Inspect the current workspace patch" },
+      { name: "audit", description: "Review permission and tool evidence" },
+      { name: "rollback", description: "Choose a checkpoint to restore" }
+    ].filter((item) => item.name.includes(query)).map((item) => ({
+      value: `/recover ${item.name}`,
+      label: item.name,
+      description: item.description
+    }));
+  }
   if (firstSpace >= 0 && commandName === "memory") {
     const query = argument.trim().toLocaleLowerCase();
     return [
@@ -15507,7 +16092,7 @@ function ToolGlyph({ state, glyphs }) {
   if (state === "cancelled") return /* @__PURE__ */ jsx(Text, { color: theme.warning, children: glyphs.warning });
   return /* @__PURE__ */ jsx(Text, { color: theme.error, children: glyphs.error });
 }
-function Timeline({ items, width = 80, glyphMode = "auto", showToolOutput = false, expandedToolId, compact: compact2 = false }) {
+function Timeline({ items, width = 80, glyphMode = "auto", showToolOutput = false, expandedToolId, compact: compact3 = false }) {
   const theme = useTheme();
   const glyphs = resolveGlyphs(glyphMode);
   if (!items.length) {
@@ -15515,13 +16100,13 @@ function Timeline({ items, width = 80, glyphMode = "auto", showToolOutput = fals
   }
   return /* @__PURE__ */ jsx(Box, { flexDirection: "column", children: items.map((item, index) => {
     if (item.kind === "user") {
-      return /* @__PURE__ */ jsxs(Box, { marginBottom: compact2 || item.clipped ? 0 : 1, children: [
+      return /* @__PURE__ */ jsxs(Box, { marginBottom: compact3 || item.clipped ? 0 : 1, children: [
         /* @__PURE__ */ jsx(Box, { width: 2, children: /* @__PURE__ */ jsx(Text, { bold: true, color: theme.accent, children: glyphs.prompt }) }),
         /* @__PURE__ */ jsx(Text, { bold: true, color: theme.textStrong, wrap: "wrap", children: sanitizeTerminalText(item.text) })
       ] }, item.id);
     }
     if (item.kind === "assistant") {
-      return /* @__PURE__ */ jsxs(Box, { flexDirection: "column", marginBottom: compact2 || item.clipped ? 0 : 1, children: [
+      return /* @__PURE__ */ jsxs(Box, { flexDirection: "column", marginBottom: compact3 || item.clipped ? 0 : 1, children: [
         /* @__PURE__ */ jsxs(Text, { bold: true, color: theme.accent, children: [
           glyphs.brand,
           " ",
@@ -15537,7 +16122,7 @@ function Timeline({ items, width = 80, glyphMode = "auto", showToolOutput = fals
     }
     if (item.kind === "context") {
       const spans = item.spans ?? [];
-      const spanLimit = compact2 ? 2 : 3;
+      const spanLimit = compact3 ? 2 : 3;
       const innerWidth = Math.max(1, safeWidth(width) - 2);
       return /* @__PURE__ */ jsxs(Box, { flexDirection: "column", children: [
         /* @__PURE__ */ jsx(
@@ -15550,7 +16135,7 @@ function Timeline({ items, width = 80, glyphMode = "auto", showToolOutput = fals
             labelColor: theme.accent
           }
         ),
-        !compact2 && item.budgetReason ? /* @__PURE__ */ jsx(Text, { color: theme.dim, children: truncateDisplay(`${glyphs.branchLast} ${sanitizeInlineTerminalText(item.budgetReason)}`, innerWidth) }) : null,
+        !compact3 && item.budgetReason ? /* @__PURE__ */ jsx(Text, { color: theme.dim, children: truncateDisplay(`${glyphs.branchLast} ${sanitizeInlineTerminalText(item.budgetReason)}`, innerWidth) }) : null,
         spans.slice(0, spanLimit).map((span, spanIndex) => {
           const lines = span.startLine === span.endLine ? `${span.startLine}` : `${span.startLine}-${span.endLine}`;
           const location = `${compactDisplayPath(sanitizeInlineTerminalText(span.path), 44)}:${lines}`;
@@ -15590,7 +16175,7 @@ function Timeline({ items, width = 80, glyphMode = "auto", showToolOutput = fals
       const duration = item.durationMs !== void 0 ? formatDuration(item.durationMs) : "";
       const detailText = [detail, duration].filter(Boolean).join("  ");
       const expanded = Boolean(item.output) && (showToolOutput || expandedToolId === item.id);
-      const verbose = expanded && item.output ? limitTerminalText(item.output, compact2 ? 24 : 80) : void 0;
+      const verbose = expanded && item.output ? limitTerminalText(item.output, compact3 ? 24 : 80) : void 0;
       const disclosure = item.output ? expanded ? glyphs.expanded : glyphs.collapsed : "";
       const disclosureWidth = disclosure ? displayWidth(disclosure) + 1 : 0;
       const nameLimit = Math.max(1, Math.min(rowWidth - 2 - disclosureWidth, rowWidth < 64 ? rowWidth - 2 - disclosureWidth : 28));
@@ -15722,9 +16307,28 @@ function Timeline({ items, width = 80, glyphMode = "auto", showToolOutput = fals
         item.id
       );
     }
+    if (item.kind === "clarification") {
+      const rowWidth = safeWidth(width);
+      const chinese = /[\u3400-\u9fff]/u.test(item.pending.question);
+      return /* @__PURE__ */ jsxs(Box, { flexDirection: "column", paddingLeft: 2, marginBottom: 1, children: [
+        /* @__PURE__ */ jsx(Text, { bold: true, color: theme.warning, children: sanitizeTerminalText(item.pending.question) }),
+        item.pending.options.map((option2, optionIndex) => {
+          const label = `${optionIndex + 1}. ${sanitizeInlineTerminalText(option2.label)}${option2.recommended ? chinese ? "\uFF08\u63A8\u8350\uFF09" : " (recommended)" : ""}`;
+          const impact = sanitizeInlineTerminalText(option2.impact);
+          if (rowWidth < 48) {
+            return /* @__PURE__ */ jsxs(Box, { flexDirection: "column", children: [
+              /* @__PURE__ */ jsx(Text, { color: option2.recommended ? theme.textStrong : theme.muted, children: truncateDisplay(label, Math.max(1, rowWidth - 2)) }),
+              /* @__PURE__ */ jsx(Text, { color: theme.dim, children: truncateDisplay(`${glyphs.branchLast} ${impact}`, Math.max(1, (rowWidth - 2) * 2)) })
+            ] }, option2.id);
+          }
+          return /* @__PURE__ */ jsx(Text, { color: option2.recommended ? theme.textStrong : theme.muted, children: truncateDisplay(`${label} ${glyphs.separator} ${impact}`, Math.max(1, rowWidth - 2)) }, option2.id);
+        }),
+        /* @__PURE__ */ jsx(Text, { color: theme.dim, children: chinese ? "\u56DE\u590D\u7F16\u53F7\u3001\u9009\u9879\u540D\u79F0\uFF0C\u6216\u7B80\u77ED\u8BF4\u660E\u4F60\u7684\u51B3\u5B9A\u3002" : "Reply with a number, option label, or a short custom decision." })
+      ] }, item.id);
+    }
     if (item.kind === "list") return /* @__PURE__ */ jsx(ListPanel, { title: item.title, entries: item.entries, width, glyphMode }, item.id);
     if (item.kind === "context-inspector") {
-      return /* @__PURE__ */ jsx(ContextInspector, { status: item.status, working: item.working, summary: item.summary, width, compact: compact2, glyphMode }, item.id);
+      return /* @__PURE__ */ jsx(ContextInspector, { status: item.status, working: item.working, summary: item.summary, width, compact: compact3, glyphMode }, item.id);
     }
     if (item.kind === "theme") return /* @__PURE__ */ jsx(ThemePreview, { name: item.name, width, glyphs }, item.id);
     if (item.kind === "banner") {
@@ -15934,7 +16538,7 @@ function TaskRail({ tasks, width = 80, glyphMode = "auto", maxItems }) {
     ] }) : null
   ] });
 }
-function PermissionCard({ call, category, width = 80, glyphMode = "auto", workspace, compact: compact2 = false }) {
+function PermissionCard({ call, category, reason, width = 80, glyphMode = "auto", workspace, compact: compact3 = false }) {
   const theme = useTheme();
   const glyphs = resolveGlyphs(glyphMode);
   const summary = permissionSummary(call);
@@ -15942,7 +16546,9 @@ function PermissionCard({ call, category, width = 80, glyphMode = "auto", worksp
   const innerWidth = Math.max(1, rowWidth - 2);
   const title = truncateDisplay(`Permission required ${glyphs.separator} ${category}`, innerWidth);
   const tool = truncateDisplay(`tool ${sanitizeInlineTerminalText(call.name)}`, innerWidth);
-  const summaryLine = truncateDisplay(`${summary.label} ${summary.value}`, innerWidth);
+  const summaryLine = truncateDisplay(`target ${summary.label} ${summary.value}`, innerWidth);
+  const reasonLine = truncateDisplay(`reason ${redactPermissionText(reason ?? `${category} tools require approval.`)}`, innerWidth);
+  const riskLine = truncateDisplay(`risk ${permissionRisk2(category)}`, innerWidth);
   const argumentCwd = typeof call.arguments.cwd === "string" ? call.arguments.cwd : void 0;
   const cwd = sanitizeInlineTerminalText(argumentCwd || workspace || "");
   const shortcuts = [
@@ -15967,11 +16573,13 @@ function PermissionCard({ call, category, width = 80, glyphMode = "auto", worksp
     /* @__PURE__ */ jsx(PermissionLine, { marker, children: /* @__PURE__ */ jsx(Text, { bold: true, color: theme.warning, children: title }) }),
     /* @__PURE__ */ jsx(PermissionLine, { marker, children: /* @__PURE__ */ jsx(Text, { color: theme.muted, children: tool }) }),
     /* @__PURE__ */ jsx(PermissionLine, { marker, children: /* @__PURE__ */ jsx(Text, { color: theme.text, children: summaryLine }) }),
+    /* @__PURE__ */ jsx(PermissionLine, { marker, children: /* @__PURE__ */ jsx(Text, { color: theme.muted, children: reasonLine }) }),
+    /* @__PURE__ */ jsx(PermissionLine, { marker, children: /* @__PURE__ */ jsx(Text, { color: theme.warning, children: riskLine }) }),
     cwd ? /* @__PURE__ */ jsx(PermissionLine, { marker, children: /* @__PURE__ */ jsx(Text, { color: theme.muted, children: truncateDisplay(`cwd ${compactDisplayPath(cwd, Math.max(1, innerWidth - 4))}`, innerWidth) }) }) : null,
     rowWidth >= 64 ? /* @__PURE__ */ jsx(Box, { paddingLeft: 2, children: /* @__PURE__ */ jsx(InlineRow, { parts: shortcuts, width: innerWidth, separator: `  ${glyphs.separator}  `, separatorColor: theme.border }) }) : rowWidth >= 28 ? /* @__PURE__ */ jsxs(Box, { paddingLeft: 2, flexDirection: "column", children: [
       /* @__PURE__ */ jsx(InlineRow, { parts: shortcuts.slice(0, 2), width: innerWidth, separator: "  ", separatorColor: theme.border }),
       /* @__PURE__ */ jsx(InlineRow, { parts: shortcuts.slice(2), width: innerWidth, separator: "  ", separatorColor: theme.border })
-    ] }) : compact2 ? /* @__PURE__ */ jsxs(Box, { paddingLeft: 2, flexDirection: "column", children: [
+    ] }) : compact3 ? /* @__PURE__ */ jsxs(Box, { paddingLeft: 2, flexDirection: "column", children: [
       /* @__PURE__ */ jsx(InlineRow, { parts: compactNarrowShortcuts.slice(0, 2), width: innerWidth, separator: " ", separatorColor: theme.border }),
       /* @__PURE__ */ jsx(InlineRow, { parts: compactNarrowShortcuts.slice(2), width: innerWidth, separator: " ", separatorColor: theme.border })
     ] }) : /* @__PURE__ */ jsx(Box, { paddingLeft: 2, flexDirection: "column", children: shortcuts.map((part) => part.color ? /* @__PURE__ */ jsx(Text, { color: part.color, children: truncateDisplay(part.text, innerWidth) }, part.text) : /* @__PURE__ */ jsx(Text, { children: truncateDisplay(part.text, innerWidth) }, part.text)) })
@@ -15987,6 +16595,13 @@ function PermissionLine({ marker, children }) {
     children
   ] });
 }
+function permissionRisk2(category) {
+  if (category === "read") return "workspace content may enter model context";
+  if (category === "write") return "workspace files may be created, replaced, or deleted";
+  if (category === "shell") return "a local process may read or change workspace state";
+  if (category === "git") return "repository state or remotes may change";
+  return "data may leave this machine or remote state may change";
+}
 function PromptBar({ busy, value, placeholder, width = 80, mode = "chat", queueCount = 0, queuePreview, attachments = [], glyphMode = "auto", children }) {
   const theme = useTheme();
   const glyphs = resolveGlyphs(glyphMode);
@@ -16232,7 +16847,7 @@ function MeterBar({ segments, total, width, glyphs }) {
     remainder ? /* @__PURE__ */ jsx(Text, { color: theme.border, children: glyphs.meterEmpty.repeat(remainder) }) : null
   ] });
 }
-function ContextInspector({ status, working, summary, width, memory, connections, sources: sources2, compact: compact2 = false, minimal = false, glyphMode = "auto" }) {
+function ContextInspector({ status, working, summary, width, memory, connections, sources: sources2, compact: compact3 = false, minimal = false, glyphMode = "auto" }) {
   const theme = useTheme();
   const glyphs = resolveGlyphs(glyphMode);
   const hasCompactedContext = status.compactedMessages > 0 || Boolean(summary);
@@ -16253,10 +16868,16 @@ function ContextInspector({ status, working, summary, width, memory, connections
     { label: "summary", detail: hasCompactedContext ? `~${formatTokens(status.summaryTokens)} tokens ${glyphs.separator} ${status.compactedMessages} compacted${summary ? "" : ` ${glyphs.separator} facts`}` : "not created" },
     { label: "long-term", detail: memory ?? `retrieved by relevance ${glyphs.separator} untrusted context` }
   ];
-  if (!compact2 && working?.constraints.length) entries.push({ label: `constraints ${working.constraints.length}`, detail: working.constraints.slice(0, 2).join(` ${glyphs.separator} `) });
-  if (!compact2 && working?.decisions.length) entries.push({ label: `decisions ${working.decisions.length}`, detail: working.decisions.slice(0, 2).join(` ${glyphs.separator} `) });
-  if (!compact2 && working?.openQuestions.length) entries.push({ label: `open ${working.openQuestions.length}`, detail: working.openQuestions.slice(0, 2).join(` ${glyphs.separator} `), tone: "warning" });
-  if (!compact2 && working?.relevantFiles.length) entries.push({ label: "relevant files", detail: working.relevantFiles.map((file) => compactDisplayPath(sanitizeInlineTerminalText(file), 28)).join(` ${glyphs.separator} `) });
+  if (status.epochIndex !== void 0 && status.epochCount !== void 0 && status.epochTokens !== void 0 && status.epochBudget !== void 0 && status.lifetimeTokens !== void 0 && status.lifetimeBudget !== void 0) {
+    entries.splice(1, 0, {
+      label: "epoch",
+      detail: `#${status.epochIndex} ${formatTokens(status.epochTokens)}/${formatTokens(status.epochBudget)} ${glyphs.separator} lifetime ${formatTokens(status.lifetimeTokens)}/${formatTokens(status.lifetimeBudget)}`
+    });
+  }
+  if (!compact3 && working?.constraints.length) entries.push({ label: `constraints ${working.constraints.length}`, detail: working.constraints.slice(0, 2).join(` ${glyphs.separator} `) });
+  if (!compact3 && working?.decisions.length) entries.push({ label: `decisions ${working.decisions.length}`, detail: working.decisions.slice(0, 2).join(` ${glyphs.separator} `) });
+  if (!compact3 && working?.openQuestions.length) entries.push({ label: `open ${working.openQuestions.length}`, detail: working.openQuestions.slice(0, 2).join(` ${glyphs.separator} `), tone: "warning" });
+  if (!compact3 && working?.relevantFiles.length) entries.push({ label: "relevant files", detail: working.relevantFiles.map((file) => compactDisplayPath(sanitizeInlineTerminalText(file), 28)).join(` ${glyphs.separator} `) });
   if (sources2?.length) {
     const pinned = sources2.filter((source) => source.state === "pinned");
     const muted = sources2.filter((source) => source.state === "muted");
@@ -16290,7 +16911,7 @@ function ContextInspector({ status, working, summary, width, memory, connections
         /* @__PURE__ */ jsx(MeterBar, { segments, total: meterTotal, width: meterWidth, glyphs })
       ] }) : null
     ] }),
-    /* @__PURE__ */ jsx(ListPanel, { title: "", hideTitle: true, entries, width, glyphMode })
+    /* @__PURE__ */ jsx(ListPanel, { title: "", hideTitle: true, entries, width: Math.max(1, rowWidth - 2), glyphMode })
   ] });
 }
 function ThemePreview({ name, width, glyphs }) {
@@ -16377,8 +16998,8 @@ function Banner({ model, engine, workspace, version, width, glyphs }) {
 function UpdateNotice({ current, latest, command: command2, highlights, width, glyphs }) {
   const theme = useTheme();
   const availableWidth = safeWidth(width);
-  const compact2 = availableWidth < 48;
-  const parts = compact2 ? [
+  const compact3 = availableWidth < 48;
+  const parts = compact3 ? [
     { text: `${glyphs.up} `, color: theme.accent, bold: true },
     { text: `v${current}`, color: theme.dim, bold: false },
     { text: ` ${glyphs.arrow} `, color: theme.muted, bold: false },
@@ -16399,7 +17020,7 @@ function UpdateNotice({ current, latest, command: command2, highlights, width, g
   const bullets = bulletWidth > 0 ? (highlights ?? []).map((line) => truncateDisplay(sanitizeInlineTerminalText(line), bulletWidth)) : [];
   return /* @__PURE__ */ jsxs(Box, { marginBottom: 1, flexDirection: "column", children: [
     /* @__PURE__ */ jsx(Box, { children: truncated ? /* @__PURE__ */ jsx(Text, { color: theme.muted, children: rendered }) : parts.map((part, index) => /* @__PURE__ */ jsx(Text, { color: part.color, bold: part.bold, children: part.text }, index)) }),
-    compact2 ? /* @__PURE__ */ jsx(Text, { color: theme.dim, children: truncateDisplay(`  run ${command2}`, availableWidth) }) : null,
+    compact3 ? /* @__PURE__ */ jsx(Text, { color: theme.dim, children: truncateDisplay(`  run ${command2}`, availableWidth) }) : null,
     bullets.map((line, index) => /* @__PURE__ */ jsx(Text, { color: theme.dim, children: `${bulletPrefix}${line}` }, index))
   ] });
 }
@@ -17265,6 +17886,40 @@ function clipTimelineItem(item, options) {
   if (item.kind === "notice") {
     return { ...item, text: tailText(item.text, width, options.rows) };
   }
+  if (item.kind === "list") {
+    if (options.rows <= 1) return { id: item.id, kind: "notice", text: truncateDisplay(item.title, width) };
+    const available = Math.max(1, options.rows - 2);
+    const entries = [];
+    let used = 0;
+    let firstIncluded = item.entries.length;
+    for (let index = item.entries.length - 1; index >= 0; index -= 1) {
+      const entry = item.entries[index];
+      const rows = 1 + (entry.detail ? 1 : 0);
+      if (entries.length && used + rows > available) break;
+      if (!entries.length && rows > available) {
+        const { detail: _detail, ...compactEntry } = entry;
+        entries.unshift(compactEntry);
+        firstIncluded = index;
+        used = 1;
+        break;
+      }
+      entries.unshift(entry);
+      firstIncluded = index;
+      used += rows;
+    }
+    if (firstIncluded > 0) {
+      while (entries.length > 1 && used >= available) {
+        const removed = entries.shift();
+        if (!removed) break;
+        firstIncluded += 1;
+        used -= 1 + (removed.detail ? 1 : 0);
+      }
+      if (used < available) {
+        entries.unshift({ label: `${terminalEllipsis()} ${firstIncluded} earlier entries hidden` });
+      }
+    }
+    return { ...item, entries };
+  }
   if (item.kind === "update") {
     const baseRows = width < 48 ? 3 : 2;
     if (options.rows < baseRows) {
@@ -17307,9 +17962,9 @@ function tailText(value, width, maxRows) {
   return `${marker}
 ${selected.join("\n")}`;
 }
-function estimateTimelineItemRows(item, { width, compact: compact2 = false, showToolOutput = false, expandedToolId }) {
+function estimateTimelineItemRows(item, { width, compact: compact3 = false, showToolOutput = false, expandedToolId }) {
   const rowWidth = Math.max(1, Math.floor(width));
-  const gap = compact2 ? 0 : 1;
+  const gap = compact3 ? 0 : 1;
   if (item.kind === "user") return wrappedRows(item.text, Math.max(1, rowWidth - 2)) + (item.clipped ? 0 : gap);
   if (item.kind === "assistant") {
     return 1 + richTextRows(item.text, Math.max(1, rowWidth - 2)) + (item.clipped ? 0 : gap);
@@ -17321,7 +17976,7 @@ function estimateTimelineItemRows(item, { width, compact: compact2 = false, show
     const detail = item.errorDetail || item.detail;
     const detailRows = narrow && detail ? 1 : 0;
     const metaRows = item.meta ? 1 : 0;
-    const outputRows = (showToolOutput || item.id === expandedToolId) && item.output ? Math.min(compact2 ? 25 : 81, richTextRows(item.output, Math.max(1, rowWidth - 2))) : 0;
+    const outputRows = (showToolOutput || item.id === expandedToolId) && item.output ? Math.min(compact3 ? 25 : 81, richTextRows(item.output, Math.max(1, rowWidth - 2))) : 0;
     return 1 + detailRows + metaRows + outputRows;
   }
   if (item.kind === "list") {
@@ -17335,7 +17990,7 @@ function estimateTimelineItemRows(item, { width, compact: compact2 = false, show
   if (item.kind === "theme") return 3;
   if (item.kind === "context") {
     const metaRows = rowWidth < 64 ? 2 : 1;
-    const spanLimit = compact2 ? 2 : 3;
+    const spanLimit = compact3 ? 2 : 3;
     const spanCount = Math.min(item.spans?.length ?? 0, spanLimit);
     const moreRow = (item.spans?.length ?? 0) > spanLimit ? 1 : 0;
     const degradationRows = item.degradation ? metaRows : 0;
@@ -17362,6 +18017,91 @@ function wrappedRows(value, width) {
   return sanitizeTerminalText(value).split("\n").reduce((rows, line) => rows + Math.max(1, Math.ceil(displayWidth(line) / safeWidth2)), 0);
 }
 
+// src/ui/review-bundle.ts
+import { relative as relative9 } from "node:path";
+var failureClasses = /* @__PURE__ */ new Set([
+  "schema_input",
+  "unknown_tool",
+  "permission_denied",
+  "command_exit",
+  "timeout",
+  "cancelled",
+  "hook",
+  "execution",
+  "no_progress",
+  "contract_required"
+]);
+function parseReviewScope(argument) {
+  const value = argument.trim();
+  if (!value || value === "working-tree") return { kind: "working-tree" };
+  const [kind, ref, ...extra] = value.split(/\s+/u);
+  if (kind !== "commit" && kind !== "branch" || !ref || extra.length) {
+    throw new Error("Usage: /review [working-tree|commit <ref>|branch <base-ref>]");
+  }
+  if (!/^[A-Za-z0-9._/@{}~^+-]{1,200}$/u.test(ref) || ref.startsWith("-")) {
+    throw new Error("Review refs must be a single Git revision without control characters or leading dashes.");
+  }
+  return { kind, ref };
+}
+function buildRedactedReviewBundle(session, workspaceRoot, scope) {
+  const lastRun = session.lastRun;
+  const failures = (session.audit ?? []).filter((event) => event.type === "tool" && event.outcome === "failure").slice(-8).map((event) => {
+    const receipt = failureReceipt2(event.metadata?.failure);
+    return {
+      tool: event.tool,
+      ...event.category ? { category: event.category } : {},
+      ...receipt?.class ? { class: receipt.class } : {},
+      ...receipt?.retryable !== void 0 ? { retryable: receipt.retryable } : {},
+      ...receipt?.circuitOpen !== void 0 ? { circuitOpen: receipt.circuitOpen } : {}
+    };
+  });
+  return {
+    version: 1,
+    redacted: true,
+    sessionId: session.id,
+    scope,
+    changedFiles: [...new Set(session.changedFiles.map((path) => relative9(workspaceRoot, path) || "."))].sort(),
+    ...lastRun ? {
+      lastRun: {
+        status: lastRun.status,
+        reason: lastRun.reason,
+        checks: lastRun.checks.map((check) => ({ tool: check.tool, kind: check.kind, ok: check.ok })),
+        ...lastRun.acceptance ? { acceptance: {
+          state: lastRun.acceptance.state,
+          satisfied: lastRun.acceptance.satisfied,
+          pending: lastRun.acceptance.pending,
+          blocked: lastRun.acceptance.blocked
+        } } : {}
+      }
+    } : {},
+    failures
+  };
+}
+function reviewRequest(scope) {
+  if (scope.kind === "working-tree") return "Review the current working tree changes.";
+  if (scope.kind === "commit") return `Review commit ${scope.ref}.`;
+  return `Review the current branch against ${scope.ref}.`;
+}
+function reviewTurnInstructions(bundle) {
+  return `A read-only review is active. Keep the review scope fixed to the bundle below. Do not mutate files, run write-capable tools, or widen the scope. Report actionable findings first with file and line evidence. Never reproduce credentials or secret values. The bundle is deliberately content-free and redacted.
+
+<redacted-review-bundle>
+${JSON.stringify(bundle, null, 2)}
+</redacted-review-bundle>`;
+}
+function failureReceipt2(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+  const record = value;
+  return {
+    ...isToolFailureClass(record.class) ? { class: record.class } : {},
+    ...typeof record.retryable === "boolean" ? { retryable: record.retryable } : {},
+    ...typeof record.circuitOpen === "boolean" ? { circuitOpen: record.circuitOpen } : {}
+  };
+}
+function isToolFailureClass(value) {
+  return typeof value === "string" && failureClasses.has(value);
+}
+
 // src/ui/timeline-reducers.ts
 var itemCounter = 0;
 var nextId = () => `ui-${Date.now()}-${itemCounter++}`;
@@ -17565,7 +18305,7 @@ function SkeinApp({ runner, config, extensions, initialPrompt, askMode = false,
   const colorEnabled = config.ui.color && !process.env.NO_COLOR;
   const [theme, setTheme] = useState2(() => resolveThemeWithColor(config.ui.theme, colorEnabled));
   const [themeCatalogRevision, setThemeCatalogRevision] = useState2(0);
-  const [compact2, setCompact] = useState2(config.ui.compact);
+  const [compact3, setCompact] = useState2(config.ui.compact);
   const [interactionMode, setInteractionMode] = useState2(planMode ? "plan" : askMode ? "ask" : "build");
   const [input2, setInput] = useState2("");
   const [busy, setBusy] = useState2(false);
@@ -17602,6 +18342,7 @@ function SkeinApp({ runner, config, extensions, initialPrompt, askMode = false,
   const controller = useRef2(void 0);
   const processing = useRef2(false);
   const queued = useRef2([]);
+  const clarificationBacklog = useRef2([]);
   const stopRequested = useRef2(false);
   const startedInitial = useRef2(false);
   const lastSubmitted = useRef2(void 0);
@@ -17704,8 +18445,13 @@ function SkeinApp({ runner, config, extensions, initialPrompt, askMode = false,
     const timer = setInterval(() => setFrameIndex((value) => (value + 1) % spinnerFrames().length), 120);
     return () => clearInterval(timer);
   }, [busy]);
-  const requestPermission = useCallback((call, category) => {
-    return new Promise((resolve26) => setPermission({ call, category, resolve: resolve26 }));
+  const requestPermission = useCallback((call, category, reason) => {
+    return new Promise((resolve26) => setPermission({
+      call,
+      category,
+      ...reason ? { reason } : {},
+      resolve: resolve26
+    }));
   }, []);
   const onEvent = useCallback((event) => {
     switch (event.type) {
@@ -17725,7 +18471,7 @@ function SkeinApp({ runner, config, extensions, initialPrompt, askMode = false,
           ...event.packed.budgetReason ? { budgetReason: event.packed.budgetReason } : {},
           truncated: event.packed.truncated,
           spans: event.packed.hits.slice(0, 5).map((hit) => ({
-            path: relative9(runner.workspace.primaryRoot, hit.path) || hit.path,
+            path: relative10(runner.workspace.primaryRoot, hit.path) || hit.path,
             startLine: hit.startLine,
             endLine: hit.endLine,
             score: hit.score,
@@ -17829,7 +18575,7 @@ function SkeinApp({ runner, config, extensions, initialPrompt, askMode = false,
           id: nextId(),
           kind: "notice",
           tone: event.status === "ready" || event.status === "integrated" ? "success" : "error",
-          text: `Writer ${event.id.slice(0, 8)} ${event.status}${separator}${event.detail}`
+          text: `Writer ${event.id.slice(0, 8)} ${event.status}${separator}${event.detail}${event.status === "conflict" || event.status === "failed" || event.status === "cancelled" ? `${separator}Run /recover before retrying or restoring.` : ""}`
         });
         break;
       case "agent_done":
@@ -17842,13 +18588,33 @@ function SkeinApp({ runner, config, extensions, initialPrompt, askMode = false,
         append({ id: nextId(), kind: "compaction", messages: event.omittedMessages, tokens: event.summaryTokens });
         refreshSession();
         break;
+      case "context_epoch":
+        append({
+          id: nextId(),
+          kind: "notice",
+          tone: "info",
+          text: `Context epoch ${event.previousIndex} \u2192 ${event.index}${separator}${event.reason.replace("_", " ")}${separator}${event.inputTokens + event.outputTokens} tokens preserved in the lifetime ledger.`
+        });
+        refreshSession();
+        break;
+      case "needs_input":
+        append({ id: nextId(), kind: "clarification", pending: event.pending });
+        refreshSession();
+        break;
+      case "input_resolved":
+        append({ id: nextId(), kind: "notice", tone: "success", text: `Clarification resolved${separator}${event.answer}` });
+        refreshSession();
+        break;
+      case "intent":
+        refreshSession();
+        break;
       case "usage":
         refreshSession();
         break;
       case "error":
         lastEventError.current = event.error.message;
         setTimeline(endStreamingAssistants);
-        append({ id: nextId(), kind: "notice", tone: "error", text: event.error.message });
+        append({ id: nextId(), kind: "notice", tone: "error", text: `${event.error.message}${separator}Run /recover to inspect evidence, changes, and safe next actions.` });
         setActivity(void 0);
         break;
       case "done":
@@ -17872,7 +18638,7 @@ function SkeinApp({ runner, config, extensions, initialPrompt, askMode = false,
             id: nextId(),
             kind: "notice",
             tone: event.reason === "aborted" ? "info" : "error",
-            text: event.reason === "aborted" ? "Run interrupted." : event.reason === "max_turns" ? "Stopped at the configured turn limit." : event.reason === "token_budget" ? "Stopped at the configured token budget." : event.reason
+            text: event.reason === "aborted" ? "Run interrupted. Use /recover to inspect changes or resume safely." : event.reason === "max_turns" ? "Stopped at the configured turn limit. Use /recover resume after adjusting the limit." : event.reason === "token_budget" ? "Stopped at the configured token budget. Use /recover to inspect state before resuming with a larger budget." : event.reason
           });
         }
         break;
@@ -17886,9 +18652,16 @@ function SkeinApp({ runner, config, extensions, initialPrompt, askMode = false,
   const runLocalCommand = useCallback(async (value) => {
     if (!value.startsWith("/")) return false;
     const [rawCommand = "", ...rest] = value.slice(1).trim().split(/\s+/);
-    const command2 = rawCommand.toLocaleLowerCase();
-    const argument = rest.join(" ").trim();
+    let command2 = rawCommand.toLocaleLowerCase();
+    let argument = rest.join(" ").trim();
     if (!command2) return true;
+    if (command2 === "recover") {
+      const [action = "", ...actionRest] = argument.split(/\s+/u);
+      if (action === "diff" || action === "audit" || action === "rollback") {
+        command2 = action;
+        argument = actionRest.join(" ").trim();
+      }
+    }
     if (command2 === "exit" || command2 === "quit") {
       exit();
       return true;
@@ -17970,10 +18743,77 @@ function SkeinApp({ runner, config, extensions, initialPrompt, askMode = false,
       });
       return true;
     }
+    if (command2 === "review") {
+      const scope = parseReviewScope(argument);
+      const bundle = buildRedactedReviewBundle(runner.getSession(), runner.workspace.primaryRoot, scope);
+      return {
+        kind: "agent",
+        display: `/review ${scope.kind}${scope.kind === "working-tree" ? "" : ` ${scope.ref}`}`,
+        runInput: reviewRequest(scope),
+        turnInstructions: reviewTurnInstructions(bundle),
+        readOnly: true
+      };
+    }
+    if (command2 === "recover") {
+      const action = argument.toLocaleLowerCase();
+      const currentSession = runner.getSession();
+      const lastRun = currentSession.lastRun;
+      const lastFailure = (currentSession.audit ?? []).findLast((event) => event.type === "tool" && event.outcome === "failure");
+      const failure = recoveryFailure(lastFailure?.metadata?.failure);
+      if (action === "retry") {
+        if (currentSession.pendingInput) throw new Error("Answer the pending clarification before retrying an operation.");
+        if (!lastFailure) throw new Error("No failed operation is available to retry.");
+        return {
+          kind: "agent",
+          display: "/recover retry",
+          runInput: `Retry the most recent failed ${lastFailure.tool} operation after inspecting the current workspace state.`,
+          turnInstructions: "Resume the existing session. Use the recorded failure receipt and current files as authority. Apply its repair hint before one targeted retry; do not replay a circuit-open or non-retryable operation unchanged."
+        };
+      }
+      if (action === "resume") {
+        if (currentSession.pendingInput) throw new Error("Answer the pending clarification in the composer to resume the same logical run.");
+        if (!lastRun || lastRun.reason === "completed") throw new Error("The latest run is already complete.");
+        return {
+          kind: "agent",
+          display: "/recover resume",
+          runInput: "Resume the most recent incomplete run from its persisted state.",
+          turnInstructions: "Resume the existing session from its Task Contract, changed-file set, last-run receipt, and unresolved failures. Inspect current state before acting, keep prior successful evidence, and run only missing verification."
+        };
+      }
+      if (action) throw new Error("Usage: /recover [retry|resume|diff|rollback|audit]");
+      const checkpoints = await runner.checkpointStore.list(currentSession.id);
+      const latestCheckpoint = checkpoints[0];
+      appendList("Recovery Center", [
+        {
+          label: `Last run  ${lastRun?.status ?? "none"}${lastRun ? `${separator}${lastRun.reason}` : ""}`,
+          detail: lastRun?.detail ?? "No completed or interrupted run has been recorded.",
+          tone: lastRun?.status === "verified" || lastRun?.status === "no_changes" ? "success" : lastRun ? "warning" : "normal"
+        },
+        ...lastFailure ? [{
+          label: `Failure  ${lastFailure.tool}${failure?.class ? `${separator}${failure.class}` : ""}`,
+          detail: failure?.repairHint ?? "Inspect the audit timeline before retrying.",
+          tone: "error"
+        }] : [],
+        {
+          label: `Workspace  ${currentSession.changedFiles.length} changed file${currentSession.changedFiles.length === 1 ? "" : "s"}`,
+          detail: currentSession.changedFiles.length ? "/diff inspects the current patch." : "No tracked session changes."
+        },
+        {
+          label: `Checkpoint  ${latestCheckpoint ? latestCheckpoint.id.slice(0, 12) : "none"}`,
+          detail: latestCheckpoint ? `${latestCheckpoint.reason}${separator}${latestCheckpoint.entries.length} files${separator}/recover rollback` : "No pre-mutation snapshot is available for this session."
+        },
+        { label: "/recover retry", detail: lastFailure ? "Apply the repair hint, then retry the latest failure once." : "Unavailable until an operation fails." },
+        { label: "/recover resume", detail: currentSession.pendingInput ? "Unavailable: answer the pending clarification in the composer." : lastRun && lastRun.reason !== "completed" ? "Continue the incomplete logical run." : "No incomplete run to resume." },
+        { label: "/recover diff", detail: "Inspect the current workspace patch." },
+        { label: "/recover audit", detail: "Review permission and tool evidence." },
+        { label: "/recover rollback", detail: "Choose a checkpoint to restore." }
+      ]);
+      return true;
+    }
     if (command2 === "changes") {
       const changed = runner.getSession().changedFiles;
       appendList("Changed files", changed.length ? changed.map((path) => ({
-        label: relative9(runner.workspace.primaryRoot, path) || ".",
+        label: relative10(runner.workspace.primaryRoot, path) || ".",
         detail: path
       })) : [{ label: "No recorded changes." }]);
       return true;
@@ -18126,7 +18966,7 @@ function SkeinApp({ runner, config, extensions, initialPrompt, askMode = false,
       const skills = extensions?.listSkills() ?? [];
       appendList("Skills", skills.length ? skills.map((skill) => ({
         label: `${skill.name}  ${skill.scope}${skill.trusted ? "" : `${separator}untrusted`}`,
-        detail: `${skill.description}${separator}${relative9(runner.workspace.primaryRoot, skill.path) || skill.path}`,
+        detail: `${skill.description}${separator}${relative10(runner.workspace.primaryRoot, skill.path) || skill.path}`,
         tone: skill.trusted ? "normal" : "warning"
       })) : [{ label: "No skills discovered.", detail: "Add SKILL.md playbooks under .agents/skills, .claude/skills, or a configured directory." }]);
       return true;
@@ -18274,7 +19114,7 @@ function SkeinApp({ runner, config, extensions, initialPrompt, askMode = false,
     }
     if (command2 === "density") {
       const normalized = argument.toLocaleLowerCase();
-      const next = normalized === "compact" ? true : normalized === "comfortable" || normalized === "normal" ? false : normalized === "" || normalized === "toggle" ? !compact2 : void 0;
+      const next = normalized === "compact" ? true : normalized === "comfortable" || normalized === "normal" ? false : normalized === "" || normalized === "toggle" ? !compact3 : void 0;
       if (next === void 0) throw new Error("Usage: /density [compact|comfortable]");
       setCompact(next);
       await saveUiPreference({ compact: next });
@@ -18367,7 +19207,7 @@ function SkeinApp({ runner, config, extensions, initialPrompt, askMode = false,
       })));
       return true;
     }
-  }, [append, appendList, compact2, config, ellipsis, exit, extensions, interactionMode, refreshSession, requestPermission, runner, separator, showToolOutput, tasks, theme, workflows]);
+  }, [append, appendList, compact3, config, ellipsis, exit, extensions, interactionMode, refreshSession, requestPermission, runner, separator, showToolOutput, tasks, theme, workflows]);
   const submit = useCallback(async (raw, mode = "normal") => {
     const trimmed = raw.trim();
     if (!trimmed) return;
@@ -18382,6 +19222,7 @@ function SkeinApp({ runner, config, extensions, initialPrompt, askMode = false,
     if (processing.current && isExitCommand(trimmed)) {
       stopRequested.current = true;
       queued.current = [];
+      clarificationBacklog.current = [];
       setQueue([]);
       controller.current?.abort();
       exit();
@@ -18455,7 +19296,7 @@ function SkeinApp({ runner, config, extensions, initialPrompt, askMode = false,
         lastEventError.current = void 0;
         try {
           const nextSession = await runner.run(current.runInput, {
-            askMode: interactionMode !== "build",
+            askMode: current.readOnly === true || interactionMode !== "build",
             signal: abortController.signal,
             ...current.turnInstructions || interactionMode === "plan" ? {
               turnInstructions: [
@@ -18469,6 +19310,31 @@ function SkeinApp({ runner, config, extensions, initialPrompt, askMode = false,
           const snapshot = snapshotSession(nextSession);
           setSession(snapshot);
           setTasks(snapshot.tasks.map((task) => ({ ...task })));
+          if (snapshot.pendingInput) {
+            const deferred = queued.current.length;
+            clarificationBacklog.current.push(...queued.current);
+            queued.current = [];
+            setQueue([]);
+            if (deferred) append({
+              id: nextId(),
+              kind: "notice",
+              tone: "info",
+              text: `Paused ${deferred} queued follow-up${deferred === 1 ? "" : "s"} for clarification; they will resume after the answer.`
+            });
+            break;
+          }
+          if (clarificationBacklog.current.length) {
+            const resumed = clarificationBacklog.current.length;
+            queued.current = [...clarificationBacklog.current, ...queued.current];
+            clarificationBacklog.current = [];
+            setQueue([...queued.current]);
+            append({
+              id: nextId(),
+              kind: "notice",
+              tone: "success",
+              text: `Clarification resolved; resuming ${resumed} queued follow-up${resumed === 1 ? "" : "s"}.`
+            });
+          }
         } catch (error) {
           const message2 = error instanceof Error ? error.message : String(error);
           if (!abortController.signal.aborted && message2 !== lastEventError.current) {
@@ -18481,8 +19347,9 @@ function SkeinApp({ runner, config, extensions, initialPrompt, askMode = false,
           }
         }
         if (abortController.signal.aborted || stopRequested.current) {
-          const discarded = queued.current.length;
+          const discarded = queued.current.length + clarificationBacklog.current.length;
           queued.current = [];
+          clarificationBacklog.current = [];
           setQueue([]);
           if (discarded) append({ id: nextId(), kind: "notice", text: `Discarded ${discarded} queued follow-up${discarded === 1 ? "" : "s"}.` });
           break;
@@ -18499,10 +19366,10 @@ function SkeinApp({ runner, config, extensions, initialPrompt, askMode = false,
   }, [append, exit, interactionMode, onEvent, requestPermission, runLocalCommand, runner]);
   const submitFromComposer = useCallback((raw, mode = "normal") => {
     if (historySearch) {
-      const selected = resolveHistorySearch(historySearch, "select");
+      const selected2 = resolveHistorySearch(historySearch, "select");
       setHistorySearch(void 0);
       setHistoryIndex(-1);
-      void submit(selected, mode === "normal" && processing.current ? "steer" : mode);
+      void submit(selected2, mode === "normal" && processing.current ? "steer" : mode);
       return;
     }
     if (suggestionMode === "mention" && selectedSuggestion) {
@@ -18513,7 +19380,8 @@ function SkeinApp({ runner, config, extensions, initialPrompt, askMode = false,
         return;
       }
     }
-    const suggestion = selectedSuggestion;
+    const selected = selectedSuggestion;
+    const suggestion = selected && !(raw.startsWith(selected.value) && raw.slice(selected.value.length).trim()) ? selected : void 0;
     const normalized = raw.trimEnd();
     if (suggestion && raw.startsWith("/") && suggestion.value !== raw && suggestion.value.endsWith(" ") && suggestion.label !== normalized) {
       setInput(suggestion.value);
@@ -18552,6 +19420,14 @@ function SkeinApp({ runner, config, extensions, initialPrompt, askMode = false,
         text: `Allowed ${call.name} for this exact ${category} target during the session.`
       });
     }
+    if (grant === false) {
+      append({
+        id: nextId(),
+        kind: "notice",
+        tone: "info",
+        text: `Denied ${call.name}; the requested ${category} action was not run. Use /permissions to inspect policy or /recover to review the run.`
+      });
+    }
     if (stop) {
       requestRunStop();
     }
@@ -18731,7 +19607,7 @@ function SkeinApp({ runner, config, extensions, initialPrompt, askMode = false,
   const tokenTotal = session.usage.inputTokens + session.usage.outputTokens;
   const contextStatus = runner.getContextStatus();
   const frame = spinnerFrames()[frameIndex % spinnerFrames().length];
-  const compactUi = compact2 || terminalHeight < 28;
+  const compactUi = compact3 || terminalHeight < 28;
   const constrainedHeight = terminalHeight < 18;
   const compactComposer = terminalHeight < 18;
   const minimalInspector = terminalHeight < 22;
@@ -18895,7 +19771,7 @@ function SkeinApp({ runner, config, extensions, initialPrompt, askMode = false,
           )
         }
       )
-    ] }) : /* @__PURE__ */ jsx3(PermissionCard, { call: permission.call, category: permission.category, workspace: runner.workspace.primaryRoot, width: contentWidth, glyphMode, compact: constrainedHeight }),
+    ] }) : /* @__PURE__ */ jsx3(PermissionCard, { call: permission.call, category: permission.category, ...permission.reason ? { reason: permission.reason } : {}, workspace: runner.workspace.primaryRoot, width: contentWidth, glyphMode, compact: constrainedHeight }),
     showFooter ? /* @__PURE__ */ jsx3(
       Footer,
       {
@@ -18947,6 +19823,9 @@ function initialTimeline(session, banner, setupProblem) {
       text: `Contract ${session.taskContract.state} | ${satisfied}/${required.length} accepted`
     });
   }
+  if (session.pendingInput) {
+    items.push({ id: `pending-input-${session.pendingInput.id}`, kind: "clarification", pending: session.pendingInput });
+  }
   if (setupProblem && items.length <= 1) items.push({ id: nextId(), kind: "notice", tone: "error", text: setupProblem });
   return items;
 }
@@ -18992,6 +19871,35 @@ function snapshotSession(source) {
         relevantFiles: [...source.workingMemory.relevantFiles]
       }
     } : {},
+    ...source.contextEpochs ? {
+      contextEpochs: source.contextEpochs.map((epoch) => ({
+        ...epoch,
+        usage: { ...epoch.usage },
+        ...epoch.handoff ? {
+          handoff: {
+            ...epoch.handoff,
+            ...epoch.handoff.contract ? {
+              contract: {
+                ...epoch.handoff.contract,
+                required: epoch.handoff.contract.required.map((criterion2) => ({
+                  ...criterion2,
+                  evidenceRefs: [...criterion2.evidenceRefs]
+                }))
+              }
+            } : {},
+            unresolvedFailures: epoch.handoff.unresolvedFailures.map((failure) => ({ ...failure })),
+            changedFiles: [...epoch.handoff.changedFiles],
+            checks: epoch.handoff.checks.map((check) => ({ ...check }))
+          }
+        } : {}
+      }))
+    } : {},
+    ...source.intentAssessment ? {
+      intentAssessment: { ...source.intentAssessment, reasons: [...source.intentAssessment.reasons] }
+    } : {},
+    ...source.pendingInput ? {
+      pendingInput: { ...source.pendingInput, options: source.pendingInput.options.map((option2) => ({ ...option2 })) }
+    } : {},
     usage: { ...source.usage }
   };
 }
@@ -19003,6 +19911,14 @@ function cloneValue(value) {
   if (value && typeof value === "object") return cloneRecord(value);
   return value;
 }
+function recoveryFailure(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+  const receipt = value;
+  return {
+    ...typeof receipt.class === "string" ? { class: sanitizeTerminalText(receipt.class).slice(0, 40) } : {},
+    ...typeof receipt.repairHint === "string" ? { repairHint: sanitizeTerminalText(receipt.repairHint).replace(/\s+/gu, " ").slice(0, 240) } : {}
+  };
+}
 function isExitCommand(value) {
   const command2 = localCommandName(value);
   return command2 === "exit" || command2 === "quit";
@@ -19020,6 +19936,9 @@ function shouldDeferLocalCommand(value) {
     "remember",
     "diff",
     "checkpoints",
+    "audit",
+    "rollback",
+    "recover",
     "workflow",
     "exit",
     "quit"
@@ -19038,17 +19957,17 @@ function composerAttachments(value) {
   const paths = [...value.matchAll(/(?:^|\s)@([^\s]+)/g)].map((match) => match[1]).filter((path) => Boolean(path));
   return [...new Set(paths)].slice(-3);
 }
-function permissionRows(width, hasCwd, compact2) {
-  const content = 3 + (hasCwd ? 1 : 0);
+function permissionRows(width, hasCwd, compact3) {
+  const content = 5 + (hasCwd ? 1 : 0);
   if (width >= 64) return content + 2;
   if (width >= 28) return content + 3;
-  if (compact2) return content + 3;
+  if (compact3) return content + 3;
   return content + 5;
 }
-function contextInspectorRows(session, compact2, width, minimal) {
+function contextInspectorRows(session, compact3, width, minimal) {
   if (minimal) return 2;
   const working = session.workingMemory;
-  const entries = 5 + (compact2 ? 0 : (working?.constraints.length ? 1 : 0) + (working?.decisions.length ? 1 : 0) + (working?.openQuestions.length ? 1 : 0) + (working?.relevantFiles.length ? 1 : 0));
+  const entries = 6 + (compact3 ? 0 : (working?.constraints.length ? 1 : 0) + (working?.decisions.length ? 1 : 0) + (working?.openQuestions.length ? 1 : 0) + (working?.relevantFiles.length ? 1 : 0));
   return 2 + entries * (width < 52 ? 2 : 1);
 }
 function contextInspectorStatus(status) {
@@ -19058,7 +19977,13 @@ function contextInspectorStatus(status) {
     activeTokens: status.activeTokens,
     summaryTokens: status.summaryTokens,
     toolTokens: status.toolTokens,
-    compactedMessages: status.compactedMessages
+    compactedMessages: status.compactedMessages,
+    epochIndex: status.epochIndex,
+    epochCount: status.epochCount,
+    epochTokens: status.epochTokens,
+    epochBudget: status.epochBudget,
+    lifetimeTokens: status.lifetimeTokens,
+    lifetimeBudget: status.lifetimeBudget
   };
 }
 function toolDetail2(call) {
@@ -19100,14 +20025,14 @@ function WorkspacePreparationView({
   const theme = useTheme();
   const safeWidth2 = Math.max(1, Math.floor(width));
   const innerWidth = Math.max(1, safeWidth2 - (safeWidth2 >= 24 ? 4 : 0));
-  const compact2 = safeWidth2 < 48;
+  const compact3 = safeWidth2 < 48;
   const constrained = height < 14;
   const ascii = process.env.SKEIN_GLYPHS === "ascii" || process.env.MOSAIC_GLYPHS === "ascii";
   const spinner = (ascii ? [".", "o", "O", "o"] : ["\u25DC", "\u25E0", "\u25DD", "\u25DE", "\u25E1", "\u25DF"])[frame % (ascii ? 4 : 6)];
   const separator = ascii ? "|" : "\xB7";
   const brand = ascii ? "*" : PRODUCT_MARK;
   const phase = readiness ? "ready" : error ? "error" : progress.phase;
-  const phaseLabel = preparationLabel(phase, progress, readiness, compact2);
+  const phaseLabel = preparationLabel(phase, progress, readiness, compact3);
   const detail = preparationDetail(phase, progress, readiness, error);
   const modelLine = `model ${sanitizeTerminalText(model)}`;
   const workspaceLine = `workspace ${compactDisplayPath(sanitizeTerminalText(workspace), Math.max(1, innerWidth - 10))}`;
@@ -19119,14 +20044,14 @@ function WorkspacePreparationView({
         "  ",
         PRODUCT_NAME.toUpperCase()
       ] }),
-      !compact2 && !constrained ? /* @__PURE__ */ jsxs4(Text4, { color: theme.dim, children: [
+      !compact3 && !constrained ? /* @__PURE__ */ jsxs4(Text4, { color: theme.dim, children: [
         "  ",
         separator,
         "  LOCAL CONTEXT"
       ] }) : null
     ] }),
     !constrained ? /* @__PURE__ */ jsx4(Text4, { color: theme.muted, children: truncateDisplay("Ground the workspace before the first request.", innerWidth) }) : null,
-    !constrained && !compact2 ? /* @__PURE__ */ jsx4(Text4, { color: theme.dim, children: truncateDisplay(`${modelLine}  ${separator}  ${workspaceLine}`, innerWidth) }) : !constrained ? /* @__PURE__ */ jsxs4(Fragment3, { children: [
+    !constrained && !compact3 ? /* @__PURE__ */ jsx4(Text4, { color: theme.dim, children: truncateDisplay(`${modelLine}  ${separator}  ${workspaceLine}`, innerWidth) }) : !constrained ? /* @__PURE__ */ jsxs4(Fragment3, { children: [
       /* @__PURE__ */ jsx4(Text4, { color: theme.dim, children: truncateDisplay(modelLine, innerWidth) }),
       /* @__PURE__ */ jsx4(Text4, { color: theme.dim, children: truncateDisplay(workspaceLine, innerWidth) })
     ] }) : /* @__PURE__ */ jsx4(Text4, { color: theme.dim, children: truncateDisplay(workspaceLine, innerWidth) }),
@@ -19140,10 +20065,10 @@ function WorkspacePreparationView({
         step2.glyph,
         " "
       ] }),
-      /* @__PURE__ */ jsx4(Text4, { bold: step2.state === "active", color: step2.state === "pending" ? theme.dim : theme.textStrong, children: truncateDisplay(step2.label, compact2 ? 8 : 10) }),
+      /* @__PURE__ */ jsx4(Text4, { bold: step2.state === "active", color: step2.state === "pending" ? theme.dim : theme.textStrong, children: truncateDisplay(step2.label, compact3 ? 8 : 10) }),
       /* @__PURE__ */ jsxs4(Text4, { color: step2.state === "active" ? theme.muted : theme.dim, children: [
         "  ",
-        truncateDisplay(step2.detail, Math.max(1, innerWidth - displayWidth(step2.glyph) - (compact2 ? 12 : 14)))
+        truncateDisplay(step2.detail, Math.max(1, innerWidth - displayWidth(step2.glyph) - (compact3 ? 12 : 14)))
       ] })
     ] }, step2.id)) }),
     /* @__PURE__ */ jsxs4(Box3, { marginTop: 1, children: [
@@ -19284,9 +20209,9 @@ async function runWorkspacePreparation(engine, config, options = {}) {
   await instance.waitUntilExit();
   return result ?? { status: "cancelled" };
 }
-function preparationLabel(phase, progress, readiness, compact2 = false) {
+function preparationLabel(phase, progress, readiness, compact3 = false) {
   if (phase === "ready") {
-    if (compact2) return "Index verified";
+    if (compact3) return "Index verified";
     return readiness?.rebuilt ? "Workspace index created and verified" : "Workspace index verified";
   }
   if (phase === "error") return "Workspace preparation failed";
@@ -19690,7 +20615,7 @@ function OnboardingFlow({ initialConfig, saveConfig, onFinish }) {
   }, [finish, saveConfig, state]);
   return /* @__PURE__ */ jsx5(OnboardingScreen, { state, dispatch, width, compact: compactHeight });
 }
-function OnboardingScreen({ state, dispatch, width, compact: compact2 = false }) {
+function OnboardingScreen({ state, dispatch, width, compact: compact3 = false }) {
   const theme = useTheme();
   const ascii = process.env.SKEIN_GLYPHS === "ascii" || process.env.MOSAIC_GLYPHS === "ascii";
   const marker = ascii ? ">" : "\u203A";
@@ -19707,14 +20632,14 @@ function OnboardingScreen({ state, dispatch, width, compact: compact2 = false })
     ] }),
     /* @__PURE__ */ jsx5(Text6, { color: theme.border, children: truncateDisplay(stageDivider(ascii, headerWidth), headerWidth) }),
     /* @__PURE__ */ jsx5(Text6, { color: theme.dim, children: truncateDisplay(stage.name, headerWidth) }),
-    !compact2 ? /* @__PURE__ */ jsx5(Box4, { height: 1 }) : null,
+    !compact3 ? /* @__PURE__ */ jsx5(Box4, { height: 1 }) : null,
     /* @__PURE__ */ jsx5(Text6, { color: theme.textStrong, bold: true, children: truncateDisplay(titleForStep(state.step), headerWidth) }),
-    !compact2 ? /* @__PURE__ */ jsx5(Text6, { color: theme.muted, wrap: "wrap", children: descriptionForStep(state) }) : null,
+    !compact3 ? /* @__PURE__ */ jsx5(Text6, { color: theme.muted, wrap: "wrap", children: descriptionForStep(state) }) : null,
     summary ? /* @__PURE__ */ jsx5(Text6, { color: theme.dim, children: truncateDisplay(summary, headerWidth) }) : null,
-    !compact2 ? /* @__PURE__ */ jsx5(Box4, { height: 1 }) : null,
-    state.step === "method" ? /* @__PURE__ */ jsx5(OptionList, { options: methods, selected: state.selected, marker, width: headerWidth, compact: compact2 }) : null,
-    state.step === "official-provider" ? /* @__PURE__ */ jsx5(OptionList, { options: officialProviders, selected: state.selected, marker, width: headerWidth, compact: compact2 }) : null,
-    state.step === "relay-protocol" ? /* @__PURE__ */ jsx5(OptionList, { options: relayProtocols, selected: state.selected, marker, width: headerWidth, compact: compact2 }) : null,
+    !compact3 ? /* @__PURE__ */ jsx5(Box4, { height: 1 }) : null,
+    state.step === "method" ? /* @__PURE__ */ jsx5(OptionList, { options: methods, selected: state.selected, marker, width: headerWidth, compact: compact3 }) : null,
+    state.step === "official-provider" ? /* @__PURE__ */ jsx5(OptionList, { options: officialProviders, selected: state.selected, marker, width: headerWidth, compact: compact3 }) : null,
+    state.step === "relay-protocol" ? /* @__PURE__ */ jsx5(OptionList, { options: relayProtocols, selected: state.selected, marker, width: headerWidth, compact: compact3 }) : null,
     inputField ? /* @__PURE__ */ jsxs5(Box4, { flexDirection: "column", children: [
       /* @__PURE__ */ jsxs5(Box4, { children: [
         /* @__PURE__ */ jsx5(Text6, { color: theme.textStrong, bold: true, children: inputField.label }),
@@ -19742,18 +20667,18 @@ function OnboardingScreen({ state, dispatch, width, compact: compact2 = false })
       "! ",
       truncateDisplay(state.error, Math.max(1, headerWidth - 2))
     ] }) : null,
-    !compact2 ? /* @__PURE__ */ jsx5(Box4, { height: 1 }) : null,
+    !compact3 ? /* @__PURE__ */ jsx5(Box4, { height: 1 }) : null,
     /* @__PURE__ */ jsx5(Text6, { color: theme.dim, children: footerForStep(state, headerWidth) })
   ] });
 }
-function OptionList({ options, selected, marker, width, compact: compact2 }) {
+function OptionList({ options, selected, marker, width, compact: compact3 }) {
   const theme = useTheme();
-  return /* @__PURE__ */ jsx5(Box4, { flexDirection: "column", children: options.map((option, index) => {
+  return /* @__PURE__ */ jsx5(Box4, { flexDirection: "column", children: options.map((option2, index) => {
     const active = index === selected;
     const prefix = active ? `${marker} ` : "  ";
     const available = Math.max(1, width - displayWidth(prefix) - (active ? 2 : 0));
-    const label = `${prefix}${truncateDisplay(option.label, available)}`;
-    return /* @__PURE__ */ jsxs5(Box4, { flexDirection: "column", marginBottom: compact2 || index === options.length - 1 ? 0 : 1, children: [
+    const label = `${prefix}${truncateDisplay(option2.label, available)}`;
+    return /* @__PURE__ */ jsxs5(Box4, { flexDirection: "column", marginBottom: compact3 || index === options.length - 1 ? 0 : 1, children: [
       /* @__PURE__ */ jsx5(
         Text6,
         {
@@ -19763,8 +20688,8 @@ function OptionList({ options, selected, marker, width, compact: compact2 }) {
           children: active ? padDisplay(label, width) : label
         }
       ),
-      !compact2 && width >= 36 || active ? /* @__PURE__ */ jsx5(Box4, { marginLeft: 2, width: Math.max(1, width - 2), children: /* @__PURE__ */ jsx5(Text6, { color: active ? theme.muted : theme.dim, wrap: "wrap", children: option.detail }) }) : null
-    ] }, option.label);
+      !compact3 && width >= 36 || active ? /* @__PURE__ */ jsx5(Box4, { marginLeft: 2, width: Math.max(1, width - 2), children: /* @__PURE__ */ jsx5(Text6, { color: active ? theme.muted : theme.dim, wrap: "wrap", children: option2.detail }) }) : null
+    ] }, option2.label);
   }) });
 }
 function Confirmation({ state, width }) {
@@ -19827,7 +20752,7 @@ function titleForStep(step2) {
   return "Saving configuration";
 }
 function descriptionForStep(state) {
-  if (state.step === "method") return "Pick one connection path. You can change it later with configuration.";
+  if (state.step === "method") return "Skein's primary agent needs an API credential. OpenAI, Anthropic, and Gemini subscription logins are not API keys; signed-in coding CLIs are separate delegated tools.";
   if (state.step === "official-provider") return "Use the API credential issued by the selected provider.";
   if (state.step === "relay-protocol") return "The protocol is explicit so requests and credentials are never guessed.";
   if (state.step === "endpoint") return "Remote endpoints require HTTPS. Loopback development servers may use HTTP.";
@@ -21465,7 +22390,7 @@ process.on("warning", (warning) => {
 var program = new Command();
 program.enablePositionalOptions();
 program.name(PRODUCT_COMMAND).description("A context-first, model-agnostic coding agent with an auditable workspace.").version(package_default.version).showSuggestionAfterError();
-program.argument("[prompt...]", "instruction for the agent").option("-p, --print", "run once and print the result").option("-a, --ask", "retrieval and inspection mode; mutation tools are denied").option("--plan", "read-only planning mode; propose changes without mutating the workspace").option("-q, --quiet", "print only the final response in text mode").addOption(new Option("--output-format <format>", "text, json, or stream-json").choices(["text", "json", "stream-json"]).default("text")).option("--compact", "reduce progress output in print mode").option("--yes", "approve all non-denied tool requests for this run").option("--auto-edit", "approve read/write requests and ask before shell/Git/network").option("--trust-project-config", "allow executable and security-sensitive settings from project config").option("--queue <prompt>", "run an additional prompt after the first one", collect, []).option("-w, --workspace <path>", "primary workspace root", process.cwd()).option("--add-workspace <path>", "additional workspace root", collect, []).option("--config <path>", "explicit config file").option("--provider <provider>", "model provider").option("--model <model>", "model identifier").option("--base-url <url>", "OpenAI-compatible or provider base URL").option("--max-turns <n>", "maximum agent turns").option("--token-budget <n>", "maximum cumulative session tokens").option("--resume [session]", "resume a session by id or prefix").option("-c, --continue", "resume the latest session").option("--no-color", "disable color output").option("--no-checkpoint", "disable pre-mutation checkpoints for this run").action(async (prompts, options) => {
+program.argument("[prompt...]", "instruction for the agent").option("-p, --print", "run once and print the result").option("-a, --ask", "retrieval and inspection mode; mutation tools are denied").option("--plan", "read-only planning mode; propose changes without mutating the workspace").option("-q, --quiet", "print only the final response in text mode").addOption(new Option("--output-format <format>", "text, json, or stream-json").choices(["text", "json", "stream-json"]).default("text")).option("--compact", "reduce progress output in print mode").option("--yes", "approve all non-denied tool requests for this run").option("--auto-edit", "approve read/write requests and ask before shell/Git/network").option("--trust-project-config", "allow executable and security-sensitive settings from project config").option("--queue <prompt>", "run an additional prompt after the first one", collect, []).option("-w, --workspace <path>", "primary workspace root", process.cwd()).option("--add-workspace <path>", "additional workspace root", collect, []).option("--config <path>", "explicit config file").option("--provider <provider>", "model provider").option("--model <model>", "model identifier").option("--base-url <url>", "OpenAI-compatible or provider base URL").option("--max-turns <n>", "maximum agent turns").option("--epoch-token-budget <n>", "maximum tokens before an internal context handoff").option("--token-budget <n>", "maximum lifetime tokens across the resumed session").option("--resume [session]", "resume a session by id or prefix").option("-c, --continue", "resume the latest session").option("--no-color", "disable color output").option("--no-checkpoint", "disable pre-mutation checkpoints for this run").action(async (prompts, options) => {
   await runChat(prompts, options);
 });
 program.command("init").description("Create a project-local config (preserving an existing .mosaic namespace)").option("-w, --workspace <path>", "workspace root").option("--provider <provider>", "openai, anthropic, gemini, or compatible", "openai").option("--model <model>", "model identifier").option("--base-url <url>", "provider base URL").option("--api-key <key>", "store a provider key in project config (prefer env vars)").option("--index", "build the index after writing config").option("--yes", "use defaults without prompting").action(async (options) => {
@@ -22071,14 +22996,26 @@ async function runCli() {
   try {
     await program.parseAsync(process.argv);
   } catch (error) {
-    const message2 = error instanceof Error ? error.message : String(error);
-    process.stderr.write(`${chalk4.red(cliGlyphs.error)} ${message2}
+    const format = structuredOutputFormat(process.argv);
+    if (format) {
+      const reporter = new HeadlessReporter({ format, color: false });
+      process.exitCode = reporter.fail(error).exitCode;
+    } else {
+      const message2 = error instanceof Error ? error.message : String(error);
+      process.stderr.write(`${chalk4.red(cliGlyphs.error)} ${message2}
 `);
-    process.exitCode = 1;
+      process.exitCode = 1;
+    }
   } finally {
     releaseCliNamespaceLeases(cliNamespaceLeases);
   }
 }
+function structuredOutputFormat(argv) {
+  const inline = argv.find((argument) => argument.startsWith("--output-format="))?.slice("--output-format=".length);
+  const index = argv.indexOf("--output-format");
+  const value = inline ?? (index >= 0 ? argv[index + 1] : void 0);
+  return value === "json" || value === "stream-json" ? value : void 0;
+}
 async function runChat(prompts, options) {
   const shouldPrint = options.print === true || !process.stdin.isTTY || !process.stdout.isTTY;
   if (options.ask && options.plan) throw new Error("--ask and --plan cannot be used together.");
@@ -22146,7 +23083,8 @@ async function runChat(prompts, options) {
     color: (options.color ?? config.ui.color) && !process.env.NO_COLOR
   });
   const colorOutput = (options.color ?? config.ui.color) && !process.env.NO_COLOR;
-  const requestPermission = options.yes ? async () => true : options.autoEdit ? async (_call, category) => category === "read" || category === "write" ? true : askConsolePermission(_call, category, colorOutput) : async (call, category) => askConsolePermission(call, category, colorOutput);
+  const requestPermission = options.yes ? async () => true : options.autoEdit ? async (_call, category, reason) => category === "read" || category === "write" ? true : askConsolePermission(_call, category, colorOutput, reason) : async (call, category, reason) => askConsolePermission(call, category, colorOutput, reason);
+  let extensionsClosed = false;
   try {
     let session = await runner.run(firstPrompt, {
       askMode: options.ask === true || options.plan === true,
@@ -22156,6 +23094,7 @@ async function runChat(prompts, options) {
       requestPermission
     });
     for (const queued of options.queue) {
+      if (session.pendingInput) break;
       session = await runner.run(queued, {
         askMode: options.ask === true || options.plan === true,
         ...options.plan ? { turnInstructions: PLAN_MODE_INSTRUCTIONS } : {},
@@ -22164,12 +23103,15 @@ async function runChat(prompts, options) {
         requestPermission
       });
     }
-    reporter.finish(session);
+    await extensions.close();
+    extensionsClosed = true;
+    const outcome2 = reporter.finish(session);
+    process.exitCode = outcome2.exitCode;
   } catch (error) {
-    reporter.fail(error);
-    process.exitCode = 1;
+    const outcome2 = reporter.fail(error, runner.getSession());
+    process.exitCode = outcome2.exitCode;
   } finally {
-    await extensions.close();
+    if (!extensionsClosed) await extensions.close().catch(() => void 0);
   }
 }
 async function openMemoryStore(config) {
@@ -22333,6 +23275,7 @@ async function runtimeConfig(workspaceInput, options) {
     agent: {
       ...loaded.agent,
       ...options.checkpoint === false ? { checkpointBeforeWrite: false } : {},
+      ...options.epochTokenBudget ? { maxEpochTokens: positiveInt(options.epochTokenBudget, loaded.agent.maxEpochTokens ?? loaded.agent.maxSessionTokens) } : {},
       ...options.tokenBudget ? { maxSessionTokens: positiveInt(options.tokenBudget, loaded.agent.maxSessionTokens) } : {}
     },
     ui: { ...loaded.ui, ...options.color === false ? { color: false } : {} }
@@ -22482,6 +23425,7 @@ function runtimeOptions(options) {
   const provider = options.provider ?? root.provider;
   const model = options.model ?? root.model;
   const baseUrl = options.baseUrl ?? root.baseUrl;
+  const epochTokenBudget = options.epochTokenBudget ?? root.epochTokenBudget;
   const tokenBudget = options.tokenBudget ?? root.tokenBudget;
   return {
     addWorkspace: [...root.addWorkspace ?? [], ...options.addWorkspace ?? []],
@@ -22490,6 +23434,7 @@ function runtimeOptions(options) {
     ...model ? { model } : {},
     ...baseUrl ? { baseUrl } : {},
     ...options.maxTokens ? { maxTokens: options.maxTokens } : {},
+    ...epochTokenBudget ? { epochTokenBudget } : {},
     ...tokenBudget ? { tokenBudget } : {},
     ...root.color !== void 0 ? { color: root.color } : {},
     ...root.checkpoint !== void 0 ? { checkpoint: root.checkpoint } : {},