harnery 0.31.6 → 0.32.0

package/src/core/agents/git-hook.ts

@@ -0,0 +1,126 @@
+/**
+ * Git-plumbing collection for `agent-coord git-hook <event>` — the in-process
+ * replacement for the bash that host pre-commit / post-commit / post-checkout
+ * hooks used to carry.
+ *
+ * Everything here is a port of hook logic that lived in host repos as shell:
+ * staged-path collection with rename handling, submodule canonicalization,
+ * the gitlink probe, and the clean-in-worktree checks that gate claim pruning.
+ * Owning it here means a harnery upgrade upgrades the behavior; the host hook
+ * file keeps only a stable managed region that invokes `git-hook <event>`.
+ *
+ * All functions take an explicit cwd and return data — no printing, no
+ * process.exit — so they unit-test against a temp repo.
+ */
+
+import { spawnSync } from "node:child_process";
+
+export type GitHookEvent = "pre-commit" | "post-commit" | "post-checkout";
+
+function git(args: string[], cwd: string): string {
+  const r = spawnSync("git", args, { cwd, encoding: "utf8", timeout: 5000 });
+  return r.status === 0 ? (r.stdout ?? "") : "";
+}
+
+/**
+ * The coordination root for a hook firing in `cwd`: the superproject when the
+ * repo is a submodule, else the repo's own toplevel. Pinning to the
+ * superproject matters because some submodules carry a config-only `.harnery/`
+ * that a cwd walk would land on, running the check against an empty claims dir.
+ */
+export function discoverCoordRoot(cwd: string): string | null {
+  const superproject = git(["rev-parse", "--show-superproject-working-tree"], cwd).trim();
+  if (superproject) return superproject;
+  const toplevel = git(["rev-parse", "--show-toplevel"], cwd).trim();
+  return toplevel || null;
+}
+
+/** Monorepo-relative prefix when `cwd` is inside a submodule ("" in the parent). */
+export function submodulePrefix(cwd: string): string {
+  const superproject = git(["rev-parse", "--show-superproject-working-tree"], cwd).trim();
+  if (!superproject) return "";
+  const toplevel = git(["rev-parse", "--show-toplevel"], cwd).trim();
+  if (!toplevel.startsWith(`${superproject}/`)) return "";
+  return toplevel.slice(superproject.length + 1);
+}
+
+/**
+ * Parse `--name-status -M` output into repo-local paths. Renames/copies emit
+ * BOTH sides so the source's claim releases too; plain statuses emit one.
+ */
+export function parseNameStatus(output: string): string[] {
+  const paths: string[] = [];
+  for (const line of output.split("\n")) {
+    if (!line.trim()) continue;
+    const parts = line.split("\t");
+    const status = parts[0] ?? "";
+    if (/^[RC]/.test(status)) {
+      if (parts[1]) paths.push(parts[1]);
+      if (parts[2]) paths.push(parts[2]);
+    } else if (parts[1]) {
+      paths.push(parts[1]);
+    }
+  }
+  return paths;
+}
+
+function canonicalize(paths: string[], prefix: string): string[] {
+  return prefix ? paths.map((p) => `${prefix}/${p}`) : [...paths];
+}
+
+/** Is this repo-local path a submodule gitlink (mode 160000) in the index? */
+function isGitlink(path: string, cwd: string): boolean {
+  return git(["ls-files", "--stage", "--", path], cwd).startsWith("160000 ");
+}
+
+/** Is this repo-local path clean in the worktree (no unstaged residue)? */
+function isCleanInWorktree(path: string, cwd: string): boolean {
+  return git(["status", "--porcelain", "--", path], cwd).trim() === "";
+}
+
+/**
+ * pre-commit: staged paths (canonical, monorepo-relative) plus which of them
+ * are submodule gitlinks — a parent-repo pointer bump is not a claim on the
+ * submodule's contents, and the conflict rule's prefix matcher needs to know.
+ */
+export function collectStaged(cwd: string): { staged: string[]; gitlinks: string[] } {
+  const out = git(["diff", "--cached", "--name-status", "-M"], cwd);
+  const local = parseNameStatus(out);
+  const prefix = submodulePrefix(cwd);
+  const staged = canonicalize(local, prefix);
+  const gitlinks: string[] = [];
+  for (let i = 0; i < local.length; i++) {
+    const l = local[i]!;
+    if (isGitlink(l, cwd)) gitlinks.push(staged[i]!);
+  }
+  return { staged, gitlinks };
+}
+
+/**
+ * post-commit: paths the just-landed HEAD commit touched that are now clean in
+ * the worktree. A path with unstaged residue keeps its claim — the agent is
+ * still mid-work on it.
+ */
+export function collectCommitted(cwd: string): string[] {
+  // --root: a repo's first commit has no parent; without it diff-tree emits
+  // nothing and the root commit's claims never prune (a bash-era blind spot).
+  const out = git(
+    ["diff-tree", "--no-commit-id", "--name-status", "-M", "-r", "--root", "HEAD"],
+    cwd,
+  );
+  const local = parseNameStatus(out).filter((p) => isCleanInWorktree(p, cwd));
+  return canonicalize(local, submodulePrefix(cwd));
+}
+
+/**
+ * post-checkout: paths the ref move rewrote that are now clean — a checkout
+ * that discarded an agent's edits should release its claims so a peer's later
+ * Edit isn't falsely blocked. `oldRef`/`newRef` are the hook's $1/$2.
+ */
+export function collectCheckoutRemoved(cwd: string, oldRef: string, newRef: string): string[] {
+  const from = oldRef || "0000000000000000000000000000000000000000";
+  const to = newRef || "HEAD";
+  const out = git(["diff", "--name-status", "-M", from, to], cwd);
+  const local = parseNameStatus(out).filter((p) => isCleanInWorktree(p, cwd));
+  return canonicalize(local, submodulePrefix(cwd));
+}

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

