@tech-leads-club/harness-toolkit 0.3.4 → 0.3.6

package/docs/log.md

@@ -16,6 +16,7 @@ newest first. For what landed in which npm release, see `CHANGELOG.md` at the re
 ## 2026-08-20
 
 - **AD-098** — Splitting is reverted: a shared chunk ran the CLI's main ([/decisions/ad-098.md](/decisions/ad-098.md))
+- **AD-099** — Reading a file claimed it, so a review agent locked the operator out of writing ([/decisions/ad-099.md](/decisions/ad-099.md))
 
 ## 2026-08-19
 

package/package.json

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

package/src/contracts/index.ts

@@ -3,4 +3,5 @@ export * from "./decision.ts";
 export * from "./effort.ts";
 export * from "./harness-event.ts";
 export * from "./policy-defaults.ts";
+export * from "./tool-names.ts";
 export * from "./wiring.ts";

package/src/contracts/tool-names.ts

@@ -0,0 +1,25 @@
+/**
+ * The host tool names that write to a file.
+ *
+ * why here: two rails need the same answer — the policy-surface guard, which refuses an agent write to policy, and
+ * the presence claim, which decides whether another session may lose work. A second copy of this list is a second
+ * thing to forget when a host adds a tool ([/decisions/ad-010.md](/decisions/ad-010.md)).
+ *
+ * hazard: the presence claim did not consult any list. It recorded whatever file the event carried, and
+ * `read.before` carries one — so reading a file claimed it for ten minutes and blocked every other session from
+ * writing it, under a rule called `edit-collision` and a message that said the file had been edited. Measured on a
+ * real machine: a review agent that only read poisoned two files, and the operator's own `git status` showed one
+ * modification, theirs ([/decisions/ad-099.md](/decisions/ad-099.md)).
+ */
+export const WRITE_TOOLS: ReadonlySet<string> = new Set([
+  "Edit",
+  "Write",
+  "Delete",
+  "MultiEdit",
+  "NotebookEdit",
+]);
+
+/** invariant: an absent tool name is not a write. A read carries a path too, and only writes may claim one. */
+export function isWriteTool(toolName: string | undefined): boolean {
+  return toolName !== undefined && WRITE_TOOLS.has(toolName);
+}

package/src/core/policy/policy.guard.ts

@@ -1,16 +1,15 @@
 import type { Decision } from "../../contracts/decision.ts";
+import { isWriteTool } from "../../contracts/tool-names.ts";
 import { isPolicySurface } from "../floor/floor.paths.ts";
 
 export { isPolicySurface };
 
-const WRITE_TOOLS = new Set(["Edit", "Write", "Delete", "MultiEdit", "NotebookEdit"]);
-
 export function guardPolicySurface(args: {
   projectDir: string;
   toolName: string | undefined;
   filePath: string | undefined;
 }): Decision {
-  if (!args.toolName || !WRITE_TOOLS.has(args.toolName) || !args.filePath) {
+  if (!isWriteTool(args.toolName) || !args.filePath) {
     return { kind: "allow" };
   }
   if (!isPolicySurface(args.projectDir, args.filePath)) {

package/src/core/presence/presence.service.ts

@@ -81,10 +81,18 @@ export function checkCollision(
       continue;
     }
     const elapsed = elapsedLabel(record, nowMs);
+    /**
+     * hazard: this said "touched" and "edited this file" for a claim that a *read* could create, so the message
+     * asserted an edit that had not happened — and an operator checking `git status` found one modification, their
+     * own. Only a write claims now, and the words say so ([/decisions/ad-099.md](/decisions/ad-099.md)).
+     *
+     * invariant: the way out is named. `ask` becomes a refusal wherever no operator can answer the prompt, and a
+     * refusal with no exit is a lock-out.
+     */
     return {
       kind: "ask",
-      reason: `${record.provider} session ${record.session} touched ${file} ${elapsed}.`,
-      userNote: `Another agent (${record.provider}, session ${record.session}) edited this file ${elapsed}. Coordinate before proceeding.`,
+      reason: `${record.provider} session ${record.session} wrote ${file} ${elapsed}.`,
+      userNote: `Another agent (${record.provider}, session ${record.session}) wrote this file ${elapsed}. Coordinate before proceeding: end that session, or wait for its claim to go stale (10 minutes without a heartbeat). \`tlc harness status\` lists the live sessions.`,
       // why: this asks unconditionally, like the floor does, and carried no rule — so an operator reading a rate of
       // interruptions could see the count and not the cause.
       rule: "edit-collision",

package/src/entrypoints/run.ts

@@ -1,5 +1,6 @@
 import { join } from "node:path";
 import type { Decision, HarnessEvent, ProviderCapabilities, Rendered } from "../contracts/index.ts";
+import { isWriteTool } from "../contracts/tool-names.ts";
 import { coreFacade, type Policy } from "../core/index.ts";
 import { appendRecord } from "../platform/fs-jsonl.ts";
 import { projectStateDir } from "../platform/paths.ts";
@@ -36,6 +37,25 @@ export type RunOutcome = {
 // (lessons.maxCharsSession) — reusing that here truncated the operator posture and handoff.
 export const CONTEXT_BUDGET_CHARS = 6000;
 
+/**
+ * Whether this event may claim its file against other sessions.
+ *
+ * invariant: a claim exists so that two writers do not lose each other's work. A reader loses nothing, so a read
+ * carries no claim however many files it opens ([/decisions/ad-099.md](/decisions/ad-099.md)).
+ *
+ * why `edit.after` with no tool name still claims: the write already happened, and the host does not always name
+ * the tool on that event. An event that reports a completed edit is a writer by definition.
+ */
+export function claimsFile(event: HarnessEvent): boolean {
+  if (event.filePath === undefined) {
+    return false;
+  }
+  if (event.event === "edit.after") {
+    return true;
+  }
+  return isWriteTool(event.toolName);
+}
+
 function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
@@ -144,10 +164,20 @@ export async function runHandler(handler: Handler, io: RunIo = {}): Promise<RunO
         effectiveBlockedPatterns(policy.subagents.blockedPatterns, provider),
       );
     }
+    /**
+     * hazard: this passed `event.filePath` for every event, and `read.before` carries one. So reading a file
+     * claimed it for ten minutes, and the next session to write it was refused — under a rule called
+     * `edit-collision`, with a message saying the file had been edited. Measured on a real machine: a review agent
+     * that only read blocked the operator's own writes to two files, while their `git status` showed a single
+     * modification, theirs ([/decisions/ad-099.md](/decisions/ad-099.md)).
+     *
+     * invariant: the heartbeat is unconditional — a reading session is still a live session, and staleness is what
+     * expires a claim. Only the *claim* is write-only, because only a writer can lose somebody's work.
+     */
     coreFacade.presence.heartbeat(event.projectDir, {
       provider: event.provider,
       session: sessionIdFromKey(event),
-      file: event.filePath,
+      ...(claimsFile(event) ? { file: event.filePath } : {}),
       now,
     });
     const context: HandlerContext = { policy, capabilities, provider, now };