harnery 0.32.0 → 0.34.0

package/src/core/hooks/index.ts

@@ -1,16 +1,9 @@
 /**
  * agent-hooks library exports.
  *
- * Phase 1 (skeleton): exposes only the canonical event schema types. Parsers,
- * resolvers, and emit helpers ship in Phase 2.
+ * Public hook types for the canonical V3 ledger.
  */
 
-export {
-  type Adapter,
-  type Event,
-  type EventEnvelope,
-  type EventType,
-  type RedactionMarker,
-  SCHEMA_VERSION,
-  type Source,
-} from "./events/schema.ts";
+export type { Adapter } from "../adapter.ts";
+export type { EventV3 as Event } from "../events/v3/contract.ts";
+export { EventV3Schema } from "../events/v3/contract.ts";

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

@@ -7,7 +7,7 @@ import { resolveCoordRoot } from "../../agents/coord-client.ts";
  * different roots. They used to: this walked up from `CLAUDE_PROJECT_DIR` or
  * cwd while the CLI's `monorepoRoot()` asked git for the superproject first, so
  * with a shell inside a submodule that carries its own `.harnery/`, the CLI's
- * `state.status_checked` landed in a stream this side never read and rule 1/3
+ * `coord.status_observed` landed in a stream this side never read and rule 1/3
  * blocked every turn.
  *
  * Resolution precedence (see `resolveCoordRoot` for the full rationale):

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

@@ -2,6 +2,8 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { coordEnv } from "../../../lib/env.ts";
+import { resolveOwnerBySessionEnv } from "../../agents/coord-client.ts";
+import { readLiveCoordinationRow } from "../../agents/state/live-coordination-view.ts";
 import { checkPidToken } from "../../agents/state/proc-start.ts";
 
 /**
@@ -9,20 +11,21 @@ import { checkPidToken } from "../../agents/state/proc-start.ts";
  *
  * Precedence:
  *
- *   1. `HARNERY_AGENT_COORD_OWNER` env var. Set by adapter 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
+ *   1. Hook payload fields. Current live V3 authority breaks ties: a live
+ *      child wins when it belongs to the payload session, otherwise the live
+ *      session/conversation wins over a stale adapter `agent_id`. With no live
+ *      evidence, the legacy `agent_id` → `subagent_id` → `session_id` →
+ *      `conversation_id` order remains the startup fallback.
+ *   2. `HARNERY_AGENT_COORD_OWNER` outside bridge mode. Bridge-marked children
+ *      ignore this unvalidated override.
+ *   3. Adapter-exported session identity matched to one live V3 generation.
+ *      This is the only payload-free identity accepted in bridge mode.
+ *   4. PID-map lookup at `.harnery/pid-map/<pid>` for our own pid, then ppid
  *      chain (up to 20 hops).
- *   4. `CODEX_THREAD_ID` env var, accepted only when a live heartbeat by that
- *      id exists under `.harnery/active/`. Codex sessions use their thread id
- *      as the heartbeat instance_id, and a Windows→WSL bridge forwards the
- *      var into process trees that descend from no registered process — the
- *      one place the pid walk can never land. Validated so a garbage value
- *      cannot fabricate an identity.
+ *
+ * Bridge-marked children fail closed after tier 3. A connector crosses a
+ * process-tree boundary, so pid ancestry and singleton state are not evidence
+ * of its logical session.
  *
  * 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
@@ -33,22 +36,46 @@ export function resolveOwner(opts: {
   coordRoot: string;
 }): {
   instance_id: string;
-  source: "env" | "payload" | "pidmap-self" | "pidmap-ancestor" | "codex-env";
+  source: "env" | "payload" | "session_env" | "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) {
+    const value = (key: "agent_id" | "subagent_id" | "session_id" | "conversation_id") => {
+      const candidate = opts.payload?.[key];
+      return typeof candidate === "string" && candidate.length > 0 ? candidate : undefined;
+    };
+    const childId = value("subagent_id") ?? value("agent_id");
+    const sessionId = value("session_id") ?? value("conversation_id");
+    const child = childId ? readLiveCoordinationRow(opts.coordRoot, childId) : null;
+    const session = sessionId ? readLiveCoordinationRow(opts.coordRoot, sessionId) : null;
+
+    if (child && sessionId && (child.kind === "subagent" || child.session_id === sessionId)) {
+      return { instance_id: childId!, source: "payload" };
+    }
+    if (session) return { instance_id: sessionId!, source: "payload" };
+    if (child) return { instance_id: childId!, source: "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" };
-      }
+      const candidate = value(key);
+      if (candidate) return { instance_id: candidate, source: "payload" };
     }
   }
 
+  const bridge = coordEnv("AGENT_COORD_BRIDGE")?.trim();
+  const env = coordEnv("AGENT_COORD_OWNER");
+  if (env && env.length > 0 && !bridge) {
+    return { instance_id: env, source: "env" };
+  }
+
+  // A Windows-hosted Codex task can replace its WSL process tree during a
+  // repository refresh. The forwarded native thread id survives that boundary
+  // and is safe only after joining to exactly one nonterminal V3 producer.
+  // Resolve it before the bridge fail-closed branch; never fall through to the
+  // old pid map when the join fails.
+  const sessionOwner = resolveOwnerBySessionEnv(opts.coordRoot);
+  if (sessionOwner) return { instance_id: sessionOwner, source: "session_env" };
+
+  if (bridge) return null;
+
   // 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 adapter PID, so
   // we'll usually find it 1-3 hops up.
@@ -85,18 +112,6 @@ export function resolveOwner(opts: {
     }
   }
 
-  // Tier 4: Codex thread id, heartbeat-validated. Last because the pid map is
-  // more specific when it answers — an inherited env var can outlive the
-  // process tree it described, a live pid-map row cannot.
-  const codexThreadId = process.env.CODEX_THREAD_ID?.trim();
-  if (
-    codexThreadId &&
-    /^[A-Za-z0-9-]+$/.test(codexThreadId) &&
-    existsSync(join(opts.coordRoot, ".harnery", "active", `${codexThreadId}.json`))
-  ) {
-    return { instance_id: codexThreadId, source: "codex-env" };
-  }
-
   return null;
 }
 
@@ -143,17 +158,9 @@ export function readShellMarker(coordRoot: string, pid: number): string | null {
   }
 }
 
-/** Read the heartbeat-recorded `agent_id` for an owner if it exists. */
+/** Read the V3-projected `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;
-  }
+  return readLiveCoordinationRow(coordRoot, instanceId)?.agent_id ?? null;
 }
 
 /** Diagnostic: list of pid-map entries (for debugging). */

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

