@warren-dean/code-kit 0.4.1 → 0.6.0

package/hooks/lib/reviews.mjs

@@ -0,0 +1,39 @@
+// The lead's send-backs: which commit of a branch a review sent back. Until the branch moves past it,
+// status reads the story as waiting for its lane's fix, not as finished again (and next proposes the
+// fix, not a second review of the same commits). Kept beside the requests, in the main checkout.
+import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { projectWorktrees } from './rules.mjs';
+
+export const REVIEWS_FILE = '.claude/state/reviews.jsonl';
+const reviewsFile = (root) => join(projectWorktrees(root)[0] ?? root, REVIEWS_FILE);
+
+/** Records that the review of `branch` at commit `sha` sent it back, and why. */
+export function recordSentBack(root, branch, sha, reason, now = Date.now()) {
+  const file = reviewsFile(root);
+  mkdirSync(dirname(file), { recursive: true });
+  appendFileSync(
+    file,
+    `${JSON.stringify({ at: new Date(now).toISOString(), branch, sha, verdict: 'sent back', reason: reason ?? null })}\n`,
+  );
+}
+
+/** The latest send-back of each branch: { branch: { at, sha, reason } }. */
+export function sentBack(root) {
+  const found = {};
+  let lines = [];
+  try {
+    lines = readFileSync(reviewsFile(root), 'utf8').split('\n').filter(Boolean);
+  } catch {
+    return found;
+  }
+  for (const line of lines) {
+    try {
+      const r = JSON.parse(line);
+      if (r.verdict === 'sent back' && r.branch && r.sha) found[r.branch] = r;
+    } catch {
+      // a line being written, or not one of ours
+    }
+  }
+  return found;
+}

package/hooks/lib/rules.mjs

@@ -20,12 +20,13 @@ import {
   readFileSync,
   readdirSync,
   realpathSync,
+  rmSync,
   statSync,
   writeFileSync,
 } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { homedir } from 'node:os';
