@warren-dean/code-kit 0.5.0 → 0.6.0

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "code-kit",
       "source": "./",
       "description": "Keeps AI coding agents inside your project's rules, from idea to merged code: spec design, lanes, layer rules, protected paths with an approval log, spec-check and design gates, proof-before-finish checks, dispatch, review, build status and CI verification, configured per project from its docs",
-      "version": "0.5.0",
+      "version": "0.6.0",
       "category": "development",
       "tags": ["guardrails", "architecture", "lanes", "layers", "spec-driven", "ci", "multi-agent"],
       "license": "MIT"

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "code-kit",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Keeps AI coding agents inside your project's rules, from idea to merged code: spec design, lanes, layer rules, protected paths with an approval log, spec-check and design gates, proof-before-finish checks, dispatch, review, build status and CI verification, configured per project from its docs",
   "author": {
     "name": "Warren Langeveldt"

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 What changed in each release of code-kit, newest first. Versions follow the plugin manifest and the npm package `@warren-dean/code-kit`. Each release is also on [GitHub Releases](https://github.com/warrendeanlangeveldt/code-kit/releases).
 
+## 0.6.0 (2026-10-10)
+
+The first parts of the harness, in the mod (Claude Code 2.1.287 or later):
+
+- **Harness settings.** A new `harness` section in `.claude/code-kit.json` holds how the lead loop acts (`autonomy`), how long a call waiting on your approval is held, when a stalled lane is nudged and restarted, the reviewer agent and its model, and the plan use at which background agents pause. `code-kit check` validates it; a wrong value gives way to its default.
+- **`code-kit settings`** lists the settings in force; `settings set <key> <value> --reason "…"` changes one, as the person, and logs it as a `kit` approval. Agents are refused.
+- **`/harness`** opens the settings in the session. A change asks your reason before anything is written, and the approval log records it as made in the pane.
+- **Usage per lane.** The mod counts each model request's tokens against the agent that made it, its story and its lane. The Lanes pane shows tokens per lane and story, the background agents' share, and the plan's 5-hour use as a bar.
+- **Outliers in the band:** a story using more than three times the median of the stories finished this session (once three have) is flagged, as "ST-7 has used 3.4× the usual". Nothing is stopped.
+- **The background pause:** the band says when the plan's 5-hour use passes `harness.background.pauseAtPercent` (80% unless set). The background agents that will honour it come in a later release.
+- **Refusals your approval would allow** (new packages, protected files, kit edits) are recognised, including a commit refused for a protected file, ready for the hold that comes next.
+- `code-kit check --json` carries the harness settings in force.
+
 ## 0.5.0 (2026-10-07)
 
 Fixes for gaps found running code-kit under an autonomous lead:

package/README.md

@@ -269,15 +269,18 @@ With Claude Code 2.1.287 or later, code-kit's mod shows the project in the sessi
 - **The band** sits above the prompt whenever something waits for you, and is gone when nothing does. It shows:
   - approvals agents have asked for: **Approve…** opens a confirmation with a reason prefilled from the request, which you keep or rewrite;
   - stories finished and waiting for review: **Review** asks the lead to run `/code-kit:review` on the branch, and **Merge** runs `verify`, checks included, then merges if it passes;
-  - a finish check failing in this session: **Lanes** opens the pane.
+  - a finish check failing in this session: **Lanes** opens the pane;
+  - a story using more than three times the median of the stories finished this session (once three have finished): **Lanes** opens the pane;
+  - background agents paused, once the plan’s 5-hour use passes `harness.background.pauseAtPercent` (80% unless set).
 
   Each button has a digit: type it in an empty prompt to press it.
 
-- **`/lanes`** opens the Lanes pane: each lane with its agent, story, branch and state (building, in review, blocked, idle), a mark while its agent is at work, and the stories ready to start. It stays current within 2 seconds of a commit, a branch change, a plan edit or an agent starting or stopping. `/lanes` again, or Escape, closes it.
+- **`/lanes`** opens the Lanes pane: each lane with its agent, story, branch and state (building, in review, blocked, idle), a mark while its agent is at work, and the stories ready to start. Beneath them, the session’s usage: tokens per lane and story, the background agents’ share, and the plan’s 5-hour use as a bar. It stays current within 2 seconds of a commit, a branch change, a plan edit or an agent starting or stopping. `/lanes` again, or Escape, closes it.
 - **Refusals** a code-kit hook gives an agent are drawn as cards: what was refused, the rule, what to do, and Approve… where your approval would allow it. The full text is a press away.
+- **`/harness`** opens the harness settings: how the lead loop acts, how long a call waiting on your approval is held, when a stalled lane is nudged and restarted, the reviewer agent and its model, and the use at which background agents pause. Changing one asks your reason, writes `.claude/code-kit.json` and logs a `kit` approval. Lanes, paths and rules still change through `/code-kit:init`.
 - **`/approvals`** lists the requests waiting and the approvals in force, with minutes left. **`/verify-branch`** runs `code-kit verify` on this branch. Neither calls the model.
 
-Approving from the band records `(approved in the code-kit pane)` with your reason, and a merge from it says it was merged by the person from the pane. Both happen only on your press: the hooks refuse `approve --via pane` and `merge --person` from every agent. Outside a project with `.claude/code-kit.json`, the mod draws nothing. Mods don't draw in the VS Code extension's chat panel, the Agent SDK or `claude -p`.
+Approving from the band records `(approved in the code-kit pane)` with your reason, and a merge from it says it was merged by the person from the pane. A settings change is logged as made in the pane. These happen only on your press: the hooks refuse `approve --via pane`, `merge --person` and `settings set` from every agent. Outside a project with `.claude/code-kit.json`, the mod draws nothing. Mods don't draw in the VS Code extension's chat panel, the Agent SDK or `claude -p`.
 
 ## Build
 
@@ -331,6 +334,8 @@ code-kit merge <branch> --delegated|--person [--into branch]  # merge a branch t
 code-kit requests [--json]                                   # approval requests the hooks refused, still open, and the approvals in force
 code-kit stops [--session id] [--json]                       # finish checks that refused an agent's last stop and still fail
 code-kit sent-back <branch> [--reason "…"]                    # record a review's send-back: status shows the story as sent back until the branch moves on
+code-kit settings [--json]                                   # the harness settings in force, with their defaults
+code-kit settings set <key> <value> --reason "…"               # change one, as the person: written to the config and logged as a kit approval
 code-kit approve <name>... --reason "…" [--lane name] [--delegated | --via pane]  # record a person's approval from chat, or (--delegated) grant one within the delegated rules; a package name stands for its dep- approval
 ```
 
@@ -361,6 +366,7 @@ code-kit approve <name>... --reason "…" [--lane name] [--delegated | --via pan
 | `approvals.lead`               | no                | `true` lets the lead act on what the person says in chat, for when `!` isn't available (on a phone, say): it records their approvals with `code-kit approve`, and runs `shell.block` commands marked `person`. Default `false`. See [Approvals](#approvals).                                                                                                                                                                                                                                                                                               |
 | `approvals.delegate`           | no                | `{ protected?: [approval names], merge?: true, dependencies?: { licences?, minWeeklyDownloads?, maxMonthsSinceRelease?, allowInstallScripts?: true \| false \| [kinds] } }`: approvals the lead may grant on its own, with `code-kit approve --delegated`, and with `merge`, merges into a protected branch with `code-kit merge --delegated`. Dependencies are checked against the npm registry; the defaults are MIT, Apache-2.0, BSD and ISC, 10,000 weekly downloads, a release within 18 months, and no install scripts. See [Approvals](#approvals). |
 | `branches.protected`           | no                | Default `["main", "master"]`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `harness`                      | no                | What the mod's harness does in the session: `autonomy` (`autonomous`, `propose` or `off`; default `autonomous`), `hold.minutes` (how long a call waiting on your approval is held, 0 to 30; default 2), `stall.nudgeMinutes` and `stall.restartMinutes` (default 5 and 10), `stall.maxRestarts` (default 2), `agents.reviewer.on` (default `false`) and `agents.reviewer.model` (default the session's), and `background.pauseAtPercent` (default 80). Change them with `/harness` or `code-kit settings set`.                                             |
 
 Add `.claude/approvals/`, `.claude/state/` and `.claude/code-kit.draft.json` to `.gitignore`, and `.claude/approval-log.jsonl merge=union` to `.gitattributes`, so merging branches that both logged changes keeps every entry. Commit `.claude/code-kit.baseline.json` if the project has one.
 

package/bin/code-kit.mjs

@@ -20,6 +20,8 @@
 //   requests [--json]                 open approval requests and approvals in force
 //   stops [--session id] [--json]     finish checks that refused an agent's last stop, still failing
 //   sent-back <branch> [--reason …]   records that a review sent the branch back at its current commit
+//   settings [--json] | settings set <key> <value> --reason … [--via pane]
+//                                    the harness settings; set is the person's own change
 //                         record approvals a person gave in chat (with approvals.lead on, the lead runs it)
 // --config <file> reads a draft (.claude/code-kit.draft.json) instead of .claude/code-kit.json.
 import { execFileSync } from 'node:child_process';
@@ -36,6 +38,7 @@ import { nextStep } from '../hooks/lib/next.mjs';
 import { traceFile } from '../hooks/lib/trace.mjs';
 import { buildStatus } from '../hooks/lib/plan.mjs';
 import { recordSentBack } from '../hooks/lib/reviews.mjs';
+import { SETTINGS, parseSetting, settingOf, withSetting } from '../hooks/lib/harness.mjs';
 import {
   APPROVAL_MINUTES,
   approvalLifetime,
@@ -119,6 +122,7 @@ function checkJson() {
   );
   report.adapters = config.adapters;
   report.docs = config.docs ?? null;
+  report.harness = config.harness;
   out(JSON.stringify(report, null, 2));
 }
 
@@ -446,6 +450,45 @@ function requests() {
     );
 }
 
+/**
+ * The harness settings (`harness` in the config): listed, or one changed as the person's own act. The
+ * change is written to the config and given a kit approval with the person's reason, so the commit that
+ * keeps it logs their reason. The hooks refuse `settings set` from every agent.
+ */
+function settings() {
+  const { raw, config } = load();
+  if (rest[0] === 'set') {
+    const [, key, value] = rest;
+    if (!key || value === undefined)
+      die('code-kit settings set <key> <value> --reason "<why>" [--via pane]');
+    if (!(key in SETTINGS))
+      die(`${key} isn't a harness setting. They are: ${Object.keys(SETTINGS).join(', ')}.`);
+    if (!reason?.trim()) die('Give a reason with --reason "…": the approval log keeps it.');
+    const changed = withSetting(raw, key, parseSetting(key, value));
+    const problems = validate(changed);
+    if (problems.length) die(`Nothing changed: ${problems.join('; ')}`);
+    writeFileSync(resolve(file), `${JSON.stringify(changed, null, 2)}\n`);
+    const mark =
+      via === 'pane' ? '(changed in the code-kit pane)' : '(changed with code-kit settings)';
+    grantApprovals(resolve('.'), ['kit'], null, reason, { kit: mark });
+    return out(
+      `Set harness.${key} to ${JSON.stringify(settingOf(changed.harness, key))}. Commit ${file} to keep it; the approval log will carry your reason.`,
+    );
+  }
+  if (rest.length) die('code-kit settings [--json] | settings set <key> <value> --reason "<why>"');
+  const rows = Object.entries(SETTINGS).map(([key, s]) => ({
+    key,
+    value: settingOf(config.harness, key),
+    default: s.default,
+    about: s.about,
+  }));
+  if (flag('--json')) return out(JSON.stringify(rows, null, 2));
+  for (const r of rows)
+    out(
+      `${r.key.padEnd(26)} ${JSON.stringify(r.value).padEnd(14)} ${r.value === r.default ? '' : `(default ${JSON.stringify(r.default)}) `}${r.about}`,
+    );
+}
+
 /** Records the review's send-back of `branch` at its current commit (lib/reviews.mjs). */
 function sentBackCommand(branch) {
   load();
@@ -725,6 +768,7 @@ const commands = {
   merge: () => (rest.length === 1 ? merge(rest[0]) : usage()),
   requests,
   stops,
+  settings,
   'sent-back': () => (rest.length === 1 ? sentBackCommand(rest[0]) : usage()),
   trace: () => (rest.length ? trace(rest) : usage()),
   adapters,
@@ -744,7 +788,8 @@ function usage() {
       '              | next [--base ref] [--json] | adapters | trace <path>... [--json]\n' +
       '              | approve <name>... --reason "…" [--lane name]   [--config file]\n' +
       '              | merge <branch> --delegated|--person [--into branch] | requests [--json]\n' +
-      '              | stops [--session id] [--json] | sent-back <branch> [--reason "…"]',
+      '              | stops [--session id] [--json] | sent-back <branch> [--reason "…"]\n' +
+      '              | settings [--json] | settings set <key> <value> --reason "…" [--via pane]',
   );
 }
 await (commands[command] ?? usage)();

package/hooks/guard-bash.mjs

@@ -140,6 +140,11 @@ if ((delegatedMerge && /\s--person\b/.test(cmd)) || (approves && /\s--via\b/.tes
   block(
     `Blocked: merging or approving as the person is the person's own act, from the code-kit pane or their terminal. Ask them, and stop.\nCommand: ${cmd}`,
   );
+// The harness settings are the person's to change, from the pane or their terminal.
+if (runs(cmd, new RegExp(String.raw`^${CODE_KIT}\s+settings\s+set\b`)))
+  block(
+    `Blocked: changing the harness settings is the person's own act, from the code-kit pane (/harness) or their terminal. Tell them what you'd change and why, and stop.\nCommand: ${cmd}`,
+  );
 if (delegatedMerge && actor.kind !== 'lead')
   block(
     `Blocked: only the lead merges into a protected branch. Finish your story and commit it on your branch; the lead reviews and merges it.\nCommand: ${cmd}`,

package/hooks/lib/config.mjs

@@ -1,6 +1,7 @@
 // The project's rules live in .claude/code-kit.json. The hooks read it from the project the session
 // was opened in; a project without one is not governed by the kit, and an invalid one fails closed.
 import { existsSync, readFileSync } from 'node:fs';
+import { harnessProblems, harnessSettings } from './harness.mjs';
 import { join } from 'node:path';
 import { ADAPTERS, applyAdapters } from './adapters/index.mjs';
 
@@ -55,6 +56,7 @@ export function withDefaults(c) {
     checks: c.checks ?? [],
     branches: { protected: c.branches?.protected ?? ['main', 'master'] },
     approvals: { lead: c.approvals?.lead === true, delegate: delegateRules(c.approvals?.delegate) },
+    harness: harnessSettings(c.harness),
   };
 }
 
@@ -191,6 +193,7 @@ export function validate(c) {
     c.branches === undefined || isList(c.branches?.protected),
     '"branches.protected" must be a list of branch names',
   );
+  p.push(...harnessProblems(c.harness));
   return p;
 }
 

package/hooks/lib/harness.mjs

@@ -0,0 +1,131 @@
+// The harness's settings (docs/specs/12-settings.md): the `harness` section of .claude/code-kit.json,
+// what the mod's loop, hold, reviewer and usage read. Defaults fill what the section leaves out; a value
+// out of range is a config problem like any other.
+
+export const AUTONOMY = ['autonomous', 'propose', 'off'];
+export const MODELS = ['haiku', 'sonnet', 'opus'];
+
+/** Each setting by its dotted key: its default, and why a value is wrong (or null when it's right). */
+export const SETTINGS = {
+  autonomy: {
+    default: 'autonomous',
+    problem: (v) => (AUTONOMY.includes(v) ? null : `must be one of ${AUTONOMY.join(', ')}`),
+    about: 'How the lead loop acts: on its own, by proposing each step, or not at all',
+  },
+  'hold.minutes': {
+    default: 2,
+    problem: (v) =>
+      Number.isFinite(v) && v >= 0 && v <= 30
+        ? null
+        : 'must be a number of minutes from 0 (off) to 30',
+    about: 'How long a call waiting on your approval is held before it is refused',
+  },
+  'stall.nudgeMinutes': {
+    default: 5,
+    problem: (v) =>
+      Number.isFinite(v) && v >= 1 ? null : 'must be a number of minutes, at least 1',
+    about: 'Minutes without a tool call before a lane agent is nudged',
+  },
+  'stall.restartMinutes': {
+    default: 10,
+    problem: (v) =>
+      Number.isFinite(v) && v >= 1 ? null : 'must be a number of minutes, at least 1',
+    about: 'Minutes without a tool call before a lane agent is restarted',
+  },
+  'stall.maxRestarts': {
+    default: 2,
+    problem: (v) =>
+      Number.isInteger(v) && v >= 0 && v <= 10 ? null : 'must be a whole number from 0 to 10',
+    about: 'Restarts on one story before the lane is flagged for you',
+  },
+  'agents.reviewer.on': {
+    default: false,
+    problem: (v) => (typeof v === 'boolean' ? null : 'must be true or false'),
+    about: 'A background reviewer for each finished branch',
+  },
+  'agents.reviewer.model': {
+    default: null,
+    problem: (v) =>
+      v === null || (typeof v === 'string' && v.length > 0)
+        ? null
+        : `must be a model (${MODELS.join(', ')}, or an id), or null for the session's`,
+    about: "The reviewer's model; none means the session's",
+  },
+  'background.pauseAtPercent': {
+    default: 80,
+    problem: (v) =>
+      Number.isFinite(v) && v > 0 && v <= 100 ? null : 'must be a percentage from 1 to 100',
+    about: "The plan's 5-hour use at which background agents pause",
+  },
+};
+
+const get = (obj, key) =>
+  key.split('.').reduce((o, k) => (o && typeof o === 'object' ? o[k] : undefined), obj);
+const set = (obj, key, value) => {
+  const parts = key.split('.');
+  let o = obj;
+  for (const k of parts.slice(0, -1)) o = o[k] && typeof o[k] === 'object' ? o[k] : (o[k] = {});
+  o[parts.at(-1)] = value;
+  return obj;
+};
+
+/** Every key the section holds, as dotted keys: `stall.nudgeMinutes`, `agents.reviewer.on`… */
+function keysOf(obj, prefix = '') {
+  return Object.entries(obj ?? {}).flatMap(([k, v]) =>
+    v && typeof v === 'object' && !Array.isArray(v) && !(`${prefix}${k}` in SETTINGS)
+      ? keysOf(v, `${prefix}${k}.`)
+      : [`${prefix}${k}`],
+  );
+}
+
+/** The settings in force: the section's values over the defaults, as a nested object. A value that's
+ * wrong (reported by `harnessProblems`) gives way to the default. */
+export function harnessSettings(section) {
+  const out = {};
+  for (const [key, s] of Object.entries(SETTINGS)) {
+    const v = section && typeof section === 'object' ? get(section, key) : undefined;
+    set(out, key, v === undefined || s.problem(v) ? s.default : v);
+  }
+  return out;
+}
+
+/** The section's problems, in the config's words. */
+export function harnessProblems(section) {
+  if (section === undefined) return [];
+  if (!section || typeof section !== 'object' || Array.isArray(section))
+    return ['"harness" must be an object'];
+  const p = [];
+  for (const key of keysOf(section)) {
+    if (!(key in SETTINGS)) {
+      p.push(
+        `"harness.${key}" isn't a harness setting (they are ${Object.keys(SETTINGS).join(', ')})`,
+      );
+      continue;
+    }
+    const why = SETTINGS[key].problem(get(section, key));
+    if (why) p.push(`"harness.${key}" ${why}`);
+  }
+  const h = harnessSettings(section);
+  if (h.stall.restartMinutes <= h.stall.nudgeMinutes)
+    p.push('"harness.stall.restartMinutes" must be more than "harness.stall.nudgeMinutes"');
+  return p;
+}
+
+/** A value typed on the command line, as the setting's type: numbers, true and false, null, or text. */
+export function parseSetting(key, text) {
+  const d = SETTINGS[key]?.default;
+  if (text === 'null') return null;
+  if (typeof d === 'boolean' || text === 'true' || text === 'false')
+    return text === 'true' ? true : text === 'false' ? false : text;
+  if (typeof d === 'number' && /^-?\d+(\.\d+)?$/.test(text)) return Number(text);
+  return text;
+}
+
+/** The raw config with one harness setting changed (a copy). */
+export function withSetting(raw, key, value) {
+  const copy = structuredClone(raw);
+  copy.harness = set(copy.harness ?? {}, key, value);
+  return copy;
+}
+
+export { get as settingOf };

package/hooks/mod/hold.mjs

@@ -0,0 +1,25 @@
+// Hold and ask (spec 06), the pure parts. The hooks stay the only judge: the mod lets a call run,
+// and when the result is a refusal a person's approval would allow, it holds the call, asks, writes the
+// approval and retries the same call (docs/spikes/harness.md, spike B). This reads such a refusal.
+import { refusalCard } from './view.mjs';
+
+/** The kinds of refusal a person's approval would allow (HOLD-1): a new package, a protected file, the kit. */
+const HOLDABLE = new Set(['dependency', 'approval', 'kit']);
+
+/**
+ * From a refused call's result text, what would let it through: { kind, names, lane, what, title }, or
+ * null when no approval a person can give would allow it (another lane's files, force-push, the log…).
+ */
+export function holdable(resultText) {
+  const card = refusalCard(resultText);
+  if (!card || !HOLDABLE.has(card.kind) || !card.request?.names.length) return null;
+  return { kind: card.kind, title: card.title, ...card.request };
+}
+
+/** A tool call's result as text, whichever shape the engine gave it. */
+export function resultText(result) {
+  if (!result) return '';
+  if (typeof result.deny === 'string') return result.deny;
+  if (typeof result.text === 'string') return result.text;
+  return typeof result.result === 'string' ? result.result : '';
+}

package/hooks/mod/register.mjs

@@ -12,18 +12,25 @@ import {
   NOT_CODE_KIT,
   PANE_ID,
   RESULT_ID,
+  SETTINGS_ID,
   approvalsText,
   agentsAtWork,
+  attribution,
   approvePane,
   band,
   bandLines,
+  finishedStories,
   lanesPane,
   parseJson,
+  planOf,
   prefilledReason,
   projectState,
   refusalCard,
   refusalView,
   resultPane,
+  settingsView,
+  usageSummary,
+  withUsage,
 } from './view.mjs';
 
 // What the session knows of the project, read again when it changes.
@@ -34,6 +41,11 @@ let approving = null; // the open Approve… confirmation: { request, reason, er
 let result = null; // what the last merge reported
 let notice = null; // why the person's last act failed
 let act = null; // the session's actions, made at session start
+let settingRows = []; // the harness settings, from `code-kit settings --json`
+let pendingSetting = null; // a change waiting for the person's reason: { key, value, reason, error }
+let ledger = {}; // the session's tokens by agent and story (USE-1)
+let rateLimits = []; // the session's limits, as session.measure last gave them
+const agentsSeen = new Map(); // agent id → its $.agent.list() entry, kept once it leaves the list
 const refusals = new Map(); // tool_use_id → the refusal text a hook gave (CARD-1)
 const expanded = new Set(); // cards showing their raw text
 const REFUSALS_KEPT = 200;
@@ -63,6 +75,14 @@ export function register(on) {
         description: 'Run code-kit verify on this branch, checks included',
       })
       .catch(unavailable('verify-branch'));
+    await $.command
+      .register({
+        name: 'harness',
+        description: "code-kit's harness settings: autonomy, agents, hold time",
+        immediate: true,
+      })
+      .catch(unavailable('harness'));
+    rateLimits = (await $.session.usage().catch(() => null))?.rateLimits ?? [];
     const cli = `${$.plugin.root}/bin/code-kit.mjs`;
     const cwd = e.cwd ?? (await $.session.cwd());
     const session = await $.session.id();
@@ -231,6 +251,74 @@ export function register(on) {
         const ran = await $.process.run(['node', cli, 'verify'], { cwd, timeoutMs: 600000 });
         return { text: `${ran.stdout}${ran.stderr}`.trim() };
       },
+      // SET-2: the Settings view; a change is the person's, confirmed with a reason.
+      harness: async () => {
+        if ((await $.ui.panes()).some((p) => p.id === SETTINGS_ID)) {
+          await $.ui.close({ id: SETTINGS_ID });
+          return {};
+        }
+        await act.reload();
+        if (model.state.kind === 'none') return { text: NOT_CODE_KIT };
+        settingRows = (await json('settings')) ?? [];
+        await $.ui.open({ id: SETTINGS_ID, title: 'Harness', focus: true, closeOnEscape: true });
+        $.ui.invalidate('ui.render');
+        return {};
+      },
+      chooseSetting: (key, value) => {
+        const row = settingRows.find((x) => x.key === key);
+        if (row && String(row.value ?? 'null') === value) return;
+        pendingSetting = { key, value, reason: '', error: null };
+        $.ui.invalidate('ui.render');
+      },
+      confirmSetting: async (reason) => {
+        if (!pendingSetting) return;
+        if (!reason?.trim()) {
+          pendingSetting = {
+            ...pendingSetting,
+            error: 'Give a reason: the approval log keeps it.',
+          };
+          $.ui.invalidate('ui.render');
+          return;
+        }
+        const ran = await $.process.run(
+          [
+            'node',
+            cli,
+            'settings',
+            'set',
+            pendingSetting.key,
+            pendingSetting.value,
+            '--reason',
+            reason.trim(),
+            '--via',
+            'pane',
+          ],
+          { cwd },
+        );
+        if (ran.exitCode !== 0) {
+          pendingSetting = {
+            ...pendingSetting,
+            error: (ran.stderr || ran.stdout).trim().split('\n')[0],
+          };
+          $.ui.invalidate('ui.render');
+          return;
+        }
+        pendingSetting = null;
+        settingRows = (await json('settings')) ?? settingRows;
+        await act.reload();
+      },
+      cancelSetting: () => {
+        pendingSetting = null;
+        $.ui.invalidate('ui.render');
+      },
+      // USE-1: a model request's tokens, put down to the agent that made it and its story and lane.
+      measure: async (agentId, usage) => {
+        if (agentId && !agentsSeen.has(agentId))
+          for (const a of (await $.agent.list()) ?? []) agentsSeen.set(a.id, a);
+        const who = attribution(agentId, agentsSeen.get(agentId) ?? null, model.check, model.state);
+        ledger = withUsage(ledger, who, usage);
+        $.ui.invalidate('ui.render');
+      },
       dismiss: async () => {
         notice = null;
         $.ui.invalidate('ui.render');
@@ -265,6 +353,9 @@ export function register(on) {
     text: `code-kit is still starting; try /${name} again in a moment.`,
   });
   on('command.run', { command: 'lanes' }, async ($, e) => (act ? act.lanes() : starting('lanes')));
+  on('command.run', { command: 'harness' }, async ($, e) =>
+    act ? act.harness() : starting('harness'),
+  );
   on('command.run', { command: 'approvals' }, async ($, e) =>
     act ? act.approvals() : starting('approvals'),
   );
@@ -313,6 +404,27 @@ export function register(on) {
     });
   });
 
