harnery 0.0.1 → 0.2.0

package/src/core/agents/rules/commit-conflict.ts

@@ -0,0 +1,303 @@
+/**
+ * Pre-commit E-guard verdict. The caller (typically a bash pre-commit hook)
+ * sends a JSON request with the staged paths, resolves its own instance_id
+ * via pid-map, and prints the verdict messages + exits with
+ * verdict.exit_code.
+ *
+ * Three outcomes:
+ *   1. allow (no conflicts): exit 0.
+ *   2. allow + suppressed (self-attribution heuristic: holder's files ⊆
+ *      staged set AND no live foreign pid anchors them): exit 0, prints
+ *      "treating as self under transient identity".
+ *   3. block: exit 1, prints "Commit blocked by multi-agent coordination".
+ *
+ * `bypass: true` flips conflict → allow + warning lines (the
+ * `HARNERY_AGENT_COORD_BYPASS=1` escape hatch).
+ *
+ * Gitlink discrimination: a parent-repo staged submodule path is a pointer
+ * bump, NOT a claim on the submodule's contents. The caller supplies
+ * `staged_gitlinks[]` (cheap to compute via `git ls-files --stage`); paths
+ * in that set are matched with the staged-is-gitlink rule.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { coordEnv } from "../../../lib/env.ts";
+
+const DEFAULT_FRESHNESS_SECS = 600;
+
+interface PeerHeartbeat {
+  instance_id: string;
+  session_id?: string;
+  name?: string;
+  files_touched?: string[];
+  last_heartbeat?: string;
+}
+
+interface Conflict {
+  /** Staged path that triggered the match. */
+  staged_path: string;
+  /** The peer's claimed path (may be a parent/child of staged_path). */
+  claimed_path: string;
+  /** Peer's instance_id. */
+  instance_id: string;
+  /** Peer's display name (or first 8 chars of instance_id). */
+  short_name: string;
+}
+
+export interface CommitVerdictRequest {
+  instance_id: string;
+  /** Group key. Subagents inherit parent's session_id. */
+  session_id: string;
+  /** Canonical monorepo-relative paths. */
+  staged_paths: string[];
+  /** Paths in `staged_paths` that resolve to submodule gitlinks (mode 160000)
+   * in the index. Used for gitlink-discrimination prefix matching. */
+  staged_gitlinks?: string[];
+  /** `HARNERY_AGENT_COORD_BYPASS=1` was set. Conflicts become warnings, not blocks. */
+  bypass?: boolean;
+}
+
+export interface CommitVerdictResult {
+  allow: boolean;
+  exit_code: number;
+  rule: string;
+  /** Conflict details (for the caller to print). */
+  conflicts: Conflict[];
+  /** Path-specific gates that fired (for `coord_log` lines). */
+  log_lines: string[];
+  /** Human-readable header for printing. */
+  message: string;
+  /** When true, conflicts were detected but suppressed (self-attribution). */
+  suppressed_self_attribution?: boolean;
+}
+
+export function evaluateCommit(coordRoot: string, req: CommitVerdictRequest): CommitVerdictResult {
+  if (req.staged_paths.length === 0) {
+    return {
+      allow: true,
+      exit_code: 0,
+      rule: "commit.pass",
+      conflicts: [],
+      log_lines: [],
+      message: "",
+    };
+  }
+
+  const peers = readActivePeers(coordRoot);
+  const cutoffMs = Date.now() - freshnessSecs() * 1000;
+  const stagedSet = new Set(req.staged_paths);
+  const gitlinkSet = new Set(req.staged_gitlinks ?? []);
+
+  const conflicts: Conflict[] = [];
+  for (const peer of peers) {
+    if (peer.instance_id === req.instance_id) continue;
+    const peerSession = peer.session_id ?? peer.instance_id;
+    if (req.session_id && peerSession === req.session_id) continue; // same group
+    const ts = peer.last_heartbeat ? Date.parse(peer.last_heartbeat) : 0;
+    if (!Number.isFinite(ts) || ts < cutoffMs) continue; // stale
+    const files = peer.files_touched ?? [];
+    if (files.length === 0) continue;
+
+    for (const staged of req.staged_paths) {
+      const stagedIsGitlink = gitlinkSet.has(staged);
+      const hit = findOverlap(staged, files, coordRoot, stagedIsGitlink);
+      if (!hit) continue;
+      conflicts.push({
+        staged_path: staged,
+        claimed_path: hit,
+        instance_id: peer.instance_id,
+        short_name: shortName(peer),
+      });
+      break; // one conflict per peer is enough
+    }
+  }
+
+  if (conflicts.length === 0) {
+    return {
+      allow: true,
+      exit_code: 0,
+      rule: "commit.pass",
+      conflicts: [],
+      log_lines: [],
+      message: "",
+    };
+  }
+
+  if (req.bypass) {
+    return {
+      allow: true,
+      exit_code: 0,
+      rule: "commit.bypass",
+      conflicts,
+      log_lines: conflicts.map(
+        (c) => `COMMIT_BYPASSED  path=${c.staged_path} owner=${c.short_name}`,
+      ),
+      message:
+        "⚠ Multi-Agent coordination: bypass active; staged paths claimed by other agents will be committed anyway:",
+    };
+  }
+
+  // Self-attribution check (Fix #2): if every conflicting holder is plausibly
+  // us under a transient identity (held files_touched ⊆ the staged set AND no
+  // live foreign PID anchors the holder via pid-map), suppress the block.
+  const allSelfAttributed = conflicts.every((c) =>
+    isHolderSelfAttributed(coordRoot, c.instance_id, stagedSet, peers),
+  );
+  if (allSelfAttributed) {
+    return {
+      allow: true,
+      exit_code: 0,
+      rule: "commit.suppressed",
+      conflicts,
+      log_lines: conflicts.map(
+        (c) =>
+          `COMMIT_SUPPRESSED  path=${c.staged_path} owner=${c.short_name} reason=self_attribution`,
+      ),
+      message:
+        "⚠ Multi-Agent coordination: self-attribution detected; staged paths\n" +
+        "  are claimed by an unanchored heartbeat that holds only files in\n" +
+        "  this commit's staged set. Treating as self under a transient\n" +
+        "  identity; commit will proceed.",
+      suppressed_self_attribution: true,
+    };
+  }
+
+  return {
+    allow: false,
+    exit_code: 1,
+    rule: "commit.conflict",
+    conflicts,
+    log_lines: conflicts.map((c) => `COMMIT_BLOCKED  path=${c.staged_path} owner=${c.short_name}`),
+    message:
+      "✗ Commit blocked by multi-agent coordination (E guard).\n\n" +
+      "  The following staged paths are currently claimed by other\n" +
+      "  active agents:",
+  };
+}
+
+function findOverlap(
+  staged: string,
+  files: readonly string[],
+  coordRoot: string,
+  stagedIsGitlink: boolean,
+): string | null {
+  for (const claimed of files) {
+    if (claimed === staged) return claimed;
+    if (claimed.startsWith(`${staged}/`)) {
+      // Staged is a submodule gitlink, claimed is a file inside it. Disjoint.
+      if (stagedIsGitlink) continue;
+      return claimed;
+    }
+    if (staged.startsWith(`${claimed}/`)) {
+      // Claimed is a gitlink, staged is a file inside it. Disjoint.
+      if (isGitlinkInIndex(coordRoot, claimed)) continue;
+      return claimed;
+    }
+  }
+  return null;
+}
+
+function isGitlinkInIndex(coordRoot: string, path: string): boolean {
+  const result = spawnSync("git", ["ls-files", "--stage", "--", path], {
+    cwd: coordRoot,
+    encoding: "utf8",
+    timeout: 2000,
+  });
+  if (result.status !== 0) return false;
+  // ls-files --stage emits "<mode> <sha> <stage>\t<path>"; mode 160000 = gitlink.
+  return result.stdout.trim().startsWith("160000 ");
+}
+
+function isHolderSelfAttributed(
+  coordRoot: string,
+  holderId: string,
+  stagedSet: Set<string>,
+  peers: readonly PeerHeartbeat[],
+): boolean {
+  // Gate B (cheaper): live foreign pid-map entry blocks self-attribution.
+  if (holderHasLiveForeignPid(coordRoot, holderId)) return false;
+
+  // Gate A: every held path is either in the staged set or already clean in HEAD.
+  const holder = peers.find((p) => p.instance_id === holderId);
+  if (!holder) return false;
+  const files = holder.files_touched ?? [];
+  if (files.length === 0) return false;
+  for (const held of files) {
+    if (stagedSet.has(held)) continue;
+    if (isPathCleanInHead(coordRoot, held)) continue;
+    return false;
+  }
+  return true;
+}
+
+function holderHasLiveForeignPid(coordRoot: string, holderId: string): boolean {
+  const dir = join(coordRoot, ".harnery", "pid-map");
+  if (!existsSync(dir)) return false;
+  for (const f of readdirSync(dir)) {
+    let row = "";
+    try {
+      row = readFileSync(join(dir, f), "utf8").trim();
+    } catch {
+      continue;
+    }
+    const owner = row.split("\t")[0]?.trim() ?? "";
+    if (owner !== holderId) continue;
+    // Process still alive?
+    const pid = Number.parseInt(f, 10);
+    if (!Number.isFinite(pid)) continue;
+    try {
+      process.kill(pid, 0); // signal 0 = liveness probe
+      return true; // live foreign pid found
+    } catch {
+      // ESRCH (no such process): pid-map entry is stale, skip
+    }
+  }
+  return false;
+}
+
+function isPathCleanInHead(coordRoot: string, relPath: string): boolean {
+  // Path is tracked + diff-clean against HEAD = "already committed, holder
+  // hasn't released the claim yet". Counts as self-attributable.
+  const tracked = spawnSync("git", ["ls-files", "--error-unmatch", "--", relPath], {
+    cwd: coordRoot,
+    encoding: "utf8",
+    timeout: 2000,
+  });
+  if (tracked.status !== 0) return false;
+  const diff = spawnSync("git", ["diff", "--quiet", "HEAD", "--", relPath], {
+    cwd: coordRoot,
+    encoding: "utf8",
+    timeout: 2000,
+  });
+  return diff.status === 0;
+}
+
+function readActivePeers(coordRoot: string): PeerHeartbeat[] {
+  const dir = join(coordRoot, ".harnery", "active");
+  if (!existsSync(dir)) return [];
+  const out: PeerHeartbeat[] = [];
+  for (const f of readdirSync(dir)) {
+    if (!f.endsWith(".json")) continue;
+    try {
+      const hb = JSON.parse(readFileSync(join(dir, f), "utf8")) as PeerHeartbeat;
+      if (hb.instance_id) out.push(hb);
+    } catch {
+      /* skip */
+    }
+  }
+  return out;
+}
+
+function freshnessSecs(): number {
+  const raw = coordEnv("AGENT_FRESHNESS");
+  if (!raw) return DEFAULT_FRESHNESS_SECS;
+  const n = Number.parseInt(raw, 10);
+  return Number.isFinite(n) && n > 0 ? n : DEFAULT_FRESHNESS_SECS;
+}
+
+function shortName(peer: PeerHeartbeat): string {
+  if (peer.name && peer.name.length > 0) return `agent-${peer.name}`;
+  return `agent-${peer.instance_id.slice(0, 8)}`;
+}

