@tech-leads-club/harness-toolkit 0.16.5 → 0.16.7

package/docs/diagnose.md

@@ -68,6 +68,14 @@ reports can be matched to the invocation that produced 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.5",
+  "version": "0.16.7",
   "type": "module",
   "description": "Multi-provider agent steering: gates, follow-up, handoff, policy",
   "keywords": [

package/src/core/core.facade.ts

@@ -56,6 +56,12 @@ 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,
+  VERIFY_SOURCE,
+} from "./gate/gate.verdicts.ts";
 import {
   clearStuckSignals,
   handoffInjectable,
@@ -317,6 +323,10 @@ export const coreFacade = {
     isRecipeRunner,
     isCommandResolutionFailure,
     filesFromOutput,
+    findShipVerdict,
+    lastShipVerdictFor,
+    recordShipVerdict,
+    VERIFY_SOURCE,
   },
   stagnation: {
     computeFingerprint,

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

@@ -0,0 +1,107 @@
+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 const VERIFY_SOURCE = "verify";
+
+export type ShipVerdict = {
+  gate: string;
+  command: string[];
+  tree: string;
+  passed: boolean;
+  exitCode: number;
+  durationMs: number;
+  outputTail: string;
+  at: string;
+  timedOut?: boolean;
+  source?: 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,
+  sources?: readonly string[],
+): ShipVerdict | null {
+  const matches = readShipVerdicts(root).filter(
+    (verdict) =>
+      verdict.timedOut !== true &&
+      (sources === undefined || (verdict.source !== undefined && sources.includes(verdict.source))) &&
+      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 && input.timedOut !== true,
+    exitCode: input.exitCode,
+    durationMs: input.durationMs,
+    outputTail: trimOutputTail(input.output),
+    at: input.at ?? new Date().toISOString(),
+    ...(input.timedOut === true ? { timedOut: true } : {}),
+    ...(input.source !== undefined ? { source: input.source } : {}),
+  };
+  const path = shipVerdictsPath(root);
+  await updateJsonAtomic<ShipVerdictFile>(
+    path,
+    (current) => {
+      const kept = (current?.verdicts ?? []).filter(
+        (existing) =>
+          !(
+            existing.gate === verdict.gate &&
+            existing.tree === verdict.tree &&
+            existing.source === verdict.source &&
+            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,72 @@ 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 requiredShipGates(
+  policy: HandlerContext["policy"],
+  scope: { codeTargets: string[]; testTargets: string[] },
+): Array<{ gate: string; command: string[] }> {
+  const required: Array<{ gate: string; command: string[] }> = [];
+  const changedCode = scope.codeTargets.length > 0;
+  if (policy.grind.enabled && policy.grind.lintCommand && changedCode) {
+    required.push({ gate: "lint", command: policy.grind.lintCommand });
+  }
+  if (policy.grind.enabled && policy.grind.testCommand && (changedCode || scope.testTargets.length > 0)) {
+    required.push({ gate: "test", command: policy.grind.testCommand });
+  }
+  if (policy.docs.command && policy.docs.command.length > 0 && policy.docs.severity === "deny") {
+    required.push({ gate: "docs", command: policy.docs.command });
+  }
+  return required;
+}
+
+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 +141,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 +155,14 @@ export async function shipGateVerdict(event: HarnessEvent, ctx: HandlerContext):
     };
   }
 
-  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,
-      };
-    }
-  }
-
-  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,
-      };
-    }
-  }
-
-  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,
-      };
+  const required = requiredShipGates(policy, scope);
+  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";
@@ -134,7 +135,8 @@ function recordGateDeferred(args: {
  */
 export type GateRun =
   | { kind: "ran"; artifact: LastGateArtifact; reused: boolean }
-  | { kind: "deferred"; holder: string };
+  | { kind: "deferred"; holder: string }
+  | { kind: "slow"; estimateMs: number; budgetMs: number };
 
 /**
  * hazard: `GATE_LOCK_WAIT_MS` is 120 000 and the Stop hook is registered with `timeoutSeconds: 120`, so waiting
@@ -143,6 +145,15 @@ export type GateRun =
  */
 export const STOP_LOCK_WAIT_MS = 10_000;
 
+export const STOP_GATE_BUDGET_MS = 90_000;
+
+const TIMED_OUT_HEADROOM = 1.25;
+
+export function stopGateBudgetMs(env: NodeJS.ProcessEnv = process.env): number {
+  const declared = Number(env.TLC_TEST_STOP_GATE_BUDGET_MS);
+  return Number.isFinite(declared) && declared > 0 ? declared : STOP_GATE_BUDGET_MS;
+}
+
 /**
  * why: a test that proves the wait has to wait, and a suite that pays ten seconds for it pays that on every gate
  * run in every environment. This is the only seam and it is read here, so the production default is a constant
@@ -191,19 +202,7 @@ async function creditPendingLessons(args: {
  * ([/decisions/ad-116.md](/decisions/ad-116.md)) can ask the identical question `stop` asks — same lock, same
  * content-hash cache, same observability. A second implementation is the drift AD-071 already named once.
  */
-export async function runLockedGate(args: {
-  root: string;
-  shaRoot: string;
-  provider: string;
-  session: string;
-  gate: "lint" | "test" | "docs";
-  command: string[];
-  argvFiles: string[];
-  recordFiles: string[];
-  sessionKey: string;
-  policy: Policy;
-  pendingCredit: PendingLessonCredit | undefined;
-}): Promise<GateRun> {
+export async function runLockedGate(args: LockedGateArgs): Promise<GateRun> {
   const command = [...args.command, ...args.argvFiles];
   // why: `args.recordFiles`/`args.argvFiles` are the turn's changed files, resolved against `shaRoot` — the
   // same split AD-129 already applied to diffing. Hashing or running against `args.root` instead reads a
@@ -217,28 +216,30 @@ export async function runLockedGate(args: {
   );
 
   let artifact: LastGateArtifact;
+  let reused = cached !== null;
+  const tree = cached === null ? await workingTreeId(args.shaRoot) : null;
+  const recorded = recordedVerdictFor(args, tree);
   if (cached !== null) {
     artifact = cached;
+  } else if (recorded !== null) {
+    reused = true;
+    artifact = writeArtifact(args, command, inputs, {
+      exitCode: recorded.exitCode,
+      durationMs: recorded.durationMs,
+      output: recorded.outputTail,
+    });
   } else {
+    const slow = overBudget(args);
+    if (slow !== null) {
+      return slow;
+    }
+    let ran: LastGateArtifact | { timedOutAfterMs: number };
     try {
-      artifact = await coreFacade.gate.withGateLock(
+      ran = await coreFacade.gate.withGateLock(
         args.root,
         args.provider,
         args.session,
-        async () => {
-          const result = await runCommand(args.shaRoot, args.command, args.argvFiles);
-          return coreFacade.gate.writeLastGate({
-            root: args.root,
-            sessionKey: args.sessionKey,
-            gate: args.gate,
-            exitCode: result.exitCode,
-            command,
-            files: args.recordFiles,
-            durationMs: result.durationMs,
-            output: result.output,
-            ...(inputs.complete ? { inputsHash: inputs.hash } : {}),
-          });
-        },
+        () => runAndRecord(args, command, inputs, tree),
         { waitMs: stopLockWaitMs() },
       );
     } catch (error) {
@@ -251,10 +252,14 @@ export async function runLockedGate(args: {
       recordGateDeferred({ ...args, holder });
       return { kind: "deferred", holder };
     }
+    if ("timedOutAfterMs" in ran) {
+      return { kind: "slow", estimateMs: ran.timedOutAfterMs, budgetMs: ran.timedOutAfterMs };
+    }
+    artifact = ran;
   }
 
   // invariant: recorded outside the lock. A measurement must not widen the window in which one gate blocks another.
-  recordGateOutcome({ ...args, artifact, reused: cached !== null });
+  recordGateOutcome({ ...args, artifact, reused });
   await observeGateForRules({ ...args, gate: args.gate, passed: artifact.passed });
   await creditPendingLessons({
     root: args.root,
@@ -264,7 +269,97 @@ export async function runLockedGate(args: {
     sessionKey: args.sessionKey,
     passed: artifact.passed,
   });
-  return { kind: "ran", artifact, reused: cached !== null };
+  return { kind: "ran", artifact, reused };
+}
+
+type LockedGateArgs = {
+  root: string;
+  shaRoot: string;
+  provider: string;
+  session: string;
+  gate: "lint" | "test" | "docs";
+  command: string[];
+  argvFiles: string[];
+  recordFiles: string[];
+  sessionKey: string;
+  policy: Policy;
+  pendingCredit: PendingLessonCredit | undefined;
+  deadline?: number;
+};
+
+type GateInputs = ReturnType<typeof coreFacade.gate.computeInputsHash>;
+
+function recordedVerdictFor(args: LockedGateArgs, tree: string | null) {
+  if (tree === null) {
+    return null;
+  }
+  return coreFacade.gate.findShipVerdict(args.root, args.gate, args.command, tree, [
+    args.sessionKey,
+    coreFacade.gate.VERIFY_SOURCE,
+  ]);
+}
+
+function writeArtifact(
+  args: LockedGateArgs,
+  command: string[],
+  inputs: GateInputs,
+  result: { exitCode: number; durationMs: number; output: string },
+): LastGateArtifact {
+  return coreFacade.gate.writeLastGate({
+    root: args.root,
+    sessionKey: args.sessionKey,
+    gate: args.gate,
+    exitCode: result.exitCode,
+    command,
+    files: args.recordFiles,
+    durationMs: result.durationMs,
+    output: result.output,
+    ...(inputs.complete ? { inputsHash: inputs.hash } : {}),
+  });
+}
+
+function overBudget(args: LockedGateArgs): GateRun | null {
+  if (args.deadline === undefined) {
+    return null;
+  }
+  const last = coreFacade.gate.lastShipVerdictFor(args.root, args.gate, args.command);
+  const needed = last?.timedOut === true ? last.durationMs * TIMED_OUT_HEADROOM : last?.durationMs;
+  const budgetMs = args.deadline - Date.now();
+  if (budgetMs > 0 && (needed === undefined || needed < budgetMs)) {
+    return null;
+  }
+  return { kind: "slow", estimateMs: last?.durationMs ?? 0, budgetMs: Math.max(0, budgetMs) };
+}
+
+async function runAndRecord(
+  args: LockedGateArgs,
+  command: string[],
+  inputs: GateInputs,
+  tree: string | null,
+): Promise<LastGateArtifact | { timedOutAfterMs: number }> {
+  const timeoutMs = args.deadline !== undefined ? Math.max(1, args.deadline - Date.now()) : undefined;
+  const result = await runCommand(
+    args.shaRoot,
+    args.command,
+    args.argvFiles,
+    timeoutMs !== undefined ? { timeoutMs } : {},
+  );
+  if (tree !== null && (await workingTreeId(args.shaRoot)) === tree) {
+    await coreFacade.gate.recordShipVerdict(args.root, {
+      gate: args.gate,
+      command: args.command,
+      tree,
+      exitCode: result.exitCode,
+      durationMs: result.durationMs,
+      output: result.output,
+      source: args.sessionKey,
+      ...(result.timedOut ? { timedOut: true } : {}),
+    });
+  }
+  if (result.timedOut) {
+    return { timedOutAfterMs: result.durationMs };
+  }
+  return writeArtifact(args, command, inputs, result);
 }
 
 async function failGate(args: {
@@ -502,6 +597,8 @@ export const stopHandler: Handler = async (event: HarnessEvent, ctx: HandlerCont
    * says so once at the end instead of three times ([/decisions/ad-073.md](/decisions/ad-073.md)).
    */
   const deferred: string[] = [];
+  const slow: Array<{ gate: string; estimateMs: number }> = [];
+  const gateDeadline = ctx.now.getTime() + stopGateBudgetMs();
   const rawChangedFiles = await listChangedRepoFiles(shaRoot, turnBase);
   const otherSessionFiles = await coreFacade.presence.filesClaimedByOtherLiveSessions(
     root,
@@ -608,9 +705,12 @@ export const stopHandler: Handler = async (event: HarnessEvent, ctx: HandlerCont
         ? codeTargets
         : [],
       recordFiles: codeTargets,
+      deadline: gateDeadline,
     });
     if (run.kind === "deferred") {
       deferred.push(run.holder);
+    } else if (run.kind === "slow") {
+      slow.push({ gate: "lint", estimateMs: run.estimateMs });
     } else if (!run.artifact.passed) {
       return failGate({
         root,
@@ -646,9 +746,12 @@ export const stopHandler: Handler = async (event: HarnessEvent, ctx: HandlerCont
           ? testTargets
           : [],
         recordFiles,
+        deadline: gateDeadline,
       });
       if (run.kind === "deferred") {
         deferred.push(run.holder);
+      } else if (run.kind === "slow") {
+        slow.push({ gate: "test", estimateMs: run.estimateMs });
       } else if (!run.artifact.passed) {
         return failGate({
           root,
@@ -805,9 +908,12 @@ export const stopHandler: Handler = async (event: HarnessEvent, ctx: HandlerCont
       command: policy.docs.command,
       argvFiles: [],
       recordFiles: changedFiles,
+      deadline: gateDeadline,
     });
     if (run.kind === "deferred") {
       deferred.push(run.holder);
+    } else if (run.kind === "slow") {
+      slow.push({ gate: "docs", estimateMs: run.estimateMs });
     } else if (!run.artifact.passed) {
       if (policy.docs.severity === "deny") {
         return failGate({
@@ -980,6 +1086,24 @@ export const stopHandler: Handler = async (event: HarnessEvent, ctx: HandlerCont
    * `{"decision":"block"}`, so telling the turn would mean blocking it — the defect being fixed. `gate.outcome` is
    * a `why` kind, so `tlc harness why` answers it after the fact.
    */
+  if (slow.length > 0) {
+    const names = slow.map(({ gate }) => gate).join(" + ");
+    const longest = Math.max(...slow.map(({ estimateMs }) => estimateMs));
+    await coreFacade.handoff.patchHandoff(root, provider, sessionKey, {
+      slice: {
+        last_gate_result: "skipped",
+        next_action: "Run `tlc harness verify` and let it finish before ending the turn.",
+      },
+    });
+    return {
+      kind: "continue",
+      text: [
+        `BLOCKED: the ${names} gate needs longer than a stop hook may run, so this turn's changes are not verified yet.`,
+        `TRIED: ${longest > 0 ? `the last run took ${Math.round(longest / 1000)}s` : "it did not finish"}; the stop hook gives its gates ${Math.round(stopGateBudgetMs() / 1000)}s.`,
+        "NEED: run `tlc harness verify` in the shell and let it finish — give it a timeout long enough for the whole suite, or run it in the background and wait — then end the turn. Its verdict is reused here and at push.",
+      ].join("\n"),
+    };
+  }
   const holders = [...new Set(deferred)];
   await coreFacade.handoff.patchHandoff(root, provider, sessionKey, {
     slice: {