+  // USE-1: each model request's usage, as the request ends; the lead's requests carry no agentId.
+  on('turn.step', async function* ($, e, next) {
+    const res = yield* next(e);
+    if (res?.usage && act) await act.measure(e.agentId, res.usage).catch(() => {});
+    return res;
+  });
+  // USE-4: the plan's 5-hour use, as Claude Code measures it.
+  on('session.measure', async ($, e, next) => {
+    if (e.changed.includes('rateLimits')) {
+      rateLimits = e.rateLimits;
+      $.ui.invalidate('ui.render');
+    }
+    return next(e);
+  });
+
+  // What the pane and band show of usage: the session's tokens and the plan's use.
+  const usageNow = () => ({
+    usage: usageSummary(ledger, finishedStories(model.state)),
+    plan: planOf(rateLimits, model.check?.harness?.background?.pauseAtPercent),
+  });
+
   on('turn.start', async ($, e, next) => {
     if (reviewTurn === 'next') reviewTurn = e.turnId;
     return next(e);
@@ -327,14 +439,15 @@ export function register(on) {
     return next(e);
   });
 
-  on('ui.render', { component: 'Pane', requestId: PANE_ID }, async ($, e) =>
-    lanesPane(model.state, $.ui.resolve(e)),
-  );
+  on('ui.render', { component: 'Pane', requestId: PANE_ID }, async ($, e) => {
+    const { usage, plan } = usageNow();
+    return lanesPane(model.state, $.ui.resolve(e), usage, plan);
+  });
 
   // BAND-2: absent when nothing waits. Its lines go above whatever else the band holds (another
   // plugin's lines, such as Context Graph's, or Claude Code's own), which it keeps.
   on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
-    const lines = bandLines({ ...model, reviewing, notice });
+    const lines = bandLines({ ...model, reviewing, notice, ...usageNow() });
     if (!lines.length || !act) return next(e);
     const ours = band(lines, $.ui.resolve(e), (id, line) => act[id](line));
     const below = await next(e);
@@ -353,6 +466,18 @@ export function register(on) {
     });
   });
 
