token-harness 0.1.3 → 0.1.6

package/README.md

@@ -1,51 +1,81 @@
 # Token Harness
 
-Token Harness has one objective: **reduce the tokens consumed by coding agents without hiding
-useful information or overstating the result**.
+Token Harness has one objective: **maximize the useful coding work you can get from Claude Code
+and Codex usage limits, without hiding quality regressions or pretending that opaque subscription
+quota is exactly equivalent to a token count**.
 
-Coding sessions repeatedly send test logs, command output, repository context, MCP schemas,
-tool results, and conversation history back to the model. Specialized tools can reduce each of
-those sources, but installing them independently creates a second problem: overlapping hooks,
-double reduction, incompatible configurations, and savings counted more than once.
+The scarce resource is no longer just model context. Subscription users are constrained by rolling
+usage windows, weekly limits, model-dependent burn, long-session context growth, MCP/tool schema
+overhead, noisy tool output, and repeated work after poor model or effort choices. Token Harness is
+evolving from a token-reduction control plane into a **quota-aware efficiency layer** for coding
+harnesses.
 
-Token Harness is the control plane for that optimization stack. It finds the coding agents and
-token-saving tools on the machine, selects a compatible owner for each interception point, shows
-every proposed change before applying it, verifies whether the integration is genuinely being
-used, and reports how many tokens or characters were saved.
+The product therefore optimizes two related budgets:
 
-The reduction still happens inside specialized providers such as RTK and HarnessTrim. Token
-Harness makes those providers safe to combine, observable, reversible, and comparable.
+1. **subscription headroom** — observe the usage windows the harness itself exposes, pace work
+   against reset time, and choose native model/effort settings that fit the task and remaining
+   budget;
+2. **context sent to the model** — keep instructions, MCP schemas, conversation history, repository
+   context, and tool output as small as possible without removing information needed to finish the
+   task correctly.
+
+RTK and HarnessTrim remain useful providers, but reducers are now one layer of the system rather
+than the product definition. Native harness controls come first because choosing the right model,
+effort, context shape, and enabled tools can avoid an expensive turn entirely.
+
+## What Token Harness should optimize
+
+| Layer | Target behavior |
+| --- | --- |
+| Usage-window observability | Read five-hour, weekly, model-specific, or credit-backed limits only from surfaces the harness can actually prove; show reset time, headroom, and burn rate |
+| Native model policy | Prefer economical models/effort for routine work, escalate only for tasks whose expected quality benefit justifies the extra quota |
+| Session hygiene | Detect task boundaries, oversized conversations, and stale context; recommend clear/compact/new-session actions before history dominates each turn |
+| Instruction budget | Keep `CLAUDE.md` / `AGENTS.md` concise and hierarchical instead of injecting one large global instruction file everywhere |
+| MCP/tool budget | Disable irrelevant MCP servers, defer schemas where the harness supports it, and expose only the tools required by the current task |
+| Tool-output budget | Reduce logs, diffs, test output, and repeated command results before they re-enter model context |
+| Cross-harness scheduling | When Claude Code and Codex have independent headroom, recommend the harness that can do the task with the best expected quality per remaining quota |
+| Measurement | Correlate quota delta, model/effort, context size, tool traffic, and task outcome; never convert local token savings into an unproven subscription-quota claim |
 
 ## Optimization ecosystem
 
-The long-term goal is to coordinate token savings across the whole coding-agent pipeline. Only
-tools marked **active** are integrated in this release; every other row is a candidate and is
-neither installed nor configured by Token Harness.
+The priority order below is deliberately different from the original Token Harness roadmap. A tool
+is high priority only when it helps **included Claude Code/Codex capacity**, not merely API cost,
+provider routing, or benchmark token counts.
 
-| Tool | Optimization layer | Token Harness status |
+| Tool or surface | Optimization layer | Token Harness direction |
 | --- | --- | --- |
