@tech-leads-club/harness-toolkit 0.2.1

package/src/entrypoints/subagent-start.ts

@@ -0,0 +1,16 @@
+import type { Decision, HarnessEvent } from "../contracts/index.ts";
+import { coreFacade } from "../core/index.ts";
+import type { Handler, HandlerContext } from "./run.ts";
+import { main } from "./run.ts";
+import { subagentSpawnInput } from "./support.ts";
+
+export const subagentStartHandler: Handler = (event: HarnessEvent, ctx: HandlerContext): Decision => {
+  const { policy, provider } = ctx;
+  return coreFacade.subagentPolicy.evaluateSubagentSpawn(
+    subagentSpawnInput(event, policy, provider, event.spawnModel ?? ""),
+  );
+};
+
+if (import.meta.main) {
+  await main(subagentStartHandler);
+}

package/src/entrypoints/subagent-stop.ts

@@ -0,0 +1,32 @@
+import type { Decision, HarnessEvent } from "../contracts/index.ts";
+import { coreFacade } from "../core/index.ts";
+import type { Handler, HandlerContext } from "./run.ts";
+import { main } from "./run.ts";
+
+// why: no legacy predecessor covers subagent.stop verification — this reuses the same unfinished-work
+// signal (blockers/pending/in_progress/previous_gaps) already carried on the handoff slice.
+export const subagentStopHandler: Handler = (event: HarnessEvent, _ctx: HandlerContext): Decision => {
+  const handoff = coreFacade.handoff.readHandoff(event.projectDir, event.provider);
+  const unfinishedWork =
+    Boolean(handoff.blockers) ||
+    Boolean(handoff.previous_gaps?.length) ||
+    Boolean(handoff.pending?.length) ||
+    Boolean(handoff.in_progress?.length);
+
+  if (!unfinishedWork) {
+    return { kind: "abstain" };
+  }
+
+  return {
+    kind: "continue",
+    text: [
+      "BLOCKED: unfinished work remains before this subagent stops.",
+      `TRIED: subagent (${event.spawnSubagentType ?? "unknown"}) reported stop.`,
+      `NEED: ${handoff.next_action ?? "resolve the open blockers before ending this subagent turn."}`,
+    ].join("\n"),
+  };
+};
+
+if (import.meta.main) {
+  await main(subagentStopHandler);
+}

package/src/entrypoints/support.ts

