@tech-leads-club/harness-toolkit 0.2.1

package/src/entrypoints/run.ts

@@ -0,0 +1,179 @@
+import { join } from "node:path";
+import type { Decision, HarnessEvent, ProviderCapabilities, Rendered } from "../contracts/index.ts";
+import { coreFacade, type Policy } from "../core/index.ts";
+import { appendRecord } from "../platform/fs-jsonl.ts";
+import { projectStateDir } from "../platform/paths.ts";
+import { readStdinText } from "../platform/process.ts";
+import {
+  degrade,
+  type ProviderPort,
+  providers as providerRegistry,
+  resolveFromRegistry,
+} from "../providers/index.ts";
+import { effectiveBlockedPatterns, obsConfigFor, sessionIdFromKey } from "./support.ts";
+
+export type HandlerContext = {
+  policy: Policy;
+  capabilities: ProviderCapabilities;
+  provider: ProviderPort;
+  now: Date;
+};
+
+export type Handler = (event: HarnessEvent, ctx: HandlerContext) => Decision | Promise<Decision>;
+
+export type RunIo = {
+  readStdin?: () => Promise<string>;
+  now?: () => Date;
+};
+
+export type RunOutcome = {
+  event: HarnessEvent | null;
+  decision: Decision;
+  rendered: Rendered;
+};
+
+// invariant: this caps the whole injected context. Lessons carry their own, smaller budget
+// (lessons.maxCharsSession) — reusing that here truncated the operator posture and handoff.
+export const CONTEXT_BUDGET_CHARS = 6000;
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// why: ObsKind is a closed union with no adapter-boundary member — these fire before a provider/session is known, so they bypass core's typed observability rather than widening that union from outside core.
+function recordAdapterEvent(root: string, kind: string, attrs: Record<string, unknown>): void {
+  try {
+    appendRecord(join(projectStateDir(root), "obs.jsonl"), {
+      schema: "harness.observability.v1",
+      provider: "unknown",
+      kind,
+      level: "signal",
+      ts: new Date().toISOString(),
+      attrs,
+    });
+  } catch {}
+}
+
+/**
+ * hazard: `policy.deny` fed `rollup.denials` and the report's "Policy denials" line, and had no producer — so a
+ * harness whose whole purpose is refusing things reported zero refusals
+ * ([/decisions/ad-027.md](/decisions/ad-027.md)).
+ *
+ * why: recorded here, after `degrade`, because this is the one place every entrypoint's decision passes through
+ * and the only place that sees the decision the provider will actually render. A per-entrypoint recording would
+ * miss whichever entrypoint is added next, and would record a decision that degrade could still change.
+ *
+ * invariant: shell decisions are recorded by `tool-before` as `shell.start`, with their own permission attribute.
+ * Recording them here as well would double-count every interruption.
+ */
+function recordRefusal(event: HarnessEvent, policy: Policy, decision: Decision): void {
+  if (decision.kind !== "deny" && decision.kind !== "ask") {
+    return;
+  }
+  if (event.event === "shell.before") {
+    return;
+  }
+  coreFacade.observability.recordObs(event.projectDir, obsConfigFor(policy), {
+    provider: event.provider,
+    kind: "policy.deny",
+    sessionKey: event.sessionKey,
+    attrs: {
+      event: event.event,
+      tool_name: event.toolName,
+      permission: decision.kind,
+      // why: unattributed rather than guessed. A refusal an operator cannot trace to a rule is noise.
+      rule: decision.rule ?? "none",
+    },
+  });
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+export async function runHandler(handler: Handler, io: RunIo = {}): Promise<RunOutcome> {
+  const readStdin = io.readStdin ?? readStdinText;
+  const now = io.now ? io.now() : new Date();
+  const abstainRendered: Rendered = { stdout: null, exitCode: 0 };
+
+  const text = await readStdin();
+  const trimmed = text.trim();
+  if (!trimmed) {
+    recordAdapterEvent(process.cwd(), "adapter.unrecognized", { reason: "empty-stdin" });
+    return { event: null, decision: { kind: "abstain" }, rendered: abstainRendered };
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    recordAdapterEvent(process.cwd(), "adapter.unrecognized", { reason: "invalid-json" });
+    return { event: null, decision: { kind: "abstain" }, rendered: abstainRendered };
+  }
+
+  const resolved = resolveFromRegistry(parsed, providerRegistry);
+  if (!resolved.provider) {
+    recordAdapterEvent(process.cwd(), "adapter.unrecognized", { reason: "no-provider-match" });
+    return { event: null, decision: { kind: "abstain" }, rendered: abstainRendered };
+  }
+  if (resolved.ambiguous) {
+    recordAdapterEvent(process.cwd(), "adapter.ambiguous", { matched: resolved.matchedNames });
+  }
+
+  const provider = resolved.provider;
+  const event = provider.toEvent(asRecord(parsed));
+  if (!event) {
+    recordAdapterEvent(process.cwd(), "adapter.unrecognized", {
+      reason: "unrecognized-event",
+      provider: provider.name,
+    });
+    return { event: null, decision: { kind: "abstain" }, rendered: abstainRendered };
+  }
+
+  const capabilities = provider.capabilities();
+
+  try {
+    const policy = coreFacade.policy.loadPolicy(event.projectDir);
+    if (event.model) {
+      coreFacade.subagentPolicy.upsertParentModelState(
+        event.projectDir,
+        event.sessionKey,
+        { model: event.model },
+        effectiveBlockedPatterns(policy.subagents.blockedPatterns, provider),
+      );
+    }
+    coreFacade.presence.heartbeat(event.projectDir, {
+      provider: event.provider,
+      session: sessionIdFromKey(event),
+      file: event.filePath,
+      now,
+    });
+    const context: HandlerContext = { policy, capabilities, provider, now };
+    const decision = await handler(event, context);
+    const degraded = degrade(decision, event, capabilities, {
+      contextBudgetChars: CONTEXT_BUDGET_CHARS,
+    });
+    recordRefusal(event, policy, degraded);
+    const rendered = provider.render(degraded, event);
+    return { event, decision: degraded, rendered };
+  } catch (error) {
+    recordAdapterEvent(event.projectDir, "adapter.error", {
+      provider: event.provider,
+      event: event.event,
+      message: errorMessage(error),
+    });
+    const abstain: Decision = { kind: "abstain" };
+    return { event, decision: abstain, rendered: provider.render(abstain, event) };
+  }
+}
+
+export async function main(handler: Handler): Promise<void> {
+  const outcome = await runHandler(handler);
+  if (outcome.rendered.stdout !== null) {
+    const text = outcome.rendered.stdout;
+    process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
+  }
+  process.exit(outcome.rendered.exitCode);
+}

package/src/entrypoints/session-end.ts

@@ -0,0 +1,58 @@
+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 { renderProviderLessonsView, sessionIdFromKey } from "./support.ts";
+
+export const sessionEndHandler: Handler = async (
+  event: HarnessEvent,
+  ctx: HandlerContext,
+): Promise<Decision> => {
+  const { policy } = ctx;
+  const root = event.projectDir;
+  const session = sessionIdFromKey(event);
+
+  await coreFacade.handoff.patchHandoff(root, event.provider, {
+    slice: {
+      next_action: "Session ended. Run `tlc harness handoff` before resuming.",
+    },
+  });
+
+  coreFacade.presence.release(root, event.provider, session);
+  coreFacade.turn.resetLoop(root, event.sessionKey);
+
+  if (policy.intelligence.lessons.enabled && policy.intelligence.lessons.gardenOnSessionEnd) {
+    const verdict = coreFacade.lesson.durableViewVerdict(
+      policy.intelligence.lessons.syncRulesFile,
+      ctx.capabilities.sessionStartContextReliable,
+    );
+    const garden = await coreFacade.lesson.gardenAndPersistLessons(root, policy.intelligence.lessons, {
+      writeDurableView: verdict.writes,
+    });
+    if (garden.markdownPath) {
+      renderProviderLessonsView(event.provider, root);
+    }
+  }
+
+  // why: written at session end, when the rollup is complete. Every field is something the harness observed —
+  // there is no claim that the code is correct or that a human approved anything, because it cannot see either and
+  // an attestation implying them would be worse than none ([/decisions/ad-028.md](/decisions/ad-028.md)).
+  const rollup = coreFacade.observability.getRollup(root, event.sessionKey);
+  const sources = coreFacade.policy.policySourceFingerprint(root);
+  coreFacade.attest.appendAttestation(root, {
+    ts: new Date().toISOString(),
+    provider: event.provider,
+    session,
+    policyFingerprint: coreFacade.attest.fingerprintOf(sources),
+    policyDiverged: coreFacade.policy.checkPolicyBaseline(root, event.sessionKey).kind !== "allow",
+    railsActive: coreFacade.policy.activeRails(policy),
+    decisionsByRule: rollup?.railsByRule ?? {},
+    gates: rollup?.gates ?? { pass: 0, fail: 0 },
+  });
+
+  return { kind: "abstain" };
+};
+
+if (import.meta.main) {
+  await main(sessionEndHandler);
+}

package/src/entrypoints/session-start.ts

@@ -0,0 +1,172 @@
+import type { Decision, HarnessEvent } from "../contracts/index.ts";
+import { coreFacade } from "../core/index.ts";
+import { projectStateDir } from "../platform/paths.ts";
+import type { Handler, HandlerContext } from "./run.ts";
+import { main } from "./run.ts";
+import {
+  currentGitBranch,
+  currentGitSha,
+  formatLessonsBlock,
+  obsConfigFor,
+  renderProviderLessonsView,
+  sessionIdFromKey,
+  sizeOf,
+} from "./support.ts";
+
+export const sessionStartHandler: Handler = async (
+  event: HarnessEvent,
+  ctx: HandlerContext,
+): Promise<Decision> => {
+  const { policy } = ctx;
+  const session = sessionIdFromKey(event);
+  const root = event.projectDir;
+
+  // why: recorded before the already-booted return so a resumed session has a baseline too. The check
+  // records lazily when one is missing, so this is robustness rather than correctness.
+  coreFacade.policy.recordPolicyBaseline(root, event.sessionKey);
+
+  let durableChars = 0;
+
+  const boot = coreFacade.turn.markBooted(root, event.sessionKey);
+  if (boot.alreadyBooted) {
+    return { kind: "context", text: "", env: { HARNESS_ACTIVE: "1" } };
+  }
+
+  const branch = await currentGitBranch(root);
+  const sha = await currentGitSha(root);
+
+  coreFacade.presence.sweepStale(root);
+  coreFacade.presence.register(root, {
+    provider: event.provider,
+    session,
+    pid: process.pid,
+    branch: branch ?? "unknown",
+  });
+
+  await coreFacade.handoff.patchHandoff(root, event.provider, {
+    shared: {
+      mode: policy.mode,
+      project_name: policy.projectName,
+      git_branch: branch ?? undefined,
+      git_sha: sha ?? undefined,
+    },
+    slice: {
+      session_key: event.sessionKey,
+      // why: names the command, not the file. The path is on the policy surface, so an instruction pointing at it
+      // asked for something the floor then refused ([/decisions/ad-047.md](/decisions/ad-047.md)).
+      next_action: "Run `tlc harness handoff` if resuming; otherwise start from the user request.",
+    },
+  });
+
+  /**
+   * why: the handoff and the lesson store are the two files the harness reads aloud to the model, so a write it
+   * did not make is text placed in front of every later turn. Withholding is the answer, not refusing the turn
+   * ([/decisions/ad-078.md](/decisions/ad-078.md)).
+   */
+  const handoffSeal = coreFacade.handoff.handoffInjectable(root);
+  const lessonSeal = coreFacade.lesson.projectLessonsInjectable(root);
+  const handoff = handoffSeal.ok
+    ? coreFacade.handoff.readHandoff(root, event.provider)
+    : ({} as ReturnType<typeof coreFacade.handoff.readHandoff>);
+  const foreign = handoffSeal.ok ? coreFacade.handoff.readForeignSlices(root, event.provider) : [];
+
+  const lines = [
+    ...[handoffSeal.note, lessonSeal.note].filter((note): note is string => note !== null),
+    ...coreFacade.policy.operatorBootstrapLines(policy, projectStateDir(root)),
+    "",
+    `Project root: ${root}`,
+  ];
+  if (policy.projectName) {
+    lines.push(`Project: ${policy.projectName}`);
+  }
+  if (branch) {
+    lines.push(`Git branch: ${branch}`);
+  }
+  if (sha) {
+    lines.push(`Git HEAD: ${sha}`);
+  }
+  if (handoff.blockers) {
+    lines.push(`Handoff blocker: ${handoff.blockers}`);
+  }
+  if (handoff.next_action) {
+    lines.push(`Handoff next: ${handoff.next_action}`);
+  }
+  // why: this is the flag's only reader. It was declared, defaulted on, described in the catalog as carrying gaps
+  // into the next bootstrap, and read nowhere — so the gaps `stop` wrote were never read back out.
+  if (policy.intelligence.progressiveHandoff) {
+    const carried = coreFacade.turn.formatCarriedGaps(handoff.previous_gaps ?? []);
+    if (carried) {
+      lines.push("", carried);
+    }
+  }
+  for (const slice of foreign) {
+    lines.push("", `Foreign slice (${slice.provider}):`);
+    if (slice.next_action) {
+      lines.push(`  next_action: ${slice.next_action}`);
+    }
+    if (slice.blockers) {
+      lines.push(`  blockers: ${slice.blockers}`);
+    }
+  }
+
+  if (policy.intelligence.lessons.enabled && lessonSeal.ok) {
+    const config = policy.intelligence.lessons;
+    const selected = await coreFacade.lesson.selectLessons({
+      projectDir: root,
+      config,
+      mode: "session",
+      text: [handoff.blockers, handoff.next_action].filter(Boolean).join(" "),
+    });
+    const block = formatLessonsBlock(
+      selected.lessons,
+      "Lessons (ranked; follow these — do not repeat known failures):",
+      selected.omitted,
+    );
+    if (block) {
+      lines.push("", block);
+    }
+    // hazard: the durable view was written only at session end, so on the host that depends on it the file carried
+    // the previous session's ranked set and did not exist at all during the first one. Written here it is in place
+    // before the first prompt ([/decisions/ad-050.md](/decisions/ad-050.md)).
+    if (
+      coreFacade.lesson.durableViewVerdict(config.syncRulesFile, ctx.capabilities.sessionStartContextReliable)
+        .writes
+    ) {
+      coreFacade.lesson.renderLessonsMarkdown(root, coreFacade.lesson.allLessons(root), config);
+      const viewPath = renderProviderLessonsView(event.provider, root);
+      // why: measured from the file that was written, not estimated from the lessons that went into it. The view
+      // carries frontmatter the injected block does not ([/decisions/ad-050.md](/decisions/ad-050.md)).
+      durableChars = viewPath === null ? 0 : sizeOf(viewPath);
+    }
+  }
+
+  lines.push(
+    policy.grind.enabled
+      ? "Grind ON: stop hook runs configured lint/test gates and auto-continues on failure."
+      : "Grind OFF (default).",
+  );
+
+  const text = lines.join("\n");
+  // why: the harness injects prose on every session and had never told the operator what it costs. Rails are not
+  // free — they are paid in input tokens, on every turn, forever — and a cost nobody can see is a cost nobody
+  // weighs ([/decisions/ad-027.md](/decisions/ad-027.md)).
+  coreFacade.observability.recordObs(root, obsConfigFor(policy), {
+    provider: event.provider,
+    kind: "session.start",
+    sessionKey: event.sessionKey,
+    attrs: {
+      injected_chars: text.length,
+      injected_lines: lines.length,
+      posture: policy.mode,
+      lessons_injected: policy.intelligence.lessons.enabled,
+      durable_chars: durableChars,
+      hook_context_reliable: ctx.capabilities.sessionStartContextReliable,
+    },
+  });
+
+  return { kind: "context", text, env: { HARNESS_ACTIVE: "1" } };
+};
+
+if (import.meta.main) {
+  await main(sessionStartHandler);
+}

package/src/entrypoints/shim.ts

@@ -0,0 +1,46 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { runtimeHome } from "../platform/paths.ts";
+
+const handler = process.argv[2];
+if (!handler) {
+  console.error("usage: shim <handler-name>");
+  process.exit(1);
+}
+
+// hazard: a project-level hook and a user-level hook both fire for the same event. The user-level
+// session start sets TLC_ACTIVE, so the project shim stands down rather than double-firing.
+if (process.env.TLC_ACTIVE === "1") {
+  process.stdout.write("{}\n");
+  process.exit(0);
+}
+
+const home = runtimeHome();
+const execBin = join(home, "bin", "tlc-exec");
+const distHandler = join(home, "dist", `${handler}.mjs`);
+const srcHandler = join(home, "src", "entrypoints", `${handler}.ts`);
+
+function run(command: string, args: string[]): void {
+  const child = spawn(command, args, { stdio: ["pipe", "pipe", "inherit"], env: process.env });
+  process.stdin.pipe(child.stdin);
+  let stdout = "";
+  child.stdout.on("data", (chunk: Buffer) => {
+    stdout += chunk.toString();
+  });
+  child.on("close", (code) => {
+    process.stdout.write(stdout);
+    process.exit(code ?? 0);
+  });
+}
+
+if (existsSync(execBin)) {
+  run(execBin, [handler]);
+} else if (existsSync(distHandler)) {
+  run(process.execPath, [distHandler]);
+} else if (existsSync(srcHandler)) {
+  run(process.env.BUN_BIN || "bun", ["run", srcHandler]);
+} else {
+  console.error(`tlc shim: handler not found: ${handler}`);
+  process.exit(127);
+}