@tech-leads-club/harness-toolkit 0.3.5 → 0.4.0

package/src/entrypoints/stop.ts

@@ -13,7 +13,7 @@ import {
 import { flagsDir } from "../platform/paths.ts";
 import type { Handler, HandlerContext } from "./run.ts";
 import { main } from "./run.ts";
-import { formatLessonsBlock, obsConfigFor, sessionIdFromKey } from "./support.ts";
+import { currentGitSha, formatLessonsBlock, obsConfigFor, sessionIdFromKey } from "./support.ts";
 
 const STAGNATION_FOLLOWUP = [
   "BLOCKED: identical validation fingerprint repeated — no progress between attempts.",
@@ -21,6 +21,31 @@ const STAGNATION_FOLLOWUP = [
   "NEED: change approach. Do not repeat the same fix. Inspect root cause, try a different path, or escalate with BLOCKED/TRIED/NEED.",
 ].join("\n");
 
+/**
+ * A gate is the one proof the harness decides rather than witnesses, so it is recorded where every gate already
+ * funnels through — the same argument `recordGateOutcome` makes for itself: a gate added later cannot be
+ * forgotten ([/decisions/ad-100.md](/decisions/ad-100.md)).
+ *
+ * invariant: only a gate that passed. Recording a failure would let "the gate ran" satisfy a rule that asked for
+ * "the gate passed", which is the whole point of asking.
+ */
+async function observeGateForRules(args: {
+  root: string;
+  sessionKey: string;
+  policy: Policy;
+  gate: string;
+  passed: boolean;
+}): Promise<void> {
+  if (!args.passed || !coreFacade.rules.wantsGate(args.root, args.policy.rules)) {
+    return;
+  }
+  coreFacade.rules.observeGate(args.root, args.policy.rules, args.gate, {
+    sha: await currentGitSha(args.root),
+    sessionKey: args.sessionKey,
+    at: new Date().toISOString(),
+  });
+}
+
 /**
  * hazard: `gate.outcome` was consumed in two places — the rollup counter and the session report's
  * "Gates pass/fail" line — and emitted by nothing. Both read structurally zero, so the report printed a
@@ -200,6 +225,7 @@ async function runLockedGate(args: {
 
   // invariant: recorded outside the lock. A measurement must not widen the window in which one gate blocks another.
   recordGateOutcome({ ...args, artifact, reused: cached !== null });
+  await observeGateForRules({ ...args, gate: args.gate, passed: artifact.passed });
   await creditPendingLessons({
     root: args.root,
     provider: args.provider,
@@ -387,6 +413,28 @@ async function failGate(args: {
   return { kind: "continue", text: parts.join("\n") };
 }
 
+/**
+ * why the sha is fetched twice-or-never: `git rev-parse` is a process spawn and this runs on every stop. The first
+ * pass answers whether any `on: stop` rule fired at all, which costs two directory reads; only then is a sha worth
+ * a process, and the second pass is the one whose verdict counts. Same shape as the action-time rail
+ * ([/decisions/ad-100.md](/decisions/ad-100.md)).
+ */
+async function decideStopRules(
+  root: string,
+  policy: Policy,
+  sessionKey: string,
+): Promise<ReturnType<typeof coreFacade.rules.decideStop>> {
+  const context = { sessionKey, mode: policy.mode };
+  const dryRun = coreFacade.rules.decideStop(root, policy.rules, { ...context, sha: null });
+  if (dryRun.outcomes.length === 0) {
+    return dryRun;
+  }
+  return coreFacade.rules.decideStop(root, policy.rules, {
+    ...context,
+    sha: await currentGitSha(root),
+  });
+}
+
 export const stopHandler: Handler = async (event: HarnessEvent, ctx: HandlerContext): Promise<Decision> => {
   const { policy, capabilities } = ctx;
   const root = event.projectDir;
@@ -829,6 +877,32 @@ export const stopHandler: Handler = async (event: HarnessEvent, ctx: HandlerCont
     });
   }
 
+  /**
+   * The operator's own bar, last among the blockers so every gate the harness owns has already spoken — and after
+   * the gates specifically, because a rule asking for `gate(lint) since HEAD` can only be satisfied once lint has
+   * run this turn ([/decisions/ad-100.md](/decisions/ad-100.md)).
+   *
+   * invariant: `warn` returns `context`, which does not block. Everything else refuses the stop, so a rule the
+   * operator wrote cannot be ended past.
+   */
+  const stopRules = await decideStopRules(root, policy, sessionKey);
+  if (stopRules.decision.kind !== "abstain") {
+    if (stopRules.decision.kind !== "context") {
+      const worst = coreFacade.rules.strictest(stopRules.outcomes);
+      await coreFacade.handoff.patchHandoff(root, provider, {
+        slice: {
+          last_gate_result: "fail",
+          last_failure_category: "policy",
+          blockers: `Rule ${worst?.rule.name ?? "unknown"} is not satisfied for this HEAD.`,
+          next_action: worst?.missing.length
+            ? `Produce ${worst.missing.join(", ")}, then stop again.`
+            : "Satisfy the rule named in the follow-up, then stop again.",
+        },
+      });
+    }
+    return stopRules.decision;
+  }
+
   // why: the pairing of a failure with what resolved it is captured here, immediately before the record that
   // holds the failure identity is cleared. This is the one moment both halves exist
   // ([/decisions/ad-028.md](/decisions/ad-028.md)).

package/src/entrypoints/subagent-stop.ts

@@ -2,10 +2,18 @@ import type { Decision, HarnessEvent } from "../contracts/index.ts";
 import { coreFacade } from "../core/index.ts";
 import type { Handler, HandlerContext } from "./run.ts";
 import { main } from "./run.ts";
+import { observeForRules } from "./support.ts";
 
 // why: no legacy predecessor covers subagent.stop verification — this reuses the same unfinished-work
 // signal (blockers/pending/in_progress/previous_gaps) already carried on the handoff slice.
-export const subagentStopHandler: Handler = (event: HarnessEvent, _ctx: HandlerContext): Decision => {
+export const subagentStopHandler: Handler = async (
+  event: HarnessEvent,
+  ctx: HandlerContext,
+): Promise<Decision> => {
+  // why before the verdict: this records that a subagent of this type finished, which is the proof an operator
+  // rule asks for. It cannot change the decision below ([/decisions/ad-100.md](/decisions/ad-100.md)).
+  await observeForRules(event, ctx);
+
   const handoff = coreFacade.handoff.readHandoff(event.projectDir, event.provider);
   const unfinishedWork =
     Boolean(handoff.blockers) ||

package/src/entrypoints/support.ts

@@ -180,3 +180,35 @@ export function formatLessonsBlock(lessons: HarnessLesson[], title: string, omit
   }
   return lines.join("\n");
 }
+
+/**
+ * The producer half of the feature: what the harness witnessed, written where only the harness can write it.
+ *
+ * hazard: this did not exist in the first cut. `observe` had no caller, so the store was never written, no proof
+ * could ever be satisfied, and every rule that parsed denied for ever — `require:` is mandatory, so that was
+ * every rule ([/decisions/ad-100.md](/decisions/ad-100.md)).
+ *
+ * why `wants` first: this runs on every tool call and the sha is a process spawn. Nothing is asked of git unless
+ * a declared rule requires this kind of proof, so an operator whose only rule wants a subagent pays no git on any
+ * command.
+ *
+ * invariant: after the event, never able to change it. A rail that records what happened must not become a rail
+ * that decides whether it may.
+ */
+export async function observeForRules(
+  event: HarnessEvent,
+  // why the shape and not `HandlerContext`: `run.ts` already imports this module, so naming its type here would
+  // close an import cycle. Only the one field is needed.
+  ctx: { policy: { rules: Policy["rules"] } },
+): Promise<void> {
+  const config = ctx.policy.rules;
+  if (!coreFacade.rules.wants(event.projectDir, config, event)) {
+    return;
+  }
+  const sha = await currentGitSha(event.projectDir);
+  coreFacade.rules.observe(event.projectDir, config, event, {
+    sha,
+    sessionKey: event.sessionKey,
+    at: new Date().toISOString(),
+  });
+}

package/src/entrypoints/tool-after.ts

@@ -4,7 +4,7 @@ import { estimateCostUsd, mapPoolToNeutral } from "../platform/pricing.ts";
 import { readClaudeUsage } from "../providers/index.ts";
 import type { Handler, HandlerContext } from "./run.ts";
 import { main } from "./run.ts";
-import { OBS_CONFIG_AUDIT, obsConfigFor } from "./support.ts";
+import { OBS_CONFIG_AUDIT, obsConfigFor, observeForRules } from "./support.ts";
 
 const OBS_KIND_BY_EVENT: Partial<Record<HarnessEventKind, ObsKind>> = {
   "tool.after": "tool.end",
@@ -48,7 +48,12 @@ function usageGenAi(event: HarnessEvent, ctx: HandlerContext): Record<string, un
   };
 }
 
-export const toolAfterHandler: Handler = (event: HarnessEvent, ctx: HandlerContext) => {
+export const toolAfterHandler: Handler = async (event: HarnessEvent, ctx: HandlerContext) => {
+  // why here and not at `*.before`: arriving on an after-event is what says the tool ran and did not fail. A
+  // failure comes as `tool.failure`, a different event this rail never sees, and the payload carries no exit code
+  // in any of the three shapes the two hosts send ([/decisions/ad-100.md](/decisions/ad-100.md)).
+  await observeForRules(event, ctx);
+
   coreFacade.observability.recordAudit(event.projectDir, event.event, event.raw, ctx.policy.obs.globalSpool);
 
   const kind = OBS_KIND_BY_EVENT[event.event];

package/src/entrypoints/tool-before.ts

@@ -2,7 +2,7 @@ import type { Decision, HarnessEvent } from "../contracts/index.ts";
 import { coreFacade } from "../core/index.ts";
 import type { Handler, HandlerContext } from "./run.ts";
 import { main } from "./run.ts";
-import { obsConfigFor, readModelFromToolInput, subagentSpawnInput } from "./support.ts";
+import { currentGitSha, obsConfigFor, readModelFromToolInput, subagentSpawnInput } from "./support.ts";
 
 const READONLY_BLOCKED_TOOLS = new Set(["Write", "Delete", "Shell"]);
 
@@ -43,6 +43,33 @@ function recordShellDecisionIfShell(event: HarnessEvent, ctx: HandlerContext, de
   }
 }
 
+/**
+ * why the sha is read here and not in `run.ts`: `git rev-parse` is a process spawn, and this fires on every tool
+ * call. It is asked for only once a rule has actually fired, so an operator who declared nothing pays nothing
+ * ([/decisions/ad-100.md](/decisions/ad-100.md)).
+ */
+async function rulesDecision(event: HarnessEvent, ctx: HandlerContext): Promise<Decision> {
+  const config = ctx.policy.rules;
+  const trigger = { event: event.event, toolName: event.toolName, command: event.command };
+  const dryRun = coreFacade.rules.decideAction(event.projectDir, config, trigger, {
+    sha: null,
+    sessionKey: event.sessionKey,
+    mode: ctx.policy.mode,
+  });
+  if (dryRun.outcomes.length === 0) {
+    return { kind: "abstain" };
+  }
+  // why twice: the first pass answers whether any rule fired at all, which costs no git. Only then is the sha
+  // worth a process, and the second pass is the one whose verdict counts.
+  const sha = await currentGitSha(event.projectDir);
+  const verdict = coreFacade.rules.decideAction(event.projectDir, config, trigger, {
+    sha,
+    sessionKey: event.sessionKey,
+    mode: ctx.policy.mode,
+  });
+  return verdict.decision;
+}
+
 function handleShellBefore(event: HarnessEvent, ctx: HandlerContext): Decision {
   const { policy } = ctx;
   const decision = coreFacade.shellPolicy.evaluateShellCommand({
@@ -108,10 +135,10 @@ async function handleToolBefore(event: HarnessEvent, ctx: HandlerContext): Promi
   return { kind: "allow" };
 }
 
-export const toolBeforeHandler: Handler = (
+export const toolBeforeHandler: Handler = async (
   event: HarnessEvent,
   ctx: HandlerContext,
-): Decision | Promise<Decision> => {
+): Promise<Decision> => {
   // invariant: the floor runs first and reads no policy, so no config value and no agent edit can
   // reach a decision before it.
   const floor = coreFacade.floor.evaluateFloor({
@@ -159,6 +186,20 @@ export const toolBeforeHandler: Handler = (
     }
   }
 
+  /**
+   * The operator's own rules, after the floor and after the integrity check, because both are unconditional and a
+   * rail comes second ([/decisions/ad-077.md](/decisions/ad-077.md)).
+   *
+   * invariant: `deny` and `ask` answer here; `follow-up` and `warn` abstain and are the stop rail's business. With
+   * the capability off, or with no rule files, `decideAction` reads two directory entries and abstains — which is
+   * what keeps a machine that never opted in byte-identical to before ([/decisions/ad-100.md](/decisions/ad-100.md)).
+   */
+  const rulesVerdict = await rulesDecision(event, ctx);
+  if (rulesVerdict.kind !== "abstain") {
+    recordShellDecisionIfShell(event, ctx, rulesVerdict);
+    return rulesVerdict;
+  }
+
   switch (event.event) {
     case "shell.before":
       return handleShellBefore(event, ctx);

package/src/platform/frontmatter.ts

@@ -0,0 +1,142 @@
+/**
+ * The one frontmatter reader.
+ *
+ * why here: there were two — a full parser in `tools/dev/check-docs-bundle.ts`, which never ships and which
+ * `core/` may not import, and a private single-field extractor in `core/release/release.decisions.ts`. Operator
+ * rules need a third caller, and a third copy is the duplication this product's own gate refuses. It sits in
+ * `platform/` because it is a format primitive with no policy in it, and because that is the one direction all
+ * three callers may import from ([/decisions/ad-100.md](/decisions/ad-100.md)).
+ *
+ * invariant: pure. No filesystem, no clock. The caller reads the file.
+ */
+
+export type FrontmatterValue = string | string[];
+export type Frontmatter = Record<string, FrontmatterValue>;
+
+/** The shape `check-docs-bundle` already consumed, kept so moving this changed no caller's contract. */
+export type ParseResult = { frontmatter: Frontmatter | null; error: string | null };
+
+export type FrontmatterDoc = {
+  fields: Frontmatter;
+  /** Everything after the closing fence, verbatim. An operator rule's instruction lives here. */
+  body: string;
+};
+
+function extractFrontmatterBlock(content: string): { block: string; bodyAt: number } | null {
+  if (!content.startsWith("---\n") && !content.startsWith("---\r\n")) {
+    return null;
+  }
+  const firstBreak = content.indexOf("\n");
+  const rest = content.slice(firstBreak + 1);
+  const closingMatch = /^---\s*$/m.exec(rest);
+  if (!closingMatch) {
+    return null;
+  }
+  return {
+    block: rest.slice(0, closingMatch.index),
+    bodyAt: firstBreak + 1 + closingMatch.index + closingMatch[0].length,
+  };
+}
+
+function stripQuotes(raw: string): string {
+  const trimmed = raw.trim();
+  if (trimmed.length >= 2) {
+    const first = trimmed[0];
+    const last = trimmed[trimmed.length - 1];
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+      return trimmed.slice(1, -1);
+    }
+  }
+  return trimmed;
+}
+
+/**
+ * hazard: an escaped quote inside a value survived the outer-quote strip and reached the operator as a literal
+ * `\"` in their terminal. Seen in a real update run ([/decisions/ad-034.md](/decisions/ad-034.md)).
+ */
+function unescapeQuotes(value: string): string {
+  return value.replace(/\\(["'\\])/g, "$1");
+}
+
+function parseValue(raw: string): FrontmatterValue {
+  const trimmed = raw.trim();
+  if (trimmed.startsWith("[") && trimmed.endsWith("]")) {
+    const inner = trimmed.slice(1, -1).trim();
+    if (inner === "") {
+      return [];
+    }
+    return inner.split(",").map((item) => unescapeQuotes(stripQuotes(item)));
+  }
+  return unescapeQuotes(stripQuotes(trimmed));
+}
+
+/**
+ * why block lists: a rule declares several proofs, and `require: [a, b]` on one line is not how anybody writes
+ * three of them. `key:` with nothing after it opens a list; `key: value` closes any list before it.
+ */
+export function parseFrontmatterDoc(content: string): { doc: FrontmatterDoc | null; error: string | null } {
+  const extracted = extractFrontmatterBlock(content);
+  if (extracted === null) {
+    return { doc: null, error: "missing --- frontmatter block" };
+  }
+  const fields: Frontmatter = {};
+  let listKey: string | null = null;
+
+  for (const line of extracted.block.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed === "" || trimmed.startsWith("#")) {
+      continue;
+    }
+    if (trimmed.startsWith("- ")) {
+      if (listKey === null) {
+        return { doc: null, error: `list item with no key above it: "${trimmed}"` };
+      }
+      const current = fields[listKey];
+      const item = unescapeQuotes(stripQuotes(trimmed.slice(2)));
+      fields[listKey] = Array.isArray(current) ? [...current, item] : [item];
+      continue;
+    }
+    const separator = trimmed.indexOf(":");
+    if (separator === -1) {
+      return { doc: null, error: `unparseable frontmatter line: "${trimmed}"` };
+    }
+    const key = trimmed.slice(0, separator).trim();
+    if (key === "") {
+      return { doc: null, error: `frontmatter line has an empty key: "${trimmed}"` };
+    }
+    const value = trimmed.slice(separator + 1);
+    if (value.trim() === "") {
+      fields[key] = [];
+      listKey = key;
+      continue;
+    }
+    fields[key] = parseValue(value);
+    listKey = null;
+  }
+
+  return { doc: { fields, body: content.slice(extracted.bodyAt).trim() }, error: null };
+}
+
+/** invariant: the shape the docs bundle check already used. One implementation, two entry points. */
+export function parseFrontmatter(content: string): ParseResult {
+  const { doc, error } = parseFrontmatterDoc(content);
+  return doc === null ? { frontmatter: null, error } : { frontmatter: doc.fields, error: null };
+}
+
+/** why: one field, by name, for a caller that wants nothing else. */
+export function frontmatterField(content: string, field: string): string | undefined {
+  const { doc } = parseFrontmatterDoc(content);
+  const value = doc?.fields[field];
+  if (typeof value !== "string" || value.trim() === "") {
+    return undefined;
+  }
+  return value.trim();
+}
+
+/** why: every field a rule reads is one value or a list of them, and the caller should not care which. */
+export function asList(value: FrontmatterValue | undefined): string[] {
+  if (value === undefined) {
+    return [];
+  }
+  return (Array.isArray(value) ? value : [value]).filter((item) => item !== "");
+}

package/src/platform/links.ts

@@ -48,6 +48,38 @@ export function linkDir(source: string, target: string): LinkOutcome {
   return { kind: replaced ? "relinked" : "linked", target, source };
 }
 
+/**
+ * Point a *file* `target` at `source`, for the `tlc` command on `PATH`.
+ *
+ * why not `linkDir`: its link type is `"junction"`, which Windows reads and which only means anything for a
+ * directory. A file gets no type argument, which is correct on every platform — and where a platform refuses to
+ * create one, the reason is reported rather than thrown, because a missing convenience link must not fail an
+ * install that otherwise worked ([/decisions/ad-101.md](/decisions/ad-101.md)).
+ *
+ * invariant: the same contract as `linkDir` — an existing link is replaced, anything else is refused. A real file
+ * called `tlc` in someone's bin directory is theirs.
+ */
+export function linkFile(source: string, target: string): LinkOutcome {
+  let replaced = false;
+  if (isLink(target)) {
+    rmSync(target, { force: true });
+    replaced = true;
+  } else if (existsSync(target)) {
+    return {
+      kind: "refused",
+      target,
+      reason: `${target} exists and is not a link — move it aside and re-run`,
+    };
+  }
+  try {
+    mkdirSync(dirname(target), { recursive: true });
+    symlinkSync(source, target);
+  } catch (error) {
+    return { kind: "refused", target, reason: (error as Error).message };
+  }
+  return { kind: replaced ? "relinked" : "linked", target, source };
+}
+
 /**
  * why lstat: a link whose destination is gone is still a link, and `existsSync` says it is not there — so the
  * check has to come first, or a dangling link reads as free space. Node reports a Windows junction as a symbolic

package/src/platform/paths.ts

@@ -1,5 +1,5 @@
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { delimiter, join, resolve } from "node:path";
 
 function harnessDir(root: string): string {
   return join(root, ".tlc", "harness");
@@ -22,15 +22,38 @@ export function runtimeHome(env: NodeJS.ProcessEnv = process.env): string {
 
 /**
  * invariant: `tlc-exec` always sets `TLC_HOME` in the child, so the child cannot tell an operator's choice from
- * the launcher's own resolution. This flag is that difference, and only the installer needs it — everything else
- * wants the resolved home either way.
+ * the launcher's own resolution. This flag is that difference.
  */
 export function runtimeHomeWasChosen(env: NodeJS.ProcessEnv = process.env): boolean {
   return env.TLC_HOME_FROM_ENV === "1";
 }
 
+/**
+ * Where this **machine's** operator data lives: the user-tier config, the global lesson tier, the global rules,
+ * the price catalogue, the cross-repo spool.
+ *
+ * hazard: all of that used to resolve through `runtimeHome()`, which names where the *code* lives and moves with
+ * the install. With two installs on one machine there were two "global" tiers, silently — and switching between
+ * them looked like data loss. Measured on an operator's machine: a lesson saved with `--global` landed in a
+ * checkout's state directory while the CLI printed "every product on this machine will read it", and a user-tier
+ * config with a subagent allowlist stopped being read the moment the runtime home changed
+ * ([/decisions/ad-101.md](/decisions/ad-101.md)).
+ *
+ * why the flag rather than always the conventional path: an operator who exports `TLC_HOME` is choosing a home and
+ * means it, and the test suite pins one for hermeticity. Only the launcher's own resolution — which marks itself
+ * `TLC_HOME_FROM_ENV=0` — must not be allowed to invent a second machine.
+ */
+export function machineHome(env: NodeJS.ProcessEnv = process.env): string {
+  return env.TLC_HOME_FROM_ENV === "0" ? conventionalRuntimeHome() : runtimeHome(env);
+}
+
+/** invariant: the one path install seeds and update never writes ([/decisions/ad-056.md](/decisions/ad-056.md)). */
+export function machineConfigPath(env: NodeJS.ProcessEnv = process.env): string {
+  return join(machineHome(env), "config.json");
+}
+
 export function runtimeStateDir(): string {
-  return join(runtimeHome(), "state");
+  return join(machineHome(), "state");
 }
 
 // why: one file for every repository on the machine. Per-repo state stays authoritative; this is the
@@ -105,3 +128,34 @@ export function userSettingsPaths(): string[] {
 export function providerConfigDirs(): string[] {
   return [cursorConfigDir(), claudeConfigDir()];
 }
+
+/**
+ * Where the `tlc` command goes so a shell can find it.
+ *
+ * hazard: this lived only in `uninstall-runtime.ts`, which removed a launcher `install` never created. The command
+ * came from npm's own shim instead — and that shim sits in the `bin` directory of whichever Node version npm ran
+ * under, which leaves `PATH` the moment a version manager switches. Measured on an operator's machine: a
+ * successful install followed immediately by `tlc: command not found`
+ * ([/decisions/ad-101.md](/decisions/ad-101.md)).
+ *
+ * invariant: one definition, so what install creates and what uninstall removes cannot drift apart.
+ */
+export function launcherBinDir(env: NodeJS.ProcessEnv = process.env): string {
+  return env.TLC_BIN_DIR?.trim() || join(homedir(), ".local", "bin");
+}
+
+/** why the extensionless wrapper: it is what a shell runs. The `.cmd` beside it is Windows's copy of the same. */
+export function launcherNames(): readonly string[] {
+  return ["tlc", "tlc.cmd"];
+}
+
+/**
+ * Whether a shell would find something in this directory.
+ *
+ * why it matters at install time: a launcher nobody can reach is worse than none, because `doctor` then reports a
+ * healthy link while the command still does not exist.
+ */
+export function isOnPath(dir: string, env: NodeJS.ProcessEnv = process.env): boolean {
+  const entries = (env.PATH ?? "").split(delimiter).filter((entry) => entry.length > 0);
+  return entries.some((entry) => resolve(entry) === resolve(dir));
+}

package/src/platform/pricing.ts

@@ -13,7 +13,7 @@
  */
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { runtimeHome } from "./paths.ts";
+import { machineHome } from "./paths.ts";
 
 export type VendorPool = "cursor_models" | "anthropic_models" | "other_models" | "auto" | "unknown";
 export type NeutralPool = "provider_native" | "other" | "auto" | "unknown";
@@ -163,7 +163,7 @@ function fuzzyFind(table: PriceTable, needle: string): { key: string; entry: Mod
 
 /** The catalogue the refresh writes. Not versioned, not packaged, per machine. */
 export function cataloguePath(): string {
-  return join(runtimeHome(), "model-prices.json");
+  return join(machineHome(), "model-prices.json");
 }
 
 /**
@@ -174,7 +174,7 @@ export function cataloguePath(): string {
  * refresh would replace. The refresh moves such a file here rather than overwriting it.
  */
 export function overridesPath(): string {
-  return join(runtimeHome(), "model-prices.local.json");
+  return join(machineHome(), "model-prices.local.json");
 }
 
 export type PriceResolution = {

package/src/platform/screen.ts

@@ -2,7 +2,14 @@ import { KV_WIDTH, type StatusLevel, type Style, SYMBOLS } from "./style.ts";
 
 export type Row = { label: string; value: string; level?: StatusLevel };
 
-export type Section = { title?: string; rows?: Row[]; lines?: string[] };
+/**
+ * `wrap` marks a section's lines as prose, so they are broken at word boundaries to fit the terminal.
+ *
+ * why opt-in rather than always: a section's lines are sometimes a command to copy — wrapping
+ * `tlc harness policy accept <path>` across two lines makes it unpasteable. Prose and payload look identical to a
+ * renderer, so the caller says which it has ([/decisions/ad-101.md](/decisions/ad-101.md)).
+ */
+export type Section = { title?: string; rows?: Row[]; lines?: string[]; wrap?: boolean };
 
 export type Screen = {
   title: string;
@@ -11,9 +18,54 @@ export type Screen = {
   footer?: string;
 };
 
+/** The two-space indent `render` puts in front of every line, which the wrap width has to leave room for. */
+const INDENT = 2;
+
+/**
+ * why clamped: a 400-column terminal produces lines nobody tracks across, and an 8-column one produces a word per
+ * line. Outside a TTY there is no width to read, and a fixed sensible one beats guessing.
+ */
+export function terminalColumns(columns: number | undefined = process.stdout.columns): number {
+  return Math.min(110, Math.max(60, columns ?? 100));
+}
+
+/**
+ * Break prose at word boundaries so nothing is hidden.
+ *
+ * hazard: the lessons list cut the instruction at 160 characters with no marker — a 263-character lesson lost 103
+ * of them mid-word, and the reader could not tell. An operator asked why their lesson had been cut; it had not
+ * been, only its display had ([/decisions/ad-101.md](/decisions/ad-101.md)).
+ *
+ * invariant: a word longer than the width stands on its own line rather than being cut. Losing a character is
+ * worse than an overlong line, because only one of the two is visible.
+ */
+export function wrapText(text: string, width: number): string[] {
+  if (text === "") {
+    return [""];
+  }
+  const lines: string[] = [];
+  let current = "";
+  for (const word of text.split(/\s+/).filter((part) => part.length > 0)) {
+    if (current === "") {
+      current = word;
+      continue;
+    }
+    if (current.length + 1 + word.length <= width) {
+      current = `${current} ${word}`;
+      continue;
+    }
+    lines.push(current);
+    current = word;
+  }
+  if (current !== "") {
+    lines.push(current);
+  }
+  return lines.length === 0 ? [""] : lines;
+}
+
 // why: screens describe their content and never their paint, so spacing, colour and alignment are decided once.
 // A new screen can only emit this shape, which is what makes "no screen outside the standard" mechanical.
-export function render(screen: Screen, style: Style): string {
+export function render(screen: Screen, style: Style, columns = terminalColumns()): string {
   const out: string[] = [style.heading(screen.title.toUpperCase())];
 
   if (screen.summary && screen.summary.length > 0) {
@@ -35,7 +87,14 @@ export function render(screen: Screen, style: Style): string {
       out.push(style.kv(row.label, value, width));
     }
     for (const line of section.lines ?? []) {
-      out.push(line === "" ? "" : `  ${line}`);
+      if (line === "") {
+        out.push("");
+        continue;
+      }
+      const parts = section.wrap ? wrapText(line, columns - INDENT) : [line];
+      for (const part of parts) {
+        out.push(`  ${part}`);
+      }
     }
   }