@skein-code/cli 0.3.11 → 0.3.12

package/docs/ARCHITECTURE.md

@@ -34,8 +34,8 @@
 ## Agent turn
 
 1. Resolve `@path` mentions inside configured workspace roots.
-2. Ask the local context engine for task-relevant spans under the configured
-   token budget.
+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,
    and conversation history.
 4. Call the model with the tools allowed by the current mode.
@@ -43,8 +43,10 @@
 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
    conversation.
-8. Continue until the model returns a final response or the turn limit is hit.
-9. Run configured verification commands after changes. The completion gate accepts
+8. 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. 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`,
@@ -116,6 +118,22 @@ are reconciled against storage before the readback tool can be exposed. Deleting
 a session removes its artifact directory. Session JSON and JSONL events carry
 only receipts and bounded previews, never artifact contents.
 
+## Token ledger and adaptive retrieval
+
+Each model request appends a maximum-256-entry token ledger to its session. A
+receipt contains only a request ID, turn, timestamp, partition counts, actual
+provider counters when present, measurement source, loaded tool names, and
+retrieval selection metadata. It never contains prompt text, workspace rules,
+source snippets, tool schemas, arguments, results, or credentials. Legacy
+sessions without provenance remain readable and are labelled `unknown` rather
+than being reported as actual usage.
+
+The local context ceiling is allocated by task shape: 2k for focused evidence,
+4k for ordinary work, 8k for cross-module or repository-wide work, and 12k only
+for explicitly exhaustive multi-part work. Each receipt reports its reason and
+the number of candidate, selected, overlapping, and budget-capped spans. These
+are estimated provider-neutral planning values, not billing claims.
+
 ## Local context selection
 
 The context boundary is deliberately in-process and local:

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.11`.
+- Current repository version: `0.3.12`.
 - 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.11.tgz`. The verifier writes
-its SHA-256 to `artifacts/package/skein-code-cli-0.3.11.tgz.sha256`, and CI
+The latest verified package is `skein-code-cli-0.3.12.tgz`. The verifier writes
+its SHA-256 to `artifacts/package/skein-code-cli-0.3.12.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.
@@ -78,13 +78,12 @@ Implementation notes:
 - `npm run release:verify` reproduces the package from source, installs it into
   an isolated prefix, rejects packaged local state, and exercises `skein`,
   `mosaic`, and `mosaic-code`.
-- The `main` branch rule requires the strict `check` status. Version 0.3.11
-  gives every tool-result path a language-aware dynamic token firewall, retains
-  complete captured output as redacted session-scoped artifacts, exposes
-  SHA-bound line or UTF-8 byte readback only when storage receipts agree, and
-  makes upstream shell/MCP truncation explicit. Session deletion and expiry
-  remove retained output; ordinary short result events keep their existing
-  shape.
+- The `main` branch rule requires the strict `check` status. Version 0.3.12
+  adds privacy-safe per-request token receipts, actual-versus-estimated usage
+  provenance, prompt partition accounting, and adaptive 2k/4k/8k/12k local
+  retrieval budgets. Session telemetry stores counts, tool names, selection
+  decisions, and discard reasons, never prompt, source, schema, argument, or
+  tool-result content.
   Its tag, GitHub verification, and npm publication use the same source commit.
 
 ### P1: Skein Storage Namespace And Migration

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skein-code/cli",
-  "version": "0.3.11",
+  "version": "0.3.12",
   "description": "A context-first, model-agnostic coding agent with an auditable terminal workspace.",
   "type": "module",
   "license": "MIT",
@@ -16,9 +16,9 @@
   },
   "skein": {
     "releaseNotes": [
-      "Large tool results now use a language-aware dynamic token budget with status-preserving head and tail receipts",
-      "Complete captured output can be read back through redacted, expiring, session-scoped local artifacts",
-      "Shell and MCP source truncation is explicit, and session deletion removes retained output"
+      "Each model request records privacy-safe token partitions and actual-versus-estimated provenance",
+      "Local retrieval now selects focused, standard, broad, or maximum evidence budgets",
+      "Terminal and JSON diagnostics expose budget decisions without storing prompt or source content"
     ]
   },
   "bin": {