token-harness 0.1.5 → 0.1.6

package/README.md

@@ -117,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
@@ -129,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 |
@@ -137,21 +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 check on 2026-09-02 with Codex 0.152.1 confirmed that boundary: the current row covers
-Codex 0.146.0 on Windows only, so `plan` and `apply --yes` refused with exit 9 and wrote nothing.
-That combination can still be observed and benchmarked with a provider installed through its own
-installer; it is not promoted to managed mutation until a real compatibility fixture is recorded.
+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
@@ -519,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` |
@@ -532,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.5",
-  "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,15 +1,15 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:f4cf234e-2ad8-b2a3-a085-7056eb8a17c4",
+  "serialNumber": "urn:uuid:f6a37c3c-4b64-1136-564f-ab6db227d91a",
   "version": 1,
   "metadata": {
     "component": {
       "type": "application",
       "bom-ref": "token-harness",
       "name": "token-harness",
-      "version": "0.1.5",
-      "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": {
@@ -20,7 +20,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "f4cf234e2ad8b2a3a0857056eb8a17c494730c3d5c11e702edc98b270f18d203"
+          "content": "f6a37c3c4b641136564fab6db227d91af645507cf96ea033321bc57cf567756a"
         }
       ]
     },