@@ -0,0 +1,182 @@
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import type { EffortLevel, HarnessEvent } from "../contracts/index.ts";
+import { coreFacade, type HarnessLesson, type ObservabilityConfig, type Policy } from "../core/index.ts";
+import { runProcess } from "../platform/process.ts";
+import { type ProviderPort, renderClaudeLessonsView, renderCursorLessonsView } from "../providers/index.ts";
+
+// invariant: one definition, taken from core rather than restated.
+export const OBS_CONFIG = coreFacade.observability.DEFAULT_OBS;
+
+// why: tool.end, shell.end, mcp.end and file.edit are debug-level kinds, so the passive audit trail only
+// persists when debug writing is on. The difference from OBS_CONFIG is stated here once instead of being
+// re-declared per entrypoint.
+export const OBS_CONFIG_AUDIT = { ...OBS_CONFIG, debugEnabled: true };
+
+// why: the base configs are module constants, so the one operator-controlled field has to be layered on
+// per call rather than baked in at import time.
+export function obsConfigFor(
+  policy: { obs: Policy["obs"] },
+  base: ObservabilityConfig = OBS_CONFIG,
+): ObservabilityConfig {
+  return {
+    ...base,
+    globalSpool: policy.obs.globalSpool,
+    // why: debugEnabled is deliberately absent from Policy.obs. The only events that resolve to debug level
+    // are emitted with OBS_CONFIG_AUDIT, which forces it on for the audit trail (AD-016 item 7), so there is
+    // nothing a project could switch. Exposing it would repeat the dead-section mistake this replaces.
+    includePayloads: policy.obs.includePayloads,
+    maxAttrChars: policy.obs.maxAttrChars,
+    sessionCostAlertUsd: policy.obs.sessionCostAlertUsd,
+    retentionDays: policy.obs.retentionDays,
+  };
+}
+
+/** Characters on disk, or zero when the file went away between the write and the read. */
+export function sizeOf(path: string): number {
+  try {
+    return statSync(path).size;
+  } catch {
+    return 0;
+  }
+}
+
+export function sessionIdFromKey(event: HarnessEvent): string {
+  const prefix = `${event.provider}-`;
+  return event.sessionKey.startsWith(prefix) ? event.sessionKey.slice(prefix.length) : event.sessionKey;
+}
+
+export async function currentGitBranch(root: string): Promise<string | null> {
+  if (!existsSync(join(root, ".git"))) {
+    return null;
+  }
+  const result = await runProcess({ command: ["git", "rev-parse", "--abbrev-ref", "HEAD"], cwd: root });
+  if (result.exitCode !== 0) {
+    return null;
+  }
+  const branch = result.stdout.trim();
+  return branch.length > 0 ? branch : null;
+}
+
+export async function currentGitSha(root: string): Promise<string | null> {
+  if (!existsSync(join(root, ".git"))) {
+    return null;
+  }
+  const result = await runProcess({ command: ["git", "rev-parse", "--short", "HEAD"], cwd: root });
+  if (result.exitCode !== 0) {
+    return null;
+  }
+  const sha = result.stdout.trim();
+  return sha.length > 0 ? sha : null;
+}
+
+/**
+ * hazard: this fell back to a shipped list whenever the project's was empty, so a spawn could be refused by an
+ * allowlist that exists nowhere in the project — and the refusal named no source, so an operator reading `[]` in
+ * their own config could only conclude that empty meant none. There is no shipped list now: the effective one is
+ * exactly what the project configured ([/decisions/ad-053.md](/decisions/ad-053.md)).
+ */
+export function effectiveAllowedModels(
+  configured: string[] | Record<string, string[]> | undefined,
+  provider: ProviderPort,
+): string[] {
+  return coreFacade.policy.forProvider(configured, provider.name) ?? [];
+}
+
+export function effectiveBlockedPatterns(
+  configured: string[] | Record<string, string[]> | undefined,
+  provider: ProviderPort,
+): string[] {
+  const fromConfig = coreFacade.policy.forProvider(configured, provider.name) ?? [];
+  return [...fromConfig, ...provider.policyDefaults().blockedPatterns];
+}
+
+export function effectiveMinEffort(
+  configured: EffortLevel | null,
+  provider: ProviderPort,
+): EffortLevel | null {
+  return configured ?? provider.policyDefaults().minEffort;
+}
+
+/**
+ * Everything `evaluateSubagentSpawn` needs about a spawn, assembled once.
+ *
+ * hazard: `subagent-start` and `tool-before` each built this object, seven identical lines apart from the
+ * indentation, so a new field in `policy.subagents` had to be remembered in two places — the shape where a
+ * consumer stops growing with its producer ([/decisions/ad-065.md](/decisions/ad-065.md)). The duplication rail
+ * found it on its first honest run ([/decisions/ad-071.md](/decisions/ad-071.md)).
+ */
+export function subagentSpawnInput(
+  event: HarnessEvent,
+  policy: Policy,
+  provider: ProviderPort,
+  model: string,
+): Parameters<typeof coreFacade.subagentPolicy.evaluateSubagentSpawn>[0] {
+  return {
+    provider: provider.name,
+    sessionKey: event.sessionKey,
+    projectDir: event.projectDir,
+    model,
+    effort: event.effort,
+    allowedModels: effectiveAllowedModels(policy.subagents.allowedModels, provider),
+    blockedPatterns: effectiveBlockedPatterns(policy.subagents.blockedPatterns, provider),
+    minEffort: effectiveMinEffort(policy.subagents.minEffort, provider),
+    requireModel: policy.subagents.requireModel,
+    enforceAllowlist: policy.subagents.enforceAllowlist,
+    blockParentFast: policy.subagents.blockParentFast,
+    blockMode: policy.subagents.blockMode,
+  };
+}
+
+export function readModelFromToolInput(toolInput: Record<string, unknown> | undefined): string {
+  if (!toolInput) {
+    return "";
+  }
+  const model = toolInput.model ?? toolInput.Model;
+  return typeof model === "string" ? model : "";
+}
+
+/**
+ * hazard: this used to be a copy of the core renderer, on the reasoning that presentation is not core's business.
+ * The copy is what the model actually receives, so the tier added to the core block rendered in `lessons list` and
+ * in nothing an agent ever saw. Two renderers for one string is the same defect as a consumer without a producer,
+ * pointed sideways ([/decisions/ad-040.md](/decisions/ad-040.md)).
+ */
+export function renderLessonLine(lesson: HarnessLesson): string {
+  return coreFacade.lesson.renderLessonBlock(lesson);
+}
+
+/**
+ * invariant: one dispatcher, imported by both session entrypoints. The durable view is written at session start and
+ * again at session end, and a copy of this switch in each would be the AD-042 defect a second time.
+ */
+export function renderProviderLessonsView(providerName: string, root: string): string | null {
+  if (providerName === "cursor") {
+    return renderCursorLessonsView(root);
+  }
+  if (providerName === "claude") {
+    return renderClaudeLessonsView(root);
+  }
+  return null;
+}
+
+/**
+ * why: `omitted` is rendered because the char budget silently cuts below `maxInjectSession` — the count promises
+ * five and a 900-char budget fits about two. A reader who cannot tell that eligible lessons were dropped has no
+ * way to know the budget is the binding constraint ([/decisions/ad-043.md](/decisions/ad-043.md)).
+ *
+ * invariant: silent when nothing was dropped. A note on every healthy turn is one more line to skim past.
+ */
+export function formatLessonsBlock(lessons: HarnessLesson[], title: string, omitted = 0): string {
+  if (lessons.length === 0) {
+    return "";
+  }
+  const lines = [title, ...lessons.map(renderLessonLine)];
+  if (omitted > 0) {
+    const noun = omitted === 1 ? "lesson" : "lessons";
+    lines.push(
+      `  (${omitted} more eligible ${noun} omitted under the char budget — raise maxCharsSession to see them)`,
+    );
+  }
+  return lines.join("\n");
+}

