@skein-code/cli 0.3.25 → 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.25",
+  version: "0.3.26",
   description: "A context-first, model-agnostic coding agent with an auditable terminal workspace.",
   type: "module",
   license: "MIT",
@@ -236,6 +236,12 @@ 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",
@@ -11975,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(
@@ -11996,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
     });
   }
@@ -13649,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 });
@@ -15009,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;
@@ -15018,7 +15079,6 @@ var HeadlessReporter = class {
   options;
   finalResponse = "";
   tools = [];
-  eventError;
   context;
   streamedAssistant = false;
   completion;
@@ -15028,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;
@@ -15046,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()}
@@ -15080,17 +15146,34 @@ ${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: compact3 } = this.options;
@@ -15197,6 +15280,7 @@ ${this.glyphs.meta} ${session.changedFiles.length} changed files ${this.glyphs.s
         break;
       case "done":
         this.printCompletion(event.completion);
+        this.printStopReason(event.reason);
         break;
       case "error":
         break;
@@ -15227,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();
@@ -15236,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 {
@@ -15245,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 };
@@ -15350,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";
@@ -15374,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]"),
@@ -15430,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 [
@@ -16407,7 +16538,7 @@ function TaskRail({ tasks, width = 80, glyphMode = "auto", maxItems }) {
     ] }) : null
   ] });
 }
-function PermissionCard({ call, category, width = 80, glyphMode = "auto", workspace, compact: compact3 = 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);
@@ -16415,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 = [
@@ -16440,6 +16573,8 @@ 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 }),
@@ -16460,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);
@@ -17744,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) {
@@ -17841,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++}`;
@@ -18184,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) {
@@ -18205,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,
@@ -18309,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":
@@ -18348,7 +18614,7 @@ function SkeinApp({ runner, config, extensions, initialPrompt, askMode = false,
       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":
@@ -18372,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;
@@ -18386,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;
@@ -18470,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;
@@ -18626,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;
@@ -18956,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: [
@@ -19026,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) {
@@ -19040,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);
@@ -19079,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();
     }
@@ -19422,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,
       {
@@ -19562,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";
@@ -19579,6 +19936,9 @@ function shouldDeferLocalCommand(value) {
     "remember",
     "diff",
     "checkpoints",
+    "audit",
+    "rollback",
+    "recover",
     "workflow",
     "exit",
     "quit"
@@ -19598,7 +19958,7 @@ function composerAttachments(value) {
   return [...new Set(paths)].slice(-3);
 }
 function permissionRows(width, hasCwd, compact3) {
-  const content = 3 + (hasCwd ? 1 : 0);
+  const content = 5 + (hasCwd ? 1 : 0);
   if (width >= 64) return content + 2;
   if (width >= 28) return content + 3;
   if (compact3) return content + 3;
@@ -20392,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.";
@@ -22636,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.");
@@ -22711,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,
@@ -22730,13 +23103,15 @@ async function runChat(prompts, options) {
         requestPermission
       });
     }
-    reporter.finish(session);
-    if (session.pendingInput) process.exitCode = 2;
+    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) {