harnery 0.30.0 → 0.31.1

package/src/core/hooks/cli.ts

@@ -3,8 +3,8 @@
  * alongside the legacy stream.
  *
  * Flow:
- *   1. Parse argv → event-name + harness.
- *   2. Read stdin → harness payload (JSON or empty).
+ *   1. Parse argv → event-name + adapter.
+ *   2. Read stdin → adapter payload (JSON or empty).
  *   3. Find coord root (walk up for .harnery/).
  *   4. Resolve instance_id (env → payload → pid-map walk).
  *   5. Map event-name → canonical event_type.
@@ -15,7 +15,7 @@
  * Phase 2 ship criterion: confirms parser correctness across thousands of
  * real events without affecting behavior. Always exits 0. Failures land in
  * `.harnery/debug/agent-hook.errors.ndjson` for audit but never break the
- * harness flow.
+ * adapter flow.
  */
 
 import { spawnSync } from "node:child_process";
@@ -23,9 +23,11 @@ import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { coordEnv } from "../../lib/env.ts";
 import { replayCodexJsonl } from "../agents/codex-replay.ts";
+import { coordBinPath } from "../agents/coord-bin.ts";
 import { consumeSince, writeCursor } from "../agents/events/consume.ts";
 import { evaluateStopHook } from "../agents/rules/stop-hook.ts";
 import { projectHeartbeats } from "../agents/state/heartbeat-projector.ts";