-import { dirname, join, relative, resolve } from 'node:path';
+import { basename, dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { DEPENDENCY_APPROVAL, isDependencyFile } from './dependencies.mjs';
 import { globToRegExp, matchesAny } from './glob.mjs';
@@ -33,6 +34,23 @@ import { globToRegExp, matchesAny } from './glob.mjs';
 export const APPROVAL_LOG = '.claude/approval-log.jsonl';
 export const APPROVALS_DIR = '.claude/approvals';
 export const APPROVAL_MINUTES = 60;
+// A dependency approval lasts until the lane commits the install it allows (the story may resume
+// hours later), and at most a week, so a forgotten one doesn't linger.
+export const DEPENDENCY_APPROVAL_DAYS = 7;
+
+/** How long an approval named `name` lasts, in minutes. */
+export const approvalMinutes = (name) =>
+  String(name).startsWith(DEPENDENCY_APPROVAL)
+    ? DEPENDENCY_APPROVAL_DAYS * 24 * 60
+    : APPROVAL_MINUTES;
+
+/** How long approvals for `names` last, in words. */
+export function approvalLifetime(names) {
+  const list = [names].flat();
+  return list.every((n) => String(n).startsWith(DEPENDENCY_APPROVAL))
+    ? `until the install is committed, at most ${DEPENDENCY_APPROVAL_DAYS} days`
+    : `for ${APPROVAL_MINUTES} minutes`;
+}
 // Marks a worktree as a lane's, for a person running that lane; the lead creates it, and it is never work.
 export const LANE_FILE = '.lane';
 const NEVER_WRITABLE = [`${APPROVALS_DIR}/**`, APPROVAL_LOG];
@@ -80,7 +98,7 @@ export function approvalHowTo(names, actor, root, allows = 'these edits', config
     : '';
   return (
     `${lines.join('\n')}\n` +
-    `(a person runs it; the reason is recorded in ${APPROVAL_LOG}, and it allows ${allows} for ${whom}, for ${APPROVAL_MINUTES} minutes)${relay}${delegated}`
+    `(a person runs it; the reason is recorded in ${APPROVAL_LOG}, and it allows ${allows} for ${whom}, ${approvalLifetime(names)})${relay}${delegated}`
   );
 }
 
@@ -211,7 +229,7 @@ export function owns(actor, rel, config) {
 function inForce(file) {
   if (!existsSync(file) || !statSync(file).isFile()) return null;
   const { mtimeMs } = statSync(file);
-  if (Date.now() - mtimeMs >= APPROVAL_MINUTES * 60_000) return null;
+  if (Date.now() - mtimeMs >= approvalMinutes(basename(file)) * 60_000) return null;
   const reason = readFileSync(file, 'utf8').trim();
   return reason ? { reason, grantedAt: new Date(mtimeMs).toISOString() } : null;
 }
@@ -223,6 +241,16 @@ export function approval(root, name, actor) {
   return lane ?? inForce(join(dir, name));
 }
 
+/** Uses up the approval in force for `name` and `actor`: a dependency approval, once its install is committed. */
+export function useApproval(root, name, actor) {
+  const dir = approvalsDir(root);
+  for (const file of [
+    ...(actor?.kind === 'lane' ? [join(dir, actor.lane, name)] : []),
+    join(dir, name),
+  ])
+    if (inForce(file)) return rmSync(file, { force: true });
+}
+
 const requestsFile = (root) => join(projectWorktrees(root)[0] ?? root, REQUESTS_FILE);
 const sameRequest = (a, b) =>
   a.actor === b.actor &&
@@ -306,7 +334,7 @@ export function approvalsInForce(root, now = Date.now()) {
       }
       const a = inForce(file);
       if (!a) continue;
-      const left = APPROVAL_MINUTES - (now - Date.parse(a.grantedAt)) / 60_000;
+      const left = approvalMinutes(name) - (now - Date.parse(a.grantedAt)) / 60_000;
       found.push({
         name,
         ...(lane ? { lane } : {}),
@@ -336,6 +364,33 @@ export function dependencyGrants(root, actor) {
     .filter((g) => g.reason);
 }
 
+/**
+ * During a merge, whether `rel` is exactly as the incoming branch (MERGE_HEAD) has it: then its change
+ * arrives with that branch's history, approvals and audit-log entries, not from the actor concluding
+ * the merge. `staged` compares what will be committed; otherwise the working tree. A file both sides
+ * delete counts too. verify still holds the branch to its rules afterwards.
+ */
+export function arrivesWithMerge(root, rel, { staged = false } = {}) {
+  const run = (...args) => {
+    try {
+      return execFileSync('git', ['-C', root, ...args], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim();
+    } catch {
+      return null;
+    }
+  };
+  if (run('rev-parse', '--verify', '--quiet', 'MERGE_HEAD') === null) return false;
+  const incoming = run('rev-parse', '--verify', '--quiet', `MERGE_HEAD:${rel}`);
+  const mine = staged
+    ? run('rev-parse', '--verify', '--quiet', `:${rel}`)
+    : existsSync(join(root, rel))
+      ? run('hash-object', '--', rel)
+      : null;
+  return incoming === mine;
+}
+
 /**
  * Whether a dependency approval lets `actor` change `rel`: a manifest or lockfile no other lane owns,
  * changed while the actor has a dependency approval in force. Installing a package rewrites them.
@@ -415,6 +470,13 @@ export function laneOf(rel, config) {
   );
 }
 
+/** Who reviews a change to a file any agent may write: the lane an anyActor entry names, else the lead. Null for other files. */
+export function reviewerOf(rel, config) {
+  if (!matchesAny(rel, config.anyActor)) return null;
+  const named = (config.anyActorReviewers ?? []).find((e) => matchesAny(rel, [e.glob]));
+  return named?.reviewer ?? 'lead';
+}
+
 export function ownerOf(rel, config) {
   const lane = laneOf(rel, config);
   if (lane) return `${lane} lane / ${config.lanes[lane].agent}`;

package/hooks/lib/shell.mjs

@@ -0,0 +1,94 @@
+// What a shell command runs, as distinct from the text it carries. Heredoc bodies and quoted strings
+// are data: a commit message, a card's --text, a grep pattern. So rules that recognise a command
+// (`git commit`, `code-kit merge`) look only at the simple commands it runs, each from its own start.
+// Rules about text the command carries (a commit trailer, a path in a redirect) still read it whole.
+
+/** The command with each heredoc's body taken out: the lines after `<<WORD` up to the line `WORD`. */
+export function withoutHeredocs(cmd) {
+  const out = [];
+  let until = null;
+  for (const line of String(cmd).split('\n')) {
+    if (until) {
+      if (line.trim() === until) until = null;
+      continue;
+    }
+    out.push(line);
+    // `<<WORD`, `<<-WORD`, `<<'WORD'` or `<<"WORD"`; not a `<<<` here-string, whose text is on the line.
+    const m = line.match(/(?<!<)<<-?\s*(['"]?)([\w.-]+)\1(?!<)/);
+    if (m && !line.includes('<<<')) until = m[2];
+  }
+  return out.join('\n');
+}
+
+/** `text` with every quoted character replaced by `_`, the quotes kept: same length, nothing inside to match. */
+export function maskQuotes(text) {
+  let out = '';
+  let quote = null;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (quote) {
+      if (c === '\\' && quote === '"' && i + 1 < text.length) {
+        out += '__';
+        i++;
+      } else if (c === quote) {
+        quote = null;
+        out += c;
+      } else out += c === '\n' ? '\n' : '_';
+    } else if (c === '\\' && i + 1 < text.length) {
+      out += '__';
+      i++;
+    } else {
+      if (c === '"' || c === "'") quote = c;
+      out += c;
+    }
+  }
+  return out;
+}
+
+const SEPARATOR = /[;&|\n()`]/;
+const LEADING =
+  /^(?:(?:[A-Za-z_]\w*=(?:"[^"]*"|'[^']*'|\S*)\s+)|(?:sudo|exec|time|command|nohup|env)\s+|!\s+)+/;
+
+/**
+ * The simple commands `cmd` runs, in order: split at `;`, `&`, `|`, newlines, parentheses and
+ * backticks outside quotes, heredoc bodies left out, each without leading `VAR=value` assignments.
+ * Each is `{ text, code }`: `text` as written, `code` with its quoted text masked.
+ */
+export function commandsOf(cmd) {
+  const text = withoutHeredocs(cmd);
+  const mask = maskQuotes(text);
+  const found = [];
+  let start = 0;
+  const take = (end) => {
+    const raw = text.slice(start, end);
+    const lead = raw.length - raw.trimStart().length;
+    const body = raw.trim();
+    const skip = body.match(LEADING)?.[0].length ?? 0;
+    const from = start + lead + skip;
+    const piece = text.slice(from, start + lead + body.length);
+    if (piece) found.push({ text: piece, code: mask.slice(from, from + piece.length) });
+  };
+  for (let i = 0; i < mask.length; i++)
+    if (SEPARATOR.test(mask[i])) {
+      take(i);
+      start = i + 1;
+    }
+  take(mask.length);
+  return found;
+}
+
+/** Whether `cmd` runs a command matching `pattern`, which is anchored at the command's start. */
+export function runs(cmd, pattern, { quoted = true } = {}) {
+  return commandsOf(cmd).some((c) => pattern.test(quoted ? c.text : c.code));
+}
+
+/** The whole command with heredoc bodies out and quoted text masked: for rules that span commands (`curl … | sh`). */
+export function codeOf(cmd) {
+  return maskQuotes(withoutHeredocs(cmd));
+}
+
+/** `git`, with any `-C dir` and `-c key=value` before its subcommand. */
+export const GIT = String.raw`git\s+(?:-[Cc]\s+(?:"[^"]*"|'[^']*'|\S+)\s+)*`;
+
+/** code-kit's command line however it's run: installed, through node (its path quoted or not), or npx. */
+export const CODE_KIT = String.raw`(?:code-kit|node\s+(?:"[^"]*code-kit(?:\.mjs)?"|'[^']*code-kit(?:\.mjs)?'|\S*code-kit(?:\.mjs)?)|npx\s+(?:--yes\s+|-y\s+)?@warren-dean\/code-kit(?:@\S+)?)`;

package/hooks/lib/trace.mjs

@@ -6,7 +6,7 @@ import { execFileSync } from 'node:child_process';
 import { matchesAny } from './glob.mjs';
 import { layerOf } from './layers.mjs';
 import { readRequirements, readStories } from './plan.mjs';
-import { ownerOf } from './rules.mjs';
+import { ownerOf, reviewerOf } from './rules.mjs';
 
 const git = (root, ...args) => {
   try {
@@ -30,7 +30,7 @@ export function storiesOf(root, rel) {
   return [...ids];
 }
 
-/** { path, owner, lane, layer, requirements: [{ id, title, spec, stories }] } for one repository path. */
+/** { path, owner, reviewer, lane, layer, requirements: [{ id, title, spec, stories }] } for one repository path. */
 export function traceFile(root, rel, config) {
   const laneName = Object.keys(config.lanes).find((l) => {
     const { paths, exclude } = config.lanes[l];
@@ -40,6 +40,8 @@ export function traceFile(root, rel, config) {
   const out = {
     path: rel,
     owner: ownerOf(rel, config),
+    // For a file any agent may write: who reviews changes to it.
+    reviewer: reviewerOf(rel, config),
     lane: laneName ? { name: laneName, agent: config.lanes[laneName].agent } : null,
     layer: layer
       ? { name: layer.name, mayImport: layer.mayImport, denyPackages: layer.denyPackages ?? [] }

package/hooks/lib/verify.mjs

@@ -1,7 +1,7 @@
 // The rules for a branch's changes as a whole, for CI and the lead's review: the hooks only see work
 // done in Claude Code sessions, so a person's commits or another tool would otherwise go unchecked.
 // Everything is judged from git (base...HEAD), except the checks, which run in the checkout.
-import { execFileSync } from 'node:child_process';
+import { execFileSync, spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { BASELINE_FILE, loadBaseline, newProblems } from './baseline.mjs';
@@ -10,7 +10,15 @@ import { CONFIG_FILE } from './config.mjs';
 import { isDependencyFile } from './dependencies.mjs';
 import { matchesAny } from './glob.mjs';
 import { layerProblems } from './layers.mjs';
-import { APPROVAL_LOG, SECRETS, laneOf, ownerOf, protectedEntry, screenProblem } from './rules.mjs';
+import {
+  APPROVAL_LOG,
+  SECRETS,
+  laneOf,
+  ownerOf,
+  owns,
+  protectedEntry,
+  screenProblem,
+} from './rules.mjs';
 
 const git = (root, ...args) =>
   execFileSync('git', ['-C', root, ...args], {
@@ -31,9 +39,30 @@ function showAt(root, ref, rel) {
 /** The lane a branch belongs to by its name (`<lane>/<story>`), or null. */
 export function laneOfBranch(branch, config) {
   const lane = branch?.split('/')[0];
+  if (lane === 'lead') return 'lead';
   return lane && config.lanes[lane] ? lane : null;
 }
 
+/** What verify holds a branch to, in words: a lane's paths, or the lead's. */
+export const heldTo = (lane) => (lane === 'lead' ? "the lead's paths" : `the ${lane} lane`);
+
+/**
+ * Files changed by commits made on the branch itself (first parents, merges left out): on the lead's
+ * branch, what the lead wrote, as distinct from lane work it merged in after review.
+ */
+function directChanges(root, from) {
+  const out = git(
+    root,
+    'log',
+    '--first-parent',
+    '--no-merges',
+    '--format=',
+    '--name-only',
+    `${from}..HEAD`,
+  );
+  return new Set(out.split('\n').filter(Boolean));
+}
+
 /** Files changed on this branch since it left `base`. */
 export function branchChanges(root, base) {
   return git(root, 'diff', '--name-only', '--no-renames', `${base}...HEAD`)
@@ -96,6 +125,33 @@ function signedByPerson(root, from, file, signedBy) {
   return messages.length > 0 && messages.every((m) => line.test(m));
 }
 
+/**
+ * Secrets anywhere in the branch's history, not only in the files as they end up: a secret committed
+ * and then deleted is still in the commits that merge. Names that look like secret files, from every
+ * commit; and, where gitleaks is installed, what it finds in the commits' content.
+ */
+function historySecrets(root, from, changed) {
+  const problems = [];
+  const touched = git(root, 'log', '--format=', '--name-only', `${from}..HEAD`)
+    .split('\n')
+    .filter(Boolean);
+  for (const f of new Set(touched))
+    if (SECRETS(f) && !changed.includes(f))
+      problems.push(
+        `${f} may hold secrets, and it's in this branch's history even though it's gone now. Rewrite the history without it before it merges.`,
+      );
+  const scan = spawnSync(
+    'gitleaks',
+    ['detect', '--source', root, `--log-opts=${from}..HEAD`, '--redact', '--no-banner'],
+    { encoding: 'utf8' },
+  );
+  if (scan.error?.code !== 'ENOENT' && scan.status === 1)
+    problems.push(
+      `gitleaks found possible secrets in this branch's commits:\n${`${scan.stdout}${scan.stderr}`.trim()}`,
+    );
+  return problems;
+}
+
 /**
  * Every problem with the branch, grouped: { ownership, protected, layers, baseline, design, checks }.
  * `lane` holds the branch to that lane's paths; `checks: false` leaves the project's checks to CI's
@@ -110,7 +166,9 @@ export function verifyBranch({ root, base, config, lane = null, checks = true })
   const { entries, problems: logProblems } = logEntries(root, from);
   found.protected.push(...logProblems);
   const logged = new Map(entries.map((e) => [e.file, e]));
+  const direct = lane === 'lead' ? directChanges(root, from) : null;
 
+  found.ownership.push(...historySecrets(root, from, changed));
   for (const f of changed) {
     if (SECRETS(f))
       found.ownership.push(`${f} may hold secrets; secrets never go in the repository.`);
@@ -122,7 +180,20 @@ export function verifyBranch({ root, base, config, lane = null, checks = true })
         `${f} is ${guarded.why}, but no approval-log entry records this change. Protected files are committed through Claude Code with code-kit, which logs them.`,
       );
     if (matchesAny(f, config.anyActor)) continue;
-    if (lane) {
+    if (lane === 'lead') {
+      // The lead's branch is held to the lead's paths for what it changes itself; lane work reaches it
+      // by merging the lane's branch, which verify held to that lane.
+      if (!direct.has(f)) continue;
+      const entry = logged.get(f);
+      const approved =
+        (guarded && entry?.approval === guarded.approval) ||
+        signed ||
+        (isDependencyFile(f) && entry?.approval === 'dependency');
+      if (!owns({ kind: 'lead' }, f, config) && !approved)
+        found.ownership.push(
+          `${f}: changed by a commit on the lead's branch, but the lead doesn't own it (owner: ${ownerOf(f, config) ?? 'nobody'}). Lane work comes in by merging the lane's reviewed branch.`,
+        );
+    } else if (lane) {
       const { paths, exclude } = config.lanes[lane];
       const own = matchesAny(f, paths) && !matchesAny(f, exclude);
       const entry = logged.get(f);

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)),
   );