package/src/entrypoints/tool-after.ts

@@ -0,0 +1,111 @@
+import type { HarnessEvent, HarnessEventKind } from "../contracts/index.ts";
+import { coreFacade, type ObsKind } from "../core/index.ts";
+import { estimateCostUsd, mapPoolToNeutral } from "../platform/pricing.ts";
+import { readClaudeUsage } from "../providers/index.ts";
+import type { Handler, HandlerContext } from "./run.ts";
+import { main } from "./run.ts";
+import { OBS_CONFIG_AUDIT, obsConfigFor } from "./support.ts";
+
+const OBS_KIND_BY_EVENT: Partial<Record<HarnessEventKind, ObsKind>> = {
+  "tool.after": "tool.end",
+  "shell.after": "shell.end",
+  "mcp.after": "mcp.end",
+  "edit.after": "file.edit",
+};
+
+function rawString(raw: Record<string, unknown>, key: string): string | undefined {
+  const value = raw[key];
+  return typeof value === "string" ? value : undefined;
+}
+
+function rawBoolean(raw: Record<string, unknown>, key: string): boolean | undefined {
+  const value = raw[key];
+  return typeof value === "boolean" ? value : undefined;
+}
+
+function usageGenAi(event: HarnessEvent, ctx: HandlerContext): Record<string, unknown> | undefined {
+  if (ctx.capabilities.usageInPayload || !event.transcriptPath) {
+    return undefined;
+  }
+  const usage = readClaudeUsage(event.transcriptPath);
+  if (!usage) {
+    return undefined;
+  }
+  const cost = estimateCostUsd(event.provider, event.model, {
+    inputTokens: usage.inputTokens,
+    outputTokens: usage.outputTokens,
+    cacheReadTokens: usage.cacheReadTokens,
+    cacheWriteTokens: usage.cacheWriteTokens,
+  });
+  return {
+    input_tokens: usage.inputTokens,
+    output_tokens: usage.outputTokens,
+    cache_read_tokens: usage.cacheReadTokens,
+    cache_write_tokens: usage.cacheWriteTokens,
+    cost_usd: cost.costUsd,
+    cost_source: cost.source,
+    cost_pool: mapPoolToNeutral(cost.pool),
+  };
+}
+
+export const toolAfterHandler: Handler = (event: HarnessEvent, ctx: HandlerContext) => {
+  coreFacade.observability.recordAudit(event.projectDir, event.event, event.raw, ctx.policy.obs.globalSpool);
+
+  const kind = OBS_KIND_BY_EVENT[event.event];
+  if (kind) {
+    const attrs: Record<string, unknown> = {
+      tool_name: event.toolName,
+      command: event.command,
+      file_path: event.filePath,
+    };
+    if (event.event === "shell.after") {
+      attrs.cwd = rawString(event.raw, "cwd");
+      attrs.sandbox = rawBoolean(event.raw, "sandbox");
+    }
+
+    coreFacade.observability.recordObs(event.projectDir, obsConfigFor(ctx.policy, OBS_CONFIG_AUDIT), {
+      provider: event.provider,
+      kind,
+      sessionKey: event.sessionKey,
+      model: event.model,
+      attrs,
+      gen_ai: usageGenAi(event, ctx),
+    });
+  }
+
+  // hazard: no degrade path consults contextAtToolAfter — the capability is declared but unread, so a
+  // provider that cannot carry context on this event would swallow the framing and leave the rail reporting
+  // a protection it never delivered. Abstaining keeps the marker unset, so a later event can still speak.
+  if (!ctx.capabilities.contextAtToolAfter) {
+    return { kind: "abstain" };
+  }
+
+  // why: recorded before the framing is decided, because the framing fires once per turn and the content of every
+  // untrusted read still has to be remembered ([/decisions/ad-077.md](/decisions/ad-077.md)).
+  if (ctx.provider.capabilities().toolOutputAtAfter) {
+    coreFacade.untrusted.rememberUntrustedOutput({
+      root: event.projectDir,
+      sessionKey: event.sessionKey,
+      event: event.event,
+      toolName: event.toolName,
+      command: event.command,
+      toolOutput: event.toolOutput,
+      config: ctx.policy.untrustedContent,
+      providerTools: ctx.provider.policyDefaults().untrustedTools,
+    });
+  }
+
+  return coreFacade.untrusted.evaluateUntrustedContent({
+    root: event.projectDir,
+    sessionKey: event.sessionKey,
+    event: event.event,
+    toolName: event.toolName,
+    command: event.command,
+    config: ctx.policy.untrustedContent,
+    providerTools: ctx.provider.policyDefaults().untrustedTools,
+  });
+};
+
+if (import.meta.main) {
+  await main(toolAfterHandler);
+}

