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

package/src/core/pricing/pricing.freshness.ts

@@ -0,0 +1,118 @@
+/**
+ * How old a price catalogue is, and whether that is old enough to refetch.
+ *
+ * why: prices belong to the machine, not to a release. Shipping them in the package means a rate published today
+ * reaches an operator only when they update the tool, and the catalogue in the repository was 23 days stale while
+ * three versions went out ([/decisions/ad-096.md](/decisions/ad-096.md)).
+ *
+ * hazard: `refreshedAt` was already written into every catalogue's `_meta` by the refresh command, and read by
+ * nothing. No age was reported and no refetch was ever skipped or triggered by it — a metadatum recorded and never
+ * consulted, which is the same shape as the guard that read an environment variable nobody set.
+ *
+ * invariant: no clock of its own. `now` is a parameter, because a function that reads the wall clock cannot be
+ * tested against a boundary.
+ */
+
+export const DEFAULT_TTL_DAYS = 7;
+
+const MS_PER_DAY = 86_400_000;
+
+export type CatalogueMeta = { refreshedAt?: string; source?: string };
+
+export type Freshness =
+  | { state: "absent" }
+  | { state: "undated" }
+  | { state: "fresh"; ageDays: number; refreshedAt: string }
+  | { state: "stale"; ageDays: number; refreshedAt: string };
+
+/**
+ * why: `undated` is its own answer rather than "infinitely old". A catalogue written by a version that did not
+ * record the date is present and usable; treating it as stale would refetch on every run, and treating it as fresh
+ * would never refetch. Naming it lets the caller decide once, visibly.
+ */
+export function freshness(
+  meta: CatalogueMeta | null,
+  now: Date,
+  ttlDays: number = DEFAULT_TTL_DAYS,
+): Freshness {
+  if (meta === null) {
+    return { state: "absent" };
+  }
+  const stamp = meta.refreshedAt;
+  if (stamp === undefined || Number.isNaN(Date.parse(stamp))) {
+    return { state: "undated" };
+  }
+  const ageMs = now.getTime() - Date.parse(stamp);
+  // invariant: a stamp from the future is age zero, not a negative age. A clock skew must not read as fresh
+  // forever nor as stale immediately.
+  const ageDays = Math.max(0, ageMs / MS_PER_DAY);
+  return ageDays > ttlDays
+    ? { state: "stale", ageDays, refreshedAt: stamp }
+    : { state: "fresh", ageDays, refreshedAt: stamp };
+}
+
+/** invariant: `undated` refetches. Once, on the next run that can, after which it has a date like everything else. */
+export function shouldRefetch(state: Freshness): boolean {
+  return state.state === "absent" || state.state === "undated" || state.state === "stale";
+}
+
+export function freshnessMessage(state: Freshness, catalogue: string): string {
+  switch (state.state) {
+    case "absent":
+      return `${catalogue}: not on this machine — run \`tlc harness prices refresh\``;
+    case "undated":
+      return `${catalogue}: present but carries no date — it will be refetched`;
+    case "fresh":
+      return `${catalogue}: ${describeAge(state.ageDays)} old`;
+    default:
+      return `${catalogue}: ${describeAge(state.ageDays)} old — run \`tlc harness prices refresh\``;
+  }
+}
+
+/**
+ * Whether a freshly parsed catalogue may replace the one on disk.
+ *
+ * hazard: the only guard was "did we parse zero entries". The upstream page grew from one table to three, the
+ * parser read the first and stopped, and 43 models became 3 — which is not zero, so it passed and overwrote the
+ * good catalogue. A refresh that silently loses nine tenths of its content is worse than a stale one, because the
+ * staleness is at least visible in the date ([/decisions/ad-096.md](/decisions/ad-096.md)).
+ *
+ * invariant: growing is always allowed, and a first catalogue is always allowed. Only a large drop is refused, and
+ * the refusal names both numbers so the operator can see whether upstream really shrank.
+ */
+export const MIN_RETAINED_RATIO = 0.5;
+
+export type ReplaceVerdict = { replace: boolean; reason: string };
+
+export function mayReplace(
+  existingCount: number,
+  incomingCount: number,
+  minRatio: number = MIN_RETAINED_RATIO,
+): ReplaceVerdict {
+  if (incomingCount === 0) {
+    return { replace: false, reason: "parsed no entries at all — the upstream format has changed" };
+  }
+  if (existingCount === 0) {
+    return { replace: true, reason: `first catalogue, ${incomingCount} entries` };
+  }
+  if (incomingCount >= existingCount) {
+    return { replace: true, reason: `${existingCount} → ${incomingCount} entries` };
+  }
+  const retained = incomingCount / existingCount;
+  return retained >= minRatio
+    ? { replace: true, reason: `${existingCount} → ${incomingCount} entries` }
+    : {
+        replace: false,
+        reason: `would drop from ${existingCount} to ${incomingCount} entries, keeping the existing catalogue — the upstream format has probably changed`,
+      };
+}
+
+/** why: an operator reads "3 days", not "3.4179". Hours below a day, because "0 days" reads as no information. */
+export function describeAge(ageDays: number): string {
+  if (ageDays < 1) {
+    const hours = Math.max(1, Math.round(ageDays * 24));
+    return `${hours} hour${hours === 1 ? "" : "s"}`;
+  }
+  const days = Math.round(ageDays);
+  return `${days} day${days === 1 ? "" : "s"}`;
+}