package/src/core/agents/rules/stop-hook.ts

@@ -0,0 +1,229 @@
+/**
+ * Stop-hook verdict: rule 1/3, 2/3, 3/3 enforcement evaluated
+ * from the canonical event stream alone (no transcript scan).
+ *
+ * Rule 1/3: `state.status_checked` event with matching turn boundary exists.
+ * Rule 2/3: latest `turn.stop` event has `status_box_present: true` (or the
+ *            stop currently firing carries that field via the in-flight event
+ *            agent-hook emits before the stop hook runs).
+ * Rule 3/3: `state.task_set` event with matching turn boundary exists.
+ *
+ * Pure-prose-turn exemption: when zero `tool.pre_use` events fire in
+ * the current turn, rules 1/3 and 3/3 do not apply. Rule 2/3 still applies
+ * as a user-visible mobile cue.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { resolveBinName } from "../../config.ts";
+
+export type VerdictResult = {
+  allow: boolean;
+  exit_code: 0 | 2;
+  rule: string;
+  reason?: string;
+};
+
+interface CanonicalEvent {
+  event_id: string;
+  event_type: string;
+  ts: string;
+  instance_id: string;
+  session_id: string;
+  turn_id?: string;
+  harness: string;
+  source: string;
+  data: Record<string, unknown>;
+}
+
+export interface StopHookRequest {
+  rule: "stop-hook";
+  instance_id: string;
+  session_id?: string;
+  /** Firing harness. Selects the end-of-turn ack signal (see `ackSignalFor`).
+   * Undefined → Claude Code semantics (transcript-scanned status box). */
+  harness?: string;
+  /** Wall-clock cutoff for the current turn; events strictly after this are not yet relevant. */
+  now_ms?: number;
+  /** Override the turn-window discovery (used by tests). */
+  turn_window?: { start_ms: number; end_ms: number };
+  /** Bypass switch: operator escape hatch identical to HARNERY_AGENT_COORD_BYPASS_STOP. */
+  bypass?: boolean;
+}
+
+/**
+ * The end-of-turn "I surfaced my status" signal, detected differently per
+ * harness because the ritual's *goal* (status visible to the human) is reached
+ * by different means:
+ *
+ * - **Claude Code / Codex** collapse tool calls in the UI, so the human-visible
+ *   signal is the verbatim status-box paste in the reply (rule 2/3, detected
+ *   by scanning the transcript for the `┌─ agent-` prefix, `status_box_present`
+ *   on `turn.stop`).
+ * - **Cursor** renders Shell output inline, so simply *running* `harn agents
+ *   status` (which emits `state.status_checked`) already puts the box on
+ *   screen. The separate paste is redundant, and undetectable anyway, since
+ *   Cursor's stop payload carries neither a transcript path nor the assistant
+ *   message. So rule 1/3 *is* the ack signal on Cursor; rule 2/3 collapses into
+ *   it rather than being a second requirement.
+ *
+ * This is why the fix is not "relax 2/3 because we can't see it": it's "2/3
+ * and 1/3 are two detections of the same thing, and Cursor's inline UI makes
+ * 1/3 the right one." The enforcement *channel* (exit-2+stderr vs Cursor's
+ * `followup_message`) is handled separately in hooks/harness/output.ts.
+ */
+type AckSignal = "status_box_present" | "status_checked";
+
+function ackSignalFor(harness?: string): AckSignal {
+  return harness === "cursor" ? "status_checked" : "status_box_present";
+}
+
+const RECENT_EVENT_WINDOW_LINES = 5_000;
+
+/**
+ * Evaluate the Stop-hook verdict. Returns the first failing rule (or allow
+ * when all three pass). Soft-fails open when the event stream isn't
+ * readable, fail-open posture on a verdict failure.
+ */
+export function evaluateStopHook(coordRoot: string, req: StopHookRequest): VerdictResult {
+  if (req.bypass) {
+    return {
+      allow: true,
+      exit_code: 0,
+      rule: "stop-hook.bypass",
+      reason: "HARNERY_AGENT_COORD_BYPASS_STOP=1",
+    };
+  }
+
+  let events: CanonicalEvent[];
+  try {
+    events = readRecentEvents(coordRoot, RECENT_EVENT_WINDOW_LINES);
+  } catch {
+    return {
+      allow: true,
+      exit_code: 0,
+      rule: "stop-hook.fail_open",
+      reason: "events.ndjson not readable; failing open",
+    };
+  }
+
+  const ownerEvents = events.filter((e) => e.instance_id === req.instance_id);
+  if (ownerEvents.length === 0) {
+    return {
+      allow: true,
+      exit_code: 0,
+      rule: "stop-hook.no_history",
+      reason: "no canonical events for this owner; defer to legacy or skip",
+    };
+  }
+
+  // Turn window: from the most recent user_prompt.submit (this owner) up to
+  // either the explicit now_ms or the last event we see. Fall back to a
+  // 5-minute window when no user_prompt.submit is in scope (fresh wiring,
+  // out-of-window prompt, etc.) so a stale stream doesn't silently pass.
+  const nowMs = req.now_ms ?? Date.now();
+  const lastUserPrompt = [...ownerEvents]
+    .reverse()
+    .find((e) => e.event_type === "user_prompt.submit");
+  const startMs = lastUserPrompt ? Date.parse(lastUserPrompt.ts) : nowMs - 5 * 60 * 1000;
+
+  const inTurn = ownerEvents.filter((e) => {
+    const t = Date.parse(e.ts);
+    return Number.isFinite(t) && t >= startMs && t <= nowMs;
+  });
+
+  const toolPreUseInTurn = inTurn.some((e) => e.event_type === "tool.pre_use");
+  const statusChecked = inTurn.some((e) => e.event_type === "state.status_checked");
+  const taskSet = inTurn.some((e) => e.event_type === "state.task_set");
+
+  // Rule 2/3: status_box_present on the most recent turn.stop for this owner.
+  // The turn.stop event fires from agent-hook stop, which is wired BEFORE
+  // the stop-hook verdict, so by the time we evaluate, the just-
+  // fired turn.stop is already in the stream.
+  const latestTurnStop = [...inTurn].reverse().find((e) => e.event_type === "turn.stop");
+  const boxPresent = latestTurnStop ? Boolean(latestTurnStop.data.status_box_present) : false;
+
+  // Harness-aware end-of-turn ack signal (see `ackSignalFor`). On Cursor the
+  // ack is `status_checked` (running `harn agents status` shows the box inline);
+  // on Claude Code / Codex it's the transcript-scanned `status_box_present`.
+  // The matching block helper carries the right "how to fix" message.
+  const ackSignal = ackSignalFor(req.harness);
+  const ackPresent = ackSignal === "status_checked" ? statusChecked : boxPresent;
+  const ackBlock = ackSignal === "status_checked" ? rule13Block : rule23Block;
+
+  // Pure-prose-turn exemption: only the ack signal applies. Parity
+  // across harnesses: CC requires the box; Cursor requires status_checked.
+  if (!toolPreUseInTurn) {
+    if (!ackPresent) {
+      return ackBlock();
+    }
+    return {
+      allow: true,
+      exit_code: 0,
+      rule: "stop-hook.pure_prose_pass",
+      reason: "no tool calls this turn; rules 1/3 + 3/3 skipped",
+    };
+  }
+
+  if (!statusChecked) return rule13Block();
+  // On Cursor `ackPresent === statusChecked` (already true here), so this is a
+  // no-op and rule 2/3 is not enforced; on CC/Codex it's the box-paste check.
+  if (!ackPresent) return ackBlock();
+  if (!taskSet) return rule33Block();
+
+  return {
+    allow: true,
+    exit_code: 0,
+    rule: "stop-hook.pass",
+  };
+}
+
+function rule13Block(): VerdictResult {
+  return {
+    allow: false,
+    exit_code: 2,
+    rule: "stop-hook.rule_1_3",
+    reason: `End-of-turn rule (1/3): no state.status_checked event found in this turn; run \`${resolveBinName()} agents status\` as your last tool call.`,
+  };
+}
+
+function rule23Block(): VerdictResult {
+  return {
+    allow: false,
+    exit_code: 2,
+    rule: "stop-hook.rule_2_3",
+    reason: `End-of-turn rule (2/3): turn.stop did not see the agent-status box in your reply text. Paste the \`${resolveBinName()} agents status\` output verbatim as a fenced code block (the \`┌─ agent-\` prefix is the detection signal).`,
+  };
+}
+
+function rule33Block(): VerdictResult {
+  return {
+    allow: false,
+    exit_code: 2,
+    rule: "stop-hook.rule_3_3",
+    reason: `End-of-turn rule (3/3): no state.task_set event found in this turn; run \`${resolveBinName()} agents set-task "<short focus>"\` to declare what you're working on. Pass an empty string if the turn was purely conversational.`,
+  };
+}
+
+/**
+ * Read the last N JSON lines from events.ndjson. The Stop-hook verdict needs
+ * just the most recent turn so we tail-read aggressively.
+ */
+function readRecentEvents(coordRoot: string, maxLines: number): CanonicalEvent[] {
+  const path = join(coordRoot, ".harnery", "events.ndjson");
+  if (!existsSync(path)) return [];
+  const raw = readFileSync(path, "utf8");
+  const lines = raw.split("\n");
+  const start = Math.max(0, lines.length - maxLines);
+  const out: CanonicalEvent[] = [];
+  for (let i = start; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line?.trim()) continue;
+    try {
+      out.push(JSON.parse(line) as CanonicalEvent);
+    } catch {
+      /* skip malformed */
+    }
+  }
+  return out;
+}