@skein-code/cli 0.3.23 → 0.3.25

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.23`.
+- Current repository version: `0.3.25`.
 - 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.23.tgz`. The verifier writes
-its SHA-256 to `artifacts/package/skein-code-cli-0.3.23.tgz.sha256`, and CI
+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
 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.
@@ -124,6 +124,32 @@ the model explicitly calls `mcp_activate` for a configured server. The release
 does not add per-server trust scopes, provider billing A/B, or Context
 Compaction 2.0.
 
+Version `0.3.24` completes the Context Compaction 2.0 engineering slice. Each
+handoff rebuilds a deterministic facts envelope from the Task Contract,
+working state, changed files, last-run verification, permission and failure
+audit, retained artifact handles, and bounded older user corrections. Generated
+narrative is fallible and optional; empty or contradictory output cannot erase
+the authoritative facts, and the complete transcript remains persisted.
+Automatic compaction calls the provider only when three predicted future prompt
+reuses yield positive net estimated savings; explicit `/compact` remains a
+manual override. Provider-reported or locally estimated compaction usage is
+included in session totals and a separate content-free receipt. JSON/JSONL and
+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.
+
 ### P0-D: Repository reuse and calibrated duplication enforcement
 
 Version `0.3.14` added the prompt ladder and pre-write `ReuseReceipt`. Version
@@ -377,6 +403,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/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.23",
+  "version": "0.3.25",
   "description": "A context-first, model-agnostic coding agent with an auditable terminal workspace.",
   "type": "module",
   "license": "MIT",
@@ -16,6 +16,15 @@
   },
   "skein": {
     "releaseNotes": [
+      "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",
+      "Empty or lossy narratives cannot erase deterministic facts, and the complete persisted transcript remains unchanged",
       "Normal chat startup now exposes a compact mcp_activate catalog instead of eagerly connecting MCP servers",
       "MCP activation connects one selected server, discovers remote tools, and loads at most eight relevant schemas",
       "Explicit MCP diagnostics can still connect eagerly while all MCP activation and remote calls remain network operations",