@skein-code/cli 0.3.11 → 0.3.13

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`,
@@ -73,6 +75,12 @@ stay in a retry/exit state and occur before an empty session is persisted.
 Headless runs retain non-animated lazy indexing so structured automation does
 not acquire terminal-only behavior.
 
+Known mutations take a narrower path: the runner validates tool-reported
+`changedFiles`, marks them dirty, targeted-upserts or deletes only those paths,
+and atomically persists the new generation before returning the tool result.
+Manifest reconciliation additionally compares ctime, closing same-size changes
+whose mtime is restored without hashing every source file on an empty query.
+
 ### Prompt layers
 
 The runner keeps the cacheable system prefix separate from mutable task state:
@@ -116,6 +124,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.13`.
 - 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,16 +41,16 @@ 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.13.tgz`. The verifier writes
+its SHA-256 to `artifacts/package/skein-code-cli-0.3.13.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.
 
-The final verification included a fresh install and real PTY interaction for
-all three executable aliases, `/about`, a permission prompt, denial, and clean
-Ctrl+C exit. PTY coverage included 20, 24 ASCII, 40, 80, 120 columns and a
-40x10 short-height case. The current 42-file, 424-test suite passes the full check.
+The final verification included a fresh install for all three executable
+aliases. PTY coverage included 20, 24 ASCII, 40, 80, 120 columns and a 40x10
+short-height case. The current full-suite count is recorded from the latest
+`npm run check` in the release evidence.
 
 ## Recommended Order
 
@@ -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.13
+  retains v0.3.12's privacy-safe per-request token ledger and adaptive budgets,
+  then adds targeted known-change index refresh, ctime freshness reconciliation,
+  and bounded no-progress search recovery. Session telemetry stores counts,
+  tool names, selection decisions, and hashes, 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
@@ -148,9 +147,10 @@ Implementation progress:
 
 ### P1: Local Context Engine Reliability And Benchmarking
 
-Keep retrieval local and measurable as the repository grows. The next slice
-should add content hashes to index entries, a small generation-keyed query cache,
-overlap-aware packing, and language adapters for common declaration styles.
+Keep retrieval local and measurable as the repository grows. Content hashes,
+generation-keyed query caching, overlap-aware packing, adaptive budgets, and
+targeted known-change refresh are now implemented. The next retrieval slice is
+language adapters and the expanded multilingual benchmark.
 
 Definition of done:
 
@@ -167,8 +167,12 @@ Implementation progress:
 - The public `pack/search/index/status` boundary is now a pure local façade.
 - Legacy external configuration is stripped at the config schema boundary and
   no external executable or database is probed by the CLI.
-- Remaining work is content-hash freshness, cache invalidation, structured
-  chunking, and the reproducible benchmark.
+- Tool-reported creates, updates, and deletes refresh only affected paths and
+  atomically persist before the next turn in TUI or headless mode.
+- Size/mtime/ctime reconciliation closes the direct-new-query zero-hit window;
+  repeated empty or unchanged searches stop through the recovery circuit.
+- Remaining work is broader language adapters and production-scale benchmark
+  calibration; the reproducible benchmark pipeline already exists.
 
 ### P1: Multi-Agent Scheduler And Team UX
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skein-code/cli",
-  "version": "0.3.11",
+  "version": "0.3.13",
   "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"
+      "Known tool changes refresh only their affected local-index paths before the next model turn",
+      "File ctime closes same-size and restored-mtime zero-hit freshness gaps without full-content scans",
+      "Repeated empty or unchanged search calls stop through the existing recovery circuit"
     ]
   },
   "bin": {