@tech-leads-club/harness-toolkit 0.3.0 → 0.3.2

package/dist/chunks/compact-before-1e4qg1qt.mjs

@@ -0,0 +1,1185 @@
+import {
+  JSON_FLAG,
+  emitJson,
+  takeJsonFlag,
+  unknownFlags
+} from "./compact-before-wnnds45y.mjs";
+import {
+  coreFacade
+} from "./compact-before-2hpbfxm5.mjs";
+import {
+  PLAIN,
+  createStyle,
+  render
+} from "./compact-before-49j320yp.mjs";
+import {
+  __require,
+  flagsDir,
+  projectConfigPath,
+  projectStateDir,
+  providerConfigDirs,
+  runtimeHome
+} from "./compact-before-4jrq0sqs.mjs";
+
+// bin/tlc-cli.ts
+import { spawnSync } from "node:child_process";
+import {
+  existsSync as existsSync2,
+  lstatSync as lstatSync2,
+  mkdirSync as mkdirSync2,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  rmSync as rmSync2,
+  writeFileSync
+} from "node:fs";
+import { delimiter, join as join2 } from "node:path";
+
+// src/platform/links.ts
+import { copyFileSync, existsSync, lstatSync, mkdirSync, rmSync, symlinkSync } from "node:fs";
+import { dirname, join } from "node:path";
+var LINK_TYPE = "junction";
+function linkDir(source, target) {
+  let replaced = false;
+  if (isLink(target)) {
+    rmSync(target, { recursive: true, 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`
+    };
+  }
+  mkdirSync(dirname(target), { recursive: true });
+  symlinkSync(source, target, LINK_TYPE);
+  return { kind: replaced ? "relinked" : "linked", target, source };
+}
+function isLink(path) {
+  try {
+    return lstatSync(path).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+function seedConfig(dest) {
+  const path = join(dest, "config.json");
+  const example = join(dest, "config.example.json");
+  if (existsSync(path) || !existsSync(example)) {
+    return { seeded: false, path };
+  }
+  copyFileSync(example, path);
+  return { seeded: true, path };
+}
+
+// bin/tlc-cli.ts
+class UsageError extends Error {
+}
+function resolveProjectRoot() {
+  return process.env.TLC_PROJECT_DIR ?? process.cwd();
+}
+function modeFilePath(root) {
+  return join2(projectStateDir(root), "harness-mode");
+}
+function grindFlagPath(root) {
+  return join2(flagsDir(root), "grind-on");
+}
+function skipFlagPath(root) {
+  return join2(flagsDir(root), "skip-verify");
+}
+function focusFlagPath(root) {
+  return join2(flagsDir(root), "focus");
+}
+function pairedFlagPath(root) {
+  return join2(flagsDir(root), "paired");
+}
+function ensureFlagsDir(root) {
+  mkdirSync2(flagsDir(root), { recursive: true });
+}
+function readMode(root) {
+  return coreFacade.policy.loadPolicy(root).mode;
+}
+function grindOn(root) {
+  return coreFacade.policy.loadPolicy(root).grind.enabled;
+}
+function gatesPaused(root) {
+  return existsSync2(skipFlagPath(root));
+}
+function acceptedModes() {
+  return coreFacade.policy.OPERATOR_MODES.join(" | ");
+}
+function statusScreen(root) {
+  const report = statusJson(root);
+  const origin = report.modeInvalid === undefined ? `from ${report.modeOrigin}` : `${report.modeOrigin} — \`${report.modeInvalid}\` is not a posture; accepted: ${acceptedModes()}`;
+  return {
+    title: "harness status",
+    summary: [root],
+    sections: [
+      {
+        rows: [
+          { label: "mode", value: `${report.mode} [${origin}]`, level: "info" },
+          {
+            label: "grind",
+            value: report.grind ? "ON — stop hook re-runs lint/tests and auto-retries on fail" : "OFF — no auto fix loops",
+            level: report.grind ? "ok" : "info"
+          },
+          {
+            label: "gates",
+            value: report.gatesPaused ? "PAUSED — stop checks disabled" : "active",
+            level: report.gatesPaused ? "warn" : "ok"
+          }
+        ]
+      },
+      {
+        title: "Postures",
+        lines: [
+          "paired  explains as it goes, and asks before any sizable move",
+          "solo    works on its own; a destructive action, a dead-end or real ambiguity reaches you",
+          "focus   only a destructive action or a dead-end reaches you; it settles ambiguity itself"
+        ]
+      }
+    ],
+    footer: "verification is identical at all three postures  ·  tlc harness why  ·  tlc harness doctor"
+  };
+}
+function statusText(root, style = PLAIN) {
+  return render(statusScreen(root), style);
+}
+function statusJson(root) {
+  const policy = coreFacade.policy.loadPolicy(root);
+  const posture = coreFacade.policy.resolveProjectPosture(root);
+  return {
+    root,
+    mode: posture.mode,
+    modeOrigin: posture.origin,
+    ...posture.invalid === undefined ? {} : { modeInvalid: posture.invalid },
+    grind: policy.grind.enabled,
+    gatesPaused: gatesPaused(root)
+  };
+}
+function setGrind(root, on) {
+  ensureFlagsDir(root);
+  const path = grindFlagPath(root);
+  if (on) {
+    writeFileSync(path, "");
+    coreFacade.policy.refreshPolicyBaselines(root);
+    return "grind ON — stop hook will lint/test and auto-retry on failure";
+  }
+  if (existsSync2(path)) {
+    rmSync2(path);
+  }
+  coreFacade.policy.refreshPolicyBaselines(root);
+  return "grind OFF — no auto fix loops";
+}
+function setPaused(root, on) {
+  ensureFlagsDir(root);
+  const path = skipFlagPath(root);
+  if (on) {
+    writeFileSync(path, "");
+    coreFacade.policy.refreshPolicyBaselines(root);
+    return "gates PAUSED — stop checks disabled until `tlc harness resume`";
+  }
+  if (existsSync2(path)) {
+    rmSync2(path);
+  }
+  coreFacade.policy.refreshPolicyBaselines(root);
+  return "gates ACTIVE again";
+}
+var MODE_CONFIRMATION = {
+  paired: "mode paired — explains as it goes, and asks before any sizable move",
+  solo: "mode solo — a destructive action, a dead-end or real ambiguity reaches you",
+  focus: "mode focus — only a destructive action or a dead-end reaches you; ambiguity is settled for you"
+};
+function setMode(root, raw) {
+  const mode = raw.toLowerCase();
+  if (!coreFacade.policy.isOperatorMode(mode)) {
+    throw new UsageError(`mode must be: ${acceptedModes()}`);
+  }
+  ensureFlagsDir(root);
+  writeFileSync(modeFilePath(root), `${mode}
+`);
+  coreFacade.policy.refreshPolicyBaselines(root);
+  return MODE_CONFIRMATION[mode];
+}
+function handoffJson(root) {
+  const file = coreFacade.handoff.readHandoffFile(root);
+  const providers = {};
+  for (const provider of Object.keys(file.by_provider)) {
+    providers[provider] = coreFacade.handoff.readHandoff(root, provider);
+  }
+  return { root, providers };
+}
+function handoffScreen(report) {
+  const names = Object.keys(report.providers).sort();
+  if (names.length === 0) {
+    return {
+      title: "handoff",
+      summary: [report.root],
+      sections: [{ lines: ["nothing recorded yet — this is a fresh start, not a missing file"] }]
+    };
+  }
+  const sections = [];
+  for (const name of names) {
+    const slice = report.providers[name];
+    if (!slice) {
+      continue;
+    }
+    const rows = [];
+    for (const [label, value, level] of [
+      ["blockers", slice.blockers, "warn"],
+      ["next", slice.next_action, "info"],
+      ["last gate", slice.last_gate_result, slice.last_gate_result === "pass" ? "ok" : "warn"],
+      ["last failure", slice.last_failure_category, "fail"]
+    ]) {
+      if (value) {
+        rows.push({ label, value: String(value), level });
+      }
+    }
+    for (const [label, list] of [
+      ["in progress", slice.in_progress],
+      ["pending", slice.pending],
+      ["gaps", slice.previous_gaps?.map((gap) => gap.summary)]
+    ]) {
+      if (list && list.length > 0) {
+        rows.push({ label, value: list.slice(0, 6).join(" | ") });
+      }
+    }
+    sections.push({ title: `${name} (updated ${slice.updated_at})`, rows });
+  }
+  return { title: "handoff", summary: [report.root], sections };
+}
+function handoffText(report, style = PLAIN) {
+  return render(handoffScreen(report), style);
+}
+function attestScreen(root) {
+  const records = coreFacade.attest.readAttestations(root);
+  const verdict = coreFacade.attest.verifyChain(records);
+  const head = verdict.ok ? { label: "chain", value: `attestation chain OK — ${verdict.length} session(s)`, level: "ok" } : {
+    label: "chain",
+    value: `attestation chain BROKEN at record ${verdict.brokenAt} (${verdict.reason})`,
+    level: "fail"
+  };
+  if (records.length === 0) {
+    return {
+      title: "attestation",
+      summary: [root],
+      sections: [{ rows: [head] }, { lines: ["no sessions recorded yet"] }]
+    };
+  }
+  const sections = [{ rows: [head] }];
+  for (const record of records.slice(-10).reverse()) {
+    const rules = Object.entries(record.decisionsByRule).map(([rule, count]) => `${rule}=${count}`).join(" ");
+    sections.push({
+      title: `${record.ts}  ${record.provider}/${record.session}`,
+      rows: [
+        {
+          label: "policy",
+          value: `${record.policyFingerprint}${record.policyDiverged ? " (DIVERGED mid-session)" : ""}`,
+          level: record.policyDiverged ? "warn" : "ok"
+        },
+        { label: "rails", value: record.railsActive.join(", ") || "none" },
+        {
+          label: "gates",
+          value: `${record.gates.pass} pass / ${record.gates.fail} fail${rules ? `  |  ${rules}` : ""}`
+        }
+      ]
+    });
+  }
+  return {
+    title: "attestation",
+    summary: [root],
+    sections,
+    footer: "chained, not signed — it detects a rewritten record and proves nothing about authorship"
+  };
+}
+function attestText(root, style = PLAIN) {
+  return render(attestScreen(root), style);
+}
+function attestJson(root) {
+  const records = coreFacade.attest.readAttestations(root);
+  const verdict = coreFacade.attest.verifyChain(records);
+  return verdict.ok ? { ok: true, sessions: verdict.length, records } : { ok: false, brokenAt: verdict.brokenAt, reason: verdict.reason, sessions: records.length, records };
+}
+function acceptPolicy(root, paths, interactive) {
+  if (!interactive) {
+    throw new UsageError("tlc harness policy accept needs an interactive terminal — clearing a policy divergence is the operator's call, not a script's.");
+  }
+  const requested = paths.includes("--all") ? coreFacade.policy.allDivergedPaths(root) : paths;
+  if (paths.includes("--all") && requested.length === 0) {
+    return `nothing to accept — no policy source diverged in ${root}`;
+  }
+  if (requested.length === 0) {
+    throw new UsageError([
+      "usage: tlc harness policy accept <path> [path...]",
+      "       tlc harness policy accept --all      accept everything `tlc harness policy` lists here"
+    ].join(`
+`));
+  }
+  const blocked = coreFacade.policy.allDivergedPaths(root);
+  const notHere = requested.filter((path) => !blocked.includes(path));
+  const outcome = coreFacade.policy.acceptPolicySources(root, requested);
+  if (outcome.kind === "not-a-source") {
+    throw new UsageError([
+      `not a policy source: ${outcome.paths.join(", ")}`,
+      "The sources the loader reads are:",
+      ...outcome.sources.map((source) => `  ${source}`)
+    ].join(`
+`));
+  }
+  if (outcome.kind === "nothing-to-accept") {
+    return [
+      `nothing to accept — ${root} has no recorded session baseline.`,
+      "Acceptance is written per project. Run this from the repository whose session is blocked:",
+      `  cd <that repo> && tlc harness policy accept ${requested.join(" ")}`
+    ].join(`
+`);
+  }
+  const lines = [
+    `accepted: ${outcome.paths.join(", ")}`,
+    `  for sessions in ${root} — acceptance is per project, not machine-wide`
+  ];
+  if (notHere.length > 0) {
+    lines.push(`  note: ${notHere.join(", ")} was not diverging here. If a session elsewhere is blocked, run this in that repository too.`);
+  }
+  return lines.join(`
+`);
+}
+function policyScreen(root) {
+  const diverged = coreFacade.policy.allDivergedPaths(root);
+  if (diverged.length === 0) {
+    return {
+      title: "policy baseline",
+      sections: [
+        {
+          rows: [
+            {
+              label: "baseline",
+              value: "matches — nothing changed out of band during any live session",
+              level: "ok"
+            }
+          ]
+        }
+      ]
+    };
+  }
+  return {
+    title: "policy baseline",
+    summary: [`policy changed out of band during a live session (${diverged.length})`],
+    sections: [
+      { rows: diverged.map((path) => ({ label: "changed", value: path, level: "warn" })) },
+      {
+        title: "If that was you, accept it from your own terminal with",
+        lines: [`tlc harness policy accept ${diverged.join(" ")}`, "", "or: tlc harness policy accept --all"]
+      }
+    ],
+    footer: "accepting is per path, so anything you leave out keeps blocking"
+  };
+}
+function policyText(root, style = PLAIN) {
+  return render(policyScreen(root), style);
+}
+function policyJson(root) {
+  const diverged = coreFacade.policy.allDivergedPaths(root);
+  return { diverged, ok: diverged.length === 0 };
+}
+function upstreamRef(dest) {
+  const read = (args) => {
+    const r = spawnSync("git", ["-C", dest, ...args], { encoding: "utf8", env: process.env });
+    return (r.status ?? 1) === 0 ? (r.stdout ?? "").trim() : "";
+  };
+  const tracked = read(["rev-parse", "--abbrev-ref", "@{u}"]);
+  if (tracked !== "") {
+    return tracked;
+  }
+  return `origin/${read(["rev-parse", "--abbrev-ref", "HEAD"]) || "main"}`;
+}
+var NPM_PACKAGE = "@tech-leads-club/harness-toolkit";
+var NPM_MARKER = "installed-from-npm";
+function classifyRuntimePath(dest, probe) {
+  if (probe.isSymlink(dest)) {
+    return "linked";
+  }
+  if (!probe.exists(dest)) {
+    return "absent";
+  }
+  if (probe.exists(join2(dest, ".git"))) {
+    return "managed";
+  }
+  return probe.exists(join2(dest, NPM_MARKER)) ? "npm" : "unmanaged";
+}
+function runtimePathKind(dest) {
+  return classifyRuntimePath(dest, {
+    isSymlink: (path) => {
+      try {
+        return lstatSync2(path).isSymbolicLink();
+      } catch {
+        return false;
+      }
+    },
+    exists: existsSync2
+  });
+}
+function missingBundles(dest) {
+  const entrypoints = join2(dest, "src", "entrypoints");
+  if (!existsSync2(entrypoints)) {
+    return [];
+  }
+  const expected = readdirSync(entrypoints).filter((name) => name.endsWith(".ts") && !name.endsWith(".test.ts")).map((name) => `${name.slice(0, -3)}.mjs`);
+  return expected.filter((bundle) => !existsSync2(join2(dest, "dist", bundle)));
+}
+function linkedRuntimeMessage(dest, target) {
+  return [
+    `update: ${dest} is a link to a working clone${target ? ` → ${target}` : ""}.`,
+    "Nothing in it is touched by this command — updating that clone is your own `git pull`.",
+    "Refreshing the machine-local parts only: CLI link, init skill, provider hooks."
+  ].join(`
+`);
+}
+function fetchFailureMessage(dest) {
+  return [
+    `update: git fetch failed in ${dest}.`,
+    `  The published package needs no clone: npm i -g ${NPM_PACKAGE}@latest, then \`tlc harness install\`.`,
+    "  If this runtime predates the move to tech-leads-club/harness-toolkit, it is still pointing at the old",
+    "  repository, and that install is what the package replaces.",
+    "  For a private fork, this needs a GitHub credential: `gh auth login`, then `gh auth setup-git`."
+  ].join(`
+`);
+}
+function unmanagedRuntimeMessage(dest) {
+  return [
+    `update: ${dest} is not a git checkout, so there is nothing to pull.`,
+    `Install the package to get a runtime update can move: npm i -g ${NPM_PACKAGE}@latest, then \`tlc harness install\`.`
+  ].join(`
+`);
+}
+function npmUpdateFailureMessage() {
+  return [
+    `update: npm could not install ${NPM_PACKAGE}@latest.`,
+    "  permissions — a global prefix owned by root needs sudo, or an npm prefix you own:",
+    "                npm config set prefix ~/.local",
+    "  not found    — the package is published; check the network and any registry proxy in ~/.npmrc",
+    "  offline      — nothing was changed; the runtime you have still works."
+  ].join(`
+`);
+}
+function resetFailureMessage(dest, mergeRef, gitOutput) {
+  return [
+    `update: could not move the runtime to ${mergeRef}.`,
+    `  path: ${dest} (managed checkout)`,
+    gitOutput.trim() ? `  git: ${gitOutput.trim().split(`
+`).slice(-3).join(" / ")}` : "",
+    `Nothing was changed. If this persists, install the package instead: npm i -g ${NPM_PACKAGE}@latest, then \`tlc harness install\`.`
+  ].filter(Boolean).join(`
+`);
+}
+function runtimeRevision(dest) {
+  if (!existsSync2(join2(dest, ".git"))) {
+    return { revision: null, date: null };
+  }
+  const read = (args) => {
+    const r = spawnSync("git", ["-C", dest, ...args], { encoding: "utf8", env: process.env });
+    const out = (r.stdout ?? "").trim();
+    return (r.status ?? 1) === 0 && out !== "" ? out : null;
+  };
+  return { revision: read(["rev-parse", "--short", "HEAD"]), date: read(["log", "-1", "--format=%cs"]) };
+}
+function versionJson(root) {
+  const dest = resolveHarnessRoot();
+  const { revision, date } = runtimeRevision(dest);
+  return {
+    runtime: dest,
+    revision,
+    date,
+    seenRevision: coreFacade.release.readReleaseSeen(root)?.revision ?? null
+  };
+}
+function versionScreen(root) {
+  const report = versionJson(root);
+  const rows = report.revision === null ? [
+    { label: "runtime", value: report.runtime },
+    {
+      label: "revision",
+      value: "unknown — the runtime path is not a git checkout, so `update` cannot pull either",
+      level: "warn"
+    }
+  ] : [
+    { label: "runtime", value: report.runtime },
+    { label: "revision", value: `${report.revision} (${report.date ?? "date unknown"})`, level: "ok" },
+    {
+      label: "project last saw",
+      value: report.seenRevision ?? "nothing yet — the next update will announce what landed"
+    }
+  ];
+  return { title: "harness version", sections: [{ rows }] };
+}
+function versionText(root, style = PLAIN) {
+  return render(versionScreen(root), style);
+}
+function pendingUpdate(dest, mergeRef) {
+  if (!existsSync2(join2(dest, ".git"))) {
+    return { ok: false, reason: "the runtime path is not a git checkout", commits: 0, decisions: [] };
+  }
+  const fetch = spawnSync("git", ["-C", dest, "fetch", "origin"], { stdio: "inherit", env: process.env });
+  if ((fetch.status ?? 1) !== 0) {
+    return { ok: false, reason: "git fetch failed", commits: 0, decisions: [] };
+  }
+  const count = spawnSync("git", ["-C", dest, "rev-list", "--count", `HEAD..${mergeRef}`], {
+    encoding: "utf8",
+    env: process.env
+  });
+  const commits = Number.parseInt((count.stdout ?? "0").trim(), 10) || 0;
+  const added = spawnSync("git", ["-C", dest, "diff", "--name-only", "--diff-filter=A", `HEAD..${mergeRef}`, "--", "docs/decisions"], { encoding: "utf8", env: process.env });
+  const files = (added.stdout ?? "").split(`
+`).map((line) => line.trim().split("/").pop() ?? "").filter(Boolean);
+  return { ok: true, commits, decisions: coreFacade.release.readDecisions(dest, files) };
+}
+function pendingScreen(report) {
+  if (!report.ok) {
+    return {
+      title: "update --check",
+      sections: [
+        {
+          rows: [{ label: "status", value: `${report.reason} — nothing to compare against`, level: "warn" }]
+        }
+      ]
+    };
+  }
+  if (report.commits === 0) {
+    return {
+      title: "update --check",
+      sections: [
+        { rows: [{ label: "status", value: "the runtime is current — nothing to pull", level: "ok" }] }
+      ]
+    };
+  }
+  const digest = coreFacade.release.formatDecisionDigest(report.decisions);
+  return {
+    title: "update --check",
+    summary: [`${report.commits} commit(s) would be pulled`, "Nothing has changed yet."],
+    sections: [{ lines: digest === "" ? ["no decisions landed in that range"] : digest.split(`
+`) }]
+  };
+}
+function pendingText(report, style = PLAIN) {
+  return render(pendingScreen(report), style);
+}
+var GATE_FIELDS = {
+  "test-command": "test",
+  "lint-command": "lint"
+};
+var EXECUTABLE_EXTENSIONS = ["", ".exe", ".cmd", ".bat", ".ps1"];
+function resolveExecutable(name, env = process.env) {
+  const candidates = (base) => EXECUTABLE_EXTENSIONS.map((ext) => `${base}${ext}`);
+  if (name.includes("/") || name.includes("\\")) {
+    return candidates(name).find((candidate) => existsSync2(candidate)) ?? null;
+  }
+  for (const dir of (env.PATH ?? "").split(delimiter)) {
+    if (!dir) {
+      continue;
+    }
+    const found = candidates(join2(dir, name)).find((candidate) => existsSync2(candidate));
+    if (found) {
+      return found;
+    }
+  }
+  return null;
+}
+function setGateCommand(root, field, argv, interactive) {
+  if (argv.length === 0) {
+    throw new UsageError(`usage: tlc harness gate ${field}-command <command> [args...]`);
+  }
+  if (!interactive) {
+    throw new UsageError(`tlc harness gate ${field}-command needs an interactive terminal — harness policy is the operator's to set, not a script's.`);
+  }
+  const binary = argv[0];
+  if (resolveExecutable(binary) === null) {
+    throw new UsageError(`\`${binary}\` was not found on PATH, and a gate command that cannot run is a config fault ([/decisions/ad-021.md](/decisions/ad-021.md)).`);
+  }
+  const path = projectConfigPath(root);
+  const parsed = existsSync2(path) ? JSON.parse(readFileSync(path, "utf8")) : {};
+  const grind = { ...parsed.grind ?? {} };
+  grind[field === "test" ? "testCommand" : "lintCommand"] = argv;
+  parsed.grind = grind;
+  mkdirSync2(join2(root, ".tlc", "harness"), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(parsed, null, 2)}
+`, "utf8");
+  coreFacade.policy.refreshPolicyBaselines(root);
+  return `grind.${field}Command = ${JSON.stringify(argv)}`;
+}
+function helpScreen() {
+  return {
+    title: "tlc harness",
+    sections: [
+      {
+        lines: `Requires Node.js 24+ (Active LTS 24 or Current 26).
+
+Read commands accept --json: status, doctor, obs, lessons, prices lookup, attest, policy.
+
+QUICK
+  tlc harness status              mode / grind / gates
+  tlc harness version             runtime revision, and what this project last saw
+  tlc harness update --check      what an update would pull, without pulling it
+  tlc harness update              pull runtime + refresh skill/CLI, then doctor
+  tlc harness doctor               health checklist
+  tlc harness why [n]             the last n decisions this tool made, with the rule behind each
+  tlc harness install             put the runtime in place from the installed npm package
+  tlc harness uninstall            print what would be undone; --yes applies it, --purge includes state
+  tlc harness build                compile dist/ for Node
+  tlc harness test                 run the full local gate
+  tlc harness help <topic>         documentation
+
+TOPICS
+  architecture | concepts | lessons | measure | prices | diagnose | init
+
+CONTROL
+  tlc harness grind [on|off]   tlc harness pause | resume   tlc harness mode solo|paired|focus
+  tlc harness gate test-command <cmd> [args...]   tlc harness gate lint-command <cmd> [args...]
+  tlc harness attest              tamper-evident record of what each session ran under
+  tlc harness policy              show a policy that changed out of band; accept <path> to clear it
+
+MEASURE
+  tlc harness obs live|events|report|prune
+  tlc harness prices refresh [all|cursor|litellm]
+  tlc harness prices lookup <model-id>
+  tlc harness lessons list|show|garden|sync-rules
+
+PROJECT
+  tlc harness init --minimal | tlc harness init --write --stdin-json`.split(`
+`)
+      }
+    ],
+    footer: "tlc harness help <topic> for a document  ·  tlc harness why to see what it decided"
+  };
+}
+function helpText(style = PLAIN) {
+  return render(helpScreen(), style);
+}
+function pricesHelpScreen() {
+  return {
+    title: "prices",
+    sections: [
+      {
+        lines: `  tlc harness prices refresh [all|cursor|litellm] [--if-stale]
+  tlc harness prices lookup <model-id>
+
+  refresh / refresh all   both planes of model-prices.json
+  refresh cursor          the provider's own rates
+  refresh litellm         the vendors' list prices
+  --if-stale              fetch only past the 7-day TTL
+  lookup <model-id>       catalog key, pool, USD for 1M in + 1M out
+
+  Catalogue: <runtime home>/model-prices.json — fetched per machine, never versioned
+  Overrides: <runtime home>/model-prices.local.json — yours, hand-written
+  Documentation: tlc harness help prices`.split(`
+`)
+      }
+    ],
+    footer: "resolution: your overrides → the asking provider's plane → the vendor plane → null"
+  };
+}
+function pricesHelpText(style = PLAIN) {
+  return render(pricesHelpScreen(), style);
+}
+function resolveHarnessRoot() {
+  const home = runtimeHome();
+  try {
+    return realpathSync(home);
+  } catch {
+    return home;
+  }
+}
+function wireRuntime(dest, home) {
+  const lines = [];
+  const seeded = seedConfig(dest);
+  if (seeded.seeded) {
+    lines.push(`config seeded → ${seeded.path}`);
+  }
+  if (!existsSync2(join2(dest, "skills", "harness-init"))) {
+    return { lines, missingSkill: true };
+  }
+  const links = coreFacade.skill.skillLinks(dest, providerConfigDirs(), existsSync2);
+  if (links.length === 0) {
+    lines.push("no provider config dir found — skill not linked");
+  }
+  for (const link of links) {
+    const outcome = linkDir(link.source, link.target);
+    lines.push(outcome.kind === "refused" ? `skill not linked — ${outcome.reason}` : `skill → ${outcome.target}`);
+  }
+  const hooks = spawnSync(process.execPath, [join2(dest, "bin", "write-user-hooks.mjs")], {
+    stdio: "inherit",
+    env: { ...process.env, TLC_HOME: home }
+  });
+  if ((hooks.status ?? 1) !== 0) {
+    lines.push("hooks unchanged (merge manually or: node bin/write-user-hooks.mjs --force)");
+  }
+  return { lines, missingSkill: false };
+}
+function execBinPath() {
+  return join2(resolveHarnessRoot(), "bin", "tlc-exec.mjs");
+}
+function buildBinPath() {
+  return join2(resolveHarnessRoot(), "bin", "tlc-build.mjs");
+}
+function route(args) {
+  const cmd = (args[0] ?? "status").toLowerCase();
+  switch (cmd) {
+    case "status":
+    case "st":
+    case "s":
+      return { kind: "status" };
+    case "build":
+    case "rebuild":
+      return { kind: "build" };
+    case "update":
+    case "upgrade": {
+      const flags = args.slice(1);
+      if (flags.includes("--check")) {
+        return { kind: "update-check" };
+      }
+      const leftover = unknownFlags(flags);
+      if (leftover.length > 0) {
+        throw new UsageError(leftover[0] === "--force" ? `update takes no --force: a managed runtime is already reset to upstream, and a linked clone is never written to. If update cannot move it, install the package instead: npm i -g ${NPM_PACKAGE}@latest.` : `unknown flag: ${leftover[0]}
+usage: tlc harness update [--check]`);
+      }
+      return { kind: "update" };
+    }
+    case "version":
+    case "--version":
+      return { kind: "version" };
+    case "test":
+      return { kind: "test" };
+    case "grind":
+    case "g": {
+      const arg = (args[1] ?? "on").toLowerCase();
+      if (arg === "on" || arg === "1" || arg === "true") {
+        return { kind: "grind", on: true };
+      }
+      if (arg === "off" || arg === "0" || arg === "false") {
+        return { kind: "grind", on: false };
+      }
+      throw new UsageError("usage: tlc harness grind [on|off]");
+    }
+    case "pause":
+    case "p":
+      return { kind: "pause" };
+    case "resume":
+    case "r":
+      return { kind: "resume" };
+    case "mode":
+    case "m": {
+      const modeArg = args[1];
+      if (!modeArg) {
+        throw new UsageError("usage: tlc harness mode <solo|paired|focus>");
+      }
+      return { kind: "mode", value: modeArg };
+    }
+    case "attest":
+      return { kind: "attest" };
+    case "handoff":
+      return { kind: "handoff" };
+    case "policy": {
+      const sub = (args[1] ?? "").toLowerCase();
+      if (!sub) {
+        return { kind: "policy", accept: [] };
+      }
+      if (sub !== "accept") {
+        throw new UsageError("usage: tlc harness policy [accept <path> [path...]]");
+      }
+      return { kind: "policy", accept: args.slice(2) };
+    }
+    case "gate": {
+      const field = GATE_FIELDS[(args[1] ?? "").toLowerCase()];
+      if (!field) {
+        throw new UsageError("usage: tlc harness gate <test-command|lint-command> <command> [args...]");
+      }
+      return { kind: "gate", field, argv: args.slice(2) };
+    }
+    case "prices": {
+      const sub = (args[1] ?? "").toLowerCase();
+      if (!sub || sub === "help" || sub === "-h" || sub === "--help") {
+        return { kind: "prices-help" };
+      }
+      if (sub === "refresh") {
+        return { kind: "prices-refresh", scope: args[2] ?? "all" };
+      }
+      if (sub === "lookup" || sub === "get") {
+        const modelId = args[2];
+        if (!modelId) {
+          throw new UsageError(`usage: tlc harness prices lookup <model-id>
+detail: tlc harness help prices`);
+        }
+        return { kind: "prices-lookup", modelId };
+      }
+      throw new UsageError(`usage: tlc harness prices refresh [all|cursor|litellm] | tlc harness prices lookup <model>
+detail: tlc harness help prices`);
+    }
+    case "obs":
+    case "o":
+      return { kind: "entry", entry: "obs-cli", args: args.slice(1) };
+    case "doctor":
+    case "doc":
+      return { kind: "entry", entry: "doctor", args: args.slice(1) };
+    case "lessons":
+    case "lesson":
+      return { kind: "entry", entry: "lessons-cli", args: args.slice(1) };
+    case "init":
+      return { kind: "entry", entry: "init-project", args: args.slice(1) };
+    case "install":
+      return { kind: "entry", entry: "install-runtime", args: args.slice(1) };
+    case "uninstall":
+      return { kind: "entry", entry: "uninstall-runtime", args: args.slice(1) };
+    case "why":
+      return { kind: "entry", entry: "obs-cli", args: ["why", ...args.slice(1)] };
+    case "help":
+    case "-h":
+    case "--help": {
+      const topic = args[1];
+      if (!topic) {
+        return { kind: "help" };
+      }
+      return { kind: "entry", entry: "help-topic", args: [topic] };
+    }
+    default:
+      return { kind: "unknown", cmd };
+  }
+}
+var TEST_ENV_IMPORT = ["--import", "./tools/test-env.mjs"];
+function buildTestSteps() {
+  return [
+    { label: "biome check", bin: "npx", args: ["biome", "check", "--error-on-warnings"] },
+    { label: "tsc --noEmit", bin: "npx", args: ["tsc", "--noEmit"] },
+    { label: "src suite", bin: "node", args: [...TEST_ENV_IMPORT, "--test", "src/**/__test__/*.test.ts"] },
+    { label: "tools suite", bin: "node", args: [...TEST_ENV_IMPORT, "--test", "tools/__test__/*.test.ts"] },
+    { label: "check-boundaries", bin: "node", args: ["tools/dev/check-boundaries.ts"] },
+    { label: "check-suppressions", bin: "node", args: ["tools/dev/check-suppressions.ts"] },
+    { label: "check-wiring", bin: "node", args: ["tools/dev/check-wiring.ts"] },
+    { label: "check-docs-bundle", bin: "node", args: ["tools/dev/check-docs-bundle.ts"] },
+    { label: "check-decisions", bin: "node", args: ["tools/dev/check-decisions.ts"] },
+    { label: "check-screens", bin: "node", args: ["tools/dev/check-screens.ts"] },
+    { label: "check-obs-contract", bin: "node", args: ["tools/dev/check-obs-contract.ts"] },
+    { label: "check-manifest", bin: "node", args: ["tools/dev/check-manifest.ts"] },
+    { label: "capabilities in sync", bin: "node", args: ["tools/dev/render-capabilities.ts", "--check"] },
+    { label: "changelog in sync", bin: "node", args: ["tools/dev/render-changelog.ts", "--check"] },
+    { label: "log in sync", bin: "node", args: ["tools/dev/render-log.ts", "--check"] },
+    { label: "coverage in sync", bin: "node", args: ["tools/dev/render-coverage.ts", "--check"] }
+  ];
+}
+function runTestSteps(steps, cwd, spawner = (bin, spawnArgs, spawnCwd) => spawnSync(bin, spawnArgs, { cwd: spawnCwd, stdio: "inherit" })) {
+  for (const step of steps) {
+    console.log(`tlc harness test: running ${step.label}`);
+    const result = spawner(step.bin, step.args, cwd);
+    const status = result.status ?? 1;
+    if (status !== 0) {
+      console.error(`tlc harness test: FAILED at "${step.label}" (exit ${status})`);
+      return status;
+    }
+  }
+  console.log("tlc harness test: all steps passed");
+  return 0;
+}
+function announceNewCapabilities(root, runtimeRoot) {
+  const catalog = coreFacade.capability.loadCatalog(runtimeRoot);
+  const policy = coreFacade.capability.readProjectPolicyRaw(root);
+  if (!catalog || !policy) {
+    return;
+  }
+  const seen = coreFacade.capability.readRuntimeSeen(root);
+  const fresh = coreFacade.capability.listNewlyAnnounceable(policy, catalog, seen.catalogVersion);
+  if (fresh.length === 0) {
+    return;
+  }
+  console.log("");
+  console.log(coreFacade.capability.formatCapabilityDigest(fresh));
+  console.log("");
+  coreFacade.capability.writeRuntimeSeen(root, catalog.catalogVersion);
+}
+function announceLandedDecisions(root, dest, before) {
+  const now = runtimeRevision(dest).revision;
+  if (now === null) {
+    return;
+  }
+  const seen = coreFacade.release.readReleaseSeen(root)?.revision ?? before;
+  if (seen === null || seen === now) {
+    coreFacade.release.writeReleaseSeen(root, now);
+    return;
+  }
+  const added = spawnSync("git", ["-C", dest, "diff", "--name-only", "--diff-filter=A", `${seen}..${now}`, "--", "docs/decisions"], { encoding: "utf8", env: process.env });
+  if ((added.status ?? 1) !== 0) {
+    console.log(`update: cannot list what landed since ${seen} — that revision is no longer in the checkout`);
+    coreFacade.release.writeReleaseSeen(root, now);
+    return;
+  }
+  const files = (added.stdout ?? "").split(`
+`).map((line) => line.trim().split("/").pop() ?? "").filter(Boolean);
+  const digest = coreFacade.release.formatDecisionDigest(coreFacade.release.readDecisions(dest, files));
+  if (digest !== "") {
+    console.log("");
+    console.log(digest);
+    console.log("");
+  }
+  coreFacade.release.writeReleaseSeen(root, now);
+}
+function runUpdate(root) {
+  const dest = resolveHarnessRoot();
+  const revisionBefore = runtimeRevision(dest).revision;
+  const home = runtimeHome();
+  console.log(`update: runtime → ${dest}`);
+  if (!existsSync2(join2(dest, "bin", "tlc-exec.mjs"))) {
+    console.error(`update: missing install at ${home}`);
+    console.error(`update: install once with \`npm i -g ${NPM_PACKAGE}\`, then \`tlc harness install\`, then retry.`);
+    process.exit(1);
+  }
+  const kind = runtimePathKind(home);
+  if (kind === "linked") {
+    console.log(linkedRuntimeMessage(home, dest === home ? null : dest));
+  } else if (kind === "npm") {
+    const bump = spawnSync("npm", ["install", "-g", `${NPM_PACKAGE}@latest`], {
+      stdio: "inherit",
+      env: process.env,
+      shell: true
+    });
+    if ((bump.status ?? 1) !== 0) {
+      console.error(npmUpdateFailureMessage());
+      process.exit(bump.status ?? 1);
+    }
+    const sync = spawnSync(process.execPath, [execBinPath(), "install-runtime"], {
+      stdio: "inherit",
+      env: process.env
+    });
+    if ((sync.status ?? 1) !== 0) {
+      process.exit(sync.status ?? 1);
+    }
+  } else if (kind === "unmanaged") {
+    console.log(unmanagedRuntimeMessage(dest));
+  } else {
+    const fetch = spawnSync("git", ["-C", dest, "fetch", "origin"], {
+      stdio: "inherit",
+      env: process.env
+    });
+    if ((fetch.status ?? 1) !== 0) {
+      console.error(fetchFailureMessage(dest));
+      process.exit(fetch.status ?? 1);
+    }
+    const mergeRef = upstreamRef(dest);
+    const reset = spawnSync("git", ["-C", dest, "reset", "--hard", mergeRef], {
+      encoding: "utf8",
+      env: process.env
+    });
+    if ((reset.status ?? 1) !== 0) {
+      console.error(resetFailureMessage(dest, mergeRef, `${reset.stderr ?? ""}${reset.stdout ?? ""}`));
+      process.exit(reset.status ?? 1);
+    }
+    const after = runtimeRevision(dest).revision;
+    console.log(revisionBefore === after ? `update: runtime already at ${after ?? "unknown"} — nothing to move` : `update: runtime ${revisionBefore ?? "unknown"} → ${after ?? "unknown"}`);
+  }
+  const wired = wireRuntime(dest, home);
+  for (const line of wired.lines) {
+    console.log(`update: ${line}`);
+  }
+  if (wired.missingSkill) {
+    console.error(`update: missing skill at ${join2(dest, "skills", "harness-init")}`);
+    process.exit(1);
+  }
+  const missing = missingBundles(dest);
+  if (missing.length === 0) {
+    console.log("update: dist/ complete — no rebuild, so the runtime path stays clean");
+  } else if (existsSync2(buildBinPath())) {
+    console.log(`update: ${missing.length} bundle(s) missing — building`);
+    const build = spawnSync(process.execPath, [buildBinPath()], { stdio: "inherit", env: process.env });
+    if ((build.status ?? 1) !== 0) {
+      console.log(`update: build failed — ${missing.length} bundle(s) still missing from dist/`);
+    }
+  }
+  announceNewCapabilities(root, dest);
+  announceLandedDecisions(root, dest, revisionBefore);
+  spawnSync(process.execPath, [execBinPath(), "refresh-model-prices", "all", "--if-stale"], {
+    stdio: "inherit",
+    env: { ...process.env, TLC_PROJECT_DIR: root }
+  });
+  console.log("update: running doctor…");
+  const doctor = spawnSync(process.execPath, [execBinPath(), "doctor"], {
+    stdio: "inherit",
+    env: { ...process.env, TLC_PROJECT_DIR: root }
+  });
+  console.log("update: ok — reload if hooks/skill should refresh");
+  process.exit(doctor.status ?? 0);
+}
+function runEntry(entry, toolArgs, root) {
+  const r = spawnSync(process.execPath, [execBinPath(), entry, ...toolArgs], {
+    stdio: "inherit",
+    env: { ...process.env, TLC_PROJECT_DIR: root }
+  });
+  process.exit(r.status ?? 1);
+}
+function main(argv) {
+  const root = resolveProjectRoot();
+  const group = (argv[0] ?? "").toLowerCase();
+  if (group !== "harness") {
+    console.error(`unknown: ${argv[0] ?? ""}`);
+    console.error("usage: tlc harness <status|doctor|help|grind|pause|resume|mode|obs|prices|lessons|init|update|test|build>");
+    process.exit(1);
+  }
+  const { json, rest: args } = takeJsonFlag(argv.slice(1));
+  let action;
+  try {
+    action = route(args);
+  } catch (error) {
+    if (error instanceof UsageError) {
+      console.error(error.message);
+      process.exit(1);
+    }
+    throw error;
+  }
+  switch (action.kind) {
+    case "status": {
+      const leftover = unknownFlags(args.slice(1));
+      if (leftover.length > 0) {
+        console.error(`unknown flag: ${leftover[0]}`);
+        console.error("usage: tlc harness status [--json]");
+        process.exit(1);
+      }
+      if (json) {
+        emitJson(statusJson(root));
+      } else {
+        console.log(statusText(root, createStyle()));
+      }
+      break;
+    }
+    case "handoff": {
+      const leftover = unknownFlags(args.slice(1));
+      if (leftover.length > 0) {
+        console.error(`unknown flag: ${leftover[0]}`);
+        console.error("usage: tlc harness handoff [--json]");
+        process.exit(1);
+      }
+      const report = handoffJson(root);
+      if (json) {
+        emitJson(report);
+      } else {
+        console.log(handoffText(report));
+      }
+      break;
+    }
+    case "attest": {
+      const leftover = unknownFlags(args.slice(1));
+      if (leftover.length > 0) {
+        console.error(`unknown flag: ${leftover[0]}`);
+        console.error("usage: tlc harness attest [--json]");
+        process.exit(1);
+      }
+      const report = attestJson(root);
+      if (json) {
+        emitJson(report);
+      } else {
+        console.log(attestText(root, createStyle()));
+      }
+      process.exit(report.ok ? 0 : 1);
+      break;
+    }
+    case "policy": {
+      if (action.accept.length === 0 && !args.includes("accept")) {
+        if (json) {
+          emitJson(policyJson(root));
+        } else {
+          console.log(policyText(root, createStyle()));
+        }
+        break;
+      }
+      try {
+        console.log(acceptPolicy(root, action.accept, Boolean(process.stdin.isTTY)));
+      } catch (error) {
+        if (error instanceof UsageError) {
+          console.error(error.message);
+          process.exit(1);
+        }
+        throw error;
+      }
+      break;
+    }
+    case "help":
+      console.log(helpText(createStyle()));
+      break;
+    case "build": {
+      const r = spawnSync(process.execPath, [buildBinPath()], { stdio: "inherit", env: process.env });
+      process.exit(r.status ?? 1);
+      break;
+    }
+    case "version":
+      if (json) {
+        emitJson(versionJson(root));
+      } else {
+        console.log(versionText(root, createStyle()));
+      }
+      break;
+    case "update-check": {
+      const dest = resolveHarnessRoot();
+      const report = pendingUpdate(dest, upstreamRef(dest));
+      if (json) {
+        emitJson(report);
+      } else {
+        console.log(pendingText(report, createStyle()));
+      }
+      break;
+    }
+    case "update":
+      runUpdate(root);
+      break;
+    case "test": {
+      const status = runTestSteps(buildTestSteps(), process.cwd());
+      process.exit(status);
+      break;
+    }
+    case "grind":
+      console.log(setGrind(root, action.on));
+      break;
+    case "pause":
+      console.log(setPaused(root, true));
+      break;
+    case "resume":
+      console.log(setPaused(root, false));
+      break;
+    case "mode":
+      try {
+        console.log(setMode(root, action.value));
+      } catch (error) {
+        if (error instanceof UsageError) {
+          console.error(error.message);
+          process.exit(1);
+        }
+        throw error;
+      }
+      break;
+    case "gate":
+      try {
+        console.log(setGateCommand(root, action.field, action.argv, process.stdin.isTTY === true));
+      } catch (error) {
+        if (error instanceof UsageError) {
+          console.error(error.message);
+          process.exit(1);
+        }
+        throw error;
+      }
+      break;
+    case "prices-help":
+      console.log(pricesHelpText(createStyle()));
+      break;
+    case "prices-refresh":
+      runEntry("refresh-model-prices", [action.scope], root);
+      break;
+    case "prices-lookup":
+      runEntry("price-lookup", json ? [action.modelId, JSON_FLAG] : [action.modelId], root);
+      break;
+    case "entry":
+      runEntry(action.entry, json ? [...action.args, JSON_FLAG] : action.args, root);
+      break;
+    case "unknown":
+      console.error(`unknown: ${action.cmd}`);
+      console.log(helpText(createStyle()));
+      process.exit(1);
+  }
+}
+if (__require.main == __require.module) {
+  main(process.argv.slice(2));
+}
+
+export { linkDir, UsageError, resolveProjectRoot, modeFilePath, grindFlagPath, skipFlagPath, focusFlagPath, pairedFlagPath, ensureFlagsDir, readMode, grindOn, gatesPaused, acceptedModes, statusScreen, statusText, statusJson, setGrind, setPaused, setMode, handoffJson, handoffScreen, handoffText, attestScreen, attestText, attestJson, acceptPolicy, policyScreen, policyText, policyJson, upstreamRef, NPM_PACKAGE, NPM_MARKER, classifyRuntimePath, runtimePathKind, missingBundles, linkedRuntimeMessage, fetchFailureMessage, unmanagedRuntimeMessage, npmUpdateFailureMessage, resetFailureMessage, runtimeRevision, versionJson, versionScreen, versionText, pendingUpdate, pendingScreen, pendingText, resolveExecutable, setGateCommand, helpScreen, helpText, pricesHelpScreen, pricesHelpText, resolveHarnessRoot, wireRuntime, execBinPath, buildBinPath, route, TEST_ENV_IMPORT, buildTestSteps, runTestSteps };