@skein-code/cli 0.3.24 → 0.3.26

package/README.md

@@ -96,7 +96,7 @@ To build, verify, and install a local package artifact from this checkout:
 
 ```bash
 npm run verify:package -- --output-dir artifacts/package
-npm install -g ./artifacts/package/skein-code-cli-0.3.24.tgz
+npm install -g ./artifacts/package/skein-code-cli-0.3.26.tgz
 ```
 
 To install the published package from npm:
@@ -278,6 +278,24 @@ allowed by policy. Use `--auto-edit` to allow file edits while retaining prompts
 for shell/Git/network, or `--yes` for intentionally unattended runs. Hard deny
 rules still win over both flags.
 
+JSON emits one `type: "result"` object; JSONL ends with a `type: "session"`
+record, or `type: "final"` after a runtime error. These terminal records follow
+[`docs/headless-output.schema.json`](docs/headless-output.schema.json), include
+`schemaVersion: 1`, `status`, `reason`, and `exitCode`, and use this stable
+exit-code contract:
+
+| Code | Status | Meaning |
+| ---: | --- | --- |
+| 0 | `completed`, `verified` | The read-only run completed or current changes were verified. |
+| 1 | `error` | Setup, provider, extension, or runtime failure. |
+| 2 | `needs_input` | One persisted clarification is required; resume the same session. |
+| 3 | `unverified` | Changes or required acceptance evidence remain unverified. |
+| 4 | `verification_failed` | A current verification command failed. |
+| 5 | `blocked` | The active Task Contract records a blocked required criterion. |
+| 6 | `cancelled` | The run was interrupted; its session state was saved. |
+| 7 | `max_turns` | The configured turn limit ended the run. |
+| 8 | `token_budget` | The lifetime token budget ended the run. |
+
 ## Commands
 
 ```text
@@ -296,6 +314,8 @@ skein session list|show|delete       local session management
 skein session export <id>            Markdown audit export
 skein checkpoint list <session>      inspect snapshots
 skein checkpoint restore <s> <c>     restore a snapshot
+skein /review [scope]                 read-only fixed-scope review in the TUI
+skein /recover [action]               recovery status, retry, resume, diff, audit, rollback
 skein tools                          tool schemas and categories
 skein rules                          loaded user/workspace rule files
 ```
@@ -366,7 +386,10 @@ permissions:
 
 agent:
   maxTurns: 24
-  maxSessionTokens: 250000
+  # Rotate deterministic context handoffs without changing the session id.
+  maxEpochTokens: 250000
+  # Hard lifetime cost/usage ceiling across every resumed epoch.
+  maxSessionTokens: 1000000
   autoVerify: true
   verifyCommands:
     - npm run typecheck
@@ -379,6 +402,20 @@ hooks:
   afterTurn: []
 ```
 
+`--epoch-token-budget` overrides the handoff boundary for one invocation;
+`--token-budget` remains the hard lifetime ceiling. Reaching an epoch boundary
+keeps the complete transcript and cumulative usage, validates Task Contract,
+failure, changed-file, and verification state, then continues in the same
+session with a bounded active window. The Context inspector shows both meters.
+
+For complex executable requests, Skein records an Intent Sufficiency receipt
+before model-driven mutation. Explicit requests proceed directly; repository
+facts are inspected rather than asked back to the user; a genuine product
+choice such as public-API compatibility pauses with one question and two or
+three concrete options. Headless JSON/JSONL emits `needs_input`, persists the
+question, performs no mutation, and exits with status 2. The next reply resumes
+the same logical run. Permission approval remains a separate runtime gate.
+
 See [examples/config.yaml](examples/config.yaml) for a ready-to-adapt file.
 Secrets should normally stay in environment variables instead of committed
 configuration.