harnery 0.0.1 → 0.2.0

package/src/core/hooks/harness/output.ts

@@ -0,0 +1,100 @@
+/**
+ * Harness-aware hook output JSON. Each adapter target has its own protocol
+ * shape, so encode it once here so post-emit handlers don't have to branch on
+ * `harness` everywhere.
+ *
+ * Shapes (verified against live dispatchers + each harness's upstream hooks docs):
+ *
+ * - **Claude Code**: `{hookSpecificOutput: {hookEventName, additionalContext}}`
+ *   for SessionStart / UserPromptSubmit / SubagentStart; deny uses
+ *   `{hookSpecificOutput: {hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason}}`.
+ * - **Cursor**: `{additional_context, env?}` flat for sessionStart /
+ *   beforeSubmitPrompt; deny uses `{permission: "deny", agent_message, user_message}`.
+ * - **Codex**: structurally identical to Claude Code (confirmed by Phase 0
+ *   probe + the matching shape in the Codex harness adapter).
+ *
+ * Every helper writes to process.stdout + newline-terminates so callers can
+ * fire-and-forget. Empty text → no-op (no JSON written).
+ */
+
+import type { Harness } from "../events/schema.ts";
+
+export type SystemEvent = "SessionStart" | "UserPromptSubmit" | "SubagentStart";
+
+/** Emit a context-injection (peer table, wiring check, council pending, …). */
+export function emitContext(harness: Harness, event: SystemEvent, text: string): void {
+  if (!text || text.length === 0) return;
+  const json = buildContextJson(harness, event, text);
+  process.stdout.write(`${JSON.stringify(json)}\n`);
+}
+
+/** Emit a PreToolUse deny: blocks the tool call with `reason` shown to the model. */
+export function emitDeny(harness: Harness, reason: string): void {
+  if (!reason) return;
+  const json = buildDenyJson(harness, reason);
+  process.stdout.write(`${JSON.stringify(json)}\n`);
+}
+
+/**
+ * Emit a Stop-hook block in the firing harness's enforcement channel and return
+ * the process exit code the caller should use.
+ *
+ * The verdict (allow/block + reason) is computed harness-agnostically in
+ * agents/rules/stop-hook.ts; this function only shapes *how the block is
+ * communicated back*, because each harness has a different mechanism:
+ *
+ * - **Claude Code / Codex** honor `exit 2` + a stderr reason as a turn block,
+ *   and the harness re-prompts the model with the stderr text.
+ * - **Cursor** ignores stop-hook exit codes (non-zero = fail-open, the turn
+ *   proceeds) and re-prompts ONLY via a `followup_message` field in stdout
+ *   JSON, which it auto-submits as the next user message: the sanctioned
+ *   "iterate until a goal is met" channel, capped by `loop_limit` (default 5).
+ *   We exit 0 so Cursor treats the run as a success and honors the output.
+ *   (Confirmed against cursor.com/docs/agent/hooks.)
+ */
+export function emitStopBlock(harness: Harness, verdict: { reason?: string; rule: string }): 0 | 2 {
+  const message = `${
+    verdict.reason ?? "End-of-turn coordination ritual incomplete."
+  }\n[agent-hook stop]: rule=${verdict.rule}`;
+  if (harness === "cursor") {
+    process.stdout.write(`${JSON.stringify({ followup_message: message })}\n`);
+    return 0;
+  }
+  process.stderr.write(`${message}\n`);
+  return 2;
+}
+
+function buildContextJson(
+  harness: Harness,
+  event: SystemEvent,
+  text: string,
+): Record<string, unknown> {
+  if (harness === "cursor") {
+    // Cursor uses a flat top-level key + an env block that survives across the
+    // session. The dispatcher historically also wrote
+    // `env: {HARNERY_AGENT_COORD_HARNESS, HARNERY_AGENT_COORD_PLATFORM}`. These are
+    // observer hints, not load-bearing; agent-hook + agent-coord recover the
+    // harness from event metadata. Drop them.
+    return { additional_context: text };
+  }
+  // Claude Code + Codex share the `hookSpecificOutput` envelope.
+  return {
+    hookSpecificOutput: {
+      hookEventName: event,
+      additionalContext: text,
+    },
+  };
+}
+
+function buildDenyJson(harness: Harness, reason: string): Record<string, unknown> {
+  if (harness === "cursor") {
+    return { permission: "deny", agent_message: reason, user_message: reason };
+  }
+  return {
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: reason,
+    },
+  };
+}

