@tech-leads-club/harness-toolkit 0.16.4 → 0.16.6

package/docs/diagnose.md

@@ -55,6 +55,27 @@ tlc harness doctor
 state, and only the floor keeps running, because a limit an agent can turn off is not a limit. A pause flag that
 appears without the CLI is a policy change, not a pause, and is ignored.
 
+## The host says a hook returned no output
+
+Every hook invocation leaves two lines in `~/.tlc/harness/state/hook-trace.jsonl`: `start`, written by the launcher
+before the handler runs, and `end`, with the duration, exit status, signal and the verdict it printed. Each line
+carries the host's `tool_use_id`, `generation_id` and `conversation_id`, never the tool input, so a refusal the host
+reports can be matched to the invocation that produced it:
+
+- no `start` for that tool call: the host never ran the launcher, or it died before its first line;
+- a `start` with no `end`: the process was killed mid-run, usually by the host's own timeout;
+- an `end` with a verdict: the harness answered, and the host discarded it.
+
+The file rotates to `hook-trace.jsonl.1` at 5 MB.
+
+## A push is refused: no passing run is recorded for this tree
+
+The push battery reads a verdict recorded for the exact working tree; it does not run the suite inside the hook.
+Run `tlc harness verify` in the shell and retry. Give that command a timeout long enough for the whole suite, or run
+it in the background and wait — Cursor's agent shell gives up on a command after about 30 seconds by default. Any
+edit after the run changes the tree and needs a new run. A gate that rewrites files (a formatter) is not recorded:
+review what it changed and run `verify` again.
+
 ## Node vs Bun
 
 - Preferred: **Bun** on PATH — every hook runs the TypeScript source directly, ~1 ms per invocation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tech-leads-club/harness-toolkit",