package/src/entrypoints/tool-before.ts

@@ -0,0 +1,186 @@
+import type { Decision, HarnessEvent } from "../contracts/index.ts";
+import { coreFacade } from "../core/index.ts";
+import type { Handler, HandlerContext } from "./run.ts";
+import { main } from "./run.ts";
+import { obsConfigFor, readModelFromToolInput, subagentSpawnInput } from "./support.ts";
+
+const READONLY_BLOCKED_TOOLS = new Set(["Write", "Delete", "Shell"]);
+
+/**
+ * hazard: `attrs.permission` was read in two places and written in none. `observability.service.ts` increments
+ * `shell.ask`/`shell.deny` from it, `observability.types.ts` grades an event `signal` when it is not `allow`, and
+ * the session report prints `Shell allow/ask/deny` — so both counters were structurally zero and the report
+ * printed a truthful-looking `0` for every ask that ever happened. Obs was emitted only on `*.after` events,
+ * which means the moment a decision is made was the one moment never recorded.
+ *
+ * why: the base config leaves `debugEnabled` false, and an `allow` grades as debug. So an allow is computed and
+ * dropped — costing nothing in the common path — while asks and denials reach disk. `shell.allow` keeps coming
+ * from `shell.end`, so nothing is double-counted.
+ *
+ * invariant: recorded after the decision and never able to change it. A rail that measures interruptions must not
+ * become one.
+ */
+function recordShellDecision(event: HarnessEvent, ctx: HandlerContext, decision: Decision): void {
+  coreFacade.observability.recordObs(event.projectDir, obsConfigFor(ctx.policy), {
+    provider: event.provider,
+    kind: "shell.start",
+    sessionKey: event.sessionKey,
+    model: event.model,
+    attrs: {
+      command: event.command,
+      permission: decision.kind,
+      posture: ctx.policy.mode,
+      // why: unattributed rather than guessed. A rate an operator cannot trace to a switch is a number, not a
+      // signal.
+      rule: "rule" in decision && decision.rule ? decision.rule : "none",
+    },
+  });
+}
+
+function recordShellDecisionIfShell(event: HarnessEvent, ctx: HandlerContext, decision: Decision): void {
+  if (event.event === "shell.before") {
+    recordShellDecision(event, ctx, decision);
+  }
+}
+
+function handleShellBefore(event: HarnessEvent, ctx: HandlerContext): Decision {
+  const { policy } = ctx;
+  const decision = coreFacade.shellPolicy.evaluateShellCommand({
+    command: event.command ?? "",
+    sessionKey: event.sessionKey,
+    projectDir: event.projectDir,
+    mode: policy.mode,
+    catastrophicAsk: policy.shell.catastrophicAsk,
+    stallDetection: policy.shell.stallDetection,
+    stallRepeatThreshold: policy.shell.stallRepeatThreshold,
+  });
+  recordShellDecision(event, ctx, decision);
+  return decision;
+}
+
+// why: a read cannot mutate the policy surface, so it is the one class of event that stays available while a
+// divergence is unresolved. Without it the agent cannot even read the file that explains the block.
+function isReadOnlyEvent(event: HarnessEvent): boolean {
+  return event.event === "read.before" || event.event === "mcp.before";
+}
+
+function filePathOf(event: HarnessEvent): string | undefined {
+  if (event.filePath) {
+    return event.filePath;
+  }
+  const fromInput = event.toolInput?.file_path;
+  return typeof fromInput === "string" ? fromInput : undefined;
+}
+
+async function handleToolBefore(event: HarnessEvent, ctx: HandlerContext): Promise<Decision> {
+  const { policy, provider } = ctx;
+
+  const isReadOnlySubagent =
+    event.subagentType !== undefined && policy.subagents.readOnlyTypes.includes(event.subagentType);
+  if (isReadOnlySubagent && event.toolName !== undefined && READONLY_BLOCKED_TOOLS.has(event.toolName)) {
+    return {
+      kind: "deny",
+      reason: `Explore/read-only subagents cannot use ${event.toolName}. Return findings to the parent agent.`,
+      rule: "subagent-read-only",
+    };
+  }
+
+  if (event.toolName === "Task") {
+    const model = event.spawnModel ?? readModelFromToolInput(event.toolInput);
+    const spawnDecision = coreFacade.subagentPolicy.evaluateSubagentSpawn(
+      subagentSpawnInput(event, policy, provider, model),
+    );
+    if (spawnDecision.kind !== "allow") {
+      return spawnDecision;
+    }
+  }
+
+  if (event.toolName === "Edit" || event.toolName === "Write") {
+    const filePath = filePathOf(event);
+    if (filePath) {
+      const collision = coreFacade.presence.checkCollision(event.projectDir, filePath, event.sessionKey);
+      if (collision.kind !== "allow") {
+        return collision;
+      }
+    }
+  }
+
+  return { kind: "allow" };
+}
+
+export const toolBeforeHandler: Handler = (
+  event: HarnessEvent,
+  ctx: HandlerContext,
+): Decision | Promise<Decision> => {
+  // invariant: the floor runs first and reads no policy, so no config value and no agent edit can
+  // reach a decision before it.
+  const floor = coreFacade.floor.evaluateFloor({
+    projectDir: event.projectDir,
+    toolName: event.toolName,
+    filePath: filePathOf(event),
+    command: event.command,
+    isReadEvent: event.event === "read.before",
+  });
+  if (floor.kind !== "allow") {
+    // invariant: one rail owns the record of every shell decision. The floor short-circuits before the shell
+    // rail runs, so without this a floor denial of a shell command was recorded by nothing at all — and the
+    // shared refusal path deliberately skips `shell.before` to avoid double-counting what this rail owns.
+    recordShellDecisionIfShell(event, ctx, floor);
+    return floor;
+  }
+
+  /**
+   * why: after the floor, because the floor is unconditional and this is a rail. A command the floor already
+   * refuses never needs an operator's opinion ([/decisions/ad-077.md](/decisions/ad-077.md)).
+   */
+  const untrustedAsk = coreFacade.untrusted.askIfFromUntrusted({
+    root: event.projectDir,
+    sessionKey: event.sessionKey,
+    command: event.command,
+    config: ctx.policy.untrustedContent,
+  });
+  if (untrustedAsk.kind !== "abstain") {
+    return untrustedAsk;
+  }
+
+  // invariant: unconditional, for the same reason the floor is. This detects a policy that changed without
+  // a harness command, so reading a policy field to decide whether to look would let the mutation switch
+  // off its own detector.
+  //
+  // hazard: it used to deny every event, reads included, which left the agent unable to look at anything —
+  // it could not diagnose the divergence or explain it, only go mute. Measured: it locked its own author out
+  // of the file holding the fix. A read cannot change a policy, so reads pass and the agent can investigate
+  // and report; everything that acts is still refused until the operator clears it.
+  if (!isReadOnlyEvent(event)) {
+    const integrity = coreFacade.policy.checkPolicyBaseline(event.projectDir, event.sessionKey);
+    if (integrity.kind !== "allow") {
+      recordShellDecisionIfShell(event, ctx, integrity);
+      return integrity;
+    }
+  }
+
+  switch (event.event) {
+    case "shell.before":
+      return handleShellBefore(event, ctx);
+    case "mcp.before":
+    case "read.before":
+      return { kind: "allow" };
+    case "tool.before": {
+      const guard = coreFacade.policy.guardPolicySurface({
+        projectDir: event.projectDir,
+        toolName: event.toolName,
+        filePath: filePathOf(event),
+      });
+      if (guard.kind !== "allow") {
+        return guard;
+      }
+      return handleToolBefore(event, ctx);
+    }
+    default:
+      return { kind: "allow" };
+  }
+};
+
+if (import.meta.main) {
+  await main(toolBeforeHandler);
+}

