harnery 0.30.0 → 0.31.0

package/src/core/agents/render/prompt-context.ts

@@ -1,19 +1,25 @@
 /**
  * UserPromptSubmit UX renderer. Combines the peer-refresh dedup, the
- * council-pending hash-dedup, and the Cursor set-task staleness nudge.
+ * council-pending hash-dedup, the cross-adapter first-session naming nudge,
+ * the Cursor/Codex set-task staleness nudge, and the Codex status-footer
+ * reminder.
  * agent-hook's user_prompt.submit post-emit handler calls this
- * and forwards the result as the harness-shaped additionalContext payload.
+ * and forwards the result as the adapter-shaped additionalContext payload.
  *
- * Three hash-dedup'd subsections combined into one additionalContext payload:
+ * Four subsections combined into one additionalContext payload:
  *   1. Peer table: semantically-relevant peer fields hashed; only re-emits
  *      when peers change (name + instance_id + session_id + kind + started_at
  *      + sorted(files_touched) + platform, sorted by instance_id).
  *   2. Council pending: pending open-council IDs hashed; re-emits when the
  *      ID set changes.
- *   3. Task staleness nudge (cursor only, since CC enforces via the Stop hook
- *      transcript scan). Fires when `task` is null or `task_updated_at` is
- *      older than HARNERY_TASK_STALE_SECONDS (default 1800 = 30 min). Hash-deduped
- *      against the previous nudge state.
+ *   3. Focus nudge. Before the first set-task in a human-facing session, tells
+ *      every adapter to reproduce set-task's suggested session name in a fenced
+ *      code block. Cursor/Codex additionally get the existing unset/stale-task
+ *      reminder because their Stop hooks do not enforce task declarations as
+ *      reliably as Claude Code's.
+ *   4. Codex status footer: a non-deduplicated reminder to put the live status
+ *      box after the substantive answer. Stop stays observe-only, so missing the
+ *      footer can never trigger a replacement response.
  *
  * Hash files live at:
  *   .harnery/.last-peer-hash.<instance_id>
@@ -36,6 +42,7 @@ import {
 import { join } from "node:path";
 
 import { coordEnv } from "../../../lib/env.ts";
+import { resolveBinName } from "../../config.ts";
 import { type RemoteMachine, readRemoteMachines } from "../../presence/index.ts";
 import { formatPendingCouncils } from "./session-context.ts";
 
@@ -51,7 +58,9 @@ interface HeartbeatRow {
   files_touched?: string[];
   platform?: string;
   task?: string;
+  task_updated_at?: string;
   turn_summary?: string;
+  workflow_run_id?: string;
 }
 
 export interface PromptContextOpts {
@@ -59,9 +68,15 @@ export interface PromptContextOpts {
   instanceId: string;
   sessionId: string;
   agentName?: string;
-  /** When true, run the task-staleness nudge check (cursor only; CC has the
-   * Stop-hook transcript-scan enforcement). */
+  /** When true, remind a human-facing session to print the session name before
+   * its first set-task. UserPromptSubmit enables this for every adapter. */
+  sessionNameNudge?: boolean;
+  /** When true, run the unset/stale-task check after the first set-task.
+   * Cursor/Codex use this; Claude Code has Stop-hook transcript enforcement. */
   taskNudge?: boolean;
