token-harness 0.1.8 → 0.1.10

package/README.md

@@ -6,119 +6,148 @@ Token Harness checks your coding agents, shows subscription allowance when it ca
 observed reliably, reduces avoidable context overhead, and recommends useful actions.
 It runs locally and never presents local token estimates as subscription quota.
 
-## The easy path
+## Open it. Approve setup. Keep coding.
 
-You need [Node.js 22.13 or newer](https://nodejs.org/) and at least one signed-in coding
-agent such as Claude Code or Codex.
-
-Open a terminal and paste:
+You need [Node.js 22.13 or newer](https://nodejs.org/) and an installed, signed-in
+Claude Code or Codex. Install Token Harness, then open it:
 
 ```sh
 npm install --global token-harness@latest
-token-harness setup
+token-harness
 ```
 
-That is the whole first-time check. `setup` tells you:
+The browser is now the primary interface. **Set up automatically** checks both agents and
+prepares the supported integration changes. It describes each change in plain language.
+Choose **Approve and apply** to apply the reviewed configuration with backups and verification.
+There are no plan IDs to copy and no daily command sequence to remember.
 
-- which coding agents it found;
-- which optimizers are already active;
-- whether the current setup works;
-- what it changed, if anything;
-- exactly one next step.
+Already configured? The app shows your existing integrations without replacing them.
+An absent provider or an unreviewed version combination is explained rather than installed
+or forced silently. Automatic setup covers the reviewed integration paths, not every possible
+provider/version. Token Harness does not install Claude Code or Codex or log you in.
 
-The first run does not change Claude Code, Codex, or project configuration. If Token
-Harness finds a supported improvement, it shows the safe plan and may suggest:
-
-```sh
-token-harness setup --yes
-```
+### Daily use
 
-`--yes` is always explicit. The change is backed up, applied transactionally, and
-verified. Unsupported combinations are left untouched.
+Continue launching `claude` or `codex` as usual. Supported output integrations operate in the
+agent, not in the dashboard. You can close the page and its terminal without disabling those
+integrations. Open `token-harness` whenever you want to see results; the visible dashboard
+imports available provider records and refreshes its readings automatically.
 
-## Open the dashboard
+**Recorded savings** shows retained history across locally recorded projects, with date bounds,
+provider, measurement class, units, changed-output counts, and before/after values. It does not
+add incompatible provider figures together. Negative results remain visible. No telemetry is
+shown as **not measured**, never a reassuring zero or an invented subscription saving.
+Some provider records may predate Token Harness; locally stored records are not guaranteed
+complete lifetime history. RTK history is imported directly. HarnessTrim project-local records
+must have been imported from their project, or exposed through a configured known metrics path;
+the app does not crawl your disk looking for private projects.
 
-After setup, run:
+For a terminal-only summary, the one command is:
 
 ```sh
-token-harness ui
+token-harness savings
 ```
 
-The dashboard opens in your browser and answers three questions in this order:
+Optional windows are `--since 7d` and `--since 30d`. The advanced `metrics` command remains
+project-scoped; opening the app from its installation folder does not change the savings scope.
 
-1. **Can I work normally right now?**
-2. **What is actually active and useful?**
-3. **Is there one action worth taking?**
+### Find what you need
 
-It shows active/relevant coding agents first, their optimization providers, observable
-allowance windows, and task guidance. Tools that are absent do not get large cards;
-secondary detected tools are kept out of the main path.
+The app has three tabs: **Overview** for agents and recorded savings, **Rules & settings**
+for one agent's rules at a time, and **Activity** for checks and guarded undo. Theme follows
+your system; the header also offers light and dark modes.
 
-The page is served only on `127.0.0.1`: no Electron app, account, or cloud service.
+Each rule shows what was actually **observed**, separately from how it works. Actions sit
+next to the relevant state: **Adjust reasoning** opens the supported review/apply flow;
+**Change in Claude/Codex** explains native steps when an automatic write is not available.
+Missing allowance data and measurement records have their own setup/help actions.
 
-### What happens after the dashboard?
+A saved Claude effort can be displayed even on an unreviewed CLI version. That does not
+admit automatic writes on that version. **No saved preference** means the user field is
+absent, not that reasoning is disabled. A failed read is a separate state with a cause.
+The displayed preference is not a live reading of an already-running session.
 
-Usually: **nothing else. You are done.**
+### The rules are visible
 
-Token Harness is not a launcher and it does not need to stay between you and your coding
-agent. Continue exactly as you normally would:
+**Rules & settings** explains each configured rule: what it does, why it is used,
+its mode, and the evidence available. Automatic integrations, persistent preferences,
+observations and features that are not enabled are explicitly distinguished.
 
-```sh
-claude
-codex
-opencode
-```
+RTK's supported command integration can reduce output automatically. HarnessTrim can use
+adapters or skills/instructions, depending on the installation; skills-only is not a transparent
+hook, and the agent must actually use the reducer. Configured never means every command was
+intercepted. Provider telemetry and its exact/estimated classification remain separate evidence.
+
+**Optional: match reasoning to your work** lets you choose the agent and the type of work
+without learning CLI flags. It previews the actual supported effort/verbosity change, then
+applies only after approval. **This is a persistent preference for future sessions, not an
+automatic per-task switch.** It does not switch models, billing, login, or hook trust. The
+baseline automatic setup never guesses a task or quietly lowers reasoning.
 
-Use whichever of those you already use. RTK, HarnessTrim, or another configured provider
-runs automatically through that coding agent's integration. You do **not** need a special
-`token-harness run` command.
+**Check integrations** performs the existing integration checks from the UI.
+**Undo last change**, available after an application in that dashboard session, previews a
+whole-file backup restoration. It refuses to undo a newer unrelated transaction. It restores
+only the last successful agent transaction; manual edits to those same files after that
+transaction would also be restored, as the confirmation explains.
 
-You can close the dashboard whenever you want. Use `Ctrl+C` in the terminal to stop its
-local web server. Closing it does not disable configured optimizers.
+### Run the current source
 
-Open it again later with `token-harness ui` when you want a status check. If you do not
-want it to open a browser:
+From an existing clone, after installing its dependencies, one command builds and opens the app:
 
 ```sh
-token-harness ui --no-open
+npm start
 ```
 
-## Daily use
+For a fresh clone:
 
-There is no mandatory command loop. These are tools you use when they answer a question:
-
-| When you want to know... | Run |
-| --- | --- |
-| Is everything still connected? | `token-harness ui` |
-| What should I do before a demanding task? | `token-harness optimize --task hard --profile quality` |
-| Is an integration actually working? | `token-harness verify` |
-| How much reducer saving has been measured? | `token-harness metrics --since 7d` |
-| Are safer provider updates available? | `token-harness update` |
-
-If a command finishes with **no action required**, stop there and use your coding agent
-normally. Token Harness should not send you around a `ui → optimize → ui` loop.
-
-## Ask your AI to install Token Harness
-
-You can give this prompt to Claude Code or Codex:
-
-```text
-Install the latest stable Token Harness from npm on this computer, then run
-`token-harness setup`. Do not install or replace Claude Code, Codex, or any
-optimization provider unless Token Harness's supported plan explicitly requires it.
-
-Explain the setup result in plain language: what was detected, what already works,
-what would change, and the single next step. Do not expose credentials, cookies,
-tokens, raw home paths, or private project contents. If setup proposes a supported
-configuration change, show me the short plan and ask before running
-`token-harness setup --yes`. After an approved change, verify it and open
-`token-harness ui` once. Then tell me clearly that setup is complete and that I should
-continue using my normal coding-agent command. Do not invent additional Token Harness
-steps when no action is required.
+```sh
+git clone https://github.com/giuliastro/token-harness.git
+cd token-harness
+npx --yes pnpm@10.33.4 install --frozen-lockfile
+npm start
 ```
 
-The AI should ask before the `--yes` step because that is the point where coding-agent
-configuration may change.
+This uses the clone, not an older global installation. An unmerged branch or unpublished main
+change is not automatically available through `token-harness@latest`.
+
+### Advanced and AI-assisted use
+
+The long CLI flag combinations are **not** the normal human interface. They are the controller API
+used by the app, automation, and optionally by a coding harness. Humans can keep using the browser
+and the two entry points above.
+
+For in-session use, this repository now includes a portable Agent Skill at
+[`skills/token-harness/SKILL.md`](skills/token-harness/SKILL.md). A compatible Claude Code or Codex
+skill mechanism can load it on demand, after which you can simply ask the harness to **use Token
+Harness for this task**. The skill classifies substantial work conservatively, calls the existing
+local `--json` optimizer at meaningful task boundaries, and can use explicit workload scheduling
+when you have actually supplied a backlog. It does not run Token Harness before every tool call.
+
+The skill is deliberately thin: Token Harness remains the deterministic policy engine. No MCP
+server, background model, persistent agent, or second quota formula is added just to make this work.
+Local tokens are still not subscription quota, and raw Claude/Codex percentages are still not a
+common currency.
+
+Agent use is read-only by default. If Token Harness recommends a persistent model, reasoning, or
+verbosity change, the harness must first build a reviewed plan, explain the exact proposed mutation,
+and wait for your explicit approval before `apply`. A saved preference may affect future sessions;
+it is not silently presented as a live change to the current session.
+
+The guided app can preview **Enable in-session guidance** for each detected Claude Code or
+Codex installation. It installs the same portable skill into the agent's documented user-level
+Agent Skills directory through the normal transactional plan/apply path. The agent card then shows
+the live guidance state: **Enabled** when the exact skill is currently owned by Token Harness,
+**Enabled externally** for a byte-identical user-owned skill, or an explicit not-enabled,
+custom/conflict, or unavailable state. Existing `token-harness` skill directories are never
+overwritten or silently adopted, and matching bytes alone never create an ownership claim. The
+browser remains fully usable without any skill or second AI subscription. See
+[RFC 0023](docs/rfcs/0023-guided-agent-skill-install.md) for the install and ownership boundary.
+
+The older automation contracts remain available: `setup`, `optimize`, `plan`, `apply`,
+`verify`, `metrics`, `rollback`, and their JSON reports. `ui --json` preserves its existing
+schema-1 report; `ui --read-only` opens the legacy read-only dashboard. `ui --no-open` starts
+the guided app without launching a browser. Stop either local server with Ctrl+C. See
+[RFC 0022](docs/rfcs/0022-agent-native-skill.md) for the agent-facing safety boundary.
 
 ## What normal output looks like
 
@@ -167,26 +196,10 @@ token-harness ui --json
 
 `--json` keeps the complete schema-1 result and diagnostics; it is not shortened.
 
-## Three commands to remember
-
-```sh
-token-harness setup
-token-harness ui
-token-harness optimize
-```
-
-| Command | Answer |
-| --- | --- |
-| `setup` | Is Token Harness ready, and what is my one next step? |
-| `ui` | What is active, how much allowance is visible, and do I need to do anything? |
-| `optimize` | What is the best evidence-based action for the task I am starting? |
+## Two entry points to remember
 
-For example:
-
-```sh
-token-harness optimize --task hard --profile quality
-token-harness optimize --task mechanical --profile economy
-```
+`token-harness` opens the application. `token-harness savings` prints recorded results.
+The advanced commands below are implementation tools, not a required user workflow.
 
 ## Safety and privacy
 
@@ -194,19 +207,23 @@ Token Harness is conservative by design:
 
 - normal read-only commands do not change coding-agent or project configuration;
 - `setup --yes`, `apply --yes`, `update --yes`, `rollback --yes`, and
-  `uninstall --yes` are the explicit configuration-changing forms;
+  `uninstall --yes` are the explicit CLI configuration-changing forms; the guided UI uses
+  a reviewed preview and explicit **Approve and apply** instead;
 - plans are checked again immediately before they are applied;
 - existing files are backed up before a managed write;
 - only exact Token Harness-owned entries are removed by `uninstall`;
 - newer or untested combinations are reported, not guessed;
 - an available provider update outside reviewed compatibility is kept out rather than
   forced, and the installed working version stays in place;
-- the dashboard binds only to the local loopback address and provides no mutation API;
+- the guided app binds only to 127.0.0.1 and protects its fixed local controls with exact
+  Host/Origin checks, a per-process anti-forgery token and single-use approval tickets;
+- the legacy read-only dashboard and external status seam remain read-only;
 - source code, prompts, command contents, credentials, and cookies are not sent to a
   Token Harness service.
 
 Plans, receipts, metrics, and backups stay in the local Token Harness state directory.
-See [RFC 0004](docs/rfcs/0004-safety-and-installation.md) for the execution model and
+See [RFC 0013](docs/rfcs/0013-guided-local-experience.md) for the local browser trust boundary,
+[RFC 0004](docs/rfcs/0004-safety-and-installation.md) for the execution model and
 [RFC 0006](docs/rfcs/0006-cli-contract.md) for CLI/JSON guarantees.
 
 ## Supported optimizations
@@ -250,8 +267,111 @@ Most people do not need this section. Run `token-harness <command> --help` for d
 | `handoff` | Build a bounded cross-harness handoff | No |
 | `benchmark*`, `transfer*` | Capture and compare empirical evidence | Local state only |
 
+## Workload-aware allowance planning
+
+If you know how many accepted tasks remain, the advanced CLI can ask whether that backlog fits the
+**currently observed** included allowance:
+
+```sh
+token-harness optimize --harness codex --task standard --tasks-left 5
+token-harness schedule --current codex --candidate claude --task-class standard --tasks-left 5
+```
+
+`--tasks-left` is explicit workload intent for a backlog of one task class. Token Harness does not
+infer it from `ccusage`, local tokens, session length, or raw provider percentages. A workload-driven
+recommendation requires complete project-local benchmark evidence for the exact model + reasoning
+effort + verbosity policy in both the five-hour and weekly windows. If that evidence is incomplete,
+capacity stays unknown.
+
+When evidence proves that the current policy cannot cover the stated backlog, `optimize` protects
+capacity instead of spending a quota-derived effort bonus and reports whether the five-hour,
+weekly, or both windows are limiting. `schedule` can use the same target to consider the other
+harness, but only when that candidate has enough conservative accepted-task capacity and passes the
+existing quality, pace, availability, and transfer checks.
+
+### Mixed task-class backlog
+
+For queued **new tasks** spanning more than one class, give `schedule` the mix explicitly:
+
+```sh
+token-harness schedule --current codex --candidate claude \
+  --workload mechanical=2,standard=3,hard=1
+```
+
+Mixed mode does not sum per-class task capacities as if they were separate quota buckets. It charges
+each proposed task's project-local p75 cost against the same shared five-hour and weekly allowance
+of that harness, then returns `stay`, `split`, `switch`, `shortfall`, or
+`insufficient-evidence`. Candidate assignments require at least three coherent quality-gated
+observations for the exact task class plus complete five-hour and weekly capacity evidence.
+Unproven work remains visibly unallocated.
+
+This mode is for queued/new tasks, not an in-progress handoff. Therefore `--workload` is mutually
+exclusive with `--task-class`, `--tasks-left`, manual pace/quality flags, and handoff/transfer
+flags. The allocator is deterministic and conservative; it does not claim globally optimal routing,
+launch either harness, or compare raw Claude and Codex percentages.
+
+No capacity after a future reset is assumed. Re-run the observation after the reset rather than
+treating a forecast as provider quota. See [RFC 0020](docs/rfcs/0020-workload-aware-allowance.md)
+and [RFC 0021](docs/rfcs/0021-mixed-workload-allocation.md).
+
+## Applying native recommendations
+
+`optimize` remains read-only. Review a plan before applying a supported native change:
+
+```sh
+token-harness plan --harness claude --native-policy --task mechanical --profile economy
+token-harness apply --plan <printed-plan-id> --yes
+```
+
+`apply --plan <id>` restores the reviewed harness/provider selection automatically; you
+should not have to repeat `--harness`, `--provider`, `--native-policy`, `--task` or `--profile`.
+Run it from the same project as `plan`. Conflicting explicit selectors are rejected, and
+actual version, ownership and configuration changes still invalidate the plan. Existing
+schema-1 plans remain usable; only their approved actions can execute.
+
+The first Claude path supports the **persisted user effort preference** on the reviewed
+Claude Code 2.1.261 build. It does not change model, authentication, hooks, endpoint or billing.
+`max` is never persisted. Project/local/ancestor settings, custom configuration roots and
+known environment/thinking overrides block the change rather than being overwritten. The
+preference affects future sessions unless overridden: reopen Claude and check `/effort`.
+This is not evidence of a running session's effective effort or a guaranteed quota saving.
+
+For Codex, the same plan/apply flow manages the existing reviewed reasoning-effort and
+verbosity fields through native `config/batchWrite`; project/profile overrides remain yours.
+`rollback --yes` restores the complete pre-change files. `uninstall --yes` removes only owned
+changes and restores a prior Claude effort preference without undoing unrelated later edits.
+
 ## Troubleshooting
 
+### Claude allowance is unavailable
+
+The dashboard now explains whether the optional companion is missing, lacks the safe CLI
+flags, cannot find Python, has no usable Claude session, reports an expired session, or returns
+an unsupported source. It does not expose credentials, raw companion errors or private paths.
+
+As observed on **September 5, 2026**, npm `cclimits@1.7.0` includes the merged Claude
+zero-configuration support and the read-only flags. The latest GitHub Release listing is older
+and is not evidence of what npm ships. To check the same path Token Harness uses:
+
+```sh
+npm list --global cclimits
+cclimits --claude --json --no-cache-write --no-stale-fallback
+token-harness budget --harness claude --verbose
+```
+
+An explicit optional installation/update is `npm install --global cclimits@1.7.0`.
+Token Harness does not install it automatically or retry without its read-only flags.
+A fresh local Claude cache is shown as **cached**, never promoted to live quota pacing.
+A missing observation is not zero remaining allowance. Never paste credentials to debug it.
+
+### Codex is configured but its hook does not run
+
+`token-harness verify --harness codex --verbose` now reads native `hooks/list` where the
+installed app-server exposes it. Disabled, untrusted and modified hooks are distinguished from
+an unavailable observation. Trust must still be granted explicitly in Codex. Enabled/trusted
+metadata does not prove interception, reduction, or task quality; the integration remains
+`config-only` until attributable runtime evidence exists.
+
 ### `token-harness` is not found
 
 Check that Node is new enough and the package is installed:
@@ -339,3 +459,22 @@ behavior or architecture.
 
 [Apache License 2.0](LICENSE). Referenced provider tools are independent projects with
 their own licenses.
+
+### Loading, impact and sharing
+
+The dashboard shows animated, named checks while it reads your setup. Agent cards and saved
+reduction records appear as they are ready; a slow allowance check does not hide the results.
+Refreshing keeps previous readings visible until newer ones arrive. Errors and waiting are
+explicit, and reduced-motion preferences disable animation without removing status text.
+
+A result can now say **"65% less tool output"**, with its source, before/after values and count
+of recorded changed outputs immediately beside it. An estimate says **"Estimated"**. This
+percentage describes only those recorded outputs, not your whole coding session, subscription
+allowance or money. Provider rows remain separate; negative results and errors remain visible.
+
+Choose **Share result** to preview the exact summary and a locally generated image. **Open X
+draft** prepares a short post. **Open Reddit** prepares a title/link; copy the summary into a
+text post and choose a community yourself. **Copy for Discord** prepares a message to paste
+in your chosen channel. **Save image** creates a PNG you can attach yourself. Nothing is
+posted or uploaded automatically, and sharing excludes private paths, code, prompts and
+account/allowance information. An open share preview stays fixed even if readings update.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "token-harness",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Quota-aware efficiency layer for Claude Code and Codex subscription limits.",
   "license": "Apache-2.0",
   "type": "module",

package/sbom.json

@@ -1,14 +1,14 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:dfdf5e8b-aba7-10dd-1c9d-dd9a38f31fb3",
+  "serialNumber": "urn:uuid:9290051f-d6be-441a-20e1-add1f9ea0ff8",
   "version": 1,
   "metadata": {
     "component": {
       "type": "application",
       "bom-ref": "token-harness",
       "name": "token-harness",
-      "version": "0.1.8",
+      "version": "0.1.10",
       "description": "Quota-aware efficiency layer for Claude Code and Codex subscription limits.",
       "licenses": [
         {
@@ -20,7 +20,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "dfdf5e8baba710dd1c9ddd9a38f31fb3aded525ea28f8b15a0fc5cff743444c6"
+          "content": "9290051fd6be441a20e1add1f9ea0ff88e9ae931921532ed8422d86db26f1b3a"
         }
       ]
     },