harnery 0.30.0 → 0.31.1

package/dist/core/hooks/cli.js

@@ -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,25 +15,27 @@
  * 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";
 import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { coordEnv } from "../../lib/env.js";
 import { replayCodexJsonl } from "../agents/codex-replay.js";
+import { coordBinPath } from "../agents/coord-bin.js";
 import { consumeSince, writeCursor } from "../agents/events/consume.js";
 import { evaluateStopHook } from "../agents/rules/stop-hook.js";
 import { projectHeartbeats } from "../agents/state/heartbeat-projector.js";
+import { writePidmapRow } from "../agents/state/pidmap.js";
 import { shellMutationPaths } from "../agents/state/shell-mutation.js";
 import { checkpointContext, completeContextRecovery, extractContextSample, markContextCompactionCompleted, prepareContextRecovery, readContextState, recordContextSample, } from "../context/index.js";
 import { ensureRelayDaemon, fetchPresence, publishPresence } from "../presence/index.js";
-import { captureImages, detectPresence, imageJanitor, playSound, resetSoundCounters, runSessionSyncExtension, runTurnSummary, scratchArchive, scratchJanitor, scratchRecoveryCue, soundForEvent, } from "./effects/index.js";
+import { detectAdapter } from "./adapter/detect.js";
+import { extractBashCommand, extractToolDescription, normalizeEventName, parsePayload, } from "./adapter/parse.js";
+import { captureImages, detectPresence, imageJanitor, journalArchive, journalJanitor, journalRecoveryCue, playSound, resetSoundCounters, runSessionSyncExtension, runTurnSummary, soundForEvent, } from "./effects/index.js";
 import { emit } from "./events/emit.js";
 import { canonicalize } from "./guard-path.js";
-import { detectHarness } from "./harness/detect.js";
-import { extractBashCommand, extractToolDescription, normalizeEventName, parsePayload, } from "./harness/parse.js";
-import { parsePsChainLine, selectAnchorPid } from "./resolve/anchor.js";
+import { adapterPidFromEnv, parsePsChainLine, selectAnchorPid } from "./resolve/anchor.js";
 import { findCoordRoot } from "./resolve/coord-root.js";
 import { extractIntentComment, resolveIntent } from "./resolve/intent.js";
 import { resolveOwner } from "./resolve/owner.js";