+  /** When true, append the non-deduplicated Codex status-footer reminder.
+   * The caller enables this only for human-facing Codex sessions. */
+  statusFooterNudge?: boolean;
 }
 
 /**
@@ -73,7 +88,15 @@ export interface PromptContextOpts {
  * councils are pending, matching the bash behavior).
  */
 export function renderPromptContext(opts: PromptContextOpts): string {
-  const { coordRoot, instanceId, sessionId, agentName, taskNudge } = opts;
+  const {
+    coordRoot,
+    instanceId,
+    sessionId,
+    agentName,
+    sessionNameNudge,
+    taskNudge,
+    statusFooterNudge,
+  } = opts;
   const sections: string[] = [];
 
   // 1. Peer table with hash dedup.
@@ -86,62 +109,107 @@ export function renderPromptContext(opts: PromptContextOpts): string {
     if (councilMsg) sections.push(councilMsg);
   }
 
-  // 3. Task staleness nudge (cursor only).
-  if (taskNudge) {
-    const nudgeMsg = computeTaskNudgeIfChanged(coordRoot, instanceId);
+  // 3. First-session naming for every adapter, plus unset/stale-task reminders
+  // for Cursor/Codex. One state machine avoids a second generic "task unset"
+  // reminder immediately after the first-session reminder has been deduped.
+  if (sessionNameNudge || taskNudge) {
+    const nudgeMsg = computeFocusNudgeIfChanged(coordRoot, instanceId, {
+      sessionNameNudge: sessionNameNudge ?? false,
+      taskNudge: taskNudge ?? false,
+    });
     if (nudgeMsg) sections.push(nudgeMsg);
   }
 
+  // 4. Codex gets this on every prompt. It is intentionally not hash-deduped:
+  // the reminder must be fresh in the model's context when it writes the reply.
+  // Missing it is harmless because Codex Stop enforcement remains observe-only.
+  if (statusFooterNudge) {
+    const statusMsg = renderStatusFooterReminder(coordRoot, instanceId);
+    if (statusMsg) sections.push(statusMsg);
+  }
+
   return sections.join("\n\n");
 }
 
-/** The set-task staleness nudge for Cursor.
- * Emits a one-line reminder when `task` is null or `task_updated_at` is older
- * than HARNERY_TASK_STALE_SECONDS (default 1800). Hash-deduped against previous
- * nudge state. */
-function computeTaskNudgeIfChanged(coordRoot: string, selfInstanceId: string): string {
+function renderStatusFooterReminder(coordRoot: string, selfInstanceId: string): string {
+  const hb = readHeartbeat(join(coordRoot, ".harnery", "active", `${selfInstanceId}.json`));
+  if (!hb || hb.kind === "subagent" || hb.kind === "transient" || hb.workflow_run_id) return "";
+
+  const bin = resolveBinName(coordRoot);
+  return (
+    "Codex status footer: complete the user's request first. " +
+    `Then run \`${bin} agents status\` as your final shell call and append its stdout verbatim in a fenced code block at the bottom of the same substantive reply. ` +
+    "Keep the answer intact. If the footer is missed, do not retry or replace the reply; the Stop hook is observe-only."
+  );
+}
+
+/**
+ * First-session naming for every adapter, followed by Cursor/Codex task
+ * staleness checks. The absence of `task_updated_at` is the same invariant
+ * `agents set-task` uses for `first_of_session`; clears still stamp the field.
+ */
+function computeFocusNudgeIfChanged(
+  coordRoot: string,
+  selfInstanceId: string,
+  opts: { sessionNameNudge: boolean; taskNudge: boolean },
+): string {
   const hbPath = join(coordRoot, ".harnery", "active", `${selfInstanceId}.json`);
   if (!existsSync(hbPath)) return "";
-  let hb: { task?: string; task_updated_at?: string };
+  let hb: HeartbeatRow;
   try {
     hb = JSON.parse(readFileSync(hbPath, "utf8"));
   } catch {
     return "";
   }
 
+  const hashFile = join(coordRoot, ".harnery", `.last-task-nudge-hash.${selfInstanceId}`);
+  // Subagents and workflow children have no human-owned session/tab to rename.
+  if (hb.kind === "subagent" || hb.kind === "transient" || hb.workflow_run_id) {
+    clearHashFile(hashFile);
+    return "";
+  }
+
+  const bin = resolveBinName(coordRoot);
   const threshold = Number.parseInt(coordEnv("TASK_STALE_SECONDS") ?? "1800", 10);
   const taskValue = hb.task ?? "";
   let needsNudge = false;
   let message = "";
+  let nudgeKind = "";
 
-  if (!taskValue) {
+  if (opts.sessionNameNudge && !hb.task_updated_at) {
+    needsNudge = true;
+    nudgeKind = "session-name";
+    message =
+      `New session: run \`${bin} agents set-task "<2-5 word session topic>"\` as your first tool call. ` +
+      "When it returns `first_of_session: true`, reproduce its `suggested_session_name` value by itself inside a fenced code block at the very top of your reply so the operator can one-click-copy it as the session/tab title. " +
+      "Then continue with the task; that first `set-task` also satisfies this turn's focus declaration.";
+  } else if (opts.taskNudge && !taskValue) {
     needsNudge = true;
+    nudgeKind = "task-unset";
     message =
-      "Heads up: your `task` field is unset. Run `agents set-task \"<short focus>\"` so peers + the coord dashboard can see what you're working on. (Cursor sessions can't enforce this from the Stop hook the way Claude Code does, so this is a one-time soft reminder per staleness state.)";
-  } else if (hb.task_updated_at) {
+      `Heads up: your \`task\` field is unset. Run \`${bin} agents set-task "<short focus>"\` so peers + the coord dashboard can see what you're working on. ` +
+      "(This adapter cannot enforce the declaration from its Stop hook as reliably as Claude Code, so this is a one-time soft reminder per staleness state.)";
+  } else if (opts.taskNudge && hb.task_updated_at) {
     const updatedSec = Math.floor(Date.parse(hb.task_updated_at) / 1000);
     const nowSec = Math.floor(Date.now() / 1000);
     if (Number.isFinite(updatedSec) && updatedSec > 0) {
       const ageSec = nowSec - updatedSec;
       if (ageSec > threshold) {
         needsNudge = true;
-        message = `Heads up: your \`task\` field hasn't changed in ${ageSec}s (threshold ${threshold}s). If you've moved on from "${taskValue.slice(0, 60)}", update via \`agents set-task "<new focus>"\`. Pass an empty string to clear.`;
+        nudgeKind = "task-stale";
+        message = `Heads up: your \`task\` field hasn't changed in ${ageSec}s (threshold ${threshold}s). If you've moved on from "${taskValue.slice(0, 60)}", update via \`${bin} agents set-task "<new focus>"\`. Pass an empty string to clear.`;
       }
     }
   }
 
-  const hashFile = join(coordRoot, ".harnery", `.last-task-nudge-hash.${selfInstanceId}`);
   if (!needsNudge) {
-    try {
-      if (existsSync(hashFile)) rmSync(hashFile, { force: true });
-    } catch {
-      /* swallow */
-    }
+    clearHashFile(hashFile);
     return "";
   }
 
-  // Dedup on a state-hash (task value + threshold) so same-state turns don't re-nudge.
-  const state = `${taskValue}|stale=1|threshold=${threshold}`;
+  // Dedup on kind + task state so the first-session reminder does not turn into
+  // a generic "task unset" reminder on the next prompt before set-task runs.
+  const state = `${nudgeKind}|task=${taskValue}|updated=${hb.task_updated_at ?? ""}|threshold=${threshold}`;
   const newHash = sha256Hex16(state);
   const oldHash = safeRead(hashFile);
   if (oldHash && oldHash === newHash) return "";
@@ -325,6 +393,14 @@ function safeRead(path: string): string {
   }
 }
 
+function clearHashFile(path: string): void {
+  try {
+    if (existsSync(path)) rmSync(path, { force: true });
+  } catch {
+    /* swallow */
+  }
+}
+
 function sha256Hex16(input: string): string {
   return createHash("sha256").update(input).digest("hex").slice(0, 16);
 }

package/src/core/agents/render/session-context.ts

@@ -11,7 +11,7 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { resolveBinName, resolveHooksSetupHint } from "../../config.ts";
-import { harneryVersion, loadHarnessWiring } from "../../hooks/harness/wiring.ts";
+import { harneryVersion, loadAdapterWiring } from "../../hooks/adapter/wiring.ts";
 import { readRemoteMachines } from "../../presence/index.ts";
 
 interface HeartbeatRow {
@@ -34,7 +34,7 @@ export interface RenderOpts {
   instanceId: string;
   sessionId: string;
   agentName?: string;
-  /** Harness label rendered in parens after the self-name (e.g. "Cursor", "Codex").
+  /** Adapter label rendered in parens after the self-name (e.g. "Cursor", "Codex").
    * Claude Code omits it. */
   platformLabel?: string;
 }
@@ -84,11 +84,11 @@ export function renderSessionContext(opts: RenderOpts): string {
     messages.push(wiringSummary);
   }
 
-  // 5. Harness-hook drift: a harnery upgrade changed the hook set, but this
-  // project's settings file hasn't been re-wired. Only fires for a harness the
+  // 5. Adapter-hook drift: a harnery upgrade changed the hook set, but this
+  // project's settings file hasn't been re-wired. Only fires for a adapter the
   // project already opted into (≥1 hook wired), so it never nags a project that
   // simply has a settings file. Remedy is always `<bin> init` (idempotent).
-  const drift = loadHarnessWiring(coordRoot);
+  const drift = loadAdapterWiring(coordRoot);
   if (drift.length > 0) {
     const bin = resolveBinName(coordRoot);
     const ver = harneryVersion();
@@ -101,7 +101,7 @@ export function renderSessionContext(opts: RenderOpts): string {
       return `  - ${d.settingsFile} — ${bits.join("; ")}`;
     });
     messages.push(
-      `Harnery hook wiring is out of date${verPart}: an upgrade changed the hook set but the harness ` +
+      `Harnery hook wiring is out of date${verPart}: an upgrade changed the hook set but the adapter ` +
         `settings file hasn't been re-wired, so the new hook(s) won't fire. Run \`${bin} init\` to wire them ` +
         `(idempotent, additive).\n${lines.join("\n")}`,
     );

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

@@ -21,12 +21,9 @@ import { emit } from "../events/emit.ts";
 
 const FRESHNESS_SECS = 600;
 
-export type VerdictResult = {
-  allow: boolean;
-  exit_code: 0 | 2;
-  rule: string;
-  reason?: string;
-};
+export type { VerdictResult } from "./verdict.ts";
+
+import type { VerdictResult } from "./verdict.ts";
 
 interface PeerView {
   instance_id: string;
@@ -329,7 +326,7 @@ function pruneClaimFromPeer(coordRoot: string, instanceId: string, relPath: stri
         event_type: "claim.release",
         instance_id: instanceId,
         session_id: (body.session_id as string | undefined) ?? instanceId,
-        harness: platform === "cursor" ? "cursor" : platform === "codex" ? "codex" : "claude-code",
+        adapter: platform === "cursor" ? "cursor" : platform === "codex" ? "codex" : "claude-code",
         source: "agent-coord",
         data: { path: target, reason: "heal" },
         // eslint-disable-next-line @typescript-eslint/consistent-type-assertions

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

@@ -21,8 +21,8 @@
  */
 
 import { spawnSync } from "node:child_process";
-import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { appendFileSync, existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
 import { coordFreshnessSeconds } from "../../config.ts";
 import { instanceHasLivePid } from "../state/pidmap.ts";
 
@@ -198,12 +198,38 @@ function findOverlap(
   return null;
 }
 
+/**
+ * Repository-discovery environment that git exports to its own hooks.
+ *
+ * A hook runs with GIT_DIR (and friends) already pointing at the repository
+ * being committed, and every child inherits them. That silently outranks `cwd`,
+ * so a probe launched from some other directory still interrogates the hook's
+ * repository. Committing inside a submodule therefore asked the submodule about
+ * superproject paths and vice versa, and the answers were wrong in whichever
+ * direction did not match. Scrubbing these lets git rediscover the repository
+ * from `cwd`, which is the whole point of choosing a `cwd` per path.
+ */
+const GIT_DISCOVERY_VARS = [
+  "GIT_DIR",
+  "GIT_WORK_TREE",
+  "GIT_COMMON_DIR",
+  "GIT_INDEX_FILE",
+  "GIT_OBJECT_DIRECTORY",
+  "GIT_ALTERNATE_OBJECT_DIRECTORIES",
+  "GIT_PREFIX",
+  "GIT_NAMESPACE",
+] as const;
+
+/** Run a read-only git probe in `cwd`, free of the caller's repo environment. */
+function gitProbe(args: string[], cwd: string): { status: number; stdout: string } {
+  const env = { ...process.env };
+  for (const v of GIT_DISCOVERY_VARS) delete env[v];
+  const result = spawnSync("git", args, { cwd, env, encoding: "utf8", timeout: 2000 });
+  return { status: result.status ?? 1, stdout: result.stdout ?? "" };
+}
+
 function isGitlinkInIndex(coordRoot: string, path: string): boolean {
-  const result = spawnSync("git", ["ls-files", "--stage", "--", path], {
-    cwd: coordRoot,
-    encoding: "utf8",
-    timeout: 2000,
-  });
+  const result = gitProbe(["ls-files", "--stage", "--", path], coordRoot);
   if (result.status !== 0) return false;
   // ls-files --stage emits "<mode> <sha> <stage>\t<path>"; mode 160000 = gitlink.
   return result.stdout.trim().startsWith("160000 ");
@@ -216,21 +242,73 @@ function isHolderSelfAttributed(
   peers: readonly PeerHeartbeat[],
 ): boolean {
   // Gate B (cheaper): live foreign pid-map entry blocks self-attribution.
-  if (holderHasLiveForeignPid(coordRoot, holderId)) return false;
+  if (holderHasLiveForeignPid(coordRoot, holderId)) {
+    debugGate(coordRoot, { holder: holderId, gate: "B", reason: "live_pid_anchor" });
+    return false;
+  }
 
   // Gate A: every held path is either in the staged set or already clean in HEAD.
   const holder = peers.find((p) => p.instance_id === holderId);
-  if (!holder) return false;
+  if (!holder) {
+    debugGate(coordRoot, { holder: holderId, gate: "A", reason: "holder_not_found" });
+    return false;
+  }
   const files = holder.files_touched ?? [];
-  if (files.length === 0) return false;
+  if (files.length === 0) {
+    debugGate(coordRoot, { holder: holderId, gate: "A", reason: "holder_holds_nothing" });
+    return false;
+  }
   for (const held of files) {
     if (stagedSet.has(held)) continue;
     if (isPathCleanInHead(coordRoot, held)) continue;
+    if (isPathIgnoredByGit(coordRoot, held)) continue;
+    debugGate(coordRoot, { holder: holderId, gate: "A", reason: "path_unverifiable", path: held });
     return false;
   }
   return true;
 }
 
+/**
+ * Append one line explaining a refused gate, when HARNERY_COORD_DEBUG is set.
+ *
+ * Worth carrying permanently: the deciding state lives inside a git hook, whose
+ * stderr the caller discards and whose process is gone before anyone can look.
+ * Reconstructing a refusal afterwards means guessing, because the holder's claim
+ * set has moved on by then. This turns that into evidence.
+ */
+function debugGate(coordRoot: string, detail: Record<string, string>): void {
+  if (!process.env.HARNERY_COORD_DEBUG) return;
+  try {
+    appendFileSync(
+      join(coordRoot, ".harnery", "coord-debug.ndjson"),
+      `${JSON.stringify({ event: "self_attribution_refused", pid: process.pid, ...detail })}\n`,
+      "utf8",
+    );
+  } catch {
+    /* diagnostics never break a verdict */
+  }
+}
+
+/**
+ * Does git ignore this path?
+ *
+ * Such a claim is safe to look past. Agents write journal files into ignored
+ * directories constantly, and each one used to leave a claim that Gate A could
+ * never vouch for: not staged, not tracked, therefore "unknown", therefore
+ * blocked. That defeated self-attribution for the rest of a session and taught
+ * agents to reach for the bypass. An ignored path cannot enter anyone's commit,
+ * so it cannot be work this commit might clobber. A merely untracked path is a
+ * different matter and still counts against the holder, since anybody could add
+ * it.
+ */
+function isPathIgnoredByGit(coordRoot: string, relPath: string): boolean {
+  const abs = join(coordRoot, relPath);
+  const cwd = dirname(abs);
+  if (!existsSync(cwd)) return false;
+  // check-ignore exits 0 when the path is ignored, 1 when it is not.
+  return gitProbe(["check-ignore", "--quiet", "--", basename(abs)], cwd).status === 0;
+}
+
 function holderHasLiveForeignPid(coordRoot: string, holderId: string): boolean {
   return instanceHasLivePid(coordRoot, holderId);
 }
@@ -238,18 +316,21 @@ function holderHasLiveForeignPid(coordRoot: string, holderId: string): boolean {
 function isPathCleanInHead(coordRoot: string, relPath: string): boolean {
   // Path is tracked + diff-clean against HEAD = "already committed, holder
   // hasn't released the claim yet". Counts as self-attributable.
-  const tracked = spawnSync("git", ["ls-files", "--error-unmatch", "--", relPath], {
-    cwd: coordRoot,
-    encoding: "utf8",
-    timeout: 2000,
-  });
-  if (tracked.status !== 0) return false;
-  const diff = spawnSync("git", ["diff", "--quiet", "HEAD", "--", relPath], {
-    cwd: coordRoot,
-    encoding: "utf8",
-    timeout: 2000,
-  });
-  return diff.status === 0;
+  //
+  // Ask the repository that actually tracks the path, by running git from the
+  // file's own directory instead of the coord root. Claims are recorded
+  // monorepo-relative, so a submodule file arrives here as `sub/src/x.ts`, and
+  // the superproject does not track submodule contents: asking it always
+  // answered "not tracked". Gate A therefore failed for every submodule path,
+  // self-attribution never suppressed a submodule commit, and the operator paid
+  // a HARNERY_AGENT_COORD_BYPASS=1 per commit. Running from the file's directory
+  // lands in the submodule's own repo and handles any nesting depth.
+  const abs = join(coordRoot, relPath);
+  const cwd = dirname(abs);
+  const base = basename(abs);
+  if (!existsSync(cwd)) return false;
+  if (gitProbe(["ls-files", "--error-unmatch", "--", base], cwd).status !== 0) return false;
+  return gitProbe(["diff", "--quiet", "HEAD", "--", base], cwd).status === 0;
 }
 
 function readActivePeers(coordRoot: string): PeerHeartbeat[] {

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

@@ -2,6 +2,10 @@
  * Stop-hook verdict: rule 1/3, 2/3, 3/3 enforcement evaluated
  * from the canonical event stream alone (no transcript scan).
  *
+ * Codex is observe-only: its Stop continuation can replace the user-facing
+ * answer in clients that retain only the final continuation response.
+ *
+ * Enforced adapters:
  * Rule 1/3: `state.status_checked` event with matching turn boundary exists.
  * Rule 2/3: latest `turn.stop` event has `status_box_present: true` (or the
  *            stop currently firing carries that field via the in-flight event
@@ -17,12 +21,9 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { resolveBinName } from "../../config.ts";
 
-export type VerdictResult = {
-  allow: boolean;
-  exit_code: 0 | 2;
-  rule: string;
-  reason?: string;
-};
+export type { VerdictResult } from "./verdict.ts";
+
+import type { VerdictResult } from "./verdict.ts";
 
 interface CanonicalEvent {
   event_id: string;
@@ -31,7 +32,7 @@ interface CanonicalEvent {
   instance_id: string;
   session_id: string;
   turn_id?: string;
-  harness: string;
+  adapter: string;
   source: string;
   data: Record<string, unknown>;
 }
@@ -40,9 +41,9 @@ export interface StopHookRequest {
   rule: "stop-hook";
   instance_id: string;
   session_id?: string;
-  /** Firing harness. Selects the end-of-turn ack signal (see `ackSignalFor`).
+  /** Firing adapter. Selects the end-of-turn ack signal (see `ackSignalFor`).
    * Undefined → Claude Code semantics (transcript-scanned status box). */
-  harness?: string;
+  adapter?: string;
   /** Wall-clock cutoff for the current turn; events strictly after this are not yet relevant. */
   now_ms?: number;
   /** Override the turn-window discovery (used by tests). */
@@ -51,7 +52,7 @@ export interface StopHookRequest {
   bypass?: boolean;
   /** Headless child spawned by `harn workflow` (HARNERY_WORKFLOW_CHILD=1).
    * The end-of-turn ritual exists to surface status to a HUMAN reader; a
-   * workflow child reports to the engine's journal instead, so the ritual is
+   * workflow child reports to the engine's transcript instead, so the ritual is
    * meaningless there — worse, blocking burns the child's turn budget on
    * re-prompts (observed as error_max_turns in the Phase 1 spike). Exempting
    * here, rather than disabling the child's hooks wholesale, keeps heartbeat +
@@ -61,7 +62,7 @@ export interface StopHookRequest {
 
 /**
  * The end-of-turn "I surfaced my status" signal, detected differently per
- * harness because the ritual's *goal* (status visible to the human) is reached
+ * adapter because the ritual's *goal* (status visible to the human) is reached
  * by different means:
  *
  * - **Claude Code / Codex** collapse tool calls in the UI, so the human-visible
@@ -78,12 +79,12 @@ export interface StopHookRequest {
  * This is why the fix is not "relax 2/3 because we can't see it": it's "2/3
  * and 1/3 are two detections of the same thing, and Cursor's inline UI makes
  * 1/3 the right one." The enforcement *channel* (exit-2+stderr vs Cursor's
- * `followup_message`) is handled separately in hooks/harness/output.ts.
+ * `followup_message`) is handled separately in hooks/adapter/output.ts.
  */
 type AckSignal = "status_box_present" | "status_checked";
 
-function ackSignalFor(harness?: string): AckSignal {
-  return harness === "cursor" ? "status_checked" : "status_box_present";
+function ackSignalFor(adapter?: string): AckSignal {
+  return adapter === "cursor" ? "status_checked" : "status_box_present";
 }
 
 const RECENT_EVENT_WINDOW_LINES = 5_000;
@@ -112,6 +113,21 @@ export function evaluateStopHook(coordRoot: string, req: StopHookRequest): Verdi
     };
   }
 
+  // A blocked Codex Stop does not reject the turn. Codex creates a continuation
+  // prompt and asks the model to answer again. Some clients retain only that
+  // final continuation response, so a coordination reminder can replace a
+  // correct user-facing answer with status output. The Stop path has already
+  // emitted turn.stop and projected the coordination state before this verdict
+  // runs. Keep that telemetry, but never continue a Codex turn for this ritual.
+  if (req.adapter === "codex") {
+    return {
+      allow: true,
+      exit_code: 0,
+      rule: "stop-hook.codex_observe_only",
+      reason: "Codex Stop continuations must not replace the user-facing answer",
+    };
+  }
+
   let events: CanonicalEvent[];
   try {
     events = readRecentEvents(coordRoot, RECENT_EVENT_WINDOW_LINES);
@@ -160,16 +176,16 @@ export function evaluateStopHook(coordRoot: string, req: StopHookRequest): Verdi
   const latestTurnStop = [...inTurn].reverse().find((e) => e.event_type === "turn.stop");
   const boxPresent = latestTurnStop ? Boolean(latestTurnStop.data.status_box_present) : false;
 
-  // Harness-aware end-of-turn ack signal (see `ackSignalFor`). On Cursor the
+  // Adapter-aware end-of-turn ack signal (see `ackSignalFor`). On Cursor the
   // ack is `status_checked` (running `harn agents status` shows the box inline);
   // on Claude Code / Codex it's the transcript-scanned `status_box_present`.
   // The matching block helper carries the right "how to fix" message.
-  const ackSignal = ackSignalFor(req.harness);
+  const ackSignal = ackSignalFor(req.adapter);
   const ackPresent = ackSignal === "status_checked" ? statusChecked : boxPresent;
   const ackBlock = ackSignal === "status_checked" ? rule13Block : rule23Block;
 
   // Pure-prose-turn exemption: only the ack signal applies. Parity
-  // across harnesses: CC requires the box; Cursor requires status_checked.
+  // across adapters: CC requires the box; Cursor requires status_checked.
   if (!toolPreUseInTurn) {
     if (!ackPresent) {
       return ackBlock();

package/src/core/agents/rules/verdict.ts

@@ -0,0 +1,13 @@
+/**
+ * The shape every coordination rule returns.
+ *
+ * Declared here once. The claim-conflict and stop-hook rules each carried a
+ * byte-identical private copy, which is how two rules drift into disagreeing
+ * about what a verdict is.
+ */
+export type VerdictResult = {
+  allow: boolean;
+  exit_code: 0 | 2;
+  rule: string;
+  reason?: string;
+};

package/src/core/agents/session-events.ts

@@ -12,7 +12,7 @@ import { randomBytes } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 // Kept dependency-light: vendored verbatim into a downstream consumer, so no coordEnv import.
-import { normalizeHarness, resolveEmitRoot } from "./canonical-emit.ts";
+import { normalizeAdapter, resolveEmitRoot } from "./canonical-emit.ts";
 import { emit } from "./events/emit.ts";
 
 /** Event types accepted by `writeSessionEvent`. Only the command stream +
@@ -98,7 +98,7 @@ const CANONICAL_TYPE: Partial<Record<SessionEventType, string>> = {
 
 interface HeartbeatEnrichment {
   session_id: string;
-  harness: "claude-code" | "cursor" | "codex";
+  adapter: "claude-code" | "cursor" | "codex";
   at: number;
 }
 /** Cache heartbeat-derived envelope fields per instance_id so a burst of
@@ -121,7 +121,7 @@ function enrichFromHeartbeat(coordRoot: string, instanceId: string): HeartbeatEn
     };
     const enrichment: HeartbeatEnrichment = {
       session_id: hb.session_id || instanceId,
-      harness: normalizeHarness(hb.platform),
+      adapter: normalizeAdapter(hb.platform),
       at: now,
     };
     enrichCache.set(instanceId, enrichment);
@@ -173,7 +173,7 @@ function emitCanonicalCommand(type: SessionEventType, fields: Record<string, unk
       event_type: eventType,
       instance_id: instanceId,
       session_id: enrich.session_id,
-      harness: enrich.harness,
+      adapter: enrich.adapter,
       data: canonicalData(type, fields),
     });
   } catch {

package/src/core/agents/state/council.ts

@@ -7,7 +7,7 @@
  *
  * This module owns: lifecycle (advance, close, archive, unarchive, delete)
  * and steward reassignment. Council CREATION + contribution writes stay
- * separate (operator-side, harness-agnostic).
+ * separate (operator-side, adapter-agnostic).
  */
 
 import {