package/src/entrypoints/tool-failure.ts

@@ -0,0 +1,26 @@
+import type { HarnessEvent } from "../contracts/index.ts";
+import { coreFacade } from "../core/index.ts";
+import type { Handler, HandlerContext } from "./run.ts";
+import { main } from "./run.ts";
+import { OBS_CONFIG_AUDIT, obsConfigFor } from "./support.ts";
+
+export const toolFailureHandler: Handler = (event: HarnessEvent, ctx: HandlerContext) => {
+  coreFacade.observability.recordAudit(event.projectDir, event.event, event.raw, ctx.policy.obs.globalSpool);
+
+  coreFacade.observability.recordObs(event.projectDir, obsConfigFor(ctx.policy, OBS_CONFIG_AUDIT), {
+    provider: event.provider,
+    kind: "tool.fail",
+    sessionKey: event.sessionKey,
+    model: event.model,
+    attrs: {
+      tool_name: event.toolName,
+      file_path: event.filePath,
+      status: event.status,
+    },
+  });
+  return { kind: "abstain" };
+};
+
+if (import.meta.main) {
+  await main(toolFailureHandler);
+}

package/src/platform/backoff.ts

@@ -0,0 +1,49 @@
+export type NextDelayOptions = {
+  attempt: number;
+  baseMs: number;
+  capMs: number;
+  random?: () => number;
+};
+
+export function nextDelay(options: NextDelayOptions): number {
+  const { attempt, baseMs, capMs, random = Math.random } = options;
+  const uncapped = baseMs * 2 ** attempt;
+  const ceiling = Math.min(capMs, uncapped);
+  return random() * ceiling;
+}
+
+export type RetryOptions = {
+  attempts: number;
+  shouldRetry?: (error: unknown) => boolean;
+  sleep?: (ms: number) => Promise<void>;
+  random?: () => number;
+  baseMs?: number;
+  capMs?: number;
+};
+
+function defaultSleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function retry<T>(fn: () => Promise<T> | T, options: RetryOptions): Promise<T> {
+  const {
+    attempts,
+    shouldRetry = () => true,
+    sleep = defaultSleep,
+    random = Math.random,
+    baseMs = 50,
+    capMs = 2000,
+  } = options;
+
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      if (attempt === attempts - 1 || !shouldRetry(error)) {
+        throw error;
+      }
+      await sleep(nextDelay({ attempt, baseMs, capMs, random }));
+    }
+  }
+  throw new Error("retry: unreachable");
+}