package/src/core/hooks/harness/parse.ts

@@ -0,0 +1,180 @@
+/**
+ * Harness payload parser. One file because all three harnesses (CC, Cursor,
+ * Codex) share most of their PreToolUse / PostToolUse field names (Codex's
+ * field names match CC's directly) and Cursor's deltas are small enough to
+ * branch inline.
+ *
+ * The parser is intentionally tolerant: every field reads through `pickStr`,
+ * `pickNum`, etc., so a missing key returns `undefined` instead of throwing.
+ * Phase 2 ship criterion is "parser correctness across thousands of real
+ * events without affecting behavior": fail-soft beats fail-hard.
+ */
+
+import type { Harness } from "../events/schema.ts";
+
+export interface ParsedPayload {
+  hook_event_name?: string;
+  session_id?: string;
+  agent_id?: string;
+  subagent_id?: string;
+  conversation_id?: string;
+  parent_session_id?: string;
+  turn_id?: string;
+  parent_turn_id?: string;
+  transcript_path?: string;
+  cwd?: string;
+  pid?: number;
+  model?: string;
+  source?: string; // SessionStart: "startup" | "resume" | …
+  prompt?: string; // UserPromptSubmit / beforeSubmitPrompt
+  tool_name?: string; // Pre/PostToolUse
+  tool_input?: unknown; // Pre/PostToolUse: the model's call arguments
+  tool_response?: unknown; // PostToolUse: the tool's output (string or object)
+  tool_use_id?: string; // CC ties pre/post via this; Codex echoes it too
+  stop_hook_active?: boolean; // Stop
+  clean_exit?: boolean; // SessionEnd
+  exit_status?: string; // SubagentStop
+  reason?: string; // SubagentStop / StopFailure
+  /** original parsed object, preserved for callers that need a field we didn't pluck. */
+  raw: Record<string, unknown>;
+}
+
+/**
+ * Parse the raw stdin payload string for any harness. Returns null when JSON
+ * parse fails (Cursor occasionally fires hooks with no payload).
+ */
+export function parsePayload(raw: string, _harness: Harness): ParsedPayload | null {
+  if (!raw || raw.trim().length === 0) return null;
+  let json: Record<string, unknown>;
+  try {
+    json = JSON.parse(raw) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+
+  return {
+    hook_event_name: pickStr(json, "hook_event_name"),
+    session_id: pickStr(json, "session_id"),
+    agent_id: pickStr(json, "agent_id"),
+    subagent_id: pickStr(json, "subagent_id"),
+    conversation_id: pickStr(json, "conversation_id"),
+    parent_session_id: pickStr(json, "parent_session_id"),
+    turn_id: pickStr(json, "turn_id"),
+    parent_turn_id: pickStr(json, "parent_turn_id"),
+    transcript_path: pickStr(json, "transcript_path"),
+    cwd: pickStr(json, "cwd"),
+    pid: pickNum(json, "pid"),
+    model: pickStr(json, "model"),
+    source: pickStr(json, "source"),
+    prompt: pickStr(json, "prompt"),
+    tool_name: pickStr(json, "tool_name"),
+    tool_input: json.tool_input,
+    tool_response: json.tool_response,
+    tool_use_id: pickStr(json, "tool_use_id"),
+    stop_hook_active: pickBool(json, "stop_hook_active"),
+    clean_exit: pickBool(json, "clean_exit"),
+    exit_status: pickStr(json, "exit_status"),
+    reason: pickStr(json, "reason"),
+    raw: json,
+  };
+}
+
+/**
+ * Pull the bash command string out of a Bash/Shell tool_input. Returns
+ * undefined for non-shell tools.
+ */
+export function extractBashCommand(
+  toolName: string | undefined,
+  toolInput: unknown,
+): string | undefined {
+  if (!toolName) return undefined;
+  if (toolName !== "Bash" && toolName !== "Shell") return undefined;
+  if (toolInput && typeof toolInput === "object") {
+    const t = toolInput as Record<string, unknown>;
+    const cmd = t.command;
+    if (typeof cmd === "string") return cmd;
+  }
+  return undefined;
+}
+
+/**
+ * Pull the model's description string out of a tool_input. Only Claude Code's
+ * Bash tool requires this field; falls back to undefined elsewhere.
+ */
+export function extractToolDescription(toolInput: unknown): string | undefined {
+  if (toolInput && typeof toolInput === "object") {
+    const t = toolInput as Record<string, unknown>;
+    const d = t.description;
+    if (typeof d === "string") return d;
+  }
+  return undefined;
+}
+
+function pickStr(o: Record<string, unknown>, k: string): string | undefined {
+  const v = o[k];
+  return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+
+function pickNum(o: Record<string, unknown>, k: string): number | undefined {
+  const v = o[k];
+  return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}
+
+function pickBool(o: Record<string, unknown>, k: string): boolean | undefined {
+  const v = o[k];
+  return typeof v === "boolean" ? v : undefined;
+}
+
+// ── Event-name normalization ────────────────────────────────────────────────
+
+/**
+ * Each harness uses a slightly different name for the "same" lifecycle event.
+ * Map the CLI-arg event-name (kebab-case, set by us in the wiring) to one of
+ * the canonical event_types. Phase 2's CLI passes the kebab event
+ * name; this returns the canonical event_type or null when the event has no
+ * canonical equivalent (e.g. Cursor's before-shell-execution duplicates
+ * pre-tool-use semantically, so we route both to `tool.pre_use`).
+ */
+export function normalizeEventName(
+  eventName: string,
+): { event_type: NormalizedEventType; intra_turn: boolean } | null {
+  switch (eventName) {
+    case "session-start":
+      return { event_type: "session.start", intra_turn: false };
+    case "session-end":
+      return { event_type: "session.end", intra_turn: false };
+    case "user-prompt-submit":
+      return { event_type: "user_prompt.submit", intra_turn: false };
+    case "stop":
+      return { event_type: "turn.stop", intra_turn: false };
+    case "stop-failure":
+      // Phase 2: a failed stop is still a turn boundary; emit turn.stop and
+      // attach the failure signal in `data`. Phase 5 may introduce a
+      // dedicated `turn.stop_failure` event if the projector needs to branch.
+      return { event_type: "turn.stop", intra_turn: false };
+    case "sub-agent-start":
+      return { event_type: "subagent.start", intra_turn: false };
+    case "sub-agent-stop":
+      return { event_type: "subagent.stop", intra_turn: false };
+    case "pre-tool-use":
+    case "before-shell-execution":
+      return { event_type: "tool.pre_use", intra_turn: true };
+    case "post-tool-use":
+      return { event_type: "tool.post_use", intra_turn: true };
+    case "post-tool-use-failure":
+      return { event_type: "tool.post_use_failure", intra_turn: true };
+    default:
+      return null;
+  }
+}
+
+export type NormalizedEventType =
+  | "session.start"
+  | "session.end"
+  | "user_prompt.submit"
+  | "turn.stop"
+  | "subagent.start"
+  | "subagent.stop"
+  | "tool.pre_use"
+  | "tool.post_use"
+  | "tool.post_use_failure";

package/src/core/hooks/index.ts

@@ -0,0 +1,16 @@
+/**
+ * agent-hooks library exports.
+ *
+ * Phase 1 (skeleton): exposes only the canonical event schema types. Parsers,
+ * resolvers, and emit helpers ship in Phase 2.
+ */
+
+export {
+  type Event,
+  type EventEnvelope,
+  type EventType,
+  type Harness,
+  type RedactionMarker,
+  SCHEMA_VERSION,
+  type Source,
+} from "./events/schema.ts";

package/src/core/hooks/resolve/anchor.ts

@@ -0,0 +1,51 @@
+/**
+ * Pure pid-map anchor selection: picks which PID in a process's ppid chain
+ * the heartbeat pid-map row should be keyed to, so the agent's later shell
+ * tool calls (which ppid-walk up to find it) resolve their own identity.
+ *
+ * Split out of cli.ts's `findHarnessAnchorPid` so the comm-matching logic is
+ * unit-testable against the real Phase 0 Cursor probe chains without needing a
+ * live /proc tree.
+ *
+ * Why the cursor `node` fallback exists: Cursor's WSL/Linux process tree has
+ * NO process named `cursor`: the chain is `bash → bash → node → node → sh →
+ * Relay → init`. The `node` ancestors are stable across every hook + tool event
+ * in one IDE-window session, so anchoring there gives the agent's shell tool
+ * calls a reachable, stable pid-map row. This faithfully restores the previous
+ * cursor anchor behavior (match `cursor` first, then fall back to `node`) that
+ * was dropped in the Phase 4-6 TS refactor, the same regression class as the
+ * heartbeat-platform + pidmap-self-heal losses. Scoped to `harness === "cursor"`
+ * so Claude Code / Codex never
+ * mis-anchor on an unrelated `node` ancestor (they match their own comm token
+ * directly).
+ *
+ * Known limitation (matches the bash original): two Cursor chats sharing one
+ * IDE window share their `node` ancestor, so the pid-map row is last-writer-
+ * wins between them. Single-chat-per-window (the common case) is correct;
+ * concurrent same-window chats disambiguate via `--session-id`.
+ */
+
+/** Harness-binary comm names. CC's tool calls descend from `claude`, Codex's
+ * from `codex`; matched directly so neither needs the `node` fallback. */
+const PRIMARY_COMM_TOKENS = new Set(["claude", "claude-code", "cursor", "codex"]);
+
+/**
+ * Pick the anchor PID from a ppid chain ordered nearest-first (the resolving
+ * process at index 0, walking up toward init). Returns the first ancestor
+ * matching a harness comm token; for cursor, falls back to the first `node`
+ * ancestor; otherwise undefined (caller falls back to process.ppid).
+ */
+export function selectAnchorPid(
+  chain: ReadonlyArray<{ pid: number; comm: string }>,
+  harness?: string,
+): number | undefined {
+  for (const hop of chain) {
+    if (PRIMARY_COMM_TOKENS.has(hop.comm)) return hop.pid;
+  }
+  if (harness === "cursor") {
+    for (const hop of chain) {
+      if (hop.comm === "node") return hop.pid;
+    }
+  }
+  return undefined;
+}

package/src/core/hooks/resolve/coord-root.ts

@@ -0,0 +1,25 @@
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { coordEnv } from "../../../lib/env.ts";
+
+/**
+ * Walk up from `start` looking for a directory containing `.harnery/`. The
+ * single coord-root resolution so every adapter agrees on the same root.
+ */
+export function findCoordRoot(start: string = process.cwd()): string | null {
+  // HARNERY_COORD_ROOT_OVERRIDE: test-mode escape hatch matched by agent-coord
+  // and the bash side. Lets the sandboxed coord-test suite run against a
+  // temp directory rather than the real monorepo root. agent-hook's
+  // session.start handler may be the FIRST thing to create .harnery/ in a
+  // fresh sandbox, so the override is honored unconditionally (we don't
+  // require .harnery/ to pre-exist).
+  const override = coordEnv("COORD_ROOT_OVERRIDE");
+  if (override) return override;
+  let dir = resolve(start);
+  while (true) {
+    if (existsSync(join(dir, ".harnery"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}

package/src/core/hooks/resolve/intent.ts

@@ -0,0 +1,89 @@
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Resolve the model-declared intent for the current tool call. Three-source
+ * precedence:
+ *
+ *   1. `# intent: X` comment on the first line of the bash command.
+ *   2. `description` field on the tool input (Claude Code only).
+ *   3. `<intent>...</intent>` tag in the most-recent assistant prose, read
+ *      from `.harnery/.last-intent.<instance_id>` (the bash bash-tap is the
+ *      only thing that does transcript scanning today; agent-hook stamps the
+ *      file on precedence 1/2 so the bash-tap can fall back to it).
+ *
+ * Phase 8 (2026-05-27): agent-hook writes the stamp file itself on precedence
+ * 1/2 (replacing coord-intent-stamp.sh's command/description branches). The
+ * transcript-tag branch is now the only thing left in coord-intent-stamp.sh.
+ */
+export function resolveIntent(opts: {
+  coordRoot: string;
+  instanceId: string;
+  /** First-line `# intent: X` comment from the bash command (preferred fresh source). */
+  commandIntentComment?: string;
+  /** `description` field on the tool input (Claude Code only). */
+  description?: string;
+}): { intent: string; source: "command-comment" | "description" | "stamp" | "none" } {
+  const stampPath = join(opts.coordRoot, ".harnery", `.last-intent.${opts.instanceId}`);
+
+  // 1. Fresh from the command itself (most reliable, cross-harness).
+  if (opts.commandIntentComment) {
+    const cleaned = clamp(opts.commandIntentComment);
+    if (cleaned) {
+      writeStamp(stampPath, cleaned);
+      return { intent: cleaned, source: "command-comment" };
+    }
+  }
+
+  // 2. Fresh from the tool input description (Claude Code only).
+  if (opts.description) {
+    const cleaned = clamp(opts.description);
+    if (cleaned) {
+      writeStamp(stampPath, cleaned);
+      return { intent: cleaned, source: "description" };
+    }
+  }
+
+  // 3. Whatever the bash-tap stamped from a transcript <intent> tag.
+  if (existsSync(stampPath)) {
+    try {
+      const stamped = readFileSync(stampPath, "utf8").trim();
+      if (stamped && stamped !== "(no intent)") {
+        return { intent: stamped, source: "stamp" };
+      }
+    } catch {
+      /* fallthrough */
+    }
+  }
+
+  return { intent: "(no intent)", source: "none" };
+}
+
+function writeStamp(path: string, value: string): void {
+  try {
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, value, "utf8");
+    renameSync(tmp, path);
+  } catch {
+    /* best-effort */
+  }
+}
+
+/**
+ * Match `# intent: X` at the start of a command (after optional leading
+ * whitespace on the first line). Mirrors `extract_command_intent_comment` in
+ * coord-intent-stamp.sh.
+ */
+export function extractIntentComment(command: string | undefined): string | undefined {
+  if (!command) return undefined;
+  const firstLine = command.split("\n", 1)[0];
+  const m = firstLine?.match(/^[ \t]*#[ \t]*intent:[ \t]*(.+)$/);
+  if (!m) return undefined;
+  return m[1]?.trimEnd();
+}
+
+function clamp(v: string): string {
+  const trimmed = v.trim();
+  if (trimmed.length <= 200) return trimmed;
+  return `${trimmed.slice(0, 197)}...`;
+}

package/src/core/hooks/resolve/owner.ts

@@ -0,0 +1,140 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { coordEnv } from "../../../lib/env.ts";
+
+/**
+ * Resolve the canonical `instance_id` for the current hook invocation.
+ *
+ * Precedence:
+ *
+ *   1. `HARNERY_AGENT_COORD_OWNER` env var. Set by harness adapters when they know
+ *      the owner identity at spawn time (Codex's apply_patch tool path uses
+ *      this).
+ *   2. Hook payload fields, in order: `agent_id` → `subagent_id` →
+ *      `session_id` → `conversation_id`. agent_id wins for CC subagent
+ *      events; session_id is the parent-shape default.
+ *   3. PID-map lookup at `.harnery/pid-map/<pid>` for our own pid, then ppid
+ *      chain (up to 20 hops).
+ *
+ * Returns null when nothing resolves. Callers must treat null as "no owner"
+ * and skip the event (Phase 2 fail-safe; Phase 3 will mint a temporary owner
+ * for orphan events).
+ */
+export function resolveOwner(opts: {
+  payload: Record<string, unknown> | null;
+  coordRoot: string;
+}): { instance_id: string; source: "env" | "payload" | "pidmap-self" | "pidmap-ancestor" } | null {
+  const env = coordEnv("AGENT_COORD_OWNER");
+  if (env && env.length > 0) {
+    return { instance_id: env, source: "env" };
+  }
+
+  if (opts.payload) {
+    for (const key of ["agent_id", "subagent_id", "session_id", "conversation_id"] as const) {
+      const v = opts.payload[key];
+      if (typeof v === "string" && v.length > 0) {
+        return { instance_id: v, source: "payload" };
+      }
+    }
+  }
+
+  // Pid-map ancestor walk. Start at own pid (the bash wrapper's bun child),
+  // walk up through ppids. The pid-map is stamped keyed by the harness PID, so
+  // we'll usually find it 1-3 hops up.
+  const pidmap = join(opts.coordRoot, ".harnery", "pid-map");
+  if (existsSync(pidmap)) {
+    let pid = process.pid;
+    let hops = 0;
+    while (hops < 20) {
+      const file = join(pidmap, String(pid));
+      if (existsSync(file)) {
+        try {
+          const row = readFileSync(file, "utf8").trim();
+          // Row shape: "<instance_id>" or "<instance_id>\t<platform>"
+          const owner = row.split("\t")[0];
+          if (owner && owner.length > 0) {
+            return {
+              instance_id: owner,
+              source: hops === 0 ? "pidmap-self" : "pidmap-ancestor",
+            };
+          }
+        } catch {
+          /* keep walking */
+        }
+      }
+      const ppid = readPpid(pid);
+      if (!ppid || ppid === 0 || ppid === 1) break;
+      pid = ppid;
+      hops++;
+    }
+  }
+
+  return null;
+}
+
+function readPpid(pid: number): number | null {
+  // Linux/WSL: /proc/<pid>/status carries `PPid:`. Falls back to null on
+  // macOS or any read failure; ancestor walk just terminates.
+  try {
+    const status = readFileSync(`/proc/${pid}/status`, "utf8");
+    for (const line of status.split("\n")) {
+      if (line.startsWith("PPid:")) {
+        const n = Number(line.split(/\s+/)[1]);
+        return Number.isFinite(n) ? n : null;
+      }
+    }
+  } catch {
+    /* fallthrough */
+  }
+  return null;
+}
+
+/**
+ * Find the parent owner for a subagent invocation. The per-shell marker at
+ * `.harnery/shells/<pid>` is set by `sub-agent-start` and removed by
+ * `sub-agent-stop`.
+ *
+ * Phase 2 stub: the marker file isn't written yet, so we return null in most
+ * cases. Phase 2 callers can pass through.
+ */
+export function readShellMarker(coordRoot: string, pid: number): string | null {
+  const path = join(coordRoot, ".harnery", "shells", String(pid));
+  if (!existsSync(path)) return null;
+  try {
+    return readFileSync(path, "utf8").trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/** Read the heartbeat-recorded `agent_id` for an owner if it exists. */
+export function readAgentIdForOwner(coordRoot: string, instanceId: string): string | null {
+  const path = join(coordRoot, ".harnery", "active", `${instanceId}.json`);
+  if (!existsSync(path)) return null;
+  try {
+    const body = readFileSync(path, "utf8");
+    const data = JSON.parse(body) as { agent_id?: string };
+    return data.agent_id ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** Diagnostic: list of pid-map entries (for debugging). */
+export function listPidmap(coordRoot: string): Array<{ pid: number; owner: string }> {
+  const dir = join(coordRoot, ".harnery", "pid-map");
+  if (!existsSync(dir)) return [];
+  const out: Array<{ pid: number; owner: string }> = [];
+  for (const f of readdirSync(dir)) {
+    const pid = Number(f);
+    if (!Number.isFinite(pid)) continue;
+    try {
+      const row = readFileSync(join(dir, f), "utf8").trim();
+      const owner = row.split("\t")[0];
+      if (owner) out.push({ pid, owner });
+    } catch {
+      /* skip */
+    }
+  }
+  return out;
+}

package/src/core/hooks/resolve/transcript.ts

@@ -0,0 +1,72 @@
+import { existsSync, statSync } from "node:fs";
+
+/**
+ * Scan a CC-style JSONL transcript for the `┌─ agent-` status-box prefix in
+ * the most-recent assistant turn. Used by `turn.stop` events to populate
+ * `status_box_present`.
+ *
+ * Cheap by default: caps the read at 256KB tailed from the file, since the
+ * status box (if present) is always near the end of the most-recent turn.
+ * Phase 2 doesn't try to fight the flush race: if the last assistant block
+ * hasn't been written yet at Stop-hook time, status_box_present is `false`
+ * and Phase 5 verdict path catches the race via a single retry.
+ */
+export function scanStatusBoxPresent(transcriptPath: string | undefined): boolean {
+  if (!transcriptPath || !existsSync(transcriptPath)) return false;
+  const text = tailText(transcriptPath);
+  if (text === undefined) return false;
+  // The box is rendered as a text content block by the assistant; we look
+  // for the prefix on any line of the trailing window.
+  return text.includes("┌─ agent-");
+}
+
+/**
+ * Resolve the agent's model from a CC-style JSONL transcript by reading the
+ * most-recent assistant message's `message.model`. Claude Code's SessionStart
+ * payload omits `model` (Codex + Cursor supply it directly), so this is the
+ * fallback that lets `session.start` / `turn.stop` populate the heartbeat's
+ * model field once the transcript has at least one assistant turn.
+ *
+ * Tail-reads the same 256KB window as the status-box scan and walks lines from
+ * the end, returning the first real model id found. Synthetic placeholders
+ * (`<synthetic>`) and empty values are skipped. Returns undefined when the
+ * transcript is missing/empty (e.g. a fresh session's first SessionStart).
+ */
+export function scanTranscriptModel(transcriptPath: string | undefined): string | undefined {
+  if (!transcriptPath || !existsSync(transcriptPath)) return undefined;
+  const text = tailText(transcriptPath);
+  if (!text) return undefined;
+  const lines = text.split("\n");
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i]?.trim();
+    if (!line?.includes('"model"')) continue;
+    try {
+      const obj = JSON.parse(line) as {
+        message?: { model?: unknown };
+        model?: unknown;
+      };
+      const model = obj.message?.model ?? obj.model;
+      if (typeof model === "string" && model.length > 0 && !model.startsWith("<")) {
+        return model;
+      }
+    } catch {
+      // Partial/truncated first line of the tail window; skip it.
+    }
+  }
+  return undefined;
+}
+
+/** Tail-read up to 256KB from the end of a file as UTF-8, or undefined on error. */
+function tailText(path: string): string | undefined {
+  try {
+    const size = statSync(path).size;
+    const start = Math.max(0, size - 256 * 1024);
+    const fd = require("node:fs").openSync(path, "r");
+    const buf = Buffer.alloc(size - start);
+    require("node:fs").readSync(fd, buf, 0, buf.length, start);
+    require("node:fs").closeSync(fd);
+    return buf.toString("utf8");
+  } catch {
+    return undefined;
+  }
+}