@tech-leads-club/harness-toolkit 0.14.2 → 0.15.1

package/src/entrypoints/run.ts

@@ -62,19 +62,55 @@ function errorMessage(error: unknown): string {
 }
 
 // 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 {
+function recordAdapterEvent(
+  root: string,
+  kind: string,
+  attrs: Record<string, unknown>,
+  provider = "unknown",
+  top: Record<string, unknown> = {},
+): void {
   try {
     appendRecord(join(projectStateDir(root), "obs.jsonl"), {
       schema: "harness.observability.v1",
-      provider: "unknown",
+      provider,
       kind,
       level: "signal",
       ts: new Date().toISOString(),
+      ...top,
       attrs,
     });
   } catch {}
 }
 
+// hazard: unscoped, one record per hook invocation of any kind flooded the signal plane and pushed
+// `prompt.submit`/`policy.deny` out of two readers' fixed-count tails ([/decisions/ad-136.md](/decisions/ad-136.md)).
+function isGateRelevantHookEvent(event: HarnessEvent): boolean {
+  return event.event === "shell.before" || event.event === "mcp.before";
+}
+
+/**
+ * AD-136 — a hook invocation that never reaches the point where any existing record gets written (the handler
+ * killed mid-flight, a host-side timeout) previously left nothing in `obs.jsonl` at all — indistinguishable
+ * from a hook that never started. This is the earliest point after an event is known: before `loadPolicy`,
+ * before `handler` runs, before anything that could throw or take time. A future incident reads as "entered,
+ * no paired completion" instead of being reconstructed from raw provider traces after the fact.
+ */
+function recordHookEnter(event: HarnessEvent): void {
+  if (!isGateRelevantHookEvent(event)) {
+    return;
+  }
+  recordAdapterEvent(
+    event.projectDir,
+    "hook.enter",
+    { event: event.event, toolName: event.toolName ?? "none", sessionKey: event.sessionKey },
+    event.provider,
+    {
+      trace_id: coreFacade.observability.deriveTraceId(event.sessionKey),
+      session_id: event.sessionKey,
+    },
+  );
+}
+
 /**
  * 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
@@ -155,6 +191,7 @@ export async function runHandler(handler: Handler, io: RunIo = {}): Promise<RunO
   }
 
   const capabilities = provider.capabilities();
+  recordHookEnter(event);
 
   try {
     const policy = coreFacade.policy.loadPolicy(event.projectDir);

package/src/entrypoints/session-start.ts

@@ -44,6 +44,7 @@ export const sessionStartHandler: Handler = async (
   });
 
   coreFacade.handoff.pruneDeadHandoffSessions(root);
+  coreFacade.gate.pruneGateSessions(root);
 
   await coreFacade.handoff.patchHandoff(root, event.provider, event.sessionKey, {
     shared: {

package/src/entrypoints/stop.ts

@@ -205,7 +205,11 @@ export async function runLockedGate(args: {
 }): Promise<GateRun> {
   const command = [...args.command, ...args.argvFiles];
   const inputs = coreFacade.gate.computeInputsHash(args.root, args.recordFiles, command);
-  const cached = coreFacade.gate.cachedVerdict(coreFacade.gate.readLastGate(args.root), args.gate, inputs);
+  const cached = coreFacade.gate.cachedVerdict(
+    coreFacade.gate.readLastGate(args.root, args.sessionKey),
+    args.gate,
+    inputs,
+  );
 
   let artifact: LastGateArtifact;
   if (cached !== null) {
@@ -220,6 +224,7 @@ export async function runLockedGate(args: {
           const result = await runCommand(args.root, args.command, args.argvFiles);
           return coreFacade.gate.writeLastGate({
             root: args.root,
+            sessionKey: args.sessionKey,
             gate: args.gate,
             exitCode: result.exitCode,
             command,
@@ -491,7 +496,14 @@ 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 changedFiles = await listChangedRepoFiles(shaRoot, turnBase);
+  const rawChangedFiles = await listChangedRepoFiles(shaRoot, turnBase);
+  const otherSessionFiles = await coreFacade.presence.filesClaimedByOtherLiveSessions(
+    root,
+    shaRoot,
+    provider,
+    sessionKey,
+  );
+  const changedFiles = rawChangedFiles.filter((file) => !otherSessionFiles.has(file));
   const codeTargets = filterCodeTargets(changedFiles, policy.codePaths);
   const testTargets = filterTestTargets(changedFiles);
   // why: the comment rail scopes by the syntax catalog (40+ languages), not `codeTargets`'s nine-extension

package/src/entrypoints/support.ts

@@ -108,7 +108,14 @@ export async function computeTurnScope(
   const seal = coreFacade.handoff.handoffInjectable(root, sessionKey);
   const handoff = seal.ok ? coreFacade.handoff.readHandoff(root, provider, sessionKey) : undefined;
   const turnBase = handoff?.turn_base_sha ?? "HEAD";
-  const changedFiles = await listChangedRepoFiles(gitRoot, turnBase);
+  const rawChangedFiles = await listChangedRepoFiles(gitRoot, turnBase);
+  const otherSessionFiles = await coreFacade.presence.filesClaimedByOtherLiveSessions(
+    root,
+    gitRoot,
+    provider,
+    sessionKey,
+  );
+  const changedFiles = rawChangedFiles.filter((file) => !otherSessionFiles.has(file));
   const codeTargets = filterCodeTargets(changedFiles, policy.codePaths);
   const testTargets = filterTestTargets(changedFiles);
   const commentScope = changedFiles.filter((file) =>

package/src/entrypoints/tool-before.ts

@@ -94,7 +94,12 @@ function recordShellDecisionIfShell(event: HarnessEvent, ctx: HandlerContext, de
  */
 async function rulesDecision(event: HarnessEvent, ctx: HandlerContext): Promise<Decision> {
   const config = ctx.policy.rules;
-  const trigger = { event: event.event, toolName: event.toolName, command: event.command };
+  const trigger = {
+    event: event.event,
+    toolName: event.toolName,
+    command: event.command,
+    toolInput: event.toolInput,
+  };
   const shaRoot = shaScopeRoot(event);
   const dryRun = coreFacade.rules.decideAction(event.projectDir, config, trigger, {
     sha: null,
@@ -110,7 +115,10 @@ async function rulesDecision(event: HarnessEvent, ctx: HandlerContext): Promise<
   // ([/decisions/ad-130.md](/decisions/ad-130.md)) — a CLI shape or an unrelated trigger never reads it.
   const [sha, repoRemote] = await Promise.all([
     currentGitSha(shaRoot),
-    event.command && coreFacade.rules.mentionsGhApi(event.command) ? localRepoRemote(shaRoot) : undefined,
+    (event.command && coreFacade.rules.mentionsGhApi(event.command)) ||
+    coreFacade.rules.mentionsMcpAct(event.toolName)
+      ? localRepoRemote(shaRoot)
+      : undefined,
   ]);
   const verdict = coreFacade.rules.decideAction(
     event.projectDir,

package/src/platform/paths.ts

@@ -132,6 +132,10 @@ export function handoffSessionsDir(root: string): string {
   return join(projectStateDir(root), "handoff-sessions");
 }
 
+export function gateSessionsDir(root: string): string {
+  return join(projectStateDir(root), "gate-sessions");
+}
+
 // why: inside the state directory on purpose — the baseline that proves the policy was not switched off
 // inherits the same protection as the policy itself.
 export function policyBaselineDir(root: string): string {

package/src/providers/cursor/cursor.inbound.ts

@@ -36,6 +36,27 @@ function asRecord(value: unknown): Record<string, unknown> | undefined {
     : undefined;
 }
 
+/**
+ * hazard: `beforeMCPExecution`'s own `tool_input` is documented as a JSON *string* ("JSON params string that
+ * will be passed to the tool"), not an object like `preToolUse`'s — `asRecord` alone left it `undefined` for
+ * every MCP call on this host, silently skipping any rule that reads `toolInput` fields
+ * ([/decisions/ad-135.md](/decisions/ad-135.md)).
+ */
+function mcpToolInput(value: unknown): Record<string, unknown> | undefined {
+  const direct = asRecord(value);
+  if (direct) {
+    return direct;
+  }
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  try {
+    return asRecord(JSON.parse(value));
+  } catch {
+    return undefined;
+  }
+}
+
 function asStatus(value: unknown): "completed" | "aborted" | "error" | undefined {
   return value === "completed" || value === "aborted" || value === "error" ? value : undefined;
 }
@@ -164,7 +185,7 @@ export function cursorToEvent(raw: Record<string, unknown>): HarnessEvent | null
       if (toolName) {
         event.toolName = toolName;
       }
-      const toolInput = asRecord(raw.tool_input);
+      const toolInput = mcpToolInput(raw.tool_input);
       if (toolInput) {
         event.toolInput = toolInput;
       }

package/tools/obs-cli.ts

@@ -2,7 +2,7 @@ import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from "nod
 import { join } from "node:path";
 import { coreFacade } from "../src/core/index.ts";
 import { readSignalEvents } from "../src/core/observability/observability.store.ts";
-import { DEFAULT_OBS, type ObsEvent } from "../src/core/observability/observability.types.ts";
+import { DEFAULT_OBS, LIVE_ALLOWLIST, type ObsEvent } from "../src/core/observability/observability.types.ts";
 import { loadPolicy } from "../src/core/policy/policy.loader.ts";
 import { emitJson, takeJsonFlag } from "../src/platform/cli-output.ts";
 import { projectStateDir } from "../src/platform/paths.ts";
@@ -31,6 +31,16 @@ export function limitFrom(raw: string | undefined, fallback: number): number {
   return Number.isFinite(parsed) ? parsed : fallback;
 }
 
+// hazard: filtering a tail already truncated to `limit` leaves a noise kind (`hook.enter`, one record per
+// gate-relevant hook call) able to push every allowlisted event out of the window the operator actually reads
+// — the window has to be read wide, filtered, then cut to `limit`, never the other order
+// ([/decisions/ad-136.md](/decisions/ad-136.md)).
+export function liveEvents(root: string, limit: number, readWide = 20): readonly ObsEvent[] {
+  const wide = readSignalEvents(root, DEFAULT_OBS.signalPath, Math.max(limit * readWide, limit));
+  const allowed = wide.filter((event) => LIVE_ALLOWLIST.has(event.kind));
+  return allowed.slice(-limit);
+}
+
 /**
  * hazard: this sorted by filename. A session id is a UUID, so alphabetical order has no relation to time — on
  * this machine it picked a session from thirteen days earlier whose every counter was zero, which reads exactly
@@ -67,7 +77,7 @@ function main(argv: string[]): void {
   const arg = rest[1];
 
   if (cmd === "live") {
-    const events = readSignalEvents(root, DEFAULT_OBS.signalPath, limitFrom(arg, 40));
+    const events = liveEvents(root, limitFrom(arg, 40));
     if (json) {
       emitJson(liveJson(events));
     } else {