@@ -12,11 +12,12 @@
  *      + sorted(files_touched) + platform, sorted by instance_id).
  *   2. Council pending: pending open-council IDs hashed; re-emits when the
  *      ID set changes.
- *   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.
+ *   3. Focus nudge. Until the session has produced its suggested name (first
+ *      non-empty set-task), tells every adapter — on every prompt, undeduped —
+ *      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.
@@ -42,7 +43,7 @@ import {
 import { join } from "node:path";
 
 import { coordEnv } from "../../../lib/env.ts";
-import { resolveBinName } from "../../config.ts";
+import { endOfTurnStatusCommand, resolveBinName } from "../../config.ts";
 import { type RemoteMachine, readRemoteMachines } from "../../presence/index.ts";
 import { formatPendingCouncils } from "./session-context.ts";
 
@@ -59,6 +60,7 @@ interface HeartbeatRow {
   platform?: string;
   task?: string;
   task_updated_at?: string;
+  suggested_session_name?: string;
   turn_summary?: string;
   workflow_run_id?: string;
 }
@@ -135,10 +137,11 @@ function renderStatusFooterReminder(coordRoot: string, selfInstanceId: 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);
+  const statusCommand = endOfTurnStatusCommand(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. ` +
+    `Then run \`${statusCommand}\` as your final shell call and append its stdout verbatim in a fenced code block at the bottom of the same substantive reply. ` +
+    "If it fails, finish the owned Git work and rerun it before replying. " +
     "Keep the answer intact. If the footer is missed, do not retry or replace the reply; the Stop hook is observe-only."
   );
 }
