token-harness 0.1.8 → 0.1.9

package/README.md

@@ -6,119 +6,120 @@ 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:
-
-- which coding agents it found;
-- which optimizers are already active;
-- whether the current setup works;
-- what it changed, if anything;
-- exactly one next step.
+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.
 
-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:
+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.
 
-```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
-
-There is no mandatory command loop. These are tools you use when they answer a question:
+For a fresh clone:
 
-| 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.
+```sh
+git clone https://github.com/giuliastro/token-harness.git
+cd token-harness
+npx --yes pnpm@10.33.4 install --frozen-lockfile
+npm start
+```
 
-## Ask your AI to install Token Harness
+This uses the clone, not an older global installation. An unmerged branch or unpublished main
+change is not automatically available through `token-harness@latest`.
 
-You can give this prompt to Claude Code or Codex:
+### Advanced and AI-assisted use
 
-```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.
-```
+An AI may use the existing JSON CLI to inspect, plan and apply an explicitly approved change.
+That is optional: another AI subscription is not required to operate the app. No persistent
+agent, background model calls or task classifier runs behind your back.
 
-The AI should ask before the `--yes` step because that is the point where coding-agent
-configuration may change.
+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.
 
 ## What normal output looks like
 
@@ -167,26 +168,10 @@ token-harness ui --json
 
 `--json` keeps the complete schema-1 result and diagnostics; it is not shortened.
 
-## Three commands to remember
+## Two entry points 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? |
-
-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 +179,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 +239,64 @@ 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 |
 
+## 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 +384,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.9",
   "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:98b38470-d012-6450-a4aa-0abf63b8e925",
   "version": 1,
   "metadata": {
     "component": {
       "type": "application",
       "bom-ref": "token-harness",
       "name": "token-harness",
-      "version": "0.1.8",
+      "version": "0.1.9",
       "description": "Quota-aware efficiency layer for Claude Code and Codex subscription limits.",
       "licenses": [
         {
@@ -20,7 +20,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "dfdf5e8baba710dd1c9ddd9a38f31fb3aded525ea28f8b15a0fc5cff743444c6"
+          "content": "98b38470d0126450a4aa0abf63b8e925b297a1f1a2110d4a1074d7e3c0b10a21"
         }
       ]
     },