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

package/README.md

@@ -485,6 +485,7 @@ See `tlc harness help architecture` or [`docs/architecture.md`](docs/architectur
 | `tlc harness help [topic]` | Docs |
 | `tlc harness build` | Compile `dist/` for the Node fallback path |
 | `tlc harness test` | Run the full local gate |
+| `tlc harness verify` | Run lint and tests on the current tree and record the verdict that push, PR open and merge read |
 | `tlc harness grind [on\|off]` | Lint/test follow-ups on stop |
 | `tlc harness pause` / `resume` | Circuit breaker: every hook steps aside except the floor / back on |
 | `tlc harness mode solo\|paired\|focus` | Operator posture |

package/bin/tlc-cli.ts

@@ -881,6 +881,7 @@ QUICK
   tlc harness uninstall            print what would be undone; --yes applies it, --purge includes state
   tlc harness build                compile dist/ for Node
   tlc harness test                 run the full local gate
+  tlc harness verify               run lint/tests on this tree; push and PR read the recorded verdict
   tlc harness help <topic>         documentation
 
 TOPICS
@@ -1203,6 +1204,8 @@ export function route(args: string[]): Action {
       return { kind: "version" };
     case "test":
       return { kind: "test" };
+    case "verify":
+      return { kind: "entry", entry: "verify", args: args.slice(1) };
     case "grind":
     case "g": {
       const arg = (args[1] ?? "on").toLowerCase();
@@ -1661,7 +1664,7 @@ async function main(argv: string[]): Promise<void> {
   if (group !== "harness") {
     console.error(`unknown: ${argv[0] ?? ""}`);
     console.error(
-      "usage: tlc harness <status|doctor|help|grind|pause|resume|reset|mode|obs|prices|lessons|init|update|test|build>",
+      "usage: tlc harness <status|doctor|help|grind|pause|resume|reset|mode|obs|prices|lessons|init|update|test|verify|build>",
     );
     process.exit(1);
   }

package/bin/tlc-exec.d.mts

@@ -59,3 +59,21 @@ export function decideRuntime(input: RuntimeDecisionInput): RuntimeDecision;
 
 export function main(argv?: string[]): void;
 export const HOOK_ENTRIES: Set<string>;
+
+export const HOOK_TRACE_MAX_BYTES: number;
+
+export function hookTracePath(harnessHome: string): string;
+
+export function appendHookTrace(harnessHome: string, record: Record<string, unknown>): void;
+
+export type HookIdentity =
+  | {
+      event?: string;
+      tool?: string;
+      tool_use_id?: string;
+      generation_id?: string;
+      conversation_id?: string;
+    }
+  | { parse_error: true };
+
+export function hookIdentity(input: Buffer): HookIdentity;

package/bin/tlc-exec.mjs

@@ -1,6 +1,16 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync, writeSync } from "node:fs";
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+  writeSync,
+} from "node:fs";
 import { homedir } from "node:os";
 import { delimiter, dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -191,6 +201,52 @@ function carryOn() {
   process.exit(0);
 }
 
+export const HOOK_TRACE_MAX_BYTES = 5 * 1024 * 1024;
+
+export function hookTracePath(harnessHome) {
+  return join(harnessHome, "state", "hook-trace.jsonl");
+}
+
+export function appendHookTrace(harnessHome, record) {
+  if (isPackagedCopy(harnessHome)) {
+    return;
+  }
+  try {
+    const path = hookTracePath(harnessHome);
+    mkdirSync(dirname(path), { recursive: true });
+    try {
+      if (statSync(path).size > HOOK_TRACE_MAX_BYTES) {
+        renameSync(path, `${path}.1`);
+      }
+    } catch {}
+    appendFileSync(path, `${JSON.stringify({ ts: new Date().toISOString(), pid: process.pid, ...record })}\n`);
+  } catch {}
+}
+
+export function hookIdentity(input) {
+  try {
+    const parsed = JSON.parse(input.toString("utf8"));
+    const pick = (key) => (typeof parsed?.[key] === "string" ? parsed[key] : undefined);
+    return {
+      event: pick("hook_event_name"),
+      tool: pick("tool_name"),
+      tool_use_id: pick("tool_use_id"),
+      generation_id: pick("generation_id"),
+      conversation_id: pick("conversation_id") ?? pick("session_id"),
+    };
+  } catch {
+    return { parse_error: true };
+  }
+}
+
+function readHookInput() {
+  try {
+    return { input: readFileSync(0) };
+  } catch (error) {
+    return { input: null, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
 export function decideRuntime({ harnessHome, entry, bunPath, nodeMajor, distExists, srcPath }) {
   const distPath = join(harnessHome, "dist", `${entry}.mjs`);
   if (bunPath && srcPath && distExists) {
@@ -236,8 +292,24 @@ export function decideRuntime({ harnessHome, entry, bunPath, nodeMajor, distExis
 
 function run(harnessHome, command, commandArgs, origin = harnessHome, entry = "") {
   const isHook = HOOK_ENTRIES.has(entry);
+  const started = Date.now();
+  const hookInput = isHook ? readHookInput() : { input: null };
+  if (isHook) {
+    appendHookTrace(harnessHome, {
+      phase: "start",
+      entry,
+      ppid: process.ppid,
+      cwd: process.cwd(),
+      node: process.version,
+      uptime_ms: Math.round(process.uptime() * 1000),
+      stdin_bytes: hookInput.input?.length ?? null,
+      stdin_error: hookInput.error,
+      ...(hookInput.input ? hookIdentity(hookInput.input) : {}),
+    });
+  }
   const result = spawnSync(command, commandArgs, {
-    stdio: isHook ? ["inherit", "pipe", "inherit"] : "inherit",
+    ...(hookInput.input ? { input: hookInput.input } : {}),
+    stdio: isHook ? [hookInput.input ? "pipe" : "inherit", "pipe", "inherit"] : "inherit",
     maxBuffer: 64 * 1024 * 1024,
     // why: `TLC_ORIGIN` is where this copy physically lives, which is not `TLC_HOME` once an npm-installed shim
     // is driving the runtime installed under the conventional path. `tlc harness install` needs the former as
@@ -254,6 +326,18 @@ function run(harnessHome, command, commandArgs, origin = harnessHome, entry = ""
     },
     shell: false,
   });
+  if (isHook) {
+    appendHookTrace(harnessHome, {
+      phase: "end",
+      entry,
+      ms: Date.now() - started,
+      status: result.status,
+      signal: result.signal,
+      spawn_error: result.error?.message,
+      stdout_bytes: result.stdout?.length ?? 0,
+      verdict: result.stdout?.toString("utf8").trim().slice(0, 60),
+    });
+  }
   if (result.error) {
     console.error(`tlc: failed to start ${command}: ${result.error.message}`);
     if (HOOK_ENTRIES.has(entry)) {
@@ -284,6 +368,14 @@ export function main(argv = process.argv) {
     console.error("  entry: session-start | tool-before | stop | doctor | ...");
     process.exit(2);
   }
+  if (HOOK_ENTRIES.has(entry)) {
+    process.on("uncaughtException", (error) => {
+      const detail = error instanceof Error ? (error.stack ?? error.message) : String(error);
+      appendHookTrace(harnessHome, { phase: "crash", entry, error: detail.slice(0, 500) });
+      console.error(`tlc: ${entry} launcher failed (${detail.split("\n")[0]}); carrying on without a verdict.`);
+      carryOn();
+    });
+  }
   const args = argv.slice(3);
 
   const nodeMajor = Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);