-| [RTK](https://github.com/rtk-ai/rtk) | Shell-command rewriting and command-output reduction | **Active — integrated** |
-| [HarnessTrim](https://github.com/giuliastro/HarnessTrim) | Deterministic reducers, harness adapters, skills, pipes, and MCP reduction | **Active — integrated** |
-| [Dejavu](https://github.com/Salnika/dejavu) | Emit only the delta when command output repeats | Not active — candidate |
-| [Lazy MCP](https://github.com/voicetreelab/lazy-mcp) | Load MCP tool schemas only when needed | Not active — candidate |
-| [repowise](https://github.com/repowise-dev/repowise) | Retrieve task-specific repository context | Not active — candidate |
-| [LiteLLM](https://github.com/BerriAI/litellm) | Model routing, fallbacks, budgets, and usage telemetry | Not active — candidate |
-| [RouteLLM](https://github.com/lm-sys/RouteLLM) | Route simpler requests to less expensive models | Not active — candidate |
-| [vLLM Semantic Router](https://github.com/vllm-project/semantic-router) | Route by task, complexity, tools, and deployment locality | Not active — candidate |
-| [Claude Code Router](https://github.com/musistudio/claude-code-router) | Route coding-agent requests across models and providers with effort-based rules and fallback chains | Not active — candidate · high priority |
-| [LLMRouter](https://github.com/ulab-uiuc/LLMRouter) | Select the model by task complexity, cost, and quality across routing strategies | Not active — candidate · high priority |
-| [Headroom](https://github.com/headroomlabs-ai/headroom) | Compress tool, MCP, file, and RAG payloads | Not active — candidate |
-| [Context Mode](https://github.com/mksglu/context-mode) | Keep raw tool results outside model context | Not active — candidate |
-| [LLMLingua](https://github.com/microsoft/LLMLingua) | Compress long prompts and context | Not active — candidate |
-| [Caveman](https://github.com/JuliusBrussee/caveman) | Reduce visible model-output verbosity | Not active — candidate |
-
-Candidate status means only that the project has identified a useful optimization layer. A tool
-becomes active only after its installation, conflicts, rollback behavior, verification, and
-metrics attribution have been implemented and tested. Token Harness never installs a candidate
-merely because it is present on the machine. Rows marked `high priority` are the next intended
-intake; the admission gates each one carries are recorded in
+| **Claude Code native controls** | Usage status, model/effort choice, context inspection, clear/compact lifecycle | **P0 — build into core**. Prefer native surfaces over third-party credential scraping; discover available models dynamically |
+| **Codex native app-server + profiles** | Structured rate-limit telemetry; model, reasoning effort, verbosity, tool-output and MCP/context controls | **P0 — build into core**. `account/rateLimits/read` is the preferred live quota source when available |
+| [cclimits](https://github.com/cruzanstx/cclimits) | Live/local quota companion across coding tools | **P0 — optional observational companion for Claude**. Token Harness uses only cacheless Claude JSON mode, never reads its credentials, and labels the result `reported` or `cached`. Codex keeps its native app-server reader |
+| [ccusage](https://github.com/ccusage/ccusage) | Local historical token/session/cost analytics for Claude Code and Codex | **P0 — high-priority read-only companion**. Useful for history and baselines; not a substitute for live subscription-limit telemetry |
+| [RTK](https://github.com/rtk-ai/rtk) | Shell-command rewriting and command-output reduction | **P1 — active, keep**. Reduces context that would otherwise be resent on later turns |
+| [HarnessTrim](https://github.com/giuliastro/HarnessTrim) | Deterministic reducers, harness adapters, skills, pipes, and MCP reduction | **P1 — active, keep**. Continue only on proven non-overlapping surfaces |
+| [Lazy MCP](https://gitlab.com/gitlab-org/ai/lazy-mcp) | Load MCP tool schemas only when needed | **P1 — high priority**. Directly attacks schema/context overhead; benchmark against native Codex tool deferral before installing another owner |
+| [Context Mode](https://github.com/mksglu/context-mode) | Keep raw tool/MCP results outside model context | **P2 — alternative broad context owner**. Evaluate against Headroom, not alongside overlapping reducers by default |
+| [Headroom](https://github.com/headroomlabs-ai/headroom) | Compress tool, MCP, file, and RAG payloads | **P2 — alternative broad context owner**. Admit only after pair-specific quality and attribution fixtures |
+| [Dejavu](https://github.com/Salnika/dejavu) | Emit only the delta when command output repeats | **P2 — useful for test/rerun loops** after the normal output-reduction path is measured |
+| [repowise](https://github.com/repowise-dev/repowise) | Retrieve task-specific repository context | **P2 — conditional**. Its MCP overhead must be lower than the repository context it avoids |
+| LiteLLM, Claude Code Router, RouteLLM, LLMRouter, vLLM Semantic Router | Route requests across models/providers | **P3 — overflow/API routing only**. Useful after included quota is exhausted or for explicit external-provider policy; not a core subscription-quota optimizer |
+| [LLMLingua](https://github.com/microsoft/LLMLingua) | Generic prompt compression | **Research only** until a harness-aware lifecycle proves must-keep recall and quality |
+| [Caveman](https://github.com/JuliusBrussee/caveman) | Reduce visible model-output verbosity | **De-prioritized**. Use native verbosity/effort controls first and measure their effect before adding another instruction owner |
+
+Candidate status still means that Token Harness neither installs nor configures the tool until its
+installation, conflicts, rollback behavior, verification, quality gates, and metrics attribution are
+implemented and tested. The intake evidence lives in
 [docs/provider-landscape.md](docs/provider-landscape.md).
 
+### Why generic routers moved down
+
+The original roadmap treated model routers as high priority. For the new objective that is backwards:
+a router can reduce API cost by sending work to another provider while consuming **none of the
+included Claude Code or Codex allowance**, or it can bypass subscription authentication entirely.
+That can be valuable as explicit overflow, but it does not demonstrate better use of the allowance
+the user already paid for.
+
+Token Harness should first exploit the harness-native choices that are actually inside the plan:
+model tier, reasoning effort, verbosity, session lifecycle, instruction size, MCP exposure, and tool
+output. External routing becomes an opt-in second budget, never an invisible shortcut.
+
 ## Quick start
 
 Install the CLI:
@@ -61,15 +91,24 @@ Then run the complete workflow from the project in which you use your coding age
 # 1. Inspect the machine. This does not change agent configuration.
 token-harness doctor
 
-# 2. Preview every proposed change.
+# 2. Inspect subscription headroom and avoidable context. Still read-only.
+token-harness budget
+token-harness context
+token-harness history --since 7d
+token-harness optimize
+
+# Optional: Claude live quota can use an already-installed cclimits build that
+# supports --no-cache-write. Token Harness never installs it automatically.
+
+# 3. Preview every proposed configuration change.
 token-harness plan
 
-# 3. Apply the reviewed plan. This is the first configuration-changing step.
+# 4. Apply the reviewed plan. This is the first configuration-changing step.
 token-harness apply --yes
 
-# 4. Restart the coding agent, then run a normal shell command through it.
+# 5. Restart the coding agent, then run a normal shell command through it.
 
-# 5. Check configuration, real interception evidence, and savings.
+# 6. Check configuration, real interception evidence, and savings.
 token-harness status
 token-harness verify
 token-harness metrics --since 7d
@@ -78,6 +117,144 @@ token-harness metrics --since 7d
 `doctor` ends with a `NEXT` section. If you are unsure what to do, run the command shown
 there.
 
+### Codex: quota-aware optimization example
+
+For a concrete Codex workflow, keep observation and mutation separate:
+
+```sh
+# Read-only: inspect live subscription windows.
+token-harness budget --harness codex
+
+# Read-only: inspect the effective model, reasoning effort, project instructions,
+# MCP servers, and visible tool inventory.
+token-harness context --harness codex
+
+# Read-only: combine quota pacing and context pressure into task-specific advice.
+token-harness optimize --harness codex --task standard --profile balanced
+
+# Dry run: preview supported Codex-native policy changes.
+token-harness plan --harness codex --native-policy
+```
+
+A typical optimization can recommend lowering reasoning effort for routine work when quota is
+under-pace, while keeping the current model until empirical model-tier evidence exists. A plan may
+also include reviewed provider actions such as a HarnessTrim skill install.
+
+Apply the exact stored plan only after reviewing it:
+
+```sh
+token-harness apply --plan <plan-id> --yes
+token-harness context --harness codex
+token-harness verify --harness codex
+```
+
+On supported recent Codex builds, Token Harness uses Codex's native app-server for authoritative
+rate-limit windows, effective configuration, model catalog, MCP inventory, and reviewed native
+configuration writes. It does not infer quota from local token counts.
+
+Useful variants:
+
+```sh
+# More conservative reasoning for routine work.
+token-harness optimize --harness codex --task mechanical --profile economy
+
+# Preserve more quality headroom for difficult work.
+token-harness optimize --harness codex --task hard --profile quality
+
+# Inspect MCP exposure directly.
+token-harness mcp --harness codex
+
+# Compare recent local history when available.
+token-harness history --harness codex --since 7d
+```
+
+### Cross-harness scheduling and compact handoff
+
+`token-harness schedule` is a read-only recommendation, not an automatic router. In the normal
+installed CLI, unknown five-hour and weekly pace fields are hydrated from the same live budget
+observer used by `token-harness budget`. Candidate quality and transfer benefit are hydrated only
+from attributable project-local benchmark evidence. Missing or conflicting evidence returns
+`insufficient-evidence` instead of guessing.
+
+Start with the minimal command:
+
+```sh
+token-harness schedule \
+  --current claude \
+  --candidate codex \
+  --task-class hard \
+  --handoff-bytes 900
+```
+
+If the task is already in progress, generate a bounded handoff rather than copying the transcript:
+
+```sh
+token-harness handoff \
+  --objective "Finish the scheduler change without weakening quota evidence" \
+  --decision "Keep Claude and Codex quota observations provider-local" \
+  --changed-file apps/cli/src/schedule-main.ts \
+  --validation "pnpm test passes" \
+  --unresolved "Need one empirical Codex comparison" \
+  --next-action "Run the candidate benchmark in Codex" \
+  --max-bytes 2048 > handoff.md
+```
+
+To teach future recommendations whether that handoff was actually worth the switch, capture one
+paired experiment. The baseline and optimized variants use the same benchmark id and task class,
+but different harnesses:
+
+```sh
+# 1. Before doing the task in the current harness.
+token-harness benchmark-start \
+  --benchmark-id scheduler-hard-01 \
+  --variant baseline \
+  --task hard \
+  --harness claude
+
+# Run the baseline task in Claude Code, then record its observed outcome.
+token-harness benchmark-finish \
+  --benchmark-id scheduler-hard-01 \
+  --variant baseline \
+  --quality passed \
+  --attempts 1 \
+  --failed-attempts 0
+
+# 2. Before the candidate run, start the optimized variant.
+token-harness benchmark-start \
+  --benchmark-id scheduler-hard-01 \
+  --variant optimized \
+  --task hard \
+  --harness codex
+
+# Give handoff.md to Codex, run the equivalent task, then close the capture.
+token-harness benchmark-finish \
+  --benchmark-id scheduler-hard-01 \
+  --variant optimized \
+  --quality passed \
+  --attempts 1 \
+  --failed-attempts 0
+
+# 3. Evaluate the exact handoff used by the candidate run.
+token-harness transfer \
+  --benchmark-id scheduler-hard-01 \
+  --handoff-file handoff.md
+
+# 4. Persist the immutable transfer verdict for future schedule calls.
+token-harness transfer-record \
+  --benchmark-id scheduler-hard-01 \
+  --handoff-file handoff.md
+```
+
+`transfer-record` re-validates the project-scoped pair, hashes the exact handoff and writes one
+immutable receipt. Future `schedule` calls consume receipts only for the exact route and task class.
+Every attributable receipt must agree on the same non-unknown transfer verdict; one `unknown` or a
+positive/non-positive conflict keeps the recommendation unresolved. Historical receipt sizes never
+replace the current `--handoff-bytes` value.
+
+Manual evidence flags remain available for controlled experiments and debugging. Explicit values,
+including an explicit `unknown`, always override automatic hydration. Run
+`token-harness schedule --help` for the full list.
+
 To try the read-only diagnosis without installing Token Harness globally:
 
 ```sh
@@ -90,7 +267,7 @@ HarnessTrim, or a coding agent.
 ### Managed compatibility rows
 
 Token Harness changes a harness configuration only when a reviewed compatibility row covers the
-exact provider version, harness version, platform, and configuration schema. Three rows ship, and each
+exact provider version, harness version, platform, and configuration schema. Four rows ship, and each
 names the recording it stands on:
 
 | Provider | Harness | Platform | Tested versions | Tier |
@@ -98,16 +275,22 @@ names the recording it stands on:
 | RTK | Claude Code | Windows | rtk 0.44.0, Claude Code 2.1.220 | `canary` |
 | HarnessTrim | Claude Code | Windows | harnesstrim 0.1.0, Claude Code 2.1.220 | `config-only` |
 | HarnessTrim | Codex | Windows | harnesstrim 0.1.0, Codex 0.146.0 | `config-only` |
+| HarnessTrim | Codex | Linux (non-WSL) | harnesstrim 0.2.1, Codex 0.152.1 | `config-only` |
 
 Everything else is refused, and that is the design rather than a gap: `doctor` detects and reports on
 every supported platform, and only the *mutation* is narrower. An uncovered combination exits 9 and
 the diagnostic names what is missing — the reviewed fixture, or the nearest row it does have.
 
+A live Linux recording on 2026-09-02 promoted exactly one combination to managed mutation:
+Codex 0.152.1 + HarnessTrim 0.2.1 on non-WSL Linux. The fixture covers an empty state, brownfield
+user-owned files, skills-only apply, drift, verified rollback, and surgical uninstall. Nearby Codex
+or HarnessTrim versions and WSL remain refused.
+
 What is not covered today, and why:
 
-- **macOS and Linux.** No row on either. The recordings a row needs are states of a real machine, and
-  a fixture cannot be written from a machine nobody ran. On those platforms `plan` and `apply` refuse;
-  install the provider with its own installer and Token Harness will detect, verify, and measure it.
+- **macOS, WSL, and other Linux version combinations.** The recordings a row needs are states of a
+  real machine. Only the exact Linux combination above has been reviewed, so all other combinations
+  continue to refuse managed mutation while detection, verification, and measurement still work.
 - **OpenCode, and permanently rather than pending.** Both providers are detected, adopted, verified
   and measured there, and neither is written. RTK reaches OpenCode through a plugin module its own
   installer places globally, which this build has no action for. HarnessTrim's OpenCode installer
@@ -475,12 +658,25 @@ Neither command removes user-owned RTK or HarnessTrim configuration.
 
 | Command | Purpose | Changes agent/project configuration? |
 | --- | --- | --- |
-| `doctor` | Detect agents, providers, ownership, and problems | No |
-| `plan` | Resolve ownership and preview exact actions | No; stores the plan in private state |
-| `apply` | Apply a plan transactionally | Yes, only with `--yes` |
+| `doctor` | Detect agents, providers, ownership, versions, and problems | No |
+| `budget` | Read live quota/headroom windows where the harness exposes them | No |
+| `context` | Inspect effective model/config, instructions, MCP exposure, and tool inventory | No |
+| `mcp` | Inspect MCP servers and tool-schema exposure | No |
+| `history` | Summarize attributable local usage history | No |
+| `optimize` | Combine quota pacing, context pressure, and task/profile policy into advice | No |
+| `schedule` | Recommend Claude Code or Codex from independently attributable evidence | No |
+| `handoff` | Build a bounded compact handoff for an in-progress cross-harness move | No |
+| `plan` | Resolve ownership and preview exact actions; use `--native-policy` for supported harness-native changes | No; stores the plan in private state |
+| `apply` | Apply a reviewed plan transactionally | Yes, only with `--yes` |
 | `status` | Detect drift and competing hooks | No |
 | `verify` | Check the declared verification tier | No |
 | `metrics` | Import provider records and report savings | No; updates only Token Harness state |
+| `benchmark` | Compare an explicit baseline/optimized receipt pair | No |
+| `benchmark-start` | Start an empirical task capture | No agent/project config change; records Token Harness benchmark state |
+| `benchmark-finish` | Finish an empirical task capture and record the outcome | No agent/project config change; records Token Harness benchmark state |
+| `benchmark-matrix` | Aggregate complete project-scoped benchmark pairs by task class and evidence | No |
+| `transfer` | Evaluate one empirical cross-harness benchmark pair and exact handoff | No |
+| `transfer-record` | Persist one immutable project-scoped transfer evidence receipt | No agent/project config change; records Token Harness benchmark state |
 | `update` | Query channels and update installed providers | Yes, only with `--yes` |
 | `rollback` | Restore files from the latest committed transaction | Yes, only with `--yes` |
 | `uninstall` | Remove owned integration entries | Yes, only with `--yes` |
@@ -488,9 +684,14 @@ Neither command removes user-owned RTK or HarnessTrim configuration.
 Every command supports `--help`. Common filters are:
 
 ```text
---harness claude|codex|opencode
---provider rtk|harnesstrim
+--harness <id>
+--provider <id>
 --project <directory>
+--task mechanical|standard|hard|critical
+--profile economy|balanced|quality|custom
+--reserve <percent>
+--native-policy
+--plan <plan-id>
 --json
 ```
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "token-harness",
-  "version": "0.1.3",
-  "description": "One control plane for token-efficient coding agents.",
+  "version": "0.1.6",
+  "description": "Quota-aware efficiency layer for Claude Code and Codex subscription limits.",
   "license": "Apache-2.0",
   "type": "module",
   "engines": {

package/sbom.json

@@ -1,14 +1,15 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
+  "serialNumber": "urn:uuid:f6a37c3c-4b64-1136-564f-ab6db227d91a",
   "version": 1,
   "metadata": {
     "component": {
       "type": "application",
       "bom-ref": "token-harness",
       "name": "token-harness",
-      "version": "0.1.3",
-      "description": "One control plane for token-efficient coding agents.",
+      "version": "0.1.6",
+      "description": "Quota-aware efficiency layer for Claude Code and Codex subscription limits.",
       "licenses": [
         {
           "license": {
@@ -19,7 +20,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "d28d7044c0215e3471e990732b14275cca61e57a823e7a04a505748be73613c8"
+          "content": "f6a37c3c4b641136564fab6db227d91af645507cf96ea033321bc57cf567756a"
         }
       ]
     },