+  on('ui.render', { component: 'Pane', requestId: SETTINGS_ID }, async ($, e) =>
+    settingsView(settingRows, pendingSetting, $.ui.resolve(e), {
+      onChoose: (key, value) => act.chooseSetting(key, value),
+      onReason: (value) => {
+        if (pendingSetting) pendingSetting = { ...pendingSetting, reason: value };
+        $.ui.invalidate('ui.render');
+      },
+      onConfirm: (reason) => act.confirmSetting(reason),
+      onCancel: () => act.cancelSetting(),
+    }),
+  );
+
   on('ui.render', { component: 'Pane', requestId: RESULT_ID }, async ($, e) =>
     resultPane(result, $.ui.resolve(e)),
   );

package/hooks/mod/register.test.ts

@@ -6,6 +6,7 @@ import { expect, mock, test } from 'claude-code/testing';
 const PANE = 'code-kit-lanes';
 const APPROVE = 'code-kit-approve';
 const RESULT = 'code-kit-result';
+const SETTINGS = 'code-kit-settings';
 
 /** A project as the stubs report it; tests change it to move the world on. */
 function project() {
@@ -68,7 +69,8 @@ function project() {
     taken: [] as string[], // command names another command already holds
     stops: [] as any[],
     refs: ' aaa refs/heads/main\n bbb refs/heads/web/st-4\n',
-    agents: [] as { type: string; status: string }[],
+    agents: [] as { type: string; status: string; id?: string; description?: string }[],
+    limits: [] as { kind: string; percentUsed: number }[],
     approveExit: 0,
     mergeExit: 0,
     answer: 'Merge',
@@ -78,6 +80,18 @@ function project() {
     prompts: [] as string[],
     acts: [] as string[][],
     runs: 0,
+    settings: [
+      {
+        key: 'autonomy',
+        value: 'autonomous',
+        default: 'autonomous',
+        about: 'How the lead loop acts',
+      },
+      { key: 'hold.minutes', value: 2, default: 2, about: 'How long a call is held' },
+      { key: 'agents.reviewer.on', value: false, default: false, about: 'A background reviewer' },
+      { key: 'agents.reviewer.model', value: null, default: null, about: "The reviewer's model" },
+    ] as any[],
+    setExit: 0,
   };
 }
 type World = ReturnType<typeof project>;
@@ -119,6 +133,29 @@ function stub(on: any, w: World) {
         ? ran(1, '', 'Nothing was merged. code-kit verify found 1 problem(s) on web/st-4')
         : ran(0, 'Merged web/st-4 into main.');
     }
+    if (sub === 'settings' && argv[3] === 'set') {
+      w.acts.push([...argv.slice(2)]);
+      if (w.setExit)
+        return ran(
+          1,
+          '',
+          '"harness.hold.minutes" must be a number of minutes from 0 (off) to 30\nNothing was changed.',
+        );
+      const row = w.settings.find((s) => s.key === argv[4]);
+      const raw = argv[5];
+      row.value =
+        raw === 'null'
+          ? null
+          : raw === 'true'
+            ? true
+            : raw === 'false'
+              ? false
+              : /^\d+$/.test(raw)
+                ? Number(raw)
+                : raw;
+      return ran(0, `Set harness.${argv[4]} to ${raw}.`);
+    }
+    if (sub === 'settings') return ran(0, JSON.stringify(w.settings));
     return ran(1, '', `unexpected ${argv.join(' ')}`);
   });
   on('session.start', () => ({ cwd: '/work' }));