@@ -176,13 +179,15 @@ function computeFocusNudgeIfChanged(
   let message = "";
   let nudgeKind = "";
 
-  if (opts.sessionNameNudge && !hb.task_updated_at) {
+  if (opts.sessionNameNudge && !hb.suggested_session_name) {
+    // Keyed on "a name was ever produced", not task_updated_at: a bare clear
+    // as the first declaration must not end the naming window.
     needsNudge = true;
     nudgeKind = "session-name";
     message =
-      `New session: run \`${bin} agents set-task "<2-5 word session topic>"\` as your first tool call. ` +
+      `This session has no name yet: 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.";
+      "Then continue with the task; that `set-task` also satisfies this turn's focus declaration.";
   } else if (opts.taskNudge && !taskValue) {
     needsNudge = true;
     nudgeKind = "task-unset";
@@ -207,8 +212,18 @@ function computeFocusNudgeIfChanged(
     return "";
   }
 
-  // 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.
+  // The session-name reminder is deliberately NOT deduped: it re-emits on
+  // every prompt until a name is produced, because the "still unnamed" state
+  // is the failure state — deduping it erases the only reminder after one
+  // ignored prompt (the miss mode operators reported). Bounded in practice:
+  // Stop rule 3/3 forces a set-task on the first tool-using turn.
+  if (nudgeKind === "session-name") {
+    clearHashFile(hashFile);
+    return message;
+  }
+
+  // Dedup the task-unset/stale reminders on kind + task state so a repeat
+  // prompt in the same state stays quiet.
   const state = `${nudgeKind}|task=${taskValue}|updated=${hb.task_updated_at ?? ""}|threshold=${threshold}`;
   const newHash = sha256Hex16(state);
   const oldHash = safeRead(hashFile);

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

@@ -13,6 +13,7 @@ import { join } from "node:path";
 import { resolveBinName, resolveHooksSetupHint } from "../../config.ts";
 import { harneryVersion, loadAdapterWiring } from "../../hooks/adapter/wiring.ts";
 import { readRemoteMachines } from "../../presence/index.ts";
+import { readForkParent } from "../state/names.ts";
 
 interface HeartbeatRow {
   instance_id?: string;
@@ -54,7 +55,19 @@ export function renderSessionContext(opts: RenderOpts): string {
   const peerTable = [localTable, formatRemoteMachines(coordRoot)].filter(Boolean).join("\n\n");
   if (agentName) {
     const suffix = platformLabel ? ` (${platformLabel})` : "";
-    const selfLine = `You are agent-${agentName}${suffix}.`;
+    // The authority clause guards forked/branched chats. An adapter that forks a
+    // conversation copies the parent's transcript, so the fork's context still
+    // asserts the parent's name, claims, and task. When recorded fork lineage
+    // (.name-history forked_from) names the parent, say so specifically — the
+    // fork is about to read a transcript full of that exact name. Otherwise
+    // fall back to the generic clause, which needs no fork detection.
+    const forkParent = readForkParent(coordRoot, instanceId);
+    const authority = forkParent?.name
+      ? `This conversation was branched from agent-${forkParent.name}'s session: earlier context showing agent-${forkParent.name}'s name, task, or file claims belongs to the pre-fork session, not to you.`
+      : forkParent
+        ? `This conversation was branched from another session (${forkParent.instance_id}); any agent name in earlier context belongs to that session, not to you.`
+        : "Any different agent name in earlier context was inherited from another session; this one is authoritative.";
+    const selfLine = `You are agent-${agentName}${suffix}. ${authority}`;
     messages.push(peerTable ? `${selfLine}\n\n${peerTable}` : selfLine);
   } else if (peerTable) {
     messages.push(peerTable);
@@ -79,7 +92,7 @@ export function renderSessionContext(opts: RenderOpts): string {
     const hint = resolveHooksSetupHint(coordRoot);
     const fix = hint
       ? `Run \`${hint}\` to install them.`
-      : "Wire each repo's pre-commit hook to invoke `agent-coord verdict --rule=commit` (harnery's commit guard).";
+      : `Run \`${resolveBinName(coordRoot)} init\` to install the harnery-managed git-hook regions (commit guard + claim pruning).`;
     const wiringSummary = `Coordination hooks are NOT wired: the E-guard will not block conflicting commits, and post-commit claim pruning will not run. ${fix} Detected:\n${wiringIssues.map((i) => `  - ${i}`).join("\n")}`;
     messages.push(wiringSummary);
   }

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

@@ -271,8 +271,8 @@ function isFresh(lastHeartbeat: string): boolean {
  *  - diff shows non-empty output (genuinely dirty)
  */
 function isFileCommittedClean(coordRoot: string, relPath: string): boolean {
-  // Tolerate either path form: files_touched can hold absolute-under-coordRoot
-  // entries (legacy file-tracking) or canonical monorepo-relative ones.
+  // Tool payloads can provide either absolute-under-coordRoot or canonical
+  // monorepo-relative paths.
   const rel = relPath.startsWith(`${coordRoot}/`) ? relPath.slice(coordRoot.length + 1) : relPath;
   const abs = join(coordRoot, rel);
   if (!existsSync(abs)) return false;
@@ -305,7 +305,7 @@ function pruneClaimFromPeer(coordRoot: string, instanceId: string, relPath: stri
     const body = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
     const files = (body.files_touched as string[] | undefined) ?? [];
     // Normalize both sides: files_touched can hold absolute-under-coordRoot
-    // entries (legacy projections) as well as canonical relative ones — an
+    // entries as well as canonical relative ones — an
     // exact-string filter silently no-ops on the mixed-form case and the
     // stale claim never heals.
     const norm = (p: string): string =>

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

@@ -1,8 +1,8 @@
 /**
  * Pre-commit E-guard verdict. The caller (typically a bash pre-commit hook)
- * sends a JSON request with the staged paths, resolves its own instance_id
- * via pid-map, and prints the verdict messages + exits with
- * verdict.exit_code.
+ * sends a JSON request with the staged paths and prints the verdict
+ * messages + exits with verdict.exit_code. Committer identity is resolved
+ * HERE via `resolveOwner()` unless the request explicitly carries one.
  *
  * Three outcomes:
  *   1. allow (no conflicts): exit 0.
@@ -24,6 +24,7 @@ import { spawnSync } from "node:child_process";
 import { appendFileSync, existsSync, readdirSync, readFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { coordFreshnessSeconds } from "../../config.ts";
+import { resolveOwner } from "../../hooks/resolve/owner.ts";
 import { instanceHasLivePid } from "../state/pidmap.ts";
 
 interface PeerHeartbeat {
@@ -46,9 +47,16 @@ interface Conflict {
 }
 
 export interface CommitVerdictRequest {
-  instance_id: string;
-  /** Group key. Subagents inherit parent's session_id. */
-  session_id: string;
+  /**
+   * Committer identity. Optional: when absent (or the legacy
+   * `__unattributed__` sentinel), the verdict resolves it via
+   * `resolveOwner()` — env → pid-map walk → validated Codex thread id —
+   * from its own process context. Callers should stop hand-rolling
+   * identity resolution and omit this.
+   */
+  instance_id?: string;
+  /** Group key. Subagents inherit parent's session_id. Same optionality. */
+  session_id?: string;
   /** Canonical monorepo-relative paths. */
   staged_paths: string[];
   /** Paths in `staged_paths` that resolve to submodule gitlinks (mode 160000)
@@ -62,6 +70,8 @@ export interface CommitVerdictResult {
   allow: boolean;
   exit_code: number;
   rule: string;
+  /** The committer identity the verdict actually used (resolved or passed). */
+  instance_id: string;
   /** Conflict details (for the caller to print). */
   conflicts: Conflict[];
   /** Path-specific gates that fired (for `coord_log` lines). */
@@ -73,11 +83,24 @@ export interface CommitVerdictResult {
 }
 
 export function evaluateCommit(coordRoot: string, req: CommitVerdictRequest): CommitVerdictResult {
+  // Resolve the committer here, not in the calling hook. The bash shims used
+  // to carry their own pid-map walk (a pre-extraction fossil of resolveOwner);
+  // a hand-rolled copy can only fall behind as tiers are added, so the rule
+  // resolves identity from its own process context and callers just omit it.
+  const passed = req.instance_id?.trim();
+  const me =
+    passed && passed !== "__unattributed__"
+      ? passed
+      : (resolveOwner({ payload: null, coordRoot })?.instance_id ?? "__unattributed__");
+  const passedSession = req.session_id?.trim();
+  const mySession = passed && passedSession ? passedSession : me;
+
   if (req.staged_paths.length === 0) {
     return {
       allow: true,
       exit_code: 0,
       rule: "commit.pass",
+      instance_id: me,
       conflicts: [],
       log_lines: [],
       message: "",
@@ -91,9 +114,9 @@ export function evaluateCommit(coordRoot: string, req: CommitVerdictRequest): Co
 
   const conflicts: Conflict[] = [];
   for (const peer of peers) {
-    if (peer.instance_id === req.instance_id) continue;
+    if (peer.instance_id === me) continue;
     const peerSession = peer.session_id ?? peer.instance_id;
-    if (req.session_id && peerSession === req.session_id) continue; // same group
+    if (mySession !== "__unattributed__" && peerSession === mySession) continue; // same group
     const ts = peer.last_heartbeat ? Date.parse(peer.last_heartbeat) : 0;
     if (!Number.isFinite(ts) || ts < cutoffMs) continue; // stale
     const files = peer.files_touched ?? [];
@@ -118,6 +141,7 @@ export function evaluateCommit(coordRoot: string, req: CommitVerdictRequest): Co
       allow: true,
       exit_code: 0,
       rule: "commit.pass",
+      instance_id: me,
       conflicts: [],
       log_lines: [],
       message: "",
@@ -129,6 +153,7 @@ export function evaluateCommit(coordRoot: string, req: CommitVerdictRequest): Co
       allow: true,
       exit_code: 0,
       rule: "commit.bypass",
+      instance_id: me,
       conflicts,
       log_lines: conflicts.map(
         (c) => `COMMIT_BYPASSED  path=${c.staged_path} owner=${c.short_name}`,
@@ -149,6 +174,7 @@ export function evaluateCommit(coordRoot: string, req: CommitVerdictRequest): Co
       allow: true,
       exit_code: 0,
       rule: "commit.suppressed",
+      instance_id: me,
       conflicts,
       log_lines: conflicts.map(
         (c) =>
@@ -167,6 +193,7 @@ export function evaluateCommit(coordRoot: string, req: CommitVerdictRequest): Co
     allow: false,
     exit_code: 1,
     rule: "commit.conflict",
+    instance_id: me,
     conflicts,
     log_lines: conflicts.map((c) => `COMMIT_BLOCKED  path=${c.staged_path} owner=${c.short_name}`),
     message:

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

@@ -11,6 +11,9 @@
  *            stop currently firing carries that field via the in-flight event
  *            agent-hook emits before the stop hook runs).
  * Rule 3/3: `state.task_set` event with matching turn boundary exists.
+ * Session-naming rule (at most once per session, CC semantics only): the turn
+ *            whose set-task produced `suggested_session_name` must carry an
+ *            in-window `turn.stop` with `session_name_present: true`.
  *
  * Pure-prose-turn exemption: when zero `tool.pre_use` events fire in
  * the current turn, rules 1/3 and 3/3 do not apply. Rule 2/3 still applies
@@ -25,7 +28,11 @@
 
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { resolveBinName } from "../../config.ts";
+import {
+  agentsRequireGitFinalization,
+  endOfTurnStatusCommand,
+  resolveBinName,
+} from "../../config.ts";
 
 export type { VerdictResult } from "./verdict.ts";
 
@@ -106,18 +113,6 @@ const RECENT_EVENT_WINDOW_LINES = 5_000;
  */
 export const STOP_REMEDIATION_MARKER = "[harnery:stop-remediation";
 
-/**
- * The pre-marker message shape, still recognized on purpose.
- *
- * A followup already sitting in the stream was written by whichever build was
- * running when it fired. An agent whose session spans an upgrade would otherwise
- * keep alternating until the first new-format followup appeared, which is the
- * exact failure this change removes. Recognizing the older trailing form closes
- * that rollout window at no cost: it only ever appears in a `prompt_text`
- * because Harnery put it there.
- */
-const STOP_REMEDIATION_LEGACY_MARKER = "[agent-hook stop]: rule=";
-
 /** How far back the remediation walk may travel. Adapters cap their own
  * followup chains (Cursor's `loop_limit`), and each prompt can appear once per
  * observing adapter, so this only guards a pathological stream. */
@@ -126,7 +121,7 @@ const MAX_REMEDIATION_WALK_BACK = 16;
 function isStopRemediationPrompt(event: CanonicalEvent): boolean {
   const text = event.data.prompt_text;
   if (typeof text !== "string") return false;
-  return text.includes(STOP_REMEDIATION_MARKER) || text.includes(STOP_REMEDIATION_LEGACY_MARKER);
+  return text.includes(STOP_REMEDIATION_MARKER);
 }
 
 /**
@@ -233,7 +228,7 @@ export function evaluateStopHook(coordRoot: string, req: StopHookRequest): Verdi
       allow: true,
       exit_code: 0,
       rule: "stop-hook.no_history",
-      reason: "no canonical events for this owner; defer to legacy or skip",
+      reason: "no canonical events for this owner; nothing to evaluate",
     };
   }
 
@@ -255,7 +250,11 @@ export function evaluateStopHook(coordRoot: string, req: StopHookRequest): Verdi
   });
 
   const toolPreUseInTurn = inTurn.some((e) => e.event_type === "tool.pre_use");
-  const statusChecked = inTurn.some((e) => e.event_type === "state.status_checked");
+  const statusEvents = inTurn.filter((e) => e.event_type === "state.status_checked");
+  const statusChecked = statusEvents.length > 0;
+  const requiredStatusChecked = agentsRequireGitFinalization(coordRoot)
+    ? statusEvents.some((e) => e.data.git_finalization_checked === true)
+    : statusChecked;
   const taskSet = inTurn.some((e) => e.event_type === "state.task_set");
 
   // Rule 2/3: status_box_present on the most recent turn.stop for this owner.
@@ -270,8 +269,14 @@ export function evaluateStopHook(coordRoot: string, req: StopHookRequest): Verdi
   // 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.adapter);
-  const ackPresent = ackSignal === "status_checked" ? statusChecked : boxPresent;
-  const ackBlock = ackSignal === "status_checked" ? rule13Block : rule23Block;
+  const ackPresent =
+    ackSignal === "status_checked"
+      ? toolPreUseInTurn
+        ? requiredStatusChecked
+        : statusChecked
+      : boxPresent;
+  const ackBlock =
+    ackSignal === "status_checked" ? () => rule13Block(coordRoot) : () => rule23Block(coordRoot);
 
   // Pure-prose-turn exemption: only the ack signal applies. Parity
   // across adapters: CC requires the box; Cursor requires status_checked.
@@ -287,12 +292,43 @@ export function evaluateStopHook(coordRoot: string, req: StopHookRequest): Verdi
     };
   }
 
-  if (!statusChecked) return rule13Block();
+  if (!requiredStatusChecked) return rule13Block(coordRoot);
   // On Cursor `ackPresent === statusChecked` (already true here), so this is a
   // no-op and rule 2/3 is not enforced; on CC/Codex it's the box-paste check.
   if (!ackPresent) return ackBlock();
   if (!taskSet) return rule33Block();
 
+  // Session-naming rule (at most once per session, evaluated last so
+  // remediation stays monotonic in the established order): the turn whose
+  // set-task produced the suggested session name must show that name in the
+  // reply. Claude Code semantics only — Cursor's Stop payload carries neither
+  // a transcript nor the assistant message, so the fence is undetectable there
+  // (the same reason rule 2/3 collapses into 1/3 on Cursor), and Codex
+  // returned observe-only above. Detection rides `turn.stop`'s
+  // `session_name_present` (assistant-text-only transcript scan), mirroring
+  // how rule 2/3 rides `status_box_present`.
+  if (ackSignal === "status_box_present") {
+    const namingTaskSet = inTurn.find(
+      (e) =>
+        e.event_type === "state.task_set" &&
+        e.data.first_of_session === true &&
+        typeof e.data.suggested_session_name === "string" &&
+        e.data.suggested_session_name.length > 0,
+    );
+    if (namingTaskSet) {
+      // ANY in-window turn.stop with the flag satisfies the rule, not just the
+      // latest: once seen, `session_name_seen_at` is stamped and later
+      // turn.stops OMIT the field, so a later block on a different rule (whose
+      // repair fires a fresh turn.stop) must not un-satisfy this one.
+      const namePresent = inTurn.some(
+        (e) => e.event_type === "turn.stop" && e.data.session_name_present === true,
+      );
+      if (!namePresent) {
+        return sessionNameBlock(String(namingTaskSet.data.suggested_session_name));
+      }
+    }
+  }
+
   return {
     allow: true,
     exit_code: 0,
@@ -300,21 +336,33 @@ export function evaluateStopHook(coordRoot: string, req: StopHookRequest): Verdi
   };
 }
 
-function rule13Block(): VerdictResult {
+function rule13Block(coordRoot?: string): VerdictResult {
+  const missingEvidence = agentsRequireGitFinalization(coordRoot)
+    ? "no Git-finalized state.status_checked event found in this turn"
+    : "no state.status_checked event found in this turn";
   return {
     allow: false,
     exit_code: 2,
     rule: "stop-hook.rule_1_3",
-    reason: `End-of-turn rule (1/3): no state.status_checked event found in this turn; run \`${resolveBinName()} agents status\` as your last tool call.`,
+    reason: `End-of-turn rule (1/3): ${missingEvidence}; run \`${endOfTurnStatusCommand(coordRoot)}\` as your last tool call.`,
   };
 }
 
-function rule23Block(): VerdictResult {
+function rule23Block(coordRoot?: string): VerdictResult {
   return {
     allow: false,
     exit_code: 2,
     rule: "stop-hook.rule_2_3",
-    reason: `End-of-turn rule (2/3): turn.stop did not see the agent-status box in your reply text. Paste the \`${resolveBinName()} agents status\` output verbatim as a fenced code block (the \`┌─ agent-\` prefix is the detection signal).`,
+    reason: `End-of-turn rule (2/3): turn.stop did not see the agent-status box in your reply text. Paste the \`${endOfTurnStatusCommand(coordRoot)}\` output verbatim as a fenced code block (the \`┌─ agent-\` prefix is the detection signal).`,
+  };
+}
+
+function sessionNameBlock(name: string): VerdictResult {
+  return {
+    allow: false,
+    exit_code: 2,
+    rule: "stop-hook.session_name",
+    reason: `Session-naming rule: this turn's set-task produced the session name, but your reply doesn't show it. Reproduce it by itself in a fenced code block so the operator can one-click-copy it as the session/tab title: ${name}`,
   };
 }