@@ -42,11 +44,11 @@ function parseArgv(argv) {
     const out = { 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="))
+        if (arg.startsWith("--adapter="))
             continue;
         if (!out.eventName && !arg.startsWith("--")) {
             out.eventName = arg;
@@ -74,7 +76,7 @@ async function readStdin() {
 /**
  * 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.
  */
@@ -111,13 +113,13 @@ function logError(coordRoot, err, context) {
 /**
  * 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.
  */
 function assignNameViaAgentCoord(coordRoot, instanceId, kind) {
-    const binary = join(coordRoot, "harnery", "bin", "agent-coord");
+    const binary = coordBinPath("agent-coord", coordRoot) ?? "";
     if (!existsSync(binary))
         return null;
     try {
@@ -139,35 +141,22 @@ function assignNameViaAgentCoord(coordRoot, instanceId, kind) {
     }
 }
 /**
- * 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, pid, instanceId, platform) {
     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 */
     }
 }
 function clampString(s, max) {
@@ -188,23 +177,23 @@ function buildEventData(eventType, ctx) {
     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(),
@@ -213,17 +202,25 @@ function buildEventData(eventType, ctx) {
                 // 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") }
+                            : {}),
+                    }
                     : {}),
             };
         }
@@ -239,7 +236,7 @@ function buildEventData(eventType, ctx) {
         }
         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),
@@ -363,13 +360,13 @@ function numberField(value) {
 }
 async function main() {
     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());
@@ -401,15 +398,15 @@ async function main() {
     const debugBase = {
         ts: new Date().toISOString(),
         event_name: eventName,
-        harness,
+        adapter,
         extra_argv: extra,
         payload_bytes: raw.length,
         cwd: process.cwd(),
         pid: process.pid,
         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;
     }
     const norm = normalizeEventName(eventName);
@@ -417,7 +414,7 @@ async function main() {
         appendDebug(coordRoot, { ...debugBase, skipped: "non-canonical-event" });
         return 0;
     }
-    const payload = parsePayload(raw, harness);
+    const payload = parsePayload(raw, adapter);
     const owner = resolveOwner({ payload: payload?.raw ?? null, coordRoot });
     if (!owner) {
         appendDebug(coordRoot, {
@@ -432,7 +429,7 @@ async function main() {
         coordRoot,
         payload,
         raw,
-        harness,
+        adapter,
         instanceId: owner.instance_id,
     });
     const envelope = emit(coordRoot, {
@@ -442,7 +439,7 @@ async function main() {
         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
     });
@@ -453,13 +450,13 @@ async function main() {
         event_id: envelope.event_id,
     });
     // 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",
@@ -471,7 +468,7 @@ async function main() {
                         event_type: "context.sampled",
                         instance_id: owner.instance_id,
                         session_id: sessionId,
-                        harness,
+                        adapter,
                         data: {
                             model: sample.model,
                             used_tokens: sample.used_tokens,
@@ -490,13 +487,13 @@ async function main() {
     }
     // 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,
@@ -505,7 +502,7 @@ async function main() {
                 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,
@@ -531,18 +528,18 @@ async function main() {
         }
     }
     // 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);
@@ -557,7 +554,7 @@ async function main() {
                     event_type: "context.compaction.completed",
                     instance_id: owner.instance_id,
                     session_id: sessionId,
-                    harness,
+                    adapter,
                     data: { trigger: "auto" },
                 });
                 markContextCompactionCompleted(coordRoot, {
@@ -575,9 +572,9 @@ async function main() {
             }
         }
         try {
-            const injected = await emitSessionStartSystemMessage(coordRoot, owner.instance_id, sessionId, data, harness, recovery?.briefing ?? "");
+            const injected = await emitSessionStartSystemMessage(coordRoot, owner.instance_id, sessionId, data, adapter, recovery?.briefing ?? "");
             if (injected && recovery) {
-                completeRecoveryInjection(coordRoot, owner.instance_id, sessionId, harness, recovery, "SessionStart");
+                completeRecoveryInjection(coordRoot, owner.instance_id, sessionId, adapter, recovery, "SessionStart");
             }
         }
         catch (err) {
@@ -595,7 +592,7 @@ async function main() {
             logError(coordRoot, err, { phase: "session-start-presence" });
         }
     }
-    // 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 {
@@ -604,10 +601,10 @@ async function main() {
         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
@@ -624,7 +621,7 @@ async function main() {
     // 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",
@@ -633,12 +630,12 @@ async function main() {
                 });
                 spawnSync(agentCoordBin, [
                     "log",
-                    `SUBAGENT_START  agent_type=${data.agent_type ?? "unknown"} agent_id=${owner.instance_id.slice(0, 8)} platform=${harnessPlatform(harness)}`,
+                    `SUBAGENT_START  agent_type=${data.agent_type ?? "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" });
@@ -648,11 +645,11 @@ async function main() {
     if (norm.event_type === "subagent.stop") {
         try {
             cleanupSessionEnd(coordRoot, owner.instance_id, data.reason ?? "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,
                 ], { encoding: "utf8", timeout: 2000, env: childEnv(coordRoot) });
@@ -663,11 +660,11 @@ async function main() {
         }
     }
     // 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 ?? "";
             if (prompt)
@@ -697,9 +694,9 @@ async function main() {
             }
         }
         try {
-            const injected = await emitUserPromptSubmitSystemMessage(coordRoot, owner.instance_id, sessionId, harness, recovery?.briefing ?? "");
+            const injected = await emitUserPromptSubmitSystemMessage(coordRoot, owner.instance_id, sessionId, adapter, recovery?.briefing ?? "");
             if (injected && recovery) {
-                completeRecoveryInjection(coordRoot, owner.instance_id, sessionId, harness, recovery, "UserPromptSubmit");
+                completeRecoveryInjection(coordRoot, owner.instance_id, sessionId, adapter, recovery, "UserPromptSubmit");
             }
         }
         catch (err) {
@@ -707,7 +704,7 @@ async function main() {
         }
     }
     // 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.
@@ -716,7 +713,7 @@ async function main() {
         // 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,
@@ -732,14 +729,14 @@ async function main() {
         }
         // 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);
         }
         // 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.
@@ -771,21 +768,21 @@ async function main() {
             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.js");
-            return emitStopBlock(harness, verdict);
+            const { emitStopBlock } = await import("./adapter/output.js");
+            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.
     //
@@ -795,8 +792,8 @@ async function main() {
     // 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" });
@@ -810,49 +807,49 @@ async function main() {
                 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
         // independent-emitter rule.)
         const shellCmd = eventName === "before-shell-execution"
             ? (payload?.raw.command ?? "")
-            : harness === "codex" && data.tool_name === "Bash"
+            : adapter === "codex" && data.tool_name === "Bash"
                 ? (payload?.raw.tool_input?.command ?? "")
                 : "";
         if (shellCmd) {
             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}`,
@@ -867,7 +864,7 @@ async function main() {
         }
     }
     // 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);
@@ -885,7 +882,7 @@ async function main() {
                 payload,
                 instanceId: owner.instance_id,
                 sessionId,
-                harness,
+                adapter,
             });
         }
         catch (err) {
@@ -893,7 +890,7 @@ async function main() {
         }
     }
     // 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);
@@ -904,14 +901,14 @@ async function main() {
     }
     return 0;
 }
-async function runPreToolUseGuard(coordRoot, instanceId, sessionId, data, harness) {
+async function runPreToolUseGuard(coordRoot, instanceId, sessionId, data, adapter) {
     const toolName = data.tool_name ?? "";
     const targets = collectGuardTargets(toolName, data)
         .map((p) => canonicalize(coordRoot, p))
         .filter((p) => 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
@@ -949,8 +946,8 @@ async function runPreToolUseGuard(coordRoot, instanceId, sessionId, data, harnes
                     reason += ` The patch also touched: ${siblings}: pick a different file or wait.`;
                 }
             }
-            const { emitDeny } = await import("./harness/output.js");
-            emitDeny(harness, reason);
+            const { emitDeny } = await import("./adapter/output.js");
+            emitDeny(adapter, reason);
             return;
         }
     }
@@ -1011,45 +1008,60 @@ function parseApplyPatchPaths(data) {
     }
     return out;
 }
-function healHeartbeatViaCli(coordRoot, instanceId, sessionId, harness) {
-    const agentCoordBin = join(coordRoot, "harnery", "bin", "agent-coord");
+function healHeartbeatViaCli(coordRoot, instanceId, sessionId, adapter) {
+    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),
     });
 }
 /**
- * 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) {
+function findAdapterAnchorPid(adapter) {
     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.
+    // 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 = [];
     let pid = process.pid;
     for (let hops = 0; hops < 20; hops++) {
@@ -1058,7 +1070,15 @@ function findHarnessAnchorPid(harness) {
             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;
+            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
@@ -1070,12 +1090,12 @@ function findHarnessAnchorPid(harness) {
         }
         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);
 }
 /**
  * Pid-map self-heal for `tool.pre_use`. Symmetric counterpart to
@@ -1084,7 +1104,7 @@ function findHarnessAnchorPid(harness) {
  *
  * 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).
  *
@@ -1092,14 +1112,14 @@ function findHarnessAnchorPid(harness) {
  * `harn agents heal-events` pidmap counts meaningful. The inline helper does
  * not yet.
  */
-function refreshPidmap(coordRoot, instanceId, harness, payloadPid) {
-    const pid = payloadPid ?? findHarnessAnchorPid(harness) ?? process.ppid;
+function refreshPidmap(coordRoot, instanceId, adapter, payloadPid) {
+    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(coordRoot, instanceId, data) {
-    const agentCoordBin = join(coordRoot, "harnery", "bin", "agent-coord");
+    const agentCoordBin = coordBinPath("agent-coord", coordRoot) ?? "";
     if (!existsSync(agentCoordBin))
         return;
     const toolName = data.tool_name ?? "";
@@ -1169,7 +1189,7 @@ function releaseClaimOnFailure(coordRoot, instanceId, data, rawPayload) {
             ? filePath.slice(coordRoot.length + 1)
             : 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], {
@@ -1213,13 +1233,13 @@ function cleanupSessionEnd(coordRoot, instanceId, reason) {
         }
     }
     // Activity log
-    const agentCoordBin = join(coordRoot, "harnery", "bin", "agent-coord");
+    const agentCoordBin = coordBinPath("agent-coord", coordRoot) ?? "";
     if (existsSync(agentCoordBin)) {
         spawnSync(agentCoordBin, ["log", `SESSION_END     reason=${reason}`, "--instance", instanceId], { encoding: "utf8", timeout: 2000 });
     }
 }
-async function emitUserPromptSubmitSystemMessage(coordRoot, instanceId, sessionId, harness, recoveryBriefing = "") {
-    const agentCoordBin = join(coordRoot, "harnery", "bin", "agent-coord");
+async function emitUserPromptSubmitSystemMessage(coordRoot, instanceId, sessionId, adapter, recoveryBriefing = "") {
+    const agentCoordBin = coordBinPath("agent-coord", coordRoot) ?? "";
     let additionalContext = "";
     if (existsSync(agentCoordBin)) {
         // Look up the agent's name from its heartbeat (for council pending rendering).
@@ -1238,11 +1258,16 @@ async function emitUserPromptSubmitSystemMessage(coordRoot, instanceId, sessionI
         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")
+        // 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();
@@ -1252,24 +1277,24 @@ async function emitUserPromptSubmitSystemMessage(coordRoot, instanceId, sessionI
     }
     if (!additionalContext)
         return false;
-    const { emitContext } = await import("./harness/output.js");
-    emitContext(harness, "UserPromptSubmit", additionalContext);
+    const { emitContext } = await import("./adapter/output.js");
+    emitContext(adapter, "UserPromptSubmit", additionalContext);
     return true;
 }
-function emitSubagentStartContext(coordRoot, instanceId, sessionId, data, harness) {
+function emitSubagentStartContext(coordRoot, instanceId, sessionId, data, adapter) {
     // 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 ?? "";
     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}.`;
     // 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(agentCoordBin, ["prompt-context", "--instance", instanceId, "--session", sessionId, "--name", subagentName], { encoding: "utf8", timeout: 3000 });
@@ -1279,17 +1304,17 @@ function emitSubagentStartContext(coordRoot, instanceId, sessionId, data, harnes
     }
     // Use SubagentStart event-name in CC's hookSpecificOutput shape; cursor's
     // flat `additional_context` works the same way.
-    void import("./harness/output.js").then(({ emitContext }) => {
-        emitContext(harness, "SubagentStart", combined);
+    void import("./adapter/output.js").then(({ emitContext }) => {
+        emitContext(adapter, "SubagentStart", combined);
     });
 }
-function harnessPlatform(harness) {
-    if (harness === "claude-code")
+function adapterPlatform(adapter) {
+    if (adapter === "claude-code")
         return "claude_code";
-    return harness;
+    return adapter;
 }
-async function emitSessionStartSystemMessage(coordRoot, instanceId, sessionId, emittedData, harness, recoveryBriefing = "") {
-    const agentCoordBin = join(coordRoot, "harnery", "bin", "agent-coord");
+async function emitSessionStartSystemMessage(coordRoot, instanceId, sessionId, emittedData, adapter, recoveryBriefing = "") {
+    const agentCoordBin = coordBinPath("agent-coord", coordRoot) ?? "";
     let additionalContext = "";
     if (existsSync(agentCoordBin)) {
         // Sync-project so the heartbeat exists for downstream readers (peer table,
@@ -1297,10 +1322,10 @@ async function emitSessionStartSystemMessage(coordRoot, instanceId, sessionId, e
         spawnSync(agentCoordBin, ["project"], { encoding: "utf8", timeout: 3000 });
         // 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 ?? "unknown";
         const source = emittedData.source ?? "startup";
-        const platform = harnessPlatform(harness);
+        const platform = adapterPlatform(adapter);
         spawnSync(agentCoordBin, [
             "log",
             `SESSION_START   model=${model} source=${source} platform=${platform}`,
@@ -1315,19 +1340,19 @@ async function emitSessionStartSystemMessage(coordRoot, instanceId, sessionId, e
         // 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");
     }
@@ -1336,17 +1361,17 @@ async function emitSessionStartSystemMessage(coordRoot, instanceId, sessionId, e
     }
     if (!additionalContext)
         return false;
-    const { emitContext } = await import("./harness/output.js");
-    emitContext(harness, "SessionStart", additionalContext);
+    const { emitContext } = await import("./adapter/output.js");
+    emitContext(adapter, "SessionStart", additionalContext);
     return true;
 }
-function completeRecoveryInjection(coordRoot, instanceId, sessionId, harness, recovery, injectionEvent) {
+function completeRecoveryInjection(coordRoot, instanceId, sessionId, adapter, recovery, injectionEvent) {
     completeContextRecovery(coordRoot, { sessionId, instanceId });
     emit(coordRoot, {
         event_type: "context.recovery.injected",
         instance_id: instanceId,
         session_id: sessionId,
-        harness,
+        adapter,
         data: {
             capsule_id: recovery.capsule.capsule_id,
             generation: recovery.capsule.generation,