@@ -135,6 +172,19 @@ function stub(on: any, w: World) {
     w.refusal ? { deny: w.refusal } : { result: { stdout: '', stderr: '', interrupted: false } },
   );
   on('agent.list', () => ({ value: w.agents }));
+  on('session.usage', () => ({ value: { startedAt: 0, context: {}, rateLimits: w.limits } }));
+  on('session.measure', ($: any, e: any) => ({ changed: e.changed }));
+  // A model request, answered with the usage the test gave it.
+  on('turn.step', async function* ($: any, e: any) {
+    return {
+      turnId: e.turnId,
+      index: e.index,
+      answer: '',
+      toolUses: [],
+      stopReason: 'end_turn',
+      usage: e.messageCount === 0 ? null : { model: e.model, ...stepUsage(e.messageCount) },
+    };
+  } as any);
   on('fs.stat', () => ({ value: { kind: 'file', size: 1, mtimeMs: 1, isLink: false } }));
   on('fs.list', () => ({ value: [] }));
   on('session.cwd', () => ({ value: '/work' }));
@@ -163,6 +213,30 @@ function stub(on: any, w: World) {
   });
 }
 
+/** A request of n thousand tokens, split as a model request's usage is. */
+function stepUsage(thousands: number) {
+  const n = thousands * 1000;
+  return {
+    input_tokens: n * 0.3,
+    cache_creation_input_tokens: n * 0.1,
+    output_tokens: n * 0.1,
+    cache_read_input_tokens: n * 0.5,
+  };
+}
+
+/** One model request by an agent (or the lead) of so many thousand tokens, run to its end. */
+async function request($: any, agentId: string | undefined, thousands: number) {
+  const s = $.turn.step({
+    turnId: `t-${agentId ?? 'lead'}`,
+    index: 0,
+    model: 'claude-sonnet-5-5',
+    messageCount: thousands, // the stub beneath answers with this many thousand tokens
+    ...(agentId ? { agentId } : {}),
+  });
+  for await (const _ of s);
+  return s.result;
+}
+
 /** A session started on the project, with the mock clock. */
 async function start($: any, on: any, w: World) {
   stub(on, w);
@@ -714,3 +788,228 @@ test(
     await ui.unmount();
   },
 );