-  "version": "0.16.4",
+  "version": "0.16.6",
   "type": "module",
   "description": "Multi-provider agent steering: gates, follow-up, handoff, policy",
   "keywords": [

package/src/core/core.facade.ts

@@ -56,6 +56,7 @@ import { filesFromOutput } from "./gate/gate.findings.ts";
 import { cachedVerdict, computeInputsHash, isCacheHit } from "./gate/gate.inputs.ts";
 import { describeHolder, GATE_LOCK_WAIT_MS, GateLockTimeoutError, withGateLock } from "./gate/gate.lock.ts";
 import { gapsFromArtifact } from "./gate/gate.service.ts";
+import { findShipVerdict, lastShipVerdictFor, recordShipVerdict } from "./gate/gate.verdicts.ts";
 import {
   clearStuckSignals,
   handoffInjectable,
@@ -317,6 +318,9 @@ export const coreFacade = {
     isRecipeRunner,
     isCommandResolutionFailure,
     filesFromOutput,
+    findShipVerdict,
+    lastShipVerdictFor,
+    recordShipVerdict,
   },
   stagnation: {
     computeFingerprint,

package/src/core/gate/gate.verdicts.ts

@@ -0,0 +1,95 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { updateJsonAtomic } from "../../platform/fs-atomic.ts";
+import { linkedWorktreeMainRoot } from "../../platform/git.ts";
+import { projectStateDir } from "../../platform/paths.ts";
+import { trimOutputTail } from "./gate.artifact.ts";
+
+const SHIP_VERDICT_SCHEMA = "harness.ship-verdicts.v1";
+export const SHIP_VERDICT_LIMIT = 50;
+
+export type ShipVerdict = {
+  gate: string;
+  command: string[];
+  tree: string;
+  passed: boolean;
+  exitCode: number;
+  durationMs: number;
+  outputTail: string;
+  at: string;
+};
+
+type ShipVerdictFile = { schema: string; verdicts: ShipVerdict[] };
+
+function shipVerdictsPath(root: string): string {
+  return join(projectStateDir(linkedWorktreeMainRoot(root) ?? root), "ship-verdicts.json");
+}
+
+function sameCommand(left: string[], right: string[]): boolean {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+export function readShipVerdicts(root: string): ShipVerdict[] {
+  const path = shipVerdictsPath(root);
+  if (!existsSync(path)) {
+    return [];
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<ShipVerdictFile>;
+    return Array.isArray(parsed.verdicts) ? parsed.verdicts : [];
+  } catch {
+    return [];
+  }
+}
+
+export function findShipVerdict(
+  root: string,
+  gate: string,
+  command: string[],
+  tree: string,
+): ShipVerdict | null {
+  const matches = readShipVerdicts(root).filter(
+    (verdict) => verdict.gate === gate && verdict.tree === tree && sameCommand(verdict.command, command),
+  );
+  return matches.at(-1) ?? null;
+}
+
+export function lastShipVerdictFor(root: string, gate: string, command: string[]): ShipVerdict | null {
+  const matches = readShipVerdicts(root).filter(
+    (verdict) => verdict.gate === gate && sameCommand(verdict.command, command),
+  );
+  return matches.at(-1) ?? null;
+}
+
+export async function recordShipVerdict(
+  root: string,
+  input: Omit<ShipVerdict, "at" | "outputTail" | "passed"> & { output: string; at?: string },
+): Promise<ShipVerdict> {
+  const verdict: ShipVerdict = {
+    gate: input.gate,
+    command: input.command,
+    tree: input.tree,
+    passed: input.exitCode === 0,
+    exitCode: input.exitCode,
+    durationMs: input.durationMs,
+    outputTail: trimOutputTail(input.output),
+    at: input.at ?? new Date().toISOString(),
+  };
+  const path = shipVerdictsPath(root);
+  await updateJsonAtomic<ShipVerdictFile>(
+    path,
+    (current) => {
+      const kept = (current?.verdicts ?? []).filter(
+        (existing) =>
+          !(
+            existing.gate === verdict.gate &&
+            existing.tree === verdict.tree &&
+            sameCommand(existing.command, verdict.command)
+          ),
+      );
+      return { schema: SHIP_VERDICT_SCHEMA, verdicts: [...kept, verdict].slice(-SHIP_VERDICT_LIMIT) };
+    },
+    { lockPath: `${path}.lock` },
+  );
+  return verdict;
+}

package/src/core/index.ts

@@ -8,6 +8,7 @@ export type { CoreFacade } from "./core.facade.ts";
 export { coreFacade } from "./core.facade.ts";
 export type { FloorInput, FloorRule } from "./floor/floor.service.ts";
 export type { FailureCategory, GateFinding, GateGap, LastGateArtifact, LockBody } from "./gate/gate.types.ts";
+export type { ShipVerdict } from "./gate/gate.verdicts.ts";
 export type {
   ForeignSlice,
   GateResult,

package/src/entrypoints/ship-gate.ts

@@ -5,16 +5,15 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import type { Decision, HarnessEvent } from "../contracts/index.ts";
 import { coreFacade } from "../core/index.ts";
-import { gitRootOf, listAddedLines, listTrackedFiles, localRepoRemote } from "../platform/git.ts";
-import type { HandlerContext } from "./run.ts";
-import { runLockedGate } from "./stop.ts";
 import {
-  computeTurnScope,
-  currentGitSha,
-  pendingCommentViolations,
-  sessionIdFromKey,
-  shaScopeRoot,
-} from "./support.ts";
+  gitRootOf,
+  listAddedLines,
+  listTrackedFiles,
+  localRepoRemote,
+  workingTreeId,
+} from "../platform/git.ts";
+import type { HandlerContext } from "./run.ts";
+import { computeTurnScope, currentGitSha, pendingCommentViolations, shaScopeRoot } from "./support.ts";
 
 // why: pr-merge is the moment code actually lands on the shared branch. Usually no local diff exists at merge
 // time, so the battery abstains — the merged commits already paid it at push/pr-open time
@@ -62,6 +61,54 @@ function gateFailureMessage(
   ].join("\n");
 }
 
+function formatDuration(ms: number): string {
+  const seconds = Math.round(ms / 1000);
+  return seconds < 60 ? `${seconds}s` : `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
+}
+
+function verdictRefusal(
+  root: string,
+  tree: string,
+  required: Array<{ gate: string; command: string[] }>,
+  diag: ReturnType<typeof coreFacade.diagnostics.rootDiagnostic>,
+): Decision | null {
+  const missing: Array<{ gate: string; command: string[] }> = [];
+  for (const { gate, command } of required) {
+    const verdict = coreFacade.gate.findShipVerdict(root, gate, command, tree);
+    if (verdict === null) {
+      missing.push({ gate, command });
+      continue;
+    }
+    if (!verdict.passed) {
+      return {
+        kind: "deny",
+        reason: gateFailureMessage(gate, verdict.command, verdict.outputTail, diag),
+        rule: `ship-gate-${gate}`,
+        diagnostic: diag.summary,
+      };
+    }
+  }
+  if (missing.length === 0) {
+    return null;
+  }
+  const last = missing
+    .map(({ gate, command }) => coreFacade.gate.lastShipVerdictFor(root, gate, command))
+    .reduce((total, verdict) => total + (verdict?.durationMs ?? 0), 0);
+  const estimate = last > 0 ? ` The last run took ${formatDuration(last)}.` : "";
+  return {
+    kind: "deny",
+    reason: [
+      `BLOCKED: no passing ${missing.map(({ gate }) => gate).join(" + ")} run is recorded for this tree, and a hook cannot wait for one.`,
+      `TRIED: looked up the verdicts recorded for tree ${tree.slice(0, 12)}.`,
+      `NEED: run \`tlc harness verify\` in the shell, let it finish, then retry the commit/push/PR.${estimate} Give the command a timeout long enough for the whole suite, or run it in the background and wait for it.`,
+      "",
+      diag.footer,
+    ].join("\n"),
+    rule: "ship-gate-unverified",
+    diagnostic: diag.summary,
+  };
+}
+
 /**
  * why after comments and before the stop-rules check: cheapest first. A comment violation costs a
  * regex scan; a gate command is a real process; the stop-rules check is a directory read plus, only
@@ -76,7 +123,6 @@ export async function shipGateVerdict(event: HarnessEvent, ctx: HandlerContext):
   const root = event.projectDir;
   const provider = event.provider;
   const sessionKey = event.sessionKey;
-  const session = sessionIdFromKey(event);
   const scope = await computeTurnScope(root, shaRoot, provider, sessionKey, policy);
   const rootDiag = coreFacade.diagnostics.rootDiagnostic(shaRoot);
 
@@ -91,84 +137,27 @@ export async function shipGateVerdict(event: HarnessEvent, ctx: HandlerContext):
     };
   }
 
+  const required: Array<{ gate: string; command: string[] }> = [];
   if (policy.grind.enabled && policy.grind.lintCommand && scope.codeTargets.length > 0) {
-    const run = await runLockedGate({
-      root,
-      shaRoot,
-      provider,
-      session,
-      pendingCredit: scope.pendingCredit,
-      sessionKey,
-      policy,
-      gate: "lint",
-      command: policy.grind.lintCommand,
-      argvFiles: coreFacade.gate.shouldAppendFiles(policy.grind.lintCommand, policy.grind.appendFiles)
-        ? scope.codeTargets
-        : [],
-      recordFiles: scope.codeTargets,
-    });
-    if (run.kind === "ran" && !run.artifact.passed) {
-      return {
-        kind: "deny",
-        reason: gateFailureMessage("lint", run.artifact.command, run.artifact.outputTail, rootDiag),
-        rule: "ship-gate-lint",
-        diagnostic: rootDiag.summary,
-      };
-    }
+    required.push({ gate: "lint", command: policy.grind.lintCommand });
   }
-
   if (
     policy.grind.enabled &&
     policy.grind.testCommand &&
     (scope.testTargets.length > 0 || scope.codeTargets.length > 0)
   ) {
-    const recordFiles = scope.testTargets.length > 0 ? scope.testTargets : scope.codeTargets;
-    const run = await runLockedGate({
-      root,
-      shaRoot,
-      provider,
-      session,
-      pendingCredit: scope.pendingCredit,
-      sessionKey,
-      policy,
-      gate: "test",
-      command: policy.grind.testCommand,
-      argvFiles: coreFacade.gate.shouldAppendFiles(policy.grind.testCommand, policy.grind.appendFiles)
-        ? recordFiles
-        : [],
-      recordFiles,
-    });
-    if (run.kind === "ran" && !run.artifact.passed) {
-      return {
-        kind: "deny",
-        reason: gateFailureMessage("test", run.artifact.command, run.artifact.outputTail, rootDiag),
-        rule: "ship-gate-test",
-        diagnostic: rootDiag.summary,
-      };
-    }
+    required.push({ gate: "test", command: policy.grind.testCommand });
   }
-
   if (policy.docs.command && policy.docs.command.length > 0 && policy.docs.severity === "deny") {
-    const run = await runLockedGate({
-      root,
-      shaRoot,
-      provider,
-      session,
-      pendingCredit: scope.pendingCredit,
-      sessionKey,
-      policy,
-      gate: "docs",
-      command: policy.docs.command,
-      argvFiles: [],
-      recordFiles: scope.changedFiles,
-    });
-    if (run.kind === "ran" && !run.artifact.passed) {
-      return {
-        kind: "deny",
-        reason: gateFailureMessage("docs", run.artifact.command, run.artifact.outputTail, rootDiag),
-        rule: "ship-gate-docs",
-        diagnostic: rootDiag.summary,
-      };
+    required.push({ gate: "docs", command: policy.docs.command });
+  }
+  if (required.length > 0) {
+    const tree = await workingTreeId(shaRoot);
+    if (tree !== null) {
+      const refusal = verdictRefusal(root, tree, required, rootDiag);
+      if (refusal) {
+        return refusal;
+      }
     }
   }
 

package/src/entrypoints/stop.ts

@@ -9,6 +9,7 @@ import {
   listAddedLines,
   listChangedRepoFiles,
   listTrackedFiles,
+  workingTreeId,
 } from "../platform/git.ts";
 import { flagsDir } from "../platform/paths.ts";
 import { runCommand } from "../platform/process.ts";
@@ -226,7 +227,18 @@ export async function runLockedGate(args: {
         args.provider,
         args.session,
         async () => {
+          const treeBefore = await workingTreeId(args.shaRoot);
           const result = await runCommand(args.shaRoot, args.command, args.argvFiles);
+          if (treeBefore !== null && (await workingTreeId(args.shaRoot)) === treeBefore) {
+            await coreFacade.gate.recordShipVerdict(args.root, {
+              gate: args.gate,
+              command: args.command,
+              tree: treeBefore,
+              exitCode: result.exitCode,
+              durationMs: result.durationMs,
+              output: result.output,
+            });
+          }
           return coreFacade.gate.writeLastGate({
             root: args.root,
             sessionKey: args.sessionKey,

package/src/platform/git.ts

@@ -1,4 +1,14 @@
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  utimesSync,
+  writeFileSync,
+} from "node:fs";
 import { realpath } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
@@ -58,6 +68,54 @@ export async function gitCommonDirOf(dir: string): Promise<string | null> {
   }
 }
 
+export async function workingTreeId(dir: string): Promise<string | null> {
+  let indexPath: string;
+  let objectsPath: string;
+  try {
+    const located = await runProcess({
+      command: ["git", "rev-parse", "--path-format=absolute", "--git-path", "index", "--git-path", "objects"],
+      cwd: dir,
+    });
+    const [index, objects] = located.stdout.trim().split("\n");
+    if (located.exitCode !== 0 || !index || !objects) {
+      return null;
+    }
+    indexPath = index;
+    objectsPath = objects;
+  } catch {
+    return null;
+  }
+  const scratch = mkdtempSync(join(tmpdir(), "tlc-tree-"));
+  const env = {
+    ...process.env,
+    GIT_INDEX_FILE: join(scratch, "index"),
+    GIT_OBJECT_DIRECTORY: join(scratch, "objects"),
+    GIT_ALTERNATE_OBJECT_DIRECTORIES: objectsPath,
+  };
+  const git = (args: string[]) =>
+    runProcess({ command: ["git", "-c", "core.fsmonitor=false", ...args], cwd: dir, env });
+  try {
+    mkdirSync(env.GIT_OBJECT_DIRECTORY);
+    if (existsSync(indexPath)) {
+      copyFileSync(indexPath, env.GIT_INDEX_FILE);
+      const original = statSync(indexPath);
+      utimesSync(env.GIT_INDEX_FILE, original.atime, original.mtime);
+    } else if ((await git(["read-tree", "--empty"])).exitCode !== 0) {
+      return null;
+    }
+    if ((await git(["add", "-A"])).exitCode !== 0) {
+      return null;
+    }
+    const tree = await git(["write-tree"]);
+    const id = tree.stdout.trim();
+    return tree.exitCode === 0 && id.length > 0 ? id : null;
+  } catch {
+    return null;
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+}
+
 export function linkedWorktreeMainRoot(root: string): string | null {
   let text: string;
   try {

package/tools/verify.ts

@@ -0,0 +1,145 @@
+import { spawn } from "node:child_process";
+import { coreFacade } from "../src/core/index.ts";
+import { emitJson, takeJsonFlag } from "../src/platform/cli-output.ts";
+import { gitRootOf, workingTreeId } from "../src/platform/git.ts";
+import { findProjectRoot } from "../src/platform/paths.ts";
+
+const OUTPUT_KEEP_CHARS = 64 * 1024;
+
+export type VerifyGate = { gate: string; command: string[] };
+
+export type VerifyOutcome = {
+  gate: string;
+  command: string[];
+  exitCode: number;
+  durationMs: number;
+  recorded: boolean;
+  treeChanged: boolean;
+};
+
+export function gatesToVerify(policy: ReturnType<typeof coreFacade.policy.loadPolicy>): VerifyGate[] {
+  const gates: VerifyGate[] = [];
+  if (policy.grind.enabled && policy.grind.lintCommand && policy.grind.lintCommand.length > 0) {
+    gates.push({ gate: "lint", command: policy.grind.lintCommand });
+  }
+  if (policy.grind.enabled && policy.grind.testCommand && policy.grind.testCommand.length > 0) {
+    gates.push({ gate: "test", command: policy.grind.testCommand });
+  }
+  if (policy.docs.command && policy.docs.command.length > 0 && policy.docs.severity === "deny") {
+    gates.push({ gate: "docs", command: policy.docs.command });
+  }
+  return gates;
+}
+
+function runStreaming(
+  command: string[],
+  cwd: string,
+  echo: boolean,
+): Promise<{ exitCode: number; output: string; durationMs: number }> {
+  const started = Date.now();
+  const [file, ...args] = command;
+  return new Promise((resolve) => {
+    let output = "";
+    const keep = (chunk: Buffer, sink: NodeJS.WriteStream) => {
+      if (echo) {
+        sink.write(chunk);
+      }
+      output = (output + chunk.toString("utf8")).slice(-OUTPUT_KEEP_CHARS);
+    };
+    const child = spawn(file ?? "", args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+    child.stdout.on("data", (chunk: Buffer) => keep(chunk, process.stdout));
+    child.stderr.on("data", (chunk: Buffer) => keep(chunk, process.stderr));
+    child.on("error", (error) => {
+      resolve({ exitCode: 127, output: `${output}\n${error.message}`, durationMs: Date.now() - started });
+    });
+    child.on("close", (code) => {
+      resolve({ exitCode: code ?? 1, output, durationMs: Date.now() - started });
+    });
+  });
+}
+
+export async function verify(args: {
+  root: string;
+  cwd: string;
+  gates: VerifyGate[];
+  echo?: boolean;
+  log?: (line: string) => void;
+}): Promise<{ tree: string | null; outcomes: VerifyOutcome[] }> {
+  const log = args.log ?? ((line: string) => console.log(line));
+  const gitRoot = (await gitRootOf(args.cwd)) ?? args.cwd;
+  const outcomes: VerifyOutcome[] = [];
+  let tree = await workingTreeId(gitRoot);
+  for (const { gate, command } of args.gates) {
+    const before = tree;
+    log(`▸ ${gate}: ${command.join(" ")}`);
+    const result = await runStreaming(command, gitRoot, args.echo ?? true);
+    tree = await workingTreeId(gitRoot);
+    const treeChanged = before === null || tree !== before;
+    if (!treeChanged && before !== null) {
+      await coreFacade.gate.recordShipVerdict(args.root, {
+        gate,
+        command,
+        tree: before,
+        exitCode: result.exitCode,
+        durationMs: result.durationMs,
+        output: result.output,
+      });
+    }
+    outcomes.push({
+      gate,
+      command,
+      exitCode: result.exitCode,
+      durationMs: result.durationMs,
+      recorded: !treeChanged,
+      treeChanged,
+    });
+    log(
+      `${result.exitCode === 0 ? "✔" : "✖"} ${gate} — exit ${result.exitCode} in ${Math.round(result.durationMs / 1000)}s`,
+    );
+    if (result.exitCode !== 0) {
+      break;
+    }
+  }
+  return { tree, outcomes };
+}
+
+export async function main(argv: string[]): Promise<void> {
+  const { json } = takeJsonFlag(argv);
+  const root = process.env.TLC_PROJECT_DIR ?? findProjectRoot(process.cwd()) ?? process.cwd();
+  const policy = coreFacade.policy.loadPolicy(root);
+  const gates = gatesToVerify(policy);
+  if (gates.length === 0) {
+    const message = "verify: no lint, test or docs gate is configured — nothing to verify";
+    if (json) {
+      emitJson({ tree: null, outcomes: [], message });
+    } else {
+      console.log(message);
+    }
+    return;
+  }
+  const { tree, outcomes } = await verify({
+    root,
+    cwd: process.cwd(),
+    gates,
+    echo: !json,
+    ...(json ? { log: (line: string) => console.error(line) } : {}),
+  });
+  const failed = outcomes.find((outcome) => outcome.exitCode !== 0);
+  const changed = outcomes.find((outcome) => outcome.treeChanged);
+  if (json) {
+    emitJson({ tree, outcomes });
+  } else if (failed) {
+    console.log(`verify: ${failed.gate} failed — fix it and run \`tlc harness verify\` again`);
+  } else if (changed) {
+    console.log(
+      `verify: ${changed.gate} changed files while it ran, so its result describes a tree that no longer exists — review the changes and run \`tlc harness verify\` again`,
+    );
+  } else {
+    console.log(`verify: all gates passed for tree ${tree?.slice(0, 12)} — commit, push and PR may proceed`);
+  }
+  process.exit(failed || changed ? 1 : 0);
+}
+
+if (import.meta.main) {
+  await main(process.argv.slice(2));
+}