package/src/core/skill/skill.link.ts

@@ -1,7 +1,7 @@
 /**
  * Where the init skill has to be linked, and what counts as a link that works.
  *
- * hazard: `install.sh` loops over every provider config directory that exists and links
+ * hazard: the installer looped over every provider config directory that exists and linked
  * `<provider>/skills/harness-init`, with the comment "Each provider only reads its own skills directory".
  * `tlc harness update` linked to `<runtime-home>/../skills/harness-init` instead — a directory no provider reads,
  * and which did not exist at all on the machine where this was found. So an update never refreshed the skill
@@ -48,11 +48,21 @@ export type LinkHealth =
  *
  * invariant: a link that resolves outside the runtime home is reported even when it currently exists, because
  * a source that is not the runtime is a source that will move.
+ *
+ * hazard: BOTH sides have to be resolved. The first version compared the link's realpath against the runtime home
+ * as configured, and on a contributor install — where `~/.tlc/harness` is a symlink to a working clone, which
+ * `doctor` reports as healthy — the two never share a prefix. It printed two failures on a machine where nothing
+ * was wrong, which is the reading AD-034 exists to forbid: a warning that fires on a healthy install is not a
+ * warning ([/decisions/ad-095.md](/decisions/ad-095.md)).
  */
 export function linkHealth(
   target: string,
   runtimeHome: string,
-  probe: { linkTarget: (path: string) => string | null; exists: (path: string) => boolean },
+  probe: {
+    linkTarget: (path: string) => string | null;
+    exists: (path: string) => boolean;
+    realpath?: (path: string) => string;
+  },
 ): LinkHealth {
   const resolved = probe.linkTarget(target);
   if (resolved === null) {
@@ -61,7 +71,8 @@ export function linkHealth(
   if (!probe.exists(resolved)) {
     return { state: "dangling", target, resolved };
   }
-  const home = runtimeHome.replace(/\/+$/, "");
+  const resolveHome = probe.realpath ?? ((path: string) => path);
+  const home = resolveHome(runtimeHome).replace(/\/+$/, "");
   return resolved === home || resolved.startsWith(`${home}/`)
     ? { state: "ok", target, resolved }
     : { state: "outside-runtime", target, resolved };

package/src/entrypoints/shim.ts

@@ -49,7 +49,13 @@ if (!decision.run) {
 }
 
 const home = runtimeHome();
-const execBin = join(home, "bin", "tlc-exec");
+/**
+ * hazard: this was the extensionless bash wrapper, which Windows cannot execute — so the first branch simply
+ * never fired there and the shim fell through to the bundle. The launcher is a `.mjs` run by the interpreter
+ * already running this, which behaves the same on every platform
+ * ([/decisions/ad-097.md](/decisions/ad-097.md)).
+ */
+const execBin = join(home, "bin", "tlc-exec.mjs");
 const distHandler = join(home, "dist", `${handler}.mjs`);
 const srcHandler = join(home, "src", "entrypoints", `${handler}.ts`);
 
@@ -67,7 +73,7 @@ function run(command: string, args: string[]): void {
 }
 
 if (existsSync(execBin)) {
-  run(execBin, [handler]);
+  run(process.execPath, [execBin, handler]);
 } else if (existsSync(distHandler)) {
   run(process.execPath, [distHandler]);
 } else if (existsSync(srcHandler)) {

package/src/platform/links.ts

@@ -0,0 +1,73 @@
+/**
+ * The two filesystem primitives an install needs: a directory link, and a config seeded once.
+ *
+ * why there is no platform branch here: the code this replaces shelled out to `ln -sfn` on POSIX and to
+ * PowerShell on Windows, and *that* is where the branch came from — not from anything Node cannot do. Node's
+ * `symlinkSync` takes a link type that is only meaningful on Windows and is ignored elsewhere, so `"junction"`
+ * is correct on all three platforms: a junction on Windows, a plain symlink on Linux and macOS. Measured on
+ * Linux, and stated in Node's own API history ([/decisions/ad-097.md](/decisions/ad-097.md)).
+ *
+ * why junction rather than a Windows symlink: a directory symlink needs Developer Mode or an elevated shell,
+ * which the PowerShell installer demanded of a contributor. A junction needs neither.
+ *
+ * The launcher on PATH is not here either. `npm i -g` generates the shims for the platform it runs on, and
+ * `npm link` does the same from a checkout — a second implementation of that is a second thing to get wrong.
+ */
+import { copyFileSync, existsSync, lstatSync, mkdirSync, rmSync, symlinkSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/** invariant: one link type, chosen because Windows is the only platform that reads it. */
+export const LINK_TYPE = "junction";
+
+export type LinkOutcome =
+  | { kind: "linked"; target: string; source: string }
+  | { kind: "relinked"; target: string; source: string }
+  | { kind: "refused"; target: string; reason: string };
+
+/**
+ * Point `target` at `source`.
+ *
+ * invariant: an existing *link* is replaced; anything else is refused. A real directory at the target is either
+ * somebody's install or somebody's work, and removing it to make room is not a decision a tool makes
+ * ([/decisions/ad-046.md](/decisions/ad-046.md)). The bash installer removed it.
+ */
+export function linkDir(source: string, target: string): LinkOutcome {
+  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 };
+}
+
+/**
+ * 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
+ * link, so one call covers both kinds.
+ */
+export function isLink(path: string): boolean {
+  try {
+    return lstatSync(path).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+/** invariant: seeded once, never overwritten. The operator's config is theirs from the moment it exists. */
+export function seedConfig(dest: string): { seeded: boolean; path: string } {
+  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 };
+}

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,8 +1,8 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, lstatSync, readFileSync, readlinkSync, realpathSync } from "node:fs";
 import { homedir, platform as osPlatform } from "node:os";
-import { basename, 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";
@@ -14,6 +14,7 @@ import {
   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 {
@@ -158,6 +159,15 @@ export function checkSkillLinks(
       }
     },
     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
@@ -172,10 +182,72 @@ export function checkSkillLinks(
     });
 }
 
+/**
+ * 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 },
@@ -188,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`,
     },
   ];
 }
@@ -573,6 +642,7 @@ export function runChecks(ctx: DoctorContext): Check[] {
     ...checkProviders(ctx.registry, ctx.runtimeHome),
     ...checkProjectPolicy(ctx.root),
     ...checkCapabilities(ctx.root, ctx.runtimeHome),
+    ...checkPrices(),
     checkGlobalCommands(ctx.home),
   ];
 }

package/tools/init-project.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,