+
+// --- the harness settings -------------------------------------------------------------------------
+
+const harness = ($: any) => $.command.run({ command: 'harness', args: '' });
+
+test('SET-2 /harness opens the settings, each with its value, and /harness again closes it', async ($, on) => {
+  const w = project();
+  await start($, on, w);
+  await harness($);
+  expect(w.opened).toContain(SETTINGS);
+  const ui = await pane($, SETTINGS);
+  expect(await ui.find({ type: 'Text', text: 'hold.minutes' })).toBeDefined();
+  expect((await ui.find({ key: 'set-hold.minutes' }))?.props.value).toBe('2');
+  expect((await ui.find({ key: 'set-autonomy' }))?.props.value).toBe('autonomous');
+  await ui.unmount();
+  await harness($);
+  expect(w.closed).toContain(SETTINGS);
+});
+
+test('SET-2 a change asks for a reason, then is written by the CLI as the pane', async ($, on) => {
+  const w = project();
+  await start($, on, w);
+  await harness($);
+  const ui = await pane($, SETTINGS);
+  await $.ui.select({
+    plugin: 'code-kit',
+    key: 'set-autonomy',
+    value: 'propose',
+    requestId: SETTINGS,
+  });
+  expect(w.acts).toEqual([]);
+  expect(await ui.find({ type: 'Text', text: /Set autonomy to propose\?/ })).toBeDefined();
+  await $.ui.input({ plugin: 'code-kit', key: 'settings-reason', text: '   ' });
+  expect(w.acts).toEqual([]);
+  expect(await ui.find({ type: 'Text', text: /Give a reason/ })).toBeDefined();
+  await $.ui.input({ plugin: 'code-kit', key: 'settings-reason', text: 'watch it for a week' });
+  expect(w.acts).toEqual([
+    ['settings', 'set', 'autonomy', 'propose', '--reason', 'watch it for a week', '--via', 'pane'],
+  ]);
+  expect(await ui.find({ key: 'settings-confirm' })).toBeUndefined();
+  expect((await ui.find({ key: 'set-autonomy' }))?.props.value).toBe('propose');
+  await ui.unmount();
+});
+
+test('SET-2 a number is typed; one the CLI refuses shows why and changes nothing', async ($, on) => {
+  const w = project();
+  w.setExit = 1;
+  await start($, on, w);
+  await harness($);
+  const ui = await pane($, SETTINGS);
+  await $.ui.input({ plugin: 'code-kit', key: 'set-hold.minutes', text: '45' });
+  await $.ui.input({ plugin: 'code-kit', key: 'settings-reason', text: 'longer' });
+  expect(await ui.find({ type: 'Text', text: /from 0 \(off\) to 30/ })).toBeDefined();
+  expect(w.settings[1].value).toBe(2);
+  await press($, 'settings-cancel', SETTINGS);
+  expect(await ui.find({ key: 'settings-confirm' })).toBeUndefined();
+  await ui.unmount();
+});
+
+test("SET-2 the reviewer's model can go back to the session's", async ($, on) => {
+  const w = project();
+  w.settings[3].value = 'haiku';
+  await start($, on, w);
+  await harness($);
+  const ui = await pane($, SETTINGS);
+  expect(await ui.find({ type: 'Text', text: /default the session's/ })).toBeDefined();
+  await $.ui.select({
+    plugin: 'code-kit',
+    key: 'set-agents.reviewer.model',
+    value: '',
+    requestId: SETTINGS,
+  });
+  await press($, 'settings-ok', SETTINGS);
+  expect(w.acts).toEqual([]);
+  await $.ui.input({ plugin: 'code-kit', key: 'settings-reason', text: 'same as the lead' });
+  expect(w.acts[0].slice(0, 4)).toEqual(['settings', 'set', 'agents.reviewer.model', 'null']);
+  await ui.unmount();
+});
+
+test('CARD-4 outside a code-kit project, /harness says so and opens nothing', async ($, on) => {
+  const w = project();
+  w.check.exists = false;
+  w.check.valid = false;
+  await start($, on, w);
+  const said = await harness($);
+  expect(String(said?.text)).toMatch(/code-kit/);
+  expect(w.opened).not.toContain(SETTINGS);
+});
+
+// --- usage per lane ---------------------------------------------------------------------------------
+
+const working = (id: string, type: string, description: string) => ({
+  id,
+  type,
+  description,
+  status: 'running',
+});
+
+test("USE-1 a lane agent's requests show on its lane's row and its story", async ($, on) => {
+  const w = project();
+  w.agents = [working('a1', 'web-engineer', 'Build ST-4: the booking form')];
+  const clock = await start($, on, w);
+  await lanes($);
+  await request($, 'a1', 120);
+  await request($, 'a1', 80);
+  await clock.advance(2000);
+  const ui = await pane($, PANE);
+  expect((await ui.find({ key: 'lane-web' }))?.text).toContain('200k');
+  expect((await ui.find({ key: 'usage-ST-4' }))?.text).toContain('200k');
+  expect((await ui.find({ key: 'lane-api' }))?.text).not.toMatch(/\d+k/);
+  await ui.unmount();
+});
+
+test("USE-1 the lead's requests are the lead's; an agent's brief names its story", async ($, on) => {
+  const w = project();
+  w.agents = [working('a2', 'core-engineer', 'ST-9 pricing rules')];
+  await start($, on, w);
+  await lanes($);
+  await request($, undefined, 30);
+  await request($, 'a2', 50);
+  const ui = await pane($, PANE);
+  expect((await ui.find({ key: 'lane-lead' }))?.text).toContain('30k');
+  expect((await ui.find({ key: 'lane-core' }))?.text).toContain('50k');
+  expect((await ui.find({ key: 'usage-ST-9' }))?.text).toContain('50k');
+  await ui.unmount();
+});
+
+test("USE-2 the background agents' share and the plan's 5-hour use", async ($, on) => {
+  const w = project();
+  w.limits = [{ kind: 'five_hour', percentUsed: 62 }];
+  w.agents = [
+    working('a1', 'web-engineer', 'ST-4 booking form'),
+    working('r1', 'code-reviewer', 'Review web/st-4'),
+  ];
+  await start($, on, w);
+  await lanes($);
+  await request($, 'a1', 150);
+  await request($, 'r1', 50);
+  const ui = await pane($, PANE);
+  expect(await ui.find({ type: 'Text', text: 'Background agents  50k (25%)' })).toBeDefined();
+  expect(await ui.find({ type: 'Text', text: '62% of the 5-hour window' })).toBeDefined();
+  expect(await ui.find({ type: 'Text', text: 'This session  200k tokens' })).toBeDefined();
+  await ui.unmount();
+});
+
+test('USE-3 a story past three times the median of three finished ones is flagged in the band', async ($, on) => {
+  const w = project();
+  w.stories = [
+    ...['ST-1', 'ST-2', 'ST-3'].map((id) => ({
+      id,
+      title: id,
+      lane: 'api',
+      state: 'done',
+      branch: `api/${id.toLowerCase()}`,
+      waitingOn: [],
+    })),
+    ...w.stories,
+  ];
+  w.agents = ['ST-1', 'ST-2', 'ST-3', 'ST-4'].map((id, i) =>
+    working(`a${i}`, i < 3 ? 'api-engineer' : 'web-engineer', `${id} work`),
+  );
+  await start($, on, w);
+  await request($, 'a0', 190);
+  await request($, 'a1', 200);
+  await request($, 'a2', 210);
+  await request($, 'a3', 500);
+  let ui = await bandUi($);
+  expect(await ui.find({ type: 'Text', text: /has used/ })).toBeUndefined();
+  await ui.unmount();
+  await request($, 'a3', 200);
+  ui = await bandUi($);
+  expect(await ui.find({ type: 'Text', text: 'ST-4 has used 3.5× the usual' })).toBeDefined();
+  await ui.unmount();
+});
+
+test('USE-3 with fewer than three finished, nothing is flagged', async ($, on) => {
+  const w = project();
+  w.stories = [
+    { id: 'ST-1', title: 'a', lane: 'api', state: 'done', branch: 'api/st-1', waitingOn: [] },
+    ...w.stories,
+  ];
+  w.agents = [working('a0', 'api-engineer', 'ST-1'), working('a1', 'web-engineer', 'ST-4')];
+  await start($, on, w);
+  await request($, 'a0', 10);
+  await request($, 'a1', 900);
+  const ui = await bandUi($);
+  expect(await ui.find({ type: 'Text', text: /has used/ })).toBeUndefined();
+  await ui.unmount();
+});
+
+test('USE-4 past the pause point the band says background agents are paused, and below it not', async ($, on) => {
+  const w = project();
+  await start($, on, w);
+  const measure = (percentUsed: number) =>
+    $.session.measure({
+      context: {} as any,
+      rateLimits: [{ kind: 'five_hour', percentUsed }],
+      changed: ['rateLimits'],
+    });
+  await measure(82);
+  let ui = await bandUi($);
+  expect(
+    await ui.find({ type: 'Text', text: 'background agents paused: plan at 82%' }),
+  ).toBeDefined();
+  await ui.unmount();
+  await measure(79);
+  ui = await bandUi($);
+  expect(await ui.find({ type: 'Text', text: /paused/ })).toBeUndefined();
+  await ui.unmount();
+});
+
+test('USE-4 the pause point is the harness setting', async ($, on) => {
+  const w = project();
+  (w.check as any).harness = { background: { pauseAtPercent: 90 } };
+  w.limits = [{ kind: 'five_hour', percentUsed: 85 }];
+  await start($, on, w);
+  let ui = await bandUi($);
+  expect(await ui.find({ type: 'Text', text: /paused/ })).toBeUndefined();
+  await ui.unmount();
+  w.limits = [{ kind: 'five_hour', percentUsed: 91 }];
+  await $.session.measure({ context: {} as any, rateLimits: w.limits, changed: ['rateLimits'] });
+  ui = await bandUi($);
+  expect(await ui.find({ type: 'Text', text: /plan at 91%/ })).toBeDefined();
+  await ui.unmount();
+});

package/hooks/mod/view.mjs

@@ -61,7 +61,8 @@ function laneRow(name, agent, stories, atWork) {
  * subagent types at work:
  *   { kind: 'none' }                             no .claude/code-kit.json
  *   { kind: 'invalid', problems }                a config that doesn't validate
- *   { kind: 'ok', lanes, ready, planGaps }       a row per lane, what's ready, the plan's gaps (or null)
+ *   { kind: 'ok', lanes, ready, planGaps, stories }  a row per lane, what's ready, the plan's gaps (or
+ *                                                     null), and each story's id, lane and state
  */
 export function projectState(check, status, next = null, atWork = new Set()) {
   if (!check || check.exists === false) return { kind: 'none' };
@@ -77,7 +78,13 @@ export function projectState(check, status, next = null, atWork = new Set()) {
     const story = stories.find((s) => s.id === id);
     return { id, title: story?.title ?? '', lane: story?.lane ?? null };
   });
-  return { kind: 'ok', lanes, ready, planGaps: status ? (status.problems ?? []).length : null };
+  return {
+    kind: 'ok',
+    lanes,
+    ready,
+    planGaps: status ? (status.problems ?? []).length : null,
+    stories: stories.map((s) => ({ id: s.id, lane: s.lane, state: s.state })),
+  };
 }
 
 const STATE_COLOR = {
@@ -88,8 +95,11 @@ const STATE_COLOR = {
   idle: undefined,
 };
 
-/** The Lanes pane's body, drawn with the elements `$.ui.resolve(e)` returned. */
-export function lanesPane(state, { Box, Text }) {
+/**
+ * The Lanes pane's body, drawn with the elements `$.ui.resolve(e)` returned; `usage` is
+ * usageSummary's, `plan` planOf's (USE-2), either null before there is any.
+ */
+export function lanesPane(state, { Box, Text }, usage = null, plan = null) {
   const text = (value, style = {}) => Text({ ...style, children: [value] });
   if (!state || state.kind === 'none') return text(NOT_CODE_KIT, { dimColor: true });
   if (state.kind === 'invalid')
@@ -108,6 +118,9 @@ export function lanesPane(state, { Box, Text }) {
             text(l.name.padEnd(width), { bold: true }),
             text(l.state.padEnd(9), STATE_COLOR[l.state] ? { color: STATE_COLOR[l.state] } : {}),
             text(l.agent ?? 'the main session', { dimColor: true }),
+            ...(usage?.lanes[l.name]
+              ? [text(tokens(usage.lanes[l.name]), { dimColor: true })]
+              : []),
           ],
         }),
         ...(l.story
@@ -152,10 +165,59 @@ export function lanesPane(state, { Box, Text }) {
       ...notes,
       Box({ flexDirection: 'column', children: rows }),
       Box({ flexDirection: 'column', children: ready }),
+      ...usageSection(usage, plan, text, Box),
     ],
   });
 }
 
+/** USE-2: the plan's 5-hour use as a bar, each story's tokens, and the background agents' share. */
+function usageSection(usage, plan, text, Box) {
+  const lines = [];
+  if (plan?.percent != null)
+    lines.push(
+      Box({
+        key: 'usage-plan',
+        flexDirection: 'row',
+        columnGap: 2,
+        children: [
+          text('Plan'),
+          text(planBar(plan.percent), { color: plan.paused ? 'red' : 'green' }),
+          text(`${plan.percent}% of the 5-hour window`, { dimColor: true }),
+          ...(plan.paused ? [text('background agents paused', { color: 'red' })] : []),
+        ],
+      }),
+    );
+  if (usage?.total) {
+    const flagged = new Map(usage.outliers.map((o) => [o.id, o.ratio]));
+    for (const [id, n] of Object.entries(usage.stories).sort((a, b) => b[1] - a[1]))
+      lines.push(
+        Box({
+          key: `usage-${id}`,
+          flexDirection: 'row',
+          columnGap: 2,
+          children: [
+            text(id),
+            text(tokens(n), { dimColor: true }),
+            ...(flagged.has(id)
+              ? [text(`${flagged.get(id)}× the usual`, { color: 'yellow' })]
+              : []),
+          ],
+        }),
+      );
+    if (usage.background)
+      lines.push(
+        text(
+          `Background agents  ${tokens(usage.background)} (${Math.round((usage.background / usage.total) * 100)}%)`,
+          { dimColor: true },
+        ),
+      );
+    lines.push(text(`This session  ${tokens(usage.total)} tokens`, { dimColor: true }));
+  }
+  return lines.length
+    ? [Box({ flexDirection: 'column', children: [text('Usage', { bold: true }), ...lines] })]
+    : [];
+}
+
 // --- the band, and the person's acts -----------------------------------------------------------
 
 export const APPROVE_ID = 'code-kit-approve';
@@ -185,9 +247,18 @@ const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
 /**
  * The band's lines (BAND-2): one per kind of thing waiting, each with its actions, and none when
  * nothing waits. `reviewing` holds the stories the person has asked the lead to review (ACT-3);
- * `notice` is why the person's last act failed, until they dismiss it.
+ * `notice` is why the person's last act failed, until they dismiss it. `usage` (usageSummary's) flags
+ * outliers (USE-3), and `plan` (planOf's) says when background agents are paused (USE-4).
  */
-export function bandLines({ state, requests, stops, reviewing = new Set(), notice = null }) {
+export function bandLines({
+  state,
+  requests,
+  stops,
+  reviewing = new Set(),
+  notice = null,
+  usage = null,
+  plan = null,
+}) {
   const lines = [];
   if (notice)
     lines.push({ kind: 'notice', text: notice, actions: [{ id: 'dismiss', label: 'Dismiss' }] });
@@ -224,6 +295,21 @@ export function bandLines({ state, requests, stops, reviewing = new Set(), notic
       text: `Finish check failing: ${stops[0].title}${stops.length > 1 ? ` (and ${stops.length - 1} more)` : ''}`,
       actions: [{ id: 'lanes', label: 'Lanes' }],
     });
+  if (usage?.outliers.length) {
+    const [top] = usage.outliers;
+    const more = usage.outliers.length - 1;
+    lines.push({
+      kind: 'usage',
+      text: `${top.id} has used ${top.ratio}× the usual${more ? ` (and ${more} more)` : ''}`,
+      actions: [{ id: 'lanes', label: 'Lanes' }],
+    });
+  }
+  if (plan?.paused)
+    lines.push({
+      kind: 'paused',
+      text: `background agents paused: plan at ${plan.percent}%`,
+      actions: [],
+    });
   // BAND-4: a digit for every action, in the order they're drawn.
   let digit = 0;
   for (const line of lines)
@@ -233,7 +319,14 @@ export function bandLines({ state, requests, stops, reviewing = new Set(), notic
 
 /** The band, drawn with the elements `$.ui.resolve(e)` returned; `onAction(id, line)` acts. */
 export function band(lines, { Box, Text, Button }, onAction) {
-  const COLOR = { notice: 'red', approvals: 'yellow', review: 'blue', finish: 'red' };
+  const COLOR = {
+    notice: 'red',
+    approvals: 'yellow',
+    review: 'blue',
+    finish: 'red',
+    usage: 'yellow',
+    paused: 'yellow',
+  };
   return Box({
     flexDirection: 'column',
     children: lines.map((line) =>
@@ -351,6 +444,25 @@ export function refusalCard(raw) {
       request: request(`write ${m[1]}`),
       raw: text,
     };
+  m = first.match(/^(\S+) is (.+); committing it needs a person's approval in force\./);
+  if (m)
+    return {
+      kind: 'approval',
+      title: `Commit refused: ${m[1]}`,
+      why: `It's ${m[2]}.`,
+      todo: 'A person approves it, here or with the `!` command, for 60 minutes.',
+      request: request(`commit ${m[1]}`),
+      raw: text,
+    };
+  if (/^the \.claude kit is changed only by the lead or with a person's approval\./.test(first))
+    return {
+      kind: 'kit',
+      title: 'Kit edit refused',
+      why: "The .claude kit is changed only by the lead or with a person's approval.",
+      todo: 'A person approves it, here or with the `!` command, for 60 minutes.',
+      request: request('change the .claude kit'),
+      raw: text,
+    };
   m = first.match(/^a new dependency \((.+?)\) needs a person's approval\./);
   if (m)
     return {
@@ -425,3 +537,226 @@ export function approvalsText(requests) {
   ];
   return lines.join('\n');
 }
+
+// --- the harness settings (SET-2) --------------------------------------------------------------
+
+export const SETTINGS_ID = 'code-kit-settings';
+const CHOICES = {
+  autonomy: ['autonomous', 'propose', 'off'],
+  'agents.reviewer.model': ['', 'haiku', 'sonnet', 'opus'],
+};
+const shown = (v) =>
+  v === null || v === '' ? "the session's" : v === true ? 'on' : v === false ? 'off' : String(v);
+
+/**
+ * The Settings view: each setting from `code-kit settings --json` with a control, and, once one is
+ * changed, a confirmation asking the person's reason before anything is written.
+ */
+export function settingsView(rows, pending, { Box, Text, Select, Input, Button }, handlers) {
+  const control = (r) => {
+    const listed = CHOICES[r.key] ?? (typeof r.default === 'boolean' ? [true, false] : null);
+    // A value the list doesn't name (a model given by its id) is still shown, as the one chosen.
+    const choices =
+      listed && !listed.map(String).includes(String(r.value ?? '')) ? [...listed, r.value] : listed;
+    if (choices)
+      return Select({
+        key: `set-${r.key}`,
+        label: '',
+        value: String(r.value ?? ''),
+        options: choices.map((c) => ({ value: String(c), label: shown(c) })),
+        onSelect: (v) => handlers.onChoose(r.key, v === '' ? 'null' : v),
+      });
+    return Input({
+      key: `set-${r.key}`,
+      label: '',
+      value: String(r.value),
+      submitLabel: 'Set',
+      onSubmit: (v) => handlers.onChoose(r.key, v.trim()),
+    });
+  };
+  const rowsView = rows.map((r) =>
+    Box({
+      key: `setting-${r.key}`,
+      flexDirection: 'column',
+      children: [
+        Box({
+          flexDirection: 'row',
+          columnGap: 2,
+          children: [
+            Box({ width: 28, children: [Text({ bold: true, children: [r.key] })] }),
+            control(r),
+            ...(r.value !== r.default
+              ? [Text({ dimColor: true, children: [`default ${shown(r.default)}`] })]
+              : []),
+          ],
+        }),
+        Text({ dimColor: true, children: [`  ${r.about}`] }),
+      ],
+    }),
+  );
+  const confirm = pending
+    ? [
+        Box({
+          key: 'settings-confirm',
+          flexDirection: 'column',
+          borderStyle: 'round',
+          paddingX: 1,
+          children: [
+            Text({
+              bold: true,
+              children: [
+                `Set ${pending.key} to ${shown(pending.value === 'null' ? null : pending.value)}?`,
+              ],
+            }),
+            Text({
+              dimColor: true,
+              children: [
+                'It goes into .claude/code-kit.json, and the approval log keeps your reason.',
+              ],
+            }),
+            Input({
+              key: 'settings-reason',
+              label: 'Reason',
+              value: pending.reason,
+              submitLabel: 'Change it',
+              autoFocus: true,
+              onInput: handlers.onReason,
+              onSubmit: handlers.onConfirm,
+            }),
+            ...(pending.error ? [Text({ color: 'red', children: [pending.error] })] : []),
+            Box({
+              flexDirection: 'row',
+              columnGap: 2,
+              children: [
+                Button({
+                  key: 'settings-ok',
+                  label: 'Change it',
+                  onPress: () => handlers.onConfirm(pending.reason),
+                }),
+                Button({ key: 'settings-cancel', label: 'Cancel', onPress: handlers.onCancel }),
+              ],
+            }),
+          ],
+        }),
+      ]
+    : [];
+  return Box({
+    flexDirection: 'column',
+    rowGap: 1,
+    children: [
+      Text({ bold: true, color: 'cyan', children: ['HARNESS SETTINGS'] }),
+      ...confirm,
+      Box({ flexDirection: 'column', children: rowsView }),
+      Text({
+        dimColor: true,
+        children: ['Lanes, paths, layers and protected paths change through /code-kit:init.'],
+      }),
+    ],
+  });
+}
+
+// --- usage per lane (USE-1 to USE-4) -----------------------------------------------------------
+
+const STORY_ID = /\bST-\d+\b/;
+
+/** A model request's tokens: input (cache writes included), output and cache reads. */
+export function tokensOf(usage) {
+  return {
+    input: (usage?.input_tokens ?? 0) + (usage?.cache_creation_input_tokens ?? 0),
+    output: usage?.output_tokens ?? 0,
+    cache: usage?.cache_read_input_tokens ?? 0,
+  };
+}
+
+/**
+ * Whom a model request is for (USE-1): the lead when no agent made it; a lane's agent by its type,
+ * on the story its brief names or else the story its lane is on; any other agent is background.
+ * `agent` is the `$.agent.list()` entry, or null when the list no longer has it.
+ */
+export function attribution(agentId, agent, check, state) {
+  const laneStory = (name) => state?.lanes?.find((l) => l.name === name)?.story?.id ?? null;
+  if (!agentId) return { key: 'lead', lane: LEAD, story: laneStory(LEAD), background: false };
+  const lane = Object.entries(check?.lanes ?? {}).find(([, l]) => l.agent === agent?.type)?.[0];
+  const named = agent?.description?.match(STORY_ID)?.[0] ?? null;
+  if (!lane) return { key: agentId, lane: null, story: named, background: true };
+  return { key: agentId, lane, story: named ?? laneStory(lane), background: false };
+}
+
+/** The ledger with one request added: entries by agent and story, their tokens summed. */
+export function withUsage(ledger, who, usage) {
+  const id = `${who.key}|${who.story ?? ''}`;
+  const t = tokensOf(usage);
+  const was = ledger[id] ?? { ...who, input: 0, output: 0, cache: 0 };
+  return {
+    ...ledger,
+    [id]: {
+      ...was,
+      input: was.input + t.input,
+      output: was.output + t.output,
+      cache: was.cache + t.cache,
+    },
+  };
+}
+
+const total = (e) => e.input + e.output + e.cache;
+const median = (xs) => {
+  const s = [...xs].sort((a, b) => a - b);
+  const m = Math.floor(s.length / 2);
+  return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2;
+};
+
+/** The stories finished: done, or their lane's branch waiting for review. */
+export function finishedStories(state) {
+  if (state?.kind !== 'ok') return new Set();
+  return new Set([
+    ...(state.stories ?? []).filter((s) => s.state === 'done').map((s) => s.id),
+    ...state.lanes.filter((l) => l.state === 'in review').map((l) => l.story.id),
+  ]);
+}
+
+/**
+ * The session's usage rolled up (USE-1, USE-2): tokens per lane, per story and for the background
+ * agents, and the outliers (USE-3), stories past three times the median of the finished ones once
+ * at least three have finished.
+ */
+export function usageSummary(ledger, finished = new Set()) {
+  const lanes = {};
+  const stories = {};
+  let background = 0;
+  let all = 0;
+  for (const e of Object.values(ledger ?? {})) {
+    const n = total(e);
+    all += n;
+    if (e.background) background += n;
+    else lanes[e.lane] = (lanes[e.lane] ?? 0) + n;
+    if (e.story) stories[e.story] = (stories[e.story] ?? 0) + n;
+  }
+  const done = Object.entries(stories).filter(([id]) => finished.has(id));
+  const usual = done.length >= 3 ? median(done.map(([, n]) => n)) : null;
+  const outliers = usual
+    ? Object.entries(stories)
+        .filter(([, n]) => n > 3 * usual)
+        .map(([id, n]) => ({ id, ratio: Math.round((n / usual) * 10) / 10 }))
+        .sort((a, b) => b.ratio - a.ratio)
+    : [];
+  return { lanes, stories, background, total: all, outliers };
+}
+
+/** The plan's 5-hour use from the session's limits (null off a subscription), and the pause (USE-4). */
+export function planOf(rateLimits, pauseAtPercent = 80) {
+  const percent = (rateLimits ?? []).find((r) => r.kind === 'five_hour')?.percentUsed ?? null;
+  return { percent, paused: percent !== null && percent > pauseAtPercent };
+}
+
+/** Tokens as a person reads them: 950, 12k, 1.4M. */
+export function tokens(n) {
+  if (n < 1000) return String(n);
+  if (n < 1e6) return `${Math.round(n / 1000)}k`;
+  return `${(n / 1e6).toFixed(1)}M`;
+}
+
+/** The plan's use as a bar of ten cells. */
+export function planBar(percent) {
+  const full = Math.max(0, Math.min(10, Math.round(percent / 10)));
+  return `${'█'.repeat(full)}${'░'.repeat(10 - full)}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warren-dean/code-kit",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Keeps AI coding agents inside your project's rules: lanes, layer rules, protected paths and proof before finish, enforced by Claude Code hooks and in CI",
   "license": "MIT",
   "author": "Warren Langeveldt",