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

package/src/platform/pricing.ts

@@ -1,3 +1,16 @@
+/**
+ * Where a model's price comes from, and how it is read.
+ *
+ * There is one catalogue file on the machine. It used to be four — a per-provider table, a ~1 MB fallback table,
+ * an overrides table and an alias table — three of them versioned in this repository and two of them holding the
+ * same models at different prices. That is not duplication to be collapsed: the same model genuinely has two
+ * prices depending on who bills the call, and a provider reselling a vendor's model charges its own rate. So the
+ * planes stay, and the file does not: one catalogue, one refresh, one read path, with each plane named by its
+ * provenance ([/decisions/ad-096.md](/decisions/ad-096.md)).
+ *
+ * invariant: nothing about prices is versioned. A rate published today has to reach an operator without a release,
+ * and a rate in the package is stale the moment it is packed.
+ */
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { runtimeHome } from "./paths.ts";
@@ -33,8 +46,40 @@ export type CostEstimate = {
   catalogKey?: string;
 };
 
-type PriceTable = Record<string, ModelPriceEntry>;
-type AliasTable = Record<string, string>;
+export type PriceTable = Record<string, ModelPriceEntry>;
+
+/**
+ * The catalogue on disk. `planes` is keyed by provenance: a provider's id for what that provider bills, and
+ * `litellm` for the vendors' own list prices.
+ *
+ * why: keyed rather than merged. `claude-sonnet-4-5` is sold by its vendor and resold by other providers at a
+ * different rate; merging the two rows would pick one at random and report the other's calls at the wrong price.
+ */
+export type PriceCatalogue = {
+  _meta?: { refreshedAt?: string; planes?: Record<string, PlaneMeta> };
+  planes?: Record<string, PriceTable>;
+};
+
+export type PlaneMeta = { source?: string; count?: number; refreshedAt?: string };
+
+/** The plane that holds the vendors' own list prices, used when the asking provider has no rate of its own. */
+export const FALLBACK_PLANE = "litellm";
+
+/**
+ * Model ids a host reports that are not the catalogue's key for them.
+ *
+ * why: in code, not in a versioned JSON file. This is a hand-curated mapping of what hosts call things — it changes
+ * when a host renames a model, which is a code change with a test, not machine state an operator maintains. The
+ * file it replaces held ten entries of which six were `"x": "x"` no-ops and two were already covered by the effort
+ * suffix stripped below ([/decisions/ad-096.md](/decisions/ad-096.md)).
+ *
+ * invariant: an operator who needs a mapping of their own writes the key straight into their overrides file. There
+ * is no second alias file to keep in sync.
+ */
+export const MODEL_ALIASES: Readonly<Record<string, string>> = {
+  "cursor-grok-4.5": "grok-4.5",
+  auto: "auto-cost",
+};
 
 const VENDOR_TO_NEUTRAL_POOL: Record<VendorPool, NeutralPool> = {
   cursor_models: "provider_native",
@@ -48,17 +93,6 @@ export function mapPoolToNeutral(pool: VendorPool): NeutralPool {
   return VENDOR_TO_NEUTRAL_POOL[pool];
 }
 
-function readJsonFile<T>(path: string): T | null {
-  if (!existsSync(path)) {
-    return null;
-  }
-  try {
-    return JSON.parse(readFileSync(path, "utf8")) as T;
-  } catch {
-    return null;
-  }
-}
-
 function stripMeta(table: PriceTable | null): PriceTable {
   if (!table) {
     return {};
@@ -67,17 +101,30 @@ function stripMeta(table: PriceTable | null): PriceTable {
   return rest;
 }
 
+/**
+ * The one way a model name becomes a catalogue key. Both sides use it: the refresh that writes the catalogue and
+ * the lookup that reads it.
+ *
+ * hazard: there were two of these, and they disagreed about parentheses. This one erased them, so a lookup for
+ * `Model X (Fast)` asked for `model-x` — the standard model's price. The writer's copy erased them too, so the two
+ * rows collapsed onto one key and the second overwrote the first. Measured on the real catalogue: 51 rows on the
+ * upstream page became 44 stored keys, and every model with a `(Fast)` variant carried the wrong price — `$3/$15`
+ * where the page said `$0.5/$2.5` ([/decisions/ad-096.md](/decisions/ad-096.md)).
+ *
+ * invariant: a qualifier is part of the identity. A markdown link keeps its text and loses its URL; everything
+ * else that is not alphanumeric is a separator. Two names that differ produce two keys.
+ */
 export function slugifyModelName(name: string): string {
   return name
     .trim()
     .toLowerCase()
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1")
     .replace(/[[\]]/g, "")
-    .replace(/\(.*?\)/g, "")
     .replace(/[^a-z0-9.+]+/g, "-")
     .replace(/^-+|-+$/g, "");
 }
 
-function candidatesFor(model: string, aliases: AliasTable): string[] {
+function candidatesFor(model: string, aliases: Readonly<Record<string, string>>): string[] {
   const trimmed = model.trim();
   const out: string[] = [];
   const push = (v: string | undefined) => {
@@ -114,20 +161,20 @@ function fuzzyFind(table: PriceTable, needle: string): { key: string; entry: Mod
   return undefined;
 }
 
-function overridesPath(): string {
+/** The catalogue the refresh writes. Not versioned, not packaged, per machine. */
+export function cataloguePath(): string {
   return join(runtimeHome(), "model-prices.json");
 }
 
-function providerNativePath(provider: string): string {
-  return join(runtimeHome(), `model-prices.${provider}.json`);
-}
-
-function litellmPath(): string {
-  return join(runtimeHome(), "model-prices.litellm.json");
-}
-
-function aliasesPath(): string {
-  return join(runtimeHome(), "model-aliases.json");
+/**
+ * The operator's own rates, which win over everything fetched.
+ *
+ * hazard: this filename was in `.gitignore` and read by nothing. The overrides that were actually read lived in
+ * `model-prices.json` — the same name the refresh now writes — so an operator's edits sat in a file the next
+ * 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");
 }
 
 export type PriceResolution = {
@@ -136,18 +183,79 @@ export type PriceResolution = {
   source: "override" | "provider" | "litellm";
 };
 
+type CacheSlot = { text: string; value: PriceCatalogue };
+const cache = new Map<string, CacheSlot>();
+
+/**
+ * why a cache at all: the fallback plane is around a megabyte and a cost estimate happens on every tool result.
+ * This used to parse every catalogue file on every single lookup.
+ *
+ * hazard: the first version keyed on mtime and size, and Windows CI caught it. Two writes of the same length
+ * inside one clock tick are indistinguishable that way — the system clock there advances about every 15 ms, so
+ * both writes carry the same timestamp however fine the filesystem's resolution is. A refresh mid-session would
+ * then serve the previous prices for the rest of the session, silently, because a price was still returned
+ * ([/decisions/ad-097.md](/decisions/ad-097.md)).
+ *
+ * invariant: the content decides. Reading 1 MB is the cheap part and the parse is what this avoids, so the file is
+ * always read and only reparsed when its bytes differ. Nothing has to remember to invalidate anything.
+ */
+function readCatalogue<T>(path: string): T | null {
+  if (!existsSync(path)) {
+    cache.delete(path);
+    return null;
+  }
+  let text: string;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch {
+    cache.delete(path);
+    return null;
+  }
+  const hit = cache.get(path);
+  if (hit && hit.text === text) {
+    return hit.value as T;
+  }
+  let parsed: PriceCatalogue;
+  try {
+    parsed = JSON.parse(text) as PriceCatalogue;
+  } catch {
+    cache.delete(path);
+    return null;
+  }
+  cache.set(path, { text, value: parsed });
+  return parsed as T;
+}
+
+/** invariant: an absent or unparseable catalogue is an empty one. A missing price is never a thrown error. */
+export function loadCatalogue(): PriceCatalogue {
+  return readCatalogue<PriceCatalogue>(cataloguePath()) ?? {};
+}
+
+export function planeMeta(): Record<string, PlaneMeta> {
+  return loadCatalogue()._meta?.planes ?? {};
+}
+
+export function catalogueMeta(): { refreshedAt?: string } | null {
+  const parsed = readCatalogue<PriceCatalogue>(cataloguePath());
+  return parsed === null ? null : (parsed._meta ?? {});
+}
+
+function planeFor(catalogue: PriceCatalogue, plane: string): PriceTable {
+  return stripMeta(catalogue.planes?.[plane] ?? null);
+}
+
 export function resolveModelPrice(provider: string, model: string): PriceResolution | undefined {
   const trimmed = model.trim();
   if (!trimmed) {
     return undefined;
   }
 
-  const overrides = stripMeta(readJsonFile<PriceTable>(overridesPath()));
-  const native = stripMeta(readJsonFile<PriceTable>(providerNativePath(provider)));
-  const litellm = stripMeta(readJsonFile<PriceTable>(litellmPath()));
-  const aliases = readJsonFile<AliasTable>(aliasesPath()) ?? {};
+  const catalogue = loadCatalogue();
+  const overrides = stripMeta(readCatalogue<PriceTable>(overridesPath()));
+  const native = provider ? planeFor(catalogue, provider) : {};
+  const litellm = planeFor(catalogue, FALLBACK_PLANE);
 
-  const candidates = candidatesFor(trimmed, aliases);
+  const candidates = candidatesFor(trimmed, MODEL_ALIASES);
 
   for (const id of candidates) {
     const entry = overrides[id];

package/src/providers/cursor/cursor.wiring.ts

@@ -33,15 +33,18 @@ const ENTRY_SPECS: readonly EntrySpec[] = [
   { hookEvent: "afterAgentResponse", handler: "response-after", timeoutSeconds: 5, matcher: "AgentResponse" },
 ];
 
-function commandFor(runtime: RuntimePaths): { command: string; argsPrefix: string[] } {
-  if (process.platform === "win32") {
-    return { command: "cmd", argsPrefix: ["/c", "node", runtime.launcherPath] };
-  }
-  return { command: "node", argsPrefix: [runtime.launcherPath] };
-}
-
+/**
+ * hazard: this used to write `cmd /c node <launcher>` on Windows and `node <launcher>` elsewhere, from the first
+ * commit, with no recorded reason. The other provider's wiring has always written plain `node` on every platform,
+ * including Windows — so the branch was the odd one, not the safe one, and it was the branch no contributor here
+ * could exercise ([/decisions/ad-097.md](/decisions/ad-097.md)).
+ *
+ * invariant: `node` is resolved by the host's own process spawn, which appends the executable extension on the
+ * platform that needs one. If a Windows session ever proves otherwise, this is the one line to change.
+ */
 export function cursorWiring(runtime: RuntimePaths): ProviderWiring {
-  const { command, argsPrefix } = commandFor(runtime);
+  const command = "node";
+  const argsPrefix = [runtime.launcherPath];
   const entries: WiringEntry[] = ENTRY_SPECS.map((spec) => ({
     hookEvent: spec.hookEvent,
     handler: spec.handler,

package/tools/doctor.ts

@@ -1,14 +1,20 @@
 import { spawnSync } from "node:child_process";
-import { existsSync, lstatSync, readFileSync, readlinkSync } from "node:fs";
+import { existsSync, lstatSync, readFileSync, readlinkSync, realpathSync } from "node:fs";
 import { homedir, platform as osPlatform } from "node:os";
-import { dirname, join } from "node:path";
-import { runtimePathKind } from "../bin/tlc-cli.ts";
+import { basename, delimiter, dirname, join } from "node:path";
+import { NPM_PACKAGE, runtimePathKind } from "../bin/tlc-cli.ts";
 import { findBunOnPath, writeRuntimeCache } from "../bin/tlc-exec.mjs";
 import { isCursorWired } from "../bin/write-user-hooks.mjs";
 import type { ProviderWiring } from "../src/contracts/index.ts";
 import { coreFacade } from "../src/core/index.ts";
 import { emitJson, takeJsonFlag } from "../src/platform/cli-output.ts";
-import { projectConfigPath, projectStateDir, runtimeHome } from "../src/platform/paths.ts";
+import {
+  projectConfigPath,
+  projectStateDir,
+  providerConfigDirs,
+  runtimeHome,
+} from "../src/platform/paths.ts";
+import { catalogueMeta, planeMeta } from "../src/platform/pricing.ts";
 import { type ColorName, createStyle, PLAIN, type Style, SYMBOLS } from "../src/platform/style.ts";
 import { mergeClaudeSettings } from "../src/providers/claude/claude.wiring.ts";
 import {
@@ -126,10 +132,122 @@ export function runtimeOwnershipCheck(home: string): Check {
   };
 }
 
+/**
+ * hazard: a skill link whose destination is gone reads as installed to anything that only checks the link exists.
+ * One on the machine that prompted this pointed at `/tmp/tlc-recovery-…/install/skills/harness-init` — a directory
+ * from a recovery run, gone on the next boot — and nothing in the harness could see it. A provider whose skill link
+ * dangles simply never routes a request to the init skill, silently
+ * ([/decisions/ad-095.md](/decisions/ad-095.md)).
+ *
+ * invariant: reported per provider, because each reads only its own skills directory, and one being healthy says
+ * nothing about the other.
+ */
+export function checkSkillLinks(
+  home: string,
+  providerDirs: readonly string[] = providerConfigDirs(),
+  probe = {
+    linkTarget: (path: string) => {
+      try {
+        return realpathSync(path);
+      } catch {
+        // a dangling link cannot be realpath'd, so read the link itself before giving up
+        try {
+          return readlinkSync(path);
+        } catch {
+          return null;
+        }
+      }
+    },
+    exists: existsSync,
+    // why: the runtime home is itself a symlink on a contributor install, so it has to be resolved before the
+    // comparison. Without this both sides are spelled differently and every healthy link reads as foreign.
+    realpath: (path: string) => {
+      try {
+        return realpathSync(path);
+      } catch {
+        return path;
+      }
+    },
+  },
+): Check[] {
+  return providerDirs
+    .filter((dir) => existsSync(dir))
+    .map((dir) => {
+      const health = coreFacade.skill.linkHealth(join(dir, "skills", "harness-init"), home, probe);
+      return {
+        level: health.state === "ok" ? ("ok" as const) : ("fail" as const),
+        name: `init skill (${basename(dir)})`,
+        detail: coreFacade.skill.linkHealthMessage(health),
+      };
+    });
+}
+
+/**
+ * How old the price catalogue on this machine is.
+ *
+ * hazard: nothing reported this. `docs/measure.md` claimed `doctor` "requires at least one provider catalog to be
+ * present" and no such check existed, while the catalogue this repository shipped was 23 days stale across three
+ * published versions. An absent catalogue is equally invisible: cost estimates simply come back null, which reads
+ * the same as a turn that spent nothing ([/decisions/ad-096.md](/decisions/ad-096.md)).
+ *
+ * invariant: a fresh catalogue is an `ok` row that states its age and asks for nothing. A warning that fires on a
+ * healthy install is not a warning ([/decisions/ad-034.md](/decisions/ad-034.md)).
+ */
+export function checkPrices(
+  now: Date = new Date(),
+  read = { meta: catalogueMeta, planes: planeMeta },
+): Check[] {
+  const state = coreFacade.pricing.freshness(read.meta(), now);
+  const planes = read.planes();
+  const named = Object.entries(planes)
+    .map(([plane, meta]) => `${plane} ${meta.count ?? 0}`)
+    .join(", ");
+  return [
+    {
+      level: state.state === "fresh" ? "ok" : "warn",
+      name: "prices",
+      detail:
+        state.state === "fresh"
+          ? `${coreFacade.pricing.freshnessMessage(state, "catalogue")}${named ? ` (${named})` : ""}`
+          : coreFacade.pricing.freshnessMessage(state, "catalogue"),
+    },
+  ];
+}
+
+/**
+ * Where a shell would find the `tlc` command, if anywhere.
+ *
+ * hazard: this row used to pass when `~/.local/bin/tlc` existed **or** `<runtime home>/bin/tlc` existed. The
+ * second is part of every install, so the check could not fail — and it printed the first path either way, so an
+ * operator whose command was not on PATH read a passing row naming a file they did not have
+ * ([/decisions/ad-034.md](/decisions/ad-034.md), [/decisions/ad-097.md](/decisions/ad-097.md)).
+ *
+ * why the four names: an npm global install writes the shims for its platform — bare on POSIX, `.cmd` and `.ps1`
+ * on Windows. Trying all four everywhere costs four `existsSync` calls and needs no platform branch.
+ */
+export function resolveOnPath(
+  command: string,
+  env: NodeJS.ProcessEnv = process.env,
+  exists = existsSync,
+): string | null {
+  for (const dir of (env.PATH ?? "").split(delimiter)) {
+    if (!dir) {
+      continue;
+    }
+    for (const name of [command, `${command}.cmd`, `${command}.exe`, `${command}.ps1`]) {
+      const candidate = join(dir, name);
+      if (exists(candidate)) {
+        return candidate;
+      }
+    }
+  }
+  return null;
+}
+
 export function checkRuntimePaths(home: string, platform: NodeJS.Platform): Check[] {
   const launcher = join(home, "bin", "tlc-exec.mjs");
   const distSample = join(home, "dist", "stop.mjs");
-  const cliLink = join(homedir(), ".local", "bin", platform === "win32" ? "tlc.cmd" : "tlc");
+  const onPath = resolveOnPath("tlc");
   return [
     { level: "ok", name: "platform", detail: platform },
     { level: existsSync(launcher) ? "ok" : "fail", name: "global runtime", detail: home },
@@ -142,12 +260,9 @@ export function checkRuntimePaths(home: string, platform: NodeJS.Platform): Chec
     },
     { level: existsSync(launcher) ? "ok" : "fail", name: "portable launcher", detail: launcher },
     {
-      level:
-        existsSync(cliLink) || existsSync(join(home, "bin", platform === "win32" ? "tlc.cmd" : "tlc"))
-          ? "ok"
-          : "fail",
+      level: onPath === null ? "fail" : "ok",
       name: "CLI on PATH",
-      detail: cliLink,
+      detail: onPath ?? `no \`tlc\` on PATH — npm i -g ${NPM_PACKAGE}, or \`npm link\` from a clone`,
     },
   ];
 }
@@ -522,10 +637,12 @@ export function runChecks(ctx: DoctorContext): Check[] {
   return [
     ...checkNodeVersion(ctx.nodeVersion, ctx.bunPath),
     ...checkRuntimePaths(ctx.runtimeHome, ctx.platform),
+    ...checkSkillLinks(ctx.runtimeHome),
     checkHookRuntime(ctx.runtimeHome, ctx.bunPath),
     ...checkProviders(ctx.registry, ctx.runtimeHome),
     ...checkProjectPolicy(ctx.root),
     ...checkCapabilities(ctx.root, ctx.runtimeHome),
+    ...checkPrices(),
     checkGlobalCommands(ctx.home),
   ];
 }

package/tools/init-project.ts

@@ -1,5 +1,5 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, join, sep } from "node:path";
 import { applyCursorWiring, renderCursorHooksDocument } from "../bin/write-user-hooks.mjs";
 import type { WiringEntry } from "../src/contracts/index.ts";
 import { DEFAULTS } from "../src/core/policy/policy.defaults.ts";
@@ -55,12 +55,12 @@ export function launcherPath(home = runtimeHome()): string {
   return join(home, "bin", "tlc-exec.mjs");
 }
 
-function shimCommand(platform = process.platform): { command: string; argsPrefix: string[] } {
-  if (platform === "win32") {
-    return { command: "cmd", argsPrefix: ["/c", "node"] };
-  }
-  return { command: "node", argsPrefix: [] };
-}
+/**
+ * invariant: the same command the provider wiring writes, on every platform — `node`, resolved by the host that
+ * spawns it. The Windows `cmd /c` wrapper this replaced existed on one of the two providers only
+ * ([/decisions/ad-097.md](/decisions/ad-097.md)).
+ */
+const SHIM_COMMAND = { command: "node", argsPrefix: [] as string[] };
 
 type ShimSpec = {
   hookEvent: string;
@@ -92,7 +92,7 @@ const CLAUDE_SHIM_SPECS: readonly ShimSpec[] = [
 ];
 
 export function cursorShimEntries(launcher: string): WiringEntry[] {
-  const { command, argsPrefix } = shimCommand();
+  const { command, argsPrefix } = SHIM_COMMAND;
   return CURSOR_SHIM_SPECS.map((spec) => ({
     hookEvent: spec.hookEvent,
     handler: spec.handler,
@@ -115,17 +115,37 @@ export function claudeShimEntries(launcher: string): WiringEntry[] {
   }));
 }
 
-export const GITIGNORE_LINE = ".tlc/harness/state/";
+/**
+ * The paths `init` writes into the project that must not be committed.
+ *
+ * hazard: this was one line, `.tlc/harness/state/`, while `init` also writes two shim documents containing an
+ * absolute path to the runtime on the machine that ran it. A user committed a `settings.json` naming their own
+ * home directory, and the next developer's hook pointed at a path that does not exist. This repository has
+ * ignored both files by hand since 2026-07-30 — commit 81c5830, "keep generated shims out of git", with the
+ * comment "per-machine artifacts rather than shared configuration" — so the protection existed here and was never
+ * delivered to anyone using the product ([/decisions/ad-095.md](/decisions/ad-095.md)).
+ *
+ * invariant: derived from what `init` writes. `PROJECT_SHIMS` is the same list the wiring below writes to, so a
+ * new shim cannot be added without appearing here.
+ */
+export const PROJECT_SHIMS = [join(".cursor", "hooks.json"), join(".claude", "settings.json")] as const;
+
+export const GITIGNORE_STATE = ".tlc/harness/state/";
+
+/** why: posix separators, because a `.gitignore` is read by git and not by the platform that wrote it. */
+export function gitignoreEntries(): string[] {
+  return [GITIGNORE_STATE, ...PROJECT_SHIMS.map((path) => path.split(sep).join("/"))];
+}
 
 export function mergeGitignore(root: string): { text: string; changed: boolean } {
   const path = join(root, ".gitignore");
   const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
   const lines = existing.split("\n");
-  const alreadyPresent = lines.includes(GITIGNORE_LINE);
-  if (alreadyPresent) {
+  const missing = gitignoreEntries().filter((entry) => !lines.includes(entry));
+  if (missing.length === 0) {
     return { text: existing.endsWith("\n") || existing === "" ? existing : `${existing}\n`, changed: false };
   }
-  lines.push(GITIGNORE_LINE);
+  lines.push(...missing);
   const withoutTrailingBlank = lines.filter((line, index, all) => line.length > 0 || index < all.length - 1);
   return { text: `${withoutTrailingBlank.join("\n").replace(/\n+$/, "")}\n`, changed: true };
 }
@@ -156,7 +176,7 @@ export type InitPlan = {
   policy: unknown;
   cursorHooksDocument: unknown | null;
   claudeHooksPreview: WiringEntry[] | null;
-  gitignoreLine: string;
+  gitignoreEntries: string[];
 };
 
 export function buildPlan(
@@ -171,7 +191,7 @@ export function buildPlan(
     policy,
     cursorHooksDocument: presence.cursor ? renderCursorHooksDocument(cursorShimEntries(launcher)) : null,
     claudeHooksPreview: presence.claude ? claudeShimEntries(launcher) : null,
-    gitignoreLine: GITIGNORE_LINE,
+    gitignoreEntries: gitignoreEntries(),
   };
 }
 

package/tools/install-runtime.ts

@@ -1,6 +1,8 @@
+import { spawnSync } from "node:child_process";
 import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join, relative, resolve, sep } from "node:path";
 import { NPM_MARKER, NPM_PACKAGE } from "../bin/tlc-cli.ts";
+import { linkDir } from "../src/platform/links.ts";
 import { conventionalRuntimeHome, runtimeHome, runtimeHomeWasChosen } from "../src/platform/paths.ts";
 import { type Row, render, type Screen } from "../src/platform/screen.ts";
 import { createStyle, PLAIN, type Style } from "../src/platform/style.ts";
@@ -23,9 +25,6 @@ export const RUNTIME_PAYLOAD = [
   "src",
   "tools",
   "config.example.json",
-  "model-aliases.json",
-  "model-prices.cursor.json",
-  "model-prices.json",
   "package.json",
 ] as const;
 
@@ -52,11 +51,12 @@ export function isShipped(relativePath: string): boolean {
 }
 
 export type InstallReport = {
-  kind: "copied" | "in-place";
+  kind: "copied" | "in-place" | "linked" | "relinked" | "refused";
   source: string;
   dest: string;
   entries: string[];
   missing: string[];
+  reason?: string;
 };
 
 /** The physical location of the copy that launched us, which is not the home once an npm shim is driving one. */
@@ -110,7 +110,62 @@ export function installRuntime(source: string, dest: string): InstallReport {
   return { kind: "copied", source, dest, entries, missing };
 }
 
+/**
+ * The contributor route: the runtime home points at a checkout, so an edit is live in the next hook with no
+ * install step.
+ *
+ * why it is here and not in a shell script: it was `ln -sfn` in bash and `mklink /J` in PowerShell, and the
+ * PowerShell one asked for Developer Mode. One `symlinkSync` covers all three platforms
+ * ([/decisions/ad-097.md](/decisions/ad-097.md)).
+ *
+ * invariant: the checkout is never written to, and a destination that is not already a link is refused rather
+ * than removed ([/decisions/ad-046.md](/decisions/ad-046.md)).
+ */
+export function linkRuntime(source: string, dest: string): InstallReport {
+  if (resolve(source) === resolve(dest)) {
+    return { kind: "in-place", source, dest, entries: [], missing: [] };
+  }
+  const outcome = linkDir(resolve(source), dest);
+  if (outcome.kind === "refused") {
+    return { kind: "refused", source, dest, entries: [], missing: [], reason: outcome.reason };
+  }
+  const missing = RUNTIME_PAYLOAD.filter((entry) => !existsSync(join(dest, entry)));
+  return { kind: outcome.kind === "relinked" ? "relinked" : "linked", source, dest, entries: [], missing };
+}
+
 export function installScreen(report: InstallReport): Screen {
+  if (report.kind === "refused") {
+    return {
+      title: "harness install",
+      sections: [{ rows: [{ label: "refused", value: report.reason ?? "", level: "fail" }] }],
+    };
+  }
+  if (report.kind === "linked" || report.kind === "relinked") {
+    return {
+      title: "harness install",
+      sections: [
+        {
+          rows: [
+            {
+              label: report.kind === "linked" ? "linked" : "relinked",
+              value: `${report.dest} → ${report.source}`,
+              level: "ok",
+            },
+            ...(report.missing.length > 0
+              ? [
+                  {
+                    label: "incomplete",
+                    value: `the checkout has no ${report.missing.join(", ")} — run the build`,
+                    level: "fail" as const,
+                  },
+                ]
+              : []),
+          ],
+        },
+      ],
+      footer: "an edit in the checkout is live in the next hook  ·  `npm link` puts `tlc` on PATH",
+    };
+  }
   if (report.kind === "in-place") {
     return {
       title: "harness install",
@@ -155,10 +210,38 @@ export function installDest(env: NodeJS.ProcessEnv = process.env): string {
   return runtimeHomeWasChosen(env) ? runtimeHome(env) : conventionalRuntimeHome();
 }
 
+/**
+ * The first price fetch, on the machine, at install time.
+ *
+ * why: prices are no longer in the package, so a fresh install has no catalogue at all until something fetches
+ * one. This is that something ([/decisions/ad-096.md](/decisions/ad-096.md)).
+ *
+ * invariant: never fails the install. An operator installing behind a proxy, on a plane, or against a page that
+ * moved still gets a working harness — they get no cost figures until the next refresh, which `doctor` reports.
+ */
+export function fetchPrices(dest: string, spawn = spawnSync): void {
+  const result = spawn(process.execPath, [join(dest, "bin", "tlc-exec.mjs"), "refresh-model-prices"], {
+    stdio: "inherit",
+    env: { ...process.env, TLC_HOME: dest },
+  });
+  if ((result.status ?? 1) !== 0) {
+    console.log("install: prices not fetched — cost estimates stay empty until `tlc harness prices refresh`");
+  }
+}
+
 if (import.meta.main) {
-  const source = originRoot();
+  /**
+   * why a flag rather than a second command: install is install. The only difference is whether the runtime home
+   * holds a copy of the package or points at a checkout ([/decisions/ad-097.md](/decisions/ad-097.md)).
+   */
+  const link = process.argv.includes("--link");
+  const source = link ? process.cwd() : originRoot();
   const dest = installDest();
-  const report = installRuntime(source, dest);
+  const report = link ? linkRuntime(source, dest) : installRuntime(source, dest);
   console.log(installReportText(report, createStyle()));
+  if (report.kind === "refused") {
+    process.exit(1);
+  }
+  fetchPrices(dest);
   process.exit(report.missing.length > 0 ? 1 : 0);
 }