@@ -3,7 +3,7 @@ import { basename, dirname, join } from "node:path";
 
 /**
  * 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
+ * the most-recent assistant turn. Used by `turn.completed` events to populate
  * `status_box_present`.
  *
  * Cheap by default: caps the read at 256KB tailed from the file, since the
@@ -13,8 +13,9 @@ import { basename, dirname, join } from "node:path";
  * 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);
+  const readablePath = resolveTranscriptPath(transcriptPath);
+  if (!readablePath) return false;
+  const text = tailText(readablePath);
   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.
@@ -23,7 +24,7 @@ export function scanStatusBoxPresent(transcriptPath: string | undefined): boolea
 
 /**
  * Scan a CC-style JSONL transcript for a needle in ASSISTANT message text
- * blocks only. Used by `turn.stop` to detect the suggested session name in the
+ * blocks only. Used by `turn.completed` to detect the suggested session name in the
  * reply.
  *
  * The row filter is load-bearing: the transcript tail also carries the needle
@@ -39,8 +40,10 @@ export function scanAssistantTextIncludes(
   transcriptPath: string | undefined,
   needle: string,
 ): boolean {
-  if (!transcriptPath || !needle || !existsSync(transcriptPath)) return false;
-  const text = tailText(transcriptPath);
+  if (!needle) return false;
+  const readablePath = resolveTranscriptPath(transcriptPath);
+  if (!readablePath) return false;
+  const text = tailText(readablePath);
   if (!text) return false;
   for (const line of text.split("\n")) {
     // Cheap gate before parsing: most lines don't contain the needle at all.
@@ -71,11 +74,156 @@ export function scanAssistantTextIncludes(
   return false;
 }
 
+/** Most recent user-visible assistant text across Claude Code and Codex JSONL. */
+export function scanLatestAssistantText(transcriptPath: string | undefined): string | undefined {
+  const readablePath = resolveTranscriptPath(transcriptPath);
+  if (!readablePath) return undefined;
+  const text = tailText(readablePath);
+  if (!text) return undefined;
+  const lines = text.split("\n");
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const row = parseTranscriptRow(lines[i]);
+    if (!row) continue;
+    const assistantText = assistantTextFromRow(row);
+    // Claude Code appends the current tool_use-only assistant row before
+    // PreToolUse fires. Skip rows with no user-visible text so the immediately
+    // preceding fenced block remains discoverable.
+    if (assistantText !== null && assistantText.trim().length > 0) return assistantText;
+  }
+  return undefined;
+}
+
+/**
+ * Verify that the first assistant message after the set-task result begins
+ * with the exact session-name block. This is the Stop-time fallback for a
+ * correctly displayed name followed by no further tool call. A name printed
+ * after later work does not pass.
+ */
+export function scanSessionNameDisplayedImmediately(
+  transcriptPath: string | undefined,
+  name: string,
+  startsWithBlock: (text: string, expectedName: string) => boolean,
+): boolean {
+  return (
+    inspectSessionNameDisplayImmediately(transcriptPath, name, startsWithBlock).state === "present"
+  );
+}
+
+export type SessionNameDisplayInspection =
+  | { state: "present" }
+  | { state: "absent" }
+  | { state: "unavailable"; reason: "missing_transcript" | "transcript_not_ready" };
+
+/**
+ * Inspect the ordered post-mint reply without conflating a malformed display
+ * with an unreadable transcript. PreToolUse can enforce the former, while the
+ * latter must remain an honest unsupported observation instead of deadlocking
+ * every tool behind evidence the adapter has not persisted yet.
+ */
+export function inspectSessionNameDisplayImmediately(
+  transcriptPath: string | undefined,
+  name: string,
+  startsWithBlock: (text: string, expectedName: string) => boolean,
+): SessionNameDisplayInspection {
+  if (!name) return { state: "absent" };
+  const readablePath = resolveTranscriptPath(transcriptPath);
+  if (!readablePath) return { state: "unavailable", reason: "missing_transcript" };
+  const text = tailText(readablePath);
+  if (!text) return { state: "unavailable", reason: "transcript_not_ready" };
+  let sawMintResult = false;
+  for (const line of text.split("\n")) {
+    if (!sawMintResult) {
+      if (line.includes(name) && line.includes("suggested_session_name")) sawMintResult = true;
+      continue;
+    }
+    const row = parseTranscriptRow(line);
+    if (!row) continue;
+    const assistantText = assistantTextFromRow(row);
+    if (assistantText !== null) {
+      return { state: startsWithBlock(assistantText, name) ? "present" : "absent" };
+    }
+  }
+  return sawMintResult
+    ? { state: "unavailable", reason: "transcript_not_ready" }
+    : { state: "absent" };
+}
+
+/**
+ * Resolve a transcript path at the adapter boundary. Windows-native Codex can
+ * send `C:\...` while the managed hook executes inside WSL, where the same
+ * file is mounted at `/mnt/c/...`.
+ */
+export function transcriptPathCandidates(transcriptPath: string | undefined): string[] {
+  if (!transcriptPath) return [];
+  const candidates = [transcriptPath];
+  const windowsDrive = /^([A-Za-z]):[\\/](.*)$/.exec(transcriptPath);
+  if (windowsDrive) {
+    candidates.push(
+      `/mnt/${windowsDrive[1]!.toLowerCase()}/${windowsDrive[2]!.replaceAll("\\", "/")}`,
+    );
+  }
+  return [...new Set(candidates)];
+}
+
+function resolveTranscriptPath(transcriptPath: string | undefined): string | undefined {
+  return transcriptPathCandidates(transcriptPath).find((candidate) => existsSync(candidate));
+}
+
+function parseTranscriptRow(line: string | undefined): Record<string, unknown> | null {
+  if (!line?.trim()) return null;
+  try {
+    const row = JSON.parse(line) as unknown;
+    return typeof row === "object" && row !== null ? (row as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** null means this row is not an assistant message; an empty string is one with no text. */
+function assistantTextFromRow(row: Record<string, unknown>): string | null {
+  if (row.type === "assistant") {
+    const message = objectValue(row.message);
+    return textFromContent(message?.content);
+  }
+
+  if (row.type === "response_item") {
+    const payload = objectValue(row.payload);
+    if (payload?.type !== "message" || payload.role !== "assistant") return null;
+    return textFromContent(payload.content);
+  }
+
+  if (row.type === "event_msg") {
+    const payload = objectValue(row.payload);
+    if (payload?.type !== "agent_message") return null;
+    return typeof payload.message === "string" ? payload.message : "";
+  }
+
+  return null;
+}
+
+function objectValue(value: unknown): Record<string, unknown> | null {
+  return typeof value === "object" && value !== null ? (value as Record<string, unknown>) : null;
+}
+
+function textFromContent(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  const parts: string[] = [];
+  for (const block of content) {
+    const value = objectValue(block);
+    if (!value) continue;
+    if ((value.type === "text" || value.type === "output_text") && typeof value.text === "string") {
+      parts.push(value.text);
+    }
+  }
+  return parts.join("\n");
+}
+
 /**
  * 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
+ * fallback that lets `session.started` / `turn.completed` populate the cache'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
@@ -84,8 +232,9 @@ export function scanAssistantTextIncludes(
  * 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);
+  const readablePath = resolveTranscriptPath(transcriptPath);
+  if (!readablePath) return undefined;
+  const text = tailText(readablePath);
   if (!text) return undefined;
   const lines = text.split("\n");
   for (let i = lines.length - 1; i >= 0; i--) {
@@ -146,15 +295,17 @@ export function detectForkParent(
   sessionId: string,
 ): string | undefined {
   try {
-    if (!transcriptPath || !sessionId || !existsSync(transcriptPath)) return undefined;
-    if (statSync(transcriptPath).size > FORK_SCAN_MAX_BYTES) return undefined;
-    const own = readFileSync(transcriptPath, "utf8");
+    if (!sessionId) return undefined;
+    const readablePath = resolveTranscriptPath(transcriptPath);
+    if (!readablePath) return undefined;
+    if (statSync(readablePath).size > FORK_SCAN_MAX_BYTES) return undefined;
+    const own = readFileSync(readablePath, "utf8");
     const uuids = messageUuids(own);
     if (uuids.length === 0) return undefined;
     const sample = sampleEvenly(uuids, FORK_SAMPLE_SIZE);
 
-    const dir = dirname(transcriptPath);
-    const ownFile = basename(transcriptPath);
+    const dir = dirname(readablePath);
+    const ownFile = basename(readablePath);
     let best: { id: string; score: number; rows: number; mtimeMs: number } | null = null;
     for (const file of readdirSync(dir)) {
       if (file === ownFile || !SESSION_FILE_RE.test(file)) continue;

package/src/core/hooks/session-name-presence.ts

@@ -1,18 +1,17 @@
 /**
- * Session-name presence for `turn.stop`.
+ * Session-name presence for `turn.completed`.
  *
- * While the heartbeat carries a `suggested_session_name`, report whether the
- * naming ritual is satisfied: either this turn's reply shows the name, or an
- * earlier reply already did. Scanning covers assistant text blocks only (the
- * raw transcript tail also carries the name inside the set-task tool_result,
- * which must not count) plus the adapter-supplied last assistant message, for
- * stops that arrive without a transcript.
+ * While the current V3 coordination row carries a `suggested_session_name`, report whether the
+ * naming ritual is satisfied: either the immediate post-mint assistant text
+ * showed the exact block, or an earlier PreToolUse already stamped it. The
+ * transcript callback must enforce ordering and block shape; a late final
+ * answer or a tool result must not count.
  *
  * Two properties the stop-hook naming rule depends on:
  *
  * 1. Once a name is satisfied, every later stop keeps reporting `true` rather
- *    than omitting the field. The rule wants an in-window `turn.stop` carrying
- *    `session_name_present: true`; omitting it after the heartbeat stamp meant
+ *    than omitting the field. The rule wants an in-window `turn.completed` carrying
+ *    `session_name_present: true`; omitting it after the coordination stamp meant
  *    nothing could ever re-emit the flag, so every subsequent reply blocked --
  *    including the replies reproducing the exact name the rule asked for.
  * 2. The result names WHICH suggested name it covered, so a projector rebuild
@@ -23,7 +22,8 @@
  * Never throws: coordination telemetry must not take down a hook.
  */
 
-import { readHeartbeat, stampSessionNameSeen } from "../agents/state/heartbeat-writer.ts";
+import { stampSessionNameSeen } from "../agents/state/heartbeat-writer.ts";
+import { readLiveCoordinationRow } from "../agents/state/live-coordination-view.ts";
 
 export interface SessionNamePresence {
   session_name_present?: boolean;
@@ -33,17 +33,16 @@ export interface SessionNamePresence {
 export function sessionNamePresence(
   coordRoot: string,
   instanceId: string,
-  lastAssistantMessage: string,
   scanAssistantText: (name: string) => boolean,
 ): SessionNamePresence {
   try {
-    const hb = readHeartbeat(coordRoot, instanceId);
-    const name = hb?.suggested_session_name;
+    const row = readLiveCoordinationRow(coordRoot, instanceId);
+    const name = row?.suggested_session_name;
     if (!name) return {};
-    if (hb?.session_name_seen_for === name) {
+    if (row?.session_name_seen_for === name) {
       return { session_name_present: true, session_name_present_for: name };
     }
-    const present = scanAssistantText(name) || lastAssistantMessage.includes(name);
+    const present = scanAssistantText(name);
     if (present) stampSessionNameSeen(coordRoot, instanceId, name);
     return { session_name_present: present, session_name_present_for: name };
   } catch {

package/src/core/hooks/unsafe-cross-shell.ts

@@ -1,5 +1,5 @@
+import type { Adapter } from "../adapter.ts";
 import { isWslUncPath } from "./codex-wsl-bridge.ts";
-import type { Adapter } from "./events/schema.ts";
 
 export interface CrossShellInspection {
   adapter: Adapter;

package/src/core/journal/index.ts

@@ -13,10 +13,13 @@ import { resolveMachineLabel } from "../../lib/machine.ts";
 import {
   assertSafeInstanceId,
   monorepoRoot,
-  readHeartbeat,
   resolveContainedFile,
   resolveOwner,
 } from "../agents/index.ts";
+import {
+  readLiveCoordinationRow,
+  readLiveCoordinationRows,
+} from "../agents/state/live-coordination-view.ts";
 
 /**
  * Agent journal: per-agent markdown journal at `.harnery/journal/<instance_id>.md`.
@@ -313,7 +316,8 @@ export function appendEntry(
   category: JournalCategory,
   body: string,
 ): JournalDoc {
-  const hb = readHeartbeat(instanceId);
+  const root = monorepoRoot();
+  const hb = root ? readLiveCoordinationRow(root, instanceId) : null;
   const path = journalPath(instanceId);
   let doc: JournalDoc;
   if (existsSync(path)) {
@@ -412,14 +416,15 @@ export function pruneArchives(days = ARCHIVE_RETENTION_DAYS): number {
   return deleted;
 }
 
-/** Sweep `.harnery/journal/<owner>.md` files whose corresponding heartbeat is gone. */
+/** Sweep journals whose corresponding authoritative V3 generation is gone. */
 export function sweepOrphanJournals(): string[] {
   const dir = journalDir();
+  const root = monorepoRoot();
   const archived: string[] = [];
   for (const f of readdirSync(dir)) {
     if (!f.endsWith(".md")) continue;
     const instanceId = f.replace(/\.md$/, "");
-    const hb = readHeartbeat(instanceId);
+    const hb = root ? readLiveCoordinationRow(root, instanceId) : null;
     if (!hb) {
       const dest = archiveJournal(instanceId);
       if (dest) archived.push(dest);
@@ -463,25 +468,13 @@ export function loadJournal(instanceId: string): JournalDoc | null {
   return parseJournal(path, readFileSync(path, "utf8"));
 }
 
-/** Resolve an agent name → instance_id by walking active heartbeats (case-insensitive). */
+/** Resolve an agent name through the authority-safe V3 coordination projection. */
 export function resolveOwnerByName(name: string): string | null {
   const root = monorepoRoot();
   if (!root) return null;
-  const activeDir = resolve(root, ".harnery", "active");
-  if (!existsSync(activeDir)) return null;
-  for (const f of readdirSync(activeDir)) {
-    if (!f.endsWith(".json")) continue;
-    try {
-      const hb = JSON.parse(readFileSync(resolve(activeDir, f), "utf8")) as {
-        instance_id?: string;
-        name?: string;
-      };
-      if ((hb.name ?? "").toLowerCase() === name.toLowerCase()) {
-        return hb.instance_id ?? null;
-      }
-    } catch {
-      // skip
-    }
-  }
-  return null;
+  return (
+    readLiveCoordinationRows(root).find(
+      (row) => (row.name ?? "").toLowerCase() === name.toLowerCase(),
+    )?.instance_id ?? null
+  );
 }