+import { writePidmapRow } from "../agents/state/pidmap.ts";
 import { shellMutationPaths } from "../agents/state/shell-mutation.ts";
 import {
   checkpointContext,
@@ -38,32 +40,32 @@ import {
   recordContextSample,
 } from "../context/index.ts";
 import { ensureRelayDaemon, fetchPresence, publishPresence } from "../presence/index.ts";
+import { detectAdapter } from "./adapter/detect.ts";
+import {
+  extractBashCommand,
+  extractToolDescription,
+  type NormalizedEventType,
+  normalizeEventName,
+  type ParsedPayload,
+  parsePayload,
+} from "./adapter/parse.ts";
 import {
   captureImages,
   detectPresence,
   imageJanitor,
+  journalArchive,
+  journalJanitor,
+  journalRecoveryCue,
   playSound,
   resetSoundCounters,
   runSessionSyncExtension,
   runTurnSummary,
-  scratchArchive,
-  scratchJanitor,
-  scratchRecoveryCue,
   soundForEvent,
 } from "./effects/index.ts";
 import { emit } from "./events/emit.ts";
-import type { Harness } from "./events/schema.ts";
+import type { Adapter } from "./events/schema.ts";
 import { canonicalize } from "./guard-path.ts";
-import { detectHarness } from "./harness/detect.ts";
-import {
-  extractBashCommand,
-  extractToolDescription,
-  type NormalizedEventType,
-  normalizeEventName,
-  type ParsedPayload,
-  parsePayload,
-} from "./harness/parse.ts";
-import { parsePsChainLine, selectAnchorPid } from "./resolve/anchor.ts";
+import { adapterPidFromEnv, parsePsChainLine, selectAnchorPid } from "./resolve/anchor.ts";
 import { findCoordRoot } from "./resolve/coord-root.ts";
 import { extractIntentComment, resolveIntent } from "./resolve/intent.ts";
 import { resolveOwner } from "./resolve/owner.ts";
@@ -78,11 +80,11 @@ function parseArgv(argv: string[]): Argv {
   const out: Argv = { eventName: null, extra: [] };
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i]!;
-    if (arg === "--harness") {
-      i++; // detectHarness will re-parse; just consume the value here.
+    if (arg === "--adapter") {
+      i++; // detectAdapter will re-parse; just consume the value here.
       continue;
     }
-    if (arg.startsWith("--harness=")) continue;
+    if (arg.startsWith("--adapter=")) continue;
     if (!out.eventName && !arg.startsWith("--")) {
       out.eventName = arg;
     } else {
@@ -108,7 +110,7 @@ async function readStdin(): Promise<string> {
 /**
  * Env for child agent-coord spawns, with the coord root pinned. The hook
  * process may be running with the session shell's cwd (inside a submodule or
- * scratch dir), and agent-coord resolves its root from cwd unless overridden —
+ * journal dir), and agent-coord resolves its root from cwd unless overridden —
  * without the pin a child could write state to a different .harnery than the
  * one this hook resolved.
  */
@@ -149,7 +151,7 @@ function logError(coordRoot: string | null, err: unknown, context: Record<string
 /**
  * Spawn `agent-coord assign-name <owner> <kind>` to mint or recover the
  * hurricane-style name for this owner. Returns null on any failure so
- * session.start emission never breaks the harness flow.
+ * session.start emission never breaks the adapter flow.
  *
  * Lives at agent-hooks side (not agent-coord) to keep emitter/consumer
  * separation: we spawn rather than import.
@@ -159,7 +161,7 @@ function assignNameViaAgentCoord(
   instanceId: string,
   kind: "session" | "subagent" | "transient",
 ): { name: string; kind: string } | null {
-  const binary = join(coordRoot, "harnery", "bin", "agent-coord");
+  const binary = coordBinPath("agent-coord", coordRoot) ?? "";
   if (!existsSync(binary)) return null;
   try {
     const result = spawnSync(binary, ["assign-name", instanceId, kind], {
@@ -182,9 +184,15 @@ function assignNameViaAgentCoord(
 }
 
 /**
- * Direct (in-process) pidmap write, avoids the spawn overhead of going via
- * the agent-coord CLI for every session.start / subagent.start. Pid-map
- * rows are essential for `harn agents whoami` ppid resolution.
+ * Direct (in-process) pidmap write, avoiding the spawn overhead of going via
+ * the agent-coord CLI for every session.start / subagent.start. Pid-map rows
+ * are essential for `harn agents whoami` ppid resolution.
+ *
+ * This used to inline its own copy of the write to keep this module's
+ * dependencies narrow, which quietly mattered: the shared writer is where row
+ * hygiene lives, so the duplicate meant the only hot write path in the system
+ * never swept dead rows, and the map grew unbounded. It calls the shared writer
+ * now, and this module already imports from that directory anyway.
  */
 function writePidmapViaAgentCoord(
   coordRoot: string,
@@ -193,26 +201,9 @@ function writePidmapViaAgentCoord(
   platform: string,
 ): void {
   try {
-    // Inline write: same atomic temp+rename pattern as
-    // agent-coord/src/state/pidmap.ts but skips importing across module
-    // boundaries to keep agent-hooks's deps explicit.
-    const dir = join(coordRoot, ".harnery", "pid-map");
-    const path = join(dir, String(pid));
-    const row = `${instanceId}\t${platform}`;
-    if (existsSync(path)) {
-      try {
-        const current = require("node:fs").readFileSync(path, "utf8");
-        if (current === row) return;
-      } catch {
-        /* fall through */
-      }
-    }
-    mkdirSync(dir, { recursive: true });
-    const tmp = `${path}.tmp.${process.pid}`;
-    require("node:fs").writeFileSync(tmp, row, "utf8");
-    require("node:fs").renameSync(tmp, path);
+    writePidmapRow(coordRoot, pid, instanceId, platform);
   } catch {
-    /* never break the harness flow */
+    /* never break the adapter flow */
   }
 }
 
@@ -234,7 +225,7 @@ interface BuildContext {
   coordRoot: string;
   payload: ParsedPayload | null;
   raw: string;
-  harness: Harness;
+  adapter: Adapter;
   instanceId: string;
 }
 
@@ -245,24 +236,24 @@ function buildEventData(
   const p = ctx.payload;
   switch (eventType) {
     case "session.start": {
-      const harnessPlatform =
-        ctx.harness === "claude-code"
+      const adapterPlatform =
+        ctx.adapter === "claude-code"
           ? "claude_code"
-          : ctx.harness === "cursor"
+          : ctx.adapter === "cursor"
             ? "cursor"
             : "codex";
       // Assign (or recover) name + kind via agent-coord. Idempotent: resume
       // returns the original name; new owner consumes a counter slot.
       const assigned = assignNameViaAgentCoord(ctx.coordRoot, ctx.instanceId, "session");
-      // Write the harness pid-map row so `harn agents whoami` ppid-walks find
+      // Write the adapter pid-map row so `harn agents whoami` ppid-walks find
       // this owner. Prefer the payload pid (the actual claude binary), then the
       // anchor walk (the `node` ancestor for Cursor, which has no payload pid),
       // then our own process.ppid. Without the anchor, Cursor anchored on the
       // ephemeral hook bash parent, a PID that dies before the agent's next
       // shell tool call, so the ppid walk found nothing (no_pidmap_entry).
-      const harnessPid = p?.pid ?? findHarnessAnchorPid(ctx.harness) ?? process.ppid;
-      if (harnessPid) {
-        writePidmapViaAgentCoord(ctx.coordRoot, harnessPid, ctx.instanceId, harnessPlatform);
+      const adapterPid = p?.pid ?? findAdapterAnchorPid(ctx.adapter) ?? process.ppid;
+      if (adapterPid) {
+        writePidmapViaAgentCoord(ctx.coordRoot, adapterPid, ctx.instanceId, adapterPlatform);
       }
       return {
         started_at: new Date().toISOString(),
@@ -271,17 +262,25 @@ function buildEventData(
         // supply it). Fall back to the transcript, populated on `resume`, and
         // backfilled later by `turn.stop` for a fresh `startup` session.
         model: p?.model ?? scanTranscriptModel(p?.transcript_path),
-        pid: harnessPid,
+        pid: adapterPid,
         source: p?.source,
-        platform: harnessPlatform,
+        platform: adapterPlatform,
         name: assigned?.name,
         kind: "session",
         agent_id: ctx.instanceId,
         // Workflow-child linkage: `workflow run` children carry the run id in
         // env (spawn adapters set it via buildChildEnv), so their sessions and
-        // heartbeats join back to the run journal + /workflows web view.
+        // heartbeats join back to the run transcript + /workflows web view.
         ...(coordEnv("WORKFLOW_CHILD") === "1" && coordEnv("WORKFLOW_RUN_ID")
-          ? { workflow_run_id: coordEnv("WORKFLOW_RUN_ID") }
+          ? {
+              workflow_run_id: coordEnv("WORKFLOW_RUN_ID"),
+              // Which agent row of that run this session is. The orchestrator
+              // stamps it on the way in, because the adapter does not report a
+              // session id until the agent has already finished.
+              ...(coordEnv("WORKFLOW_AGENT_ID")
+                ? { workflow_agent_id: coordEnv("WORKFLOW_AGENT_ID") }
+                : {}),
+            }
           : {}),
       };
     }
@@ -300,7 +299,7 @@ function buildEventData(
 
     case "turn.stop": {
       return {
-        // Backfill the model for harnesses that omit it at session.start
+        // Backfill the model for adapters that omit it at session.start
         // (Claude Code). The transcript is populated with assistant turns by
         // Stop-hook time, so this resolves even for fresh `startup` sessions.
         model: p?.model ?? scanTranscriptModel(p?.transcript_path),
@@ -442,14 +441,14 @@ function numberField(value: unknown): number | undefined {
 
 async function main(): Promise<number> {
   const { eventName, extra } = parseArgv(process.argv.slice(2));
-  const harness = detectHarness(process.argv.slice(2));
+  const adapter = detectAdapter(process.argv.slice(2));
   const raw = await readStdin();
 
   // Kill-switch-INDEPENDENT effects: notification sounds fire BEFORE the
   // HARNERY_AGENT_COORD_OFF gate so audible feedback survives incident-triage
   // bypass: sound playback happens before the kill-switch bailout.
   // Claude-Code-only; stop-failure → error, sub-agent-start → subagent-start.
-  if (harness === "claude-code" && eventName) {
+  if (adapter === "claude-code" && eventName) {
     const s = soundForEvent(eventName);
     if (s) {
       const repoRoot = findCoordRoot(process.cwd());
@@ -481,7 +480,7 @@ async function main(): Promise<number> {
   const debugBase = {
     ts: new Date().toISOString(),
     event_name: eventName,
-    harness,
+    adapter,
     extra_argv: extra,
     payload_bytes: raw.length,
     cwd: process.cwd(),
@@ -489,8 +488,8 @@ async function main(): Promise<number> {
     ppid: process.ppid,
   };
 
-  if (!eventName || !harness) {
-    appendDebug(coordRoot, { ...debugBase, skipped: "missing-event-or-harness" });
+  if (!eventName || !adapter) {
+    appendDebug(coordRoot, { ...debugBase, skipped: "missing-event-or-adapter" });
     return 0;
   }
 
@@ -500,7 +499,7 @@ async function main(): Promise<number> {
     return 0;
   }
 
-  const payload = parsePayload(raw, harness);
+  const payload = parsePayload(raw, adapter);
   const owner = resolveOwner({ payload: payload?.raw ?? null, coordRoot });
   if (!owner) {
     appendDebug(coordRoot, {
@@ -517,7 +516,7 @@ async function main(): Promise<number> {
     coordRoot,
     payload,
     raw,
-    harness,
+    adapter,
     instanceId: owner.instance_id,
   });
 
@@ -528,7 +527,7 @@ async function main(): Promise<number> {
     parent_session_id: payload?.parent_session_id,
     turn_id: payload?.turn_id,
     parent_turn_id: payload?.parent_turn_id,
-    harness,
+    adapter,
     data,
     // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
   } as Parameters<typeof emit>[1]);
@@ -541,13 +540,13 @@ async function main(): Promise<number> {
   });
 
   // Context telemetry is opportunistic and truthful: only persist a sample
-  // when the harness payload actually exposes usage/window data. Identical
+  // when the adapter payload actually exposes usage/window data. Identical
   // measurements are de-duplicated before they reach the canonical stream.
   if (payload?.raw) {
     try {
       const sample = extractContextSample(payload.raw, {
         sessionId,
-        harness,
+        adapter,
         model: payload.model,
         source: "hook",
         confidence: "reported",
@@ -559,7 +558,7 @@ async function main(): Promise<number> {
             event_type: "context.sampled",
             instance_id: owner.instance_id,
             session_id: sessionId,
-            harness,
+            adapter,
             data: {
               model: sample.model,
               used_tokens: sample.used_tokens,
@@ -578,13 +577,13 @@ async function main(): Promise<number> {
 
   // A native pre-compaction signal is the safest available point to capture
   // external work state. The operation is idempotent until recovery, so a
-  // harness retry cannot create a storm of near-identical capsules.
+  // adapter retry cannot create a storm of near-identical capsules.
   if (norm.event_type === "context.compaction.started") {
     try {
       const checkpoint = checkpointContext(coordRoot, {
         sessionId,
         instanceId: owner.instance_id,
-        harness,
+        adapter,
         cwd: payload?.cwd ?? process.cwd(),
         reason: "pre_compact",
         model: payload?.model,
@@ -593,7 +592,7 @@ async function main(): Promise<number> {
         event_type: "context.checkpoint.created",
         instance_id: owner.instance_id,
         session_id: sessionId,
-        harness,
+        adapter,
         data: {
           capsule_id: checkpoint.capsule.capsule_id,
           generation: checkpoint.capsule.generation,
@@ -619,17 +618,17 @@ async function main(): Promise<number> {
   }
 
   // Phase 8: SessionStart post-emit: project the event so the heartbeat
-  // lands synchronously, run stale-sweep, and emit the harness-shaped
+  // lands synchronously, run stale-sweep, and emit the adapter-shaped
   // systemMessage JSON (peer table + wiring check + council invites).
-  // Harness-agnostic since v0.5.0; replaces the previous bash UX layer
-  // and the equivalent per-harness bash session_start handlers.
+  // Adapter-agnostic since v0.5.0; replaces the previous bash UX layer
+  // and the equivalent per-adapter bash session_start handlers.
   if (norm.event_type === "session.start") {
-    // Effect (claude-code): prune stale scratch archives + sweep orphans.
+    // Effect (claude-code): prune stale journal archives + sweep orphans.
     // The recovery-cue is merged into the
     // session-start additionalContext inside emitSessionStartSystemMessage.
-    if (harness === "claude-code") scratchJanitor(coordRoot);
-    // Image-feed retention sweep (size + age cap on .harnery/images/). Harness-
-    // agnostic, cheap (one readdir), fail-soft. Paired with scratchJanitor as a
+    if (adapter === "claude-code") journalJanitor(coordRoot);
+    // Image-feed retention sweep (size + age cap on .harnery/images/). Adapter-
+    // agnostic, cheap (one readdir), fail-soft. Paired with journalJanitor as a
     // session-start "tidy the coord layer" step.
     try {
       imageJanitor(coordRoot);
@@ -643,7 +642,7 @@ async function main(): Promise<number> {
           event_type: "context.compaction.completed",
           instance_id: owner.instance_id,
           session_id: sessionId,
-          harness,
+          adapter,
           data: { trigger: "auto" },
         });
         markContextCompactionCompleted(coordRoot, {
@@ -665,7 +664,7 @@ async function main(): Promise<number> {
         owner.instance_id,
         sessionId,
         data,
-        harness,
+        adapter,
         recovery?.briefing ?? "",
       );
       if (injected && recovery) {
@@ -673,7 +672,7 @@ async function main(): Promise<number> {
           coordRoot,
           owner.instance_id,
           sessionId,
-          harness,
+          adapter,
           recovery,
           "SessionStart",
         );
@@ -693,7 +692,7 @@ async function main(): Promise<number> {
     }
   }
 
-  // Phase 8: SessionEnd cleanup: delete heartbeat + pid-map rows. Harness-
+  // Phase 8: SessionEnd cleanup: delete heartbeat + pid-map rows. Adapter-
   // agnostic since v0.5.0.
   if (norm.event_type === "session.end") {
     try {
@@ -701,10 +700,10 @@ async function main(): Promise<number> {
     } catch (err) {
       logError(coordRoot, err, { phase: "session-end-cleanup" });
     }
-    // Effects (claude-code): archive the ending agent's scratchpad + force a
+    // Effects (claude-code): archive the ending agent's journal + force a
     // session-telemetry sync (via HARNERY_CLAUDE_SESSIONS_FORCE=1).
-    if (harness === "claude-code") {
-      scratchArchive(coordRoot, owner.instance_id);
+    if (adapter === "claude-code") {
+      journalArchive(coordRoot, owner.instance_id);
       runSessionSyncExtension(coordRoot, true);
     }
     // Presence: publish the post-cleanup state so peers see this session gone
@@ -721,7 +720,7 @@ async function main(): Promise<number> {
   // subagent (claude-code + cursor; codex doesn't fan out subagents today).
   if (norm.event_type === "subagent.start") {
     try {
-      const agentCoordBin = join(coordRoot, "harnery", "bin", "agent-coord");
+      const agentCoordBin = coordBinPath("agent-coord", coordRoot) ?? "";
       if (existsSync(agentCoordBin)) {
         spawnSync(agentCoordBin, ["project"], {
           encoding: "utf8",
@@ -732,14 +731,14 @@ async function main(): Promise<number> {
           agentCoordBin,
           [
             "log",
-            `SUBAGENT_START  agent_type=${(data.agent_type as string) ?? "unknown"} agent_id=${owner.instance_id.slice(0, 8)} platform=${harnessPlatform(harness)}`,
+            `SUBAGENT_START  agent_type=${(data.agent_type as string) ?? "unknown"} agent_id=${owner.instance_id.slice(0, 8)} platform=${adapterPlatform(adapter)}`,
             "--instance",
             owner.instance_id,
           ],
           { encoding: "utf8", timeout: 2000, env: childEnv(coordRoot) },
         );
       }
-      emitSubagentStartContext(coordRoot, owner.instance_id, sessionId, data, harness);
+      emitSubagentStartContext(coordRoot, owner.instance_id, sessionId, data, adapter);
     } catch (err) {
       logError(coordRoot, err, { phase: "subagent-start-project" });
     }
@@ -749,13 +748,13 @@ async function main(): Promise<number> {
   if (norm.event_type === "subagent.stop") {
     try {
       cleanupSessionEnd(coordRoot, owner.instance_id, (data.reason as string) ?? "unknown");
-      const agentCoordBin = join(coordRoot, "harnery", "bin", "agent-coord");
+      const agentCoordBin = coordBinPath("agent-coord", coordRoot) ?? "";
       if (existsSync(agentCoordBin)) {
         spawnSync(
           agentCoordBin,
           [
             "log",
-            `SUBAGENT_STOP   agent_id=${owner.instance_id.slice(0, 8)} platform=${harnessPlatform(harness)}`,
+            `SUBAGENT_STOP   agent_id=${owner.instance_id.slice(0, 8)} platform=${adapterPlatform(adapter)}`,
             "--instance",
             owner.instance_id,
           ],
@@ -768,11 +767,11 @@ async function main(): Promise<number> {
   }
 
   // Phase 8: UserPromptSubmit: render dedup'd peer table + council pending
-  // and emit the harness-shaped systemMessage JSON. Harness-agnostic since v0.5.0.
+  // and emit the adapter-shaped systemMessage JSON. Adapter-agnostic since v0.5.0.
   if (norm.event_type === "user_prompt.submit") {
     // Effects (claude-code): reset per-turn sound rate-limit counters + run
     // presence detection on the prompt.
-    if (harness === "claude-code") {
+    if (adapter === "claude-code") {
       resetSoundCounters(sessionId);
       const prompt = (payload?.raw?.prompt as string | undefined) ?? "";
       if (prompt) detectPresence(prompt);
@@ -805,7 +804,7 @@ async function main(): Promise<number> {
         coordRoot,
         owner.instance_id,
         sessionId,
-        harness,
+        adapter,
         recovery?.briefing ?? "",
       );
       if (injected && recovery) {
@@ -813,7 +812,7 @@ async function main(): Promise<number> {
           coordRoot,
           owner.instance_id,
           sessionId,
-          harness,
+          adapter,
           recovery,
           "UserPromptSubmit",
         );
@@ -824,7 +823,7 @@ async function main(): Promise<number> {
   }
 
   // turn.stop: telemetry + turn-summary effects, then the stop verdict. The
-  // verdict + codex-replay previously lived in the per-harness shell adapters;
+  // verdict + codex-replay previously lived in the per-adapter shell adapters;
   // agent-hook owns them now. Runs on the normal "stop" event only;
   // "stop-failure" (API error) gets no gate, matching the previous
   // stop vs stop-failure split.
@@ -833,7 +832,7 @@ async function main(): Promise<number> {
     // the status_checked / task_set / status_box_present evidence (codex
     // doesn't emit those live; this re-emits turn.stop after agent-hook's own,
     // so the verdict reads the replay's box signal as the latest).
-    if (harness === "codex" && payload?.transcript_path && existsSync(payload.transcript_path)) {
+    if (adapter === "codex" && payload?.transcript_path && existsSync(payload.transcript_path)) {
       try {
         replayCodexJsonl({
           coordRoot,
@@ -849,7 +848,7 @@ async function main(): Promise<number> {
 
     // CC effects: rate-limited session-telemetry sync + turn-summary Haiku
     // auto-summary.
-    if (harness === "claude-code") {
+    if (adapter === "claude-code") {
       runSessionSyncExtension(coordRoot, false);
       runTurnSummary(coordRoot, owner.instance_id, sessionId, payload?.transcript_path);
     }
@@ -857,7 +856,7 @@ async function main(): Promise<number> {
     // Master-state heartbeat projection. Drains events.ndjson since the last
     // cursor → per-owner heartbeats. Was a SECOND binary (`agent-coord project`)
     // pinned to Claude Code Stop only; folded in here so it (a) is one
-    // entry per event like everything else and (b) fires on EVERY harness's stop,
+    // entry per event like everything else and (b) fires on EVERY adapter's stop,
     // not just CC. Runs unconditionally before the verdict's possible exit-2 return
     // (the events are real regardless of whether the agent gets nagged), and after
     // codex-replay above so codex's replayed events are included in the drain.
@@ -888,22 +887,22 @@ async function main(): Promise<number> {
       rule: "stop-hook",
       instance_id: owner.instance_id,
       session_id: sessionId,
-      harness,
+      adapter,
       bypass: coordEnv("AGENT_COORD_BYPASS_STOP") === "1",
       workflow_child: coordEnv("WORKFLOW_CHILD") === "1",
     });
     if (!verdict.allow) {
-      // Harness-aware enforcement channel: Claude Code / Codex honor exit-2 +
+      // Adapter-aware enforcement channel: Claude Code / Codex honor exit-2 +
       // stderr as a turn block; Cursor ignores exit codes (fail-open) and
       // re-prompts only via a `followup_message` it auto-submits. emitStopBlock
       // writes the right shape and returns the exit code to use.
-      const { emitStopBlock } = await import("./harness/output.ts");
-      return emitStopBlock(harness, verdict);
+      const { emitStopBlock } = await import("./adapter/output.ts");
+      return emitStopBlock(adapter, verdict);
     }
   }
 
   // Phase 7: PreToolUse: heartbeat + pid-map self-heal on every tool call.
-  // Harness-agnostic: both writes have the same shape regardless of who fired.
+  // Adapter-agnostic: both writes have the same shape regardless of who fired.
   // Cursor/Codex bash dispatchers still fire their own G-guard logic, but the
   // heals here keep the agent-coord layer's view of liveness fresh.
   //
@@ -913,8 +912,8 @@ async function main(): Promise<number> {
   // call was restored here afterward.
   if (norm.event_type === "tool.pre_use") {
     try {
-      healHeartbeatViaCli(coordRoot, owner.instance_id, sessionId, harness);
-      refreshPidmap(coordRoot, owner.instance_id, harness, payload?.pid);
+      healHeartbeatViaCli(coordRoot, owner.instance_id, sessionId, adapter);
+      refreshPidmap(coordRoot, owner.instance_id, adapter, payload?.pid);
     } catch (err) {
       logError(coordRoot, err, { phase: "pre-tool-use-heal" });
     }
@@ -928,29 +927,29 @@ async function main(): Promise<number> {
         payload,
         instanceId: owner.instance_id,
         sessionId,
-        harness,
+        adapter,
       });
     } catch (err) {
       logError(coordRoot, err, { phase: "pre-tool-use-image-capture" });
     }
 
-    // G-guard for ALL harnesses. Claude Code previously ran this via a
+    // G-guard for ALL adapters. Claude Code previously ran this via a
     // pre-tool-use bash adapter (which called `agent-coord verdict --rule=claim`);
-    // that adapter is now deleted, so agent-hook owns the deny for every harness.
-    // emitDeny() inside emits the harness-shaped permission JSON (claude-code +
+    // that adapter is now deleted, so agent-hook owns the deny for every adapter.
+    // emitDeny() inside emits the adapter-shaped permission JSON (claude-code +
     // codex use hookSpecificOutput.permissionDecision; cursor uses .permission).
     // apply_patch (codex) parses paths from the patch body and runs verdict
     // per-path; Edit/Write/NotebookEdit resolve a single target. Non-write tools
     // (incl. Agent) yield no targets and pass through with no deny.
     try {
-      await runPreToolUseGuard(coordRoot, owner.instance_id, sessionId, data, harness);
+      await runPreToolUseGuard(coordRoot, owner.instance_id, sessionId, data, adapter);
     } catch (err) {
       logError(coordRoot, err, { phase: "pre-tool-use-guard" });
     }
 
     // Shell-mutation warn (warn-only, never blocks). Was the cursor
     // beforeShellExecution + codex preToolUse-Bash shell-mutation-claim-log in
-    // the per-harness shell adapters. Cursor sends the command at payload.command;
+    // the per-adapter shell adapters. Cursor sends the command at payload.command;
     // codex Bash at tool_input.command. Emits a decision.warn per candidate-mutated
     // path so a peer sees the write in events.ndjson. (CC never did this,
     // preserved; it emits with its own hooks-side emitter per the
@@ -958,7 +957,7 @@ async function main(): Promise<number> {
     const shellCmd =
       eventName === "before-shell-execution"
         ? ((payload?.raw.command as string | undefined) ?? "")
-        : harness === "codex" && data.tool_name === "Bash"
+        : adapter === "codex" && data.tool_name === "Bash"
           ? (((payload?.raw.tool_input as Record<string, unknown> | undefined)?.command as
               | string
               | undefined) ?? "")
@@ -967,13 +966,13 @@ async function main(): Promise<number> {
       try {
         const paths = shellMutationPaths(shellCmd, coordRoot);
         const truncated = shellCmd.length > 80 ? shellCmd.slice(0, 80) : shellCmd;
-        const platform = harnessPlatform(harness);
+        const platform = adapterPlatform(adapter);
         for (const p of paths) {
           emit(coordRoot, {
             event_type: "decision.warn",
             instance_id: owner.instance_id,
             session_id: sessionId,
-            harness,
+            adapter,
             data: {
               rule: "shell_mutation_candidate",
               reason: `path=${p} cmd=${truncated} platform=${platform}`,
@@ -988,7 +987,7 @@ async function main(): Promise<number> {
   }
 
   // Phase 7: PostToolUse: stamp last_tool + last_tool_target on heartbeat.
-  // Harness-agnostic for the same reason as tool.pre_use above.
+  // Adapter-agnostic for the same reason as tool.pre_use above.
   if (norm.event_type === "tool.post_use") {
     try {
       stampToolActivity(coordRoot, owner.instance_id, data);
@@ -1006,7 +1005,7 @@ async function main(): Promise<number> {
         payload,
         instanceId: owner.instance_id,
         sessionId,
-        harness,
+        adapter,
       });
     } catch (err) {
       logError(coordRoot, err, { phase: "post-tool-use-image-capture" });
@@ -1014,7 +1013,7 @@ async function main(): Promise<number> {
   }
 
   // Phase 7: PostToolUseFailure: release claim on failed Edit (the file
-  // never landed; the claim is stale). Harness-agnostic.
+  // never landed; the claim is stale). Adapter-agnostic.
   if (norm.event_type === "tool.post_use_failure") {
     try {
       releaseClaimOnFailure(coordRoot, owner.instance_id, data, payload?.raw);
@@ -1031,7 +1030,7 @@ async function runPreToolUseGuard(
   instanceId: string,
   sessionId: string,
   data: Record<string, unknown>,
-  harness: Harness,
+  adapter: Adapter,
 ): Promise<void> {
   const toolName = (data.tool_name as string | undefined) ?? "";
   const targets = collectGuardTargets(toolName, data)
@@ -1039,7 +1038,7 @@ async function runPreToolUseGuard(
     .filter((p): p is string => p !== null);
   if (targets.length === 0) return;
 
-  const agentCoordBin = join(coordRoot, "harnery", "bin", "agent-coord");
+  const agentCoordBin = coordBinPath("agent-coord", coordRoot) ?? "";
   if (!existsSync(agentCoordBin)) return;
 
   // For apply_patch (multi-file), collect siblings so the deny reason names
@@ -1075,8 +1074,8 @@ async function runPreToolUseGuard(
           reason += ` The patch also touched: ${siblings}: pick a different file or wait.`;
         }
       }
-      const { emitDeny } = await import("./harness/output.ts");
-      emitDeny(harness, reason);
+      const { emitDeny } = await import("./adapter/output.ts");
+      emitDeny(adapter, reason);
       return;
     }
   }
@@ -1142,15 +1141,15 @@ function healHeartbeatViaCli(
   coordRoot: string,
   instanceId: string,
   sessionId: string,
-  harness: string,
+  adapter: string,
 ): void {
-  const agentCoordBin = join(coordRoot, "harnery", "bin", "agent-coord");
+  const agentCoordBin = coordBinPath("agent-coord", coordRoot) ?? "";
   if (!existsSync(agentCoordBin)) return;
-  // Pass the detected harness so a pruned Cursor/Codex heartbeat is recreated
+  // Pass the detected adapter so a pruned Cursor/Codex heartbeat is recreated
   // with the correct platform; without it, healHeartbeat defaults to
   // claude_code and the dashboard mislabels the agent. See
   // heartbeat-writer.healHeartbeat.
-  spawnSync(agentCoordBin, ["heal-heartbeat", instanceId, sessionId, `--harness=${harness}`], {
+  spawnSync(agentCoordBin, ["heal-heartbeat", instanceId, sessionId, `--adapter=${adapter}`], {
     encoding: "utf8",
     timeout: 2000,
     env: childEnv(coordRoot),
@@ -1158,38 +1157,59 @@ function healHeartbeatViaCli(
 }
 
 /**
- * Walk up the ppid chain on Linux/WSL looking for the harness anchor PID,
+ * Walk up the ppid chain on Linux/WSL looking for the adapter anchor PID,
  * the PID of the claude / cursor / codex binary. Finds the agent PID. Used by
- * `tool.pre_use`'s pid-map self-heal so a re-parented harness binary (the
+ * `tool.pre_use`'s pid-map self-heal so a re-parented adapter binary (the
  * VS Code 2.1.x sibling-claude spawn case) gets its pid-map row rewritten on
  * the next tool call rather than going invisible until SessionStart fires
  * again, which it may never do.
  *
  * Returns undefined only when no anchor is found; callers fall back to
- * `process.ppid` (the bash wrapper's parent, which is usually the harness binary
+ * `process.ppid` (the bash wrapper's parent, which is usually the adapter binary
  * itself). `HARNERY_AGENT_COORD_TEST_ANCHOR_PID` overrides everything so the
  * test sandbox can pin a deterministic PID.
  */
-function findHarnessAnchorPid(harness?: Harness): number | undefined {
+function findAdapterAnchorPid(adapter?: Adapter): number | undefined {
   const override = coordEnv("AGENT_COORD_TEST_ANCHOR_PID");
   if (override) {
     const n = Number(override);
     if (Number.isFinite(n) && n > 0) return n;
   }
+  // A adapter that states its own pid ends the search. Nothing inferred from the
+  // process tree beats the adapter naming itself, and the inference is the part
+  // that has been failing: comm matching wants a binary called after its
+  // adapter, and one Claude Code build ships its CLI under a version-numbered
+  // filename, so the walk found nothing and the caller fell back to the hook's
+  // own shell. That row was dead within seconds, leaving every session in this
+  // environment unattributed.
+  const fromEnv = adapterPidFromEnv();
+  if (fromEnv) return fromEnv;
   // Build the ppid chain (nearest → root, up to 20 hops), then hand it to the
   // pure selector. Linux/WSL reads /proc; macOS/BSD (no /proc) falls back to
   // `ps -o ppid=,comm=` parsed by the unit-tested `parsePsChainLine`. Splitting
-  // the walk (untestable off a live box) from the comm-matching keeps the
-  // cursor `node`-fallback logic verifiable.
-  const chain: Array<{ pid: number; comm: string }> = [];
+  // the walk (untestable off a live box) from the matching keeps the selector
+  // logic verifiable.
+  //
+  // Only the /proc branch carries an executable path for the selector's
+  // path-based pass. Asking `ps` for one means either a second spawn per hop or
+  // splitting `comm` from `args` on a line where comm may itself contain spaces,
+  // and the adapter that needs the path pass states its pid in the env anyway.
+  const chain: Array<{ pid: number; comm: string; exe?: string }> = [];
   let pid = process.pid;
   for (let hops = 0; hops < 20; hops++) {
-    let hop: { comm: string; ppid: number } | null = null;
+    let hop: { comm: string; ppid: number; exe?: string } | null = null;
     try {
       const comm = readFileSync(`/proc/${pid}/comm`, "utf8").trim();
       const status = readFileSync(`/proc/${pid}/status`, "utf8");
       const m = status.match(/^PPid:\s+(\d+)/m);
-      hop = { comm, ppid: m ? Number(m[1]) : 0 };
+      // argv[0], for the path-based second pass. cmdline is NUL-separated.
+      let exe: string | undefined;
+      try {
+        exe = readFileSync(`/proc/${pid}/cmdline`, "utf8").split("\0")[0] || undefined;
+      } catch {
+        /* exe is optional */
+      }
+      hop = { comm, ppid: m ? Number(m[1]) : 0, exe };
     } catch {
       // no /proc (macOS/BSD) — fall through to ps
     }
@@ -1198,11 +1218,11 @@ function findHarnessAnchorPid(harness?: Harness): number | undefined {
       if (out.status === 0) hop = parsePsChainLine(out.stdout);
     }
     if (!hop) break;
-    chain.push({ pid, comm: hop.comm });
+    chain.push({ pid, comm: hop.comm, exe: hop.exe });
     if (!Number.isFinite(hop.ppid) || hop.ppid === 0 || hop.ppid === 1) break;
     pid = hop.ppid;
   }
-  return selectAnchorPid(chain, harness);
+  return selectAnchorPid(chain, adapter);
 }
 
 /**
@@ -1212,7 +1232,7 @@ function findHarnessAnchorPid(harness?: Harness): number | undefined {
  *
  * The pid argument prefers the payload's `pid` (CC populates it on
  * SessionStart and may also send it on PreToolUse), then
- * `findHarnessAnchorPid`, then `process.ppid`. Writes go through the same
+ * `findAdapterAnchorPid`, then `process.ppid`. Writes go through the same
  * idempotent `writePidmapViaAgentCoord` helper that SessionStart uses: no
  * disk I/O on no-op heals (when the row already points at us).
  *
@@ -1223,12 +1243,12 @@ function findHarnessAnchorPid(harness?: Harness): number | undefined {
 function refreshPidmap(
   coordRoot: string,
   instanceId: string,
-  harness: Harness,
+  adapter: Adapter,
   payloadPid?: number,
 ): void {
-  const pid = payloadPid ?? findHarnessAnchorPid(harness) ?? process.ppid;
+  const pid = payloadPid ?? findAdapterAnchorPid(adapter) ?? process.ppid;
   if (!Number.isFinite(pid) || pid <= 0) return;
-  writePidmapViaAgentCoord(coordRoot, pid, instanceId, harnessPlatform(harness));
+  writePidmapViaAgentCoord(coordRoot, pid, instanceId, adapterPlatform(adapter));
 }
 
 function stampToolActivity(
@@ -1236,7 +1256,7 @@ function stampToolActivity(
   instanceId: string,
   data: Record<string, unknown>,
 ): void {
-  const agentCoordBin = join(coordRoot, "harnery", "bin", "agent-coord");
+  const agentCoordBin = coordBinPath("agent-coord", coordRoot) ?? "";
   if (!existsSync(agentCoordBin)) return;
   const toolName = (data.tool_name as string | undefined) ?? "";
   // Extract a 1-line target from the tool_input blob (file path / command head).
@@ -1308,7 +1328,7 @@ function releaseClaimOnFailure(
       : filePath;
   }
 
-  const agentCoordBin = join(coordRoot, "harnery", "bin", "agent-coord");
+  const agentCoordBin = coordBinPath("agent-coord", coordRoot) ?? "";
   if (!existsSync(agentCoordBin)) return;
   spawnSync(agentCoordBin, ["release-claim", instanceId, canonical], {
     encoding: "utf8",
@@ -1349,7 +1369,7 @@ function cleanupSessionEnd(coordRoot: string, instanceId: string, reason: string
     }
   }
   // Activity log
-  const agentCoordBin = join(coordRoot, "harnery", "bin", "agent-coord");
+  const agentCoordBin = coordBinPath("agent-coord", coordRoot) ?? "";
   if (existsSync(agentCoordBin)) {
     spawnSync(
       agentCoordBin,
@@ -1363,10 +1383,10 @@ async function emitUserPromptSubmitSystemMessage(
   coordRoot: string,
   instanceId: string,
   sessionId: string,
-  harness: Harness,
+  adapter: Adapter,
   recoveryBriefing = "",
 ): Promise<boolean> {
-  const agentCoordBin = join(coordRoot, "harnery", "bin", "agent-coord");
+  const agentCoordBin = coordBinPath("agent-coord", coordRoot) ?? "";
   let additionalContext = "";
 
   if (existsSync(agentCoordBin)) {
@@ -1385,10 +1405,14 @@ async function emitUserPromptSubmitSystemMessage(
 
     const args = ["prompt-context", "--instance", instanceId, "--session", sessionId];
     if (agentName) args.push("--name", agentName);
-    // Cursor + Codex sessions get the set-task staleness nudge. CC enforces it
-    // via the Stop-hook transcript scan; the nudge replaces that for harnesses
-    // that don't reliably expose a transcript_path during stop.
-    if (harness === "cursor" || harness === "codex") args.push("--task-nudge");
+    // Every human-facing adapter gets the first-session naming reminder from
+    // the shared hook path. Cursor + Codex additionally get ongoing set-task
+    // staleness nudges; Claude Code enforces those via its Stop transcript.
+    // Codex gets a fresh status-footer reminder on every prompt. Its Stop hook
+    // stays observe-only, so missing the footer never replaces the answer.
+    args.push("--session-name-nudge");
+    if (adapter === "cursor" || adapter === "codex") args.push("--task-nudge");
+    if (adapter === "codex") args.push("--status-footer-nudge");
     const result = spawnSync(agentCoordBin, args, { encoding: "utf8", timeout: 3000 });
     if (result.status === 0 && result.stdout) additionalContext = result.stdout.trim();
   }
@@ -1397,8 +1421,8 @@ async function emitUserPromptSubmitSystemMessage(
   }
   if (!additionalContext) return false;
 
-  const { emitContext } = await import("./harness/output.ts");
-  emitContext(harness, "UserPromptSubmit", additionalContext);
+  const { emitContext } = await import("./adapter/output.ts");
+  emitContext(adapter, "UserPromptSubmit", additionalContext);
   return true;
 }
 
@@ -1407,14 +1431,14 @@ function emitSubagentStartContext(
   instanceId: string,
   sessionId: string,
   data: Record<string, unknown>,
-  harness: Harness,
+  adapter: Adapter,
 ): void {
   // Look up the subagent's assigned name (just-written by agent-coord assignName
   // in session.start data) + the parent's short id for the "you are a subagent
   // of X" framing.
   const subagentName = (data.name as string | undefined) ?? "";
   if (!subagentName) return;
-  const platformLabel = harnessPlatform(harness);
+  const platformLabel = adapterPlatform(adapter);
   const parentShort =
     sessionId && sessionId !== instanceId ? `agent-${sessionId.slice(0, 8)}` : "the parent session";
   const message = `You are agent-${subagentName} (${platformLabel} subagent). You're a subagent of ${parentShort}.`;
@@ -1422,7 +1446,7 @@ function emitSubagentStartContext(
   // Render peer table inline since the subagent might want to know who else
   // is around. Reuse prompt-context (which dedups against the per-owner hash);
   // first call will always emit.
-  const agentCoordBin = join(coordRoot, "harnery", "bin", "agent-coord");
+  const agentCoordBin = coordBinPath("agent-coord", coordRoot) ?? "";
   let combined = message;
   if (existsSync(agentCoordBin)) {
     const result = spawnSync(
@@ -1436,14 +1460,14 @@ function emitSubagentStartContext(
 
   // Use SubagentStart event-name in CC's hookSpecificOutput shape; cursor's
   // flat `additional_context` works the same way.
-  void import("./harness/output.ts").then(({ emitContext }) => {
-    emitContext(harness, "SubagentStart", combined);
+  void import("./adapter/output.ts").then(({ emitContext }) => {
+    emitContext(adapter, "SubagentStart", combined);
   });
 }
 
-function harnessPlatform(harness: Harness): string {
-  if (harness === "claude-code") return "claude_code";
-  return harness;
+function adapterPlatform(adapter: Adapter): string {
+  if (adapter === "claude-code") return "claude_code";
+  return adapter;
 }
 
 async function emitSessionStartSystemMessage(
@@ -1451,10 +1475,10 @@ async function emitSessionStartSystemMessage(
   instanceId: string,
   sessionId: string,
   emittedData: Record<string, unknown>,
-  harness: Harness,
+  adapter: Adapter,
   recoveryBriefing = "",
 ): Promise<boolean> {
-  const agentCoordBin = join(coordRoot, "harnery", "bin", "agent-coord");
+  const agentCoordBin = coordBinPath("agent-coord", coordRoot) ?? "";
   let additionalContext = "";
   if (existsSync(agentCoordBin)) {
     // Sync-project so the heartbeat exists for downstream readers (peer table,
@@ -1463,10 +1487,10 @@ async function emitSessionStartSystemMessage(
     // Stale-sweep dead peers before rendering peer table.
     spawnSync(agentCoordBin, ["stale-sweep"], { encoding: "utf8", timeout: 3000 });
 
-    // SESSION_START activity log line, fired across all harnesses.
+    // SESSION_START activity log line, fired across all adapters.
     const model = (emittedData.model as string | undefined) ?? "unknown";
     const source = (emittedData.source as string | undefined) ?? "startup";
-    const platform = harnessPlatform(harness);
+    const platform = adapterPlatform(adapter);
     spawnSync(
       agentCoordBin,
       [
@@ -1485,19 +1509,19 @@ async function emitSessionStartSystemMessage(
     // The "You are agent-X." prefix in session-context renders unqualified by
     // default (claude-code-style). For cursor/codex the bash dispatchers add
     // a "(Cursor)" / "(Codex)" suffix; pass it through as --platform-label.
-    if (harness !== "claude-code") {
+    if (adapter !== "claude-code") {
       args.push("--platform-label", platform === "cursor" ? "Cursor" : "Codex");
     }
     const result = spawnSync(agentCoordBin, args, { encoding: "utf8", timeout: 3000 });
     if (result.status === 0 && result.stdout) additionalContext = result.stdout.trim();
   }
 
-  // Effect (claude-code): merge the scratch recovery cue into the session-start
+  // Effect (claude-code): merge the journal recovery cue into the session-start
   // context. Was a standalone additionalContext emission from the previous
-  // scratch-on-start adapter; now that agent-hook is the single SessionStart
+  // journal-on-start adapter; now that agent-hook is the single SessionStart
   // entry, it folds in here.
-  if (harness === "claude-code") {
-    const cue = scratchRecoveryCue(coordRoot);
+  if (adapter === "claude-code") {
+    const cue = journalRecoveryCue(coordRoot);
     if (cue) additionalContext = [additionalContext, cue].filter(Boolean).join("\n\n");
   }
   if (recoveryBriefing) {
@@ -1505,8 +1529,8 @@ async function emitSessionStartSystemMessage(
   }
   if (!additionalContext) return false;
 
-  const { emitContext } = await import("./harness/output.ts");
-  emitContext(harness, "SessionStart", additionalContext);
+  const { emitContext } = await import("./adapter/output.ts");
+  emitContext(adapter, "SessionStart", additionalContext);
   return true;
 }
 
@@ -1514,7 +1538,7 @@ function completeRecoveryInjection(
   coordRoot: string,
   instanceId: string,
   sessionId: string,
-  harness: Harness,
+  adapter: Adapter,
   recovery: PreparedContextRecovery,
   injectionEvent: "SessionStart" | "UserPromptSubmit",
 ): void {
@@ -1523,7 +1547,7 @@ function completeRecoveryInjection(
     event_type: "context.recovery.injected",
     instance_id: instanceId,
     session_id: sessionId,
-    harness,
+    adapter,
     data: {
       capsule_id: recovery.capsule.capsule_id,
       generation: recovery.capsule.generation,