package/src/platform/cli-output.ts

@@ -0,0 +1,30 @@
+export type JsonFlagResult = { json: boolean; rest: string[] };
+
+export const JSON_FLAG = "--json";
+
+export function takeJsonFlag(args: readonly string[]): JsonFlagResult {
+  const rest: string[] = [];
+  let json = false;
+  for (const arg of args) {
+    if (arg === JSON_FLAG) {
+      json = true;
+      continue;
+    }
+    rest.push(arg);
+  }
+  return { json, rest };
+}
+
+// why: one line per invocation keeps the contract stream-parseable — a caller can read a single line and
+// hand it to a JSON parser without buffering to EOF or stripping a trailing newline.
+export function emitJson(value: unknown, write: (text: string) => void = writeStdout): void {
+  write(`${JSON.stringify(value)}\n`);
+}
+
+function writeStdout(text: string): void {
+  process.stdout.write(text);
+}
+
+export function unknownFlags(args: readonly string[]): string[] {
+  return args.filter((arg) => arg.startsWith("--"));
+}

package/src/platform/env-scope.ts

@@ -0,0 +1,22 @@
+/**
+ * why: variables that name WHICH project. A gate that runs with one of these set is reading a project root the
+ * hook supplied rather than the one the command assumed, and a suite that builds fixtures in temp directories
+ * reads the real repository under them. That is documented in `tools/test-env.mjs` and it cost four stop loops
+ * of editing code that was not broken ([/decisions/ad-060.md](/decisions/ad-060.md)).
+ *
+ * invariant: this list lives in `platform/` because `core/` may not spell a vendor identifier
+ * (`tools/dev/check-boundaries.ts`). Core asks which ones are set and never names one.
+ *
+ * invariant: `TLC_HOME` is deliberately absent. It names which runtime, not which project, and CI sets it on
+ * purpose.
+ */
+export const PROJECT_SCOPED_ENV_NAMES = [
+  "CLAUDE_PROJECT_DIR",
+  "CURSOR_PROJECT_DIR",
+  "TLC_PROJECT_DIR",
+] as const;
+
+/** The names that are set and non-empty, in declaration order, so the reading is stable across runs. */
+export function setProjectScopedEnv(env: NodeJS.ProcessEnv = process.env): string[] {
+  return PROJECT_SCOPED_ENV_NAMES.filter((name) => (env[name] ?? "").trim() !== "");
+}