@skein-code/cli 0.3.24 → 0.3.26

package/docs/ARCHITECTURE.md

@@ -36,20 +36,23 @@
 1. Resolve `@path` mentions inside configured workspace roots.
 2. Classify the task evidence surface and ask the local context engine for
    task-relevant spans under an adaptive budget capped by configuration.
-3. Combine product rules, project rules, retrieved spans, mentions, current plan,
+3. Run the Intent Sufficiency Gate. Clear requests execute; repository-derived
+   gaps route to inspection; only user-owned product choices create a persisted
+   `needs_input` state. Shell/Git/network approval remains a separate policy.
+4. Combine product rules, project rules, retrieved spans, mentions, current plan,
    and conversation history.
-4. Call the model with the tools allowed by the current mode.
-5. Evaluate every requested tool against workspace and permission policy.
-6. Create a checkpoint before the first mutation in a tool batch.
-7. Execute tools, emit events, and append their grounded results to the model
+5. Call the model with the tools allowed by the current mode.
+6. Evaluate every requested tool against workspace and permission policy.
+7. Create a checkpoint before the first mutation in a tool batch.
+8. Execute tools, emit events, and append their grounded results to the model
    conversation.
-8. Record a bounded, content-free token receipt for the model request and
+9. Record a bounded, content-free token receipt for the model request and
    persist actual provider counters separately from local estimates.
-9. Continue until the model returns a final response or the turn limit is hit.
-10. Before the first substantive write, run the warning-only repository reuse
+10. Continue until the model returns a final response or the turn limit is hit.
+11. Before the first substantive write, run the warning-only repository reuse
     gate. It binds current candidate/read evidence to the request, index
     generation, and change sequence without retaining source text.
-11. Capture content-free TS/JS function fingerprints from that pre-write index
+12. Capture content-free TS/JS function fingerprints from that pre-write index
     generation. After the write succeeds, compare only newly added or at least
     1.5x-expanded functions before refreshing changed index paths. Exact
     normalized hashes identify Type-1/2 clones; winnowed 10-token shingles and
@@ -57,15 +60,33 @@
     matrix calibrates threshold 0.55: unsuppressed Type-1/2 matches block the
     existing completion gate, while Type-3 remains warning-only. Type-4 semantic
     equivalence is explicitly outside this deterministic contract.
-12. Run configured verification commands after changes. The completion gate accepts
+13. Run configured verification commands after changes. The completion gate accepts
    only current successful test, typecheck, lint, build, check, or `git diff
    --check` evidence recorded after the last mutation. An early final response
    receives one bounded recovery turn; the runtime persists `verified`,
    `unverified`, or `verification_failed` instead of trusting completion claims
    in model text.
-13. Persist the outcome and expose the same status through the TUI, text, JSON,
+14. Persist the outcome and expose the same status through the TUI, text, JSON,
     and JSONL surfaces.
 
+## Long-session epoch ledger
+
+A user-visible session has two different token boundaries:
+
+- `agent.maxEpochTokens` (default 250,000) bounds one internal reasoning epoch.
+- `agent.maxSessionTokens` (default 1,000,000) is the hard lifetime ceiling
+  across every epoch and resume.
+
+Crossing the epoch boundary never clears lifetime usage or changes the session
+id. The runner optionally compacts only when predicted reuse has positive net
+savings, then persists a content-free handoff containing the Task Contract
+criterion states and evidence references, unresolved failure circuits, changed
+files, and last-run verification receipts. The next epoch starts with zero
+epoch usage while the transcript and lifetime ledger remain intact. Generated
+narrative is fallible; deterministic handoff facts and fresh tool evidence keep
+precedence. Epochs, pending clarification, and their public reason codes are
+backward-compatible optional session fields and contain no hidden reasoning.
+
 ## Interactive startup gate
 
 New interactive sessions establish local context readiness before creating or

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.24`.
+- 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.24.tgz`. The verifier writes
-its SHA-256 to `artifacts/package/skein-code-cli-0.3.24.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.
@@ -138,6 +138,41 @@ the Context Inspector expose the resulting decision without retaining prompt or
 source text. Paid same-model task-success A/B remains required before closing
 P0-E or making a provider-billing savings claim.
 
+Version `0.3.25` separates one user-visible session into bounded internal
+context epochs and a hard lifetime token ceiling. Epoch rotation preserves the
+same session id and complete transcript while carrying content-free Contract,
+unresolved-failure, changed-file, and verification evidence; an identical
+successful tool call clears its recovered failure from future handoffs. The
+Intent Sufficiency Gate sends clear requests directly to execution, routes
+repository-inferable gaps to inspection, and persists one keyboard-answerable
+question only for genuine user-owned product choices. TUI queues pause during
+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
@@ -391,6 +426,18 @@ optional subprocess sandbox before any marketplace. Do not load arbitrary plugin
 JavaScript in-process; package reusable extensions as data-only Skills/workflows
 plus explicitly trusted MCP servers.
 
+### Delivered: bounded long-session continuity and intent sufficiency
+
+- Durable sessions now separate a 250k-token context epoch from a 1m-token
+  lifetime ceiling. Epoch handoffs retain Contract, failure, changed-file, and
+  verification receipts while preserving the complete transcript and session id.
+- The Context inspector and structured session summary expose epoch/lifetime
+  state, compaction receipts, and handoff evidence without prompt or source text.
+- Complex ambiguous public-API or UI choices pause as `needs_input`; simple
+  requests stay zero-question, repository facts route to inspection, and
+  permission approval remains independent. A numbered or custom answer resumes
+  the same logical run.
+
 ### P2: Memory Quality And User Control
 
 Keep SQLite as the default durable engine. Improve the lifecycle around the

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/examples/config.yaml

@@ -33,7 +33,8 @@ permissions:
 
 agent:
   maxTurns: 24
-  maxSessionTokens: 250000
+  maxEpochTokens: 250000
+  maxSessionTokens: 1000000
   autoVerify: true
   verifyCommands:
     - npm run typecheck

package/package.json

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