@skein-code/cli 0.3.25 → 0.3.26

package/docs/NEXT_STEPS.md

@@ -9,7 +9,7 @@ one of the milestones below.
 
 - Product name: `Skein`; primary executable: `skein`.
 - Compatibility executables: `mosaic` and `mosaic-code`.
-- Current repository version: `0.3.25`.
+- Current repository version: `0.3.26`.
 - Runtime requirement: Node.js `>=22.16.0` (the runtime uses unflagged
   `node:sqlite` with FTS5, and current CLI/build dependencies require this
   Node 22 baseline).
@@ -41,8 +41,8 @@ npm audit --omit=dev
 npm run release:verify -- --output-dir artifacts/package
 ```
 
-The latest verified package is `skein-code-cli-0.3.25.tgz`. The verifier writes
-its SHA-256 to `artifacts/package/skein-code-cli-0.3.25.tgz.sha256`, and CI
+The latest verified package is `skein-code-cli-0.3.26.tgz`. The verifier writes
+its SHA-256 to `artifacts/package/skein-code-cli-0.3.26.tgz.sha256`, and CI
 retains the checksum beside the package metadata. The checksum is deliberately
 not copied into this packaged document because doing so would change the
 archive it describes.
@@ -150,6 +150,29 @@ clarification and resume afterward; text, JSON, and JSONL expose the same
 `needs_input` state. Real same-model success/token A/B remains an external
 validation gate rather than an implied claim of this release.
 
+### Phase 2: First-run, permission, recovery, review, and headless contracts (complete in 0.3.26)
+
+Version `0.3.26` makes the first-run screen explicit that the primary agent
+uses API credentials while provider subscription sessions and signed-in coding
+CLIs remain separate delegated tools. Permission prompts now show the runtime
+policy reason, redacted target, working directory, category risk, and all four
+keyboard outcomes without leaking secrets.
+
+The interactive Recovery Center joins last-run status, content-free failure
+repair hints, changed files, checkpoints, diff, audit, rollback, bounded retry,
+and safe resume. `/review` fixes working-tree, commit, or branch scope, forces
+read-only runner capabilities even from Build mode, and injects a redacted
+content-free evidence bundle as ephemeral turn instructions rather than user
+transcript. Pending clarifications must still be answered directly and cannot
+be consumed by a recovery command.
+
+JSON and JSONL terminal records follow `docs/headless-output.schema.json` v1
+and carry stable statuses plus exit codes for completed/verified, runtime error,
+needs input, unverified, verification failed, blocked, cancelled, max turns,
+and token budget. Text and TUI surfaces provide matching actionable stop and
+recovery guidance. Responsive list clipping keeps the Recovery Center bounded
+in narrow and short terminals.
+
 ### P0-D: Repository reuse and calibrated duplication enforcement
 
 Version `0.3.14` added the prompt ladder and pre-write `ReuseReceipt`. Version

package/docs/headless-output.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skein.dev/schemas/headless-output-v1.json",
+  "title": "Skein headless terminal record v1",
+  "description": "The terminal object emitted by --output-format json or as the final line of --output-format stream-json.",
+  "type": "object",
+  "required": ["schemaVersion", "type", "ok", "status", "exitCode", "reason"],
+  "properties": {
+    "schemaVersion": {"const": 1},
+    "type": {"enum": ["result", "session", "final"]},
+    "ok": {"type": "boolean"},
+    "status": {
+      "enum": [
+        "completed",
+        "verified",
+        "needs_input",
+        "unverified",
+        "verification_failed",
+        "blocked",
+        "cancelled",
+        "max_turns",
+        "token_budget",
+        "error"
+      ]
+    },
+    "exitCode": {"type": "integer", "minimum": 0, "maximum": 8},
+    "reason": {"type": "string", "minLength": 1},
+    "response": {"type": "string"},
+    "error": {"type": "string"},
+    "session": {"type": "object"},
+    "completion": {"type": "object"},
+    "context": {"type": "object"},
+    "tools": {"type": "array"}
+  },
+  "additionalProperties": true
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "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",
@@ -16,6 +16,12 @@
   },
   "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",