harnery 0.31.5 → 0.32.0

package/src/core/governor/planning.ts

@@ -47,7 +47,9 @@ const MAX_RECORD_BYTES = 256 * 1024;
 const MAX_EVENTS_BYTES = 512 * 1024;
 const MAX_REASON = 2_000;
 const PROPOSAL_ROOT_RULE =
-  "proposal.root names one newly proposed work key using a root-capable template; it does not preserve or repeat active_root, which is context only";
+  "proposal.root is inferred by Harnery as the single final outcome that no other proposed item depends on; it must use a root-capable template and depend transitively on every other proposed item; it never preserves or repeats active_root, which is context only";
+const PLANNER_ROOT_RULE =
+  "Dependencies point from later work to earlier prerequisites. Do not return proposal.root. Harnery infers it as the single final outcome that no other proposed item depends on; make that outcome use a root-capable template and depend transitively on every other proposed item.";
 
 export interface RunGovernorPlannerInput {
   coordRoot: string;
@@ -729,7 +731,7 @@ function plannerScript(
       : "Return decision=apply with a replacement immutable root graph, or decision=attention when human judgment is required.",
     "Never claim mission completion unless the frozen mission acceptance is met. Never request a workflow outside the frozen template catalog.",
     "Dependencies may name an active work ID or an earlier key in your proposed work array.",
-    `Every proposed item must be reachable from root. ${PROPOSAL_ROOT_RULE}.`,
+    PLANNER_ROOT_RULE,
     "Work keys are lowercase identifiers no longer than 32 characters. Keep titles within 200 characters, objectives within 4000 characters, and each acceptance criterion within 500 characters.",
     `Plan id: ${planId}`,
     `Planning trigger: ${trigger}`,
@@ -1331,12 +1333,6 @@ function planProposalSchema(
   const applyProperties: Record<string, StageSchema> = {
     decision: { type: "string", enum: ["apply"] },
     rationale,
-    root: {
-      type: "string",
-      minLength: 1,
-      maxLength: 32,
-      pattern: "^[a-z][a-z0-9-]{0,31}$",
-    },
     work: {
       type: "array",
       minItems: 1,
@@ -1344,7 +1340,7 @@ function planProposalSchema(
       items: workItem,
     },
   };
-  const applyRequired = ["decision", "rationale", "root", "work"];
+  const applyRequired = ["decision", "rationale", "work"];
   if (record.intent.mission) {
     applyProperties.milestone = milestone;
     applyRequired.push("milestone");
@@ -1390,10 +1386,10 @@ function normalizeProposal(
   const proposedAt = preservedProposedAt ?? new Date().toISOString();
   const decision = enumValue(value.decision, ["apply", "complete", "attention"], "plan decision");
   const rationale = bounded(value.rationale, "plan rationale", MAX_REASON);
-  const root = typeof value.root === "string" ? value.root.trim() : "";
+  const terminalRoot = typeof value.root === "string" ? value.root.trim() : "";
   if (!Array.isArray(value.work)) throw new Error("plan work must be an array");
   if (decision === "attention" || decision === "complete") {
-    if (root || value.work.length > 0 || value.milestone !== undefined) {
+    if (terminalRoot || value.work.length > 0 || value.milestone !== undefined) {
       throw new Error(`${decision} plan must not contain work or milestone data`);
     }
     if (decision === "complete" && (!record.intent.mission || trigger !== "milestone")) {
@@ -1473,7 +1469,16 @@ function normalizeProposal(
       template,
     };
   });
-  if (!seen.has(root)) throw new Error(`plan root ${root || "(empty)"} is not a proposed key`);
+  const dependedOn = new Set(
+    work.flatMap((item) => item.dependencies.filter((dependency) => seen.has(dependency))),
+  );
+  const terminalOutcomes = work.filter((item) => !dependedOn.has(item.key));
+  if (terminalOutcomes.length !== 1) {
+    throw new Error(
+      `plan must have exactly one final outcome; found ${terminalOutcomes.map((item) => item.key).join(", ")}`,
+    );
+  }
+  const root = terminalOutcomes[0]!.key;
   const rootSpec = work.find((item) => item.key === root);
   if (!rootSpec || !policy.templates[rootSpec.template]?.root) {
     throw new Error(`plan root ${root} must use a root-capable template`);

package/src/core/hooks/adapter/detect.ts

@@ -4,32 +4,23 @@ import type { Adapter } from "../events/schema.ts";
 /**
  * Resolve the adapter firing the hook. The dispatcher binary is always
  * invoked with `--adapter <name>` per the current wiring in each adapter's
- * settings file. `--harness` remains an accepted alias because settings files
- * written by older releases survive a package upgrade until the consumer
- * re-runs `harn init`. Returns null when neither flag is present; caller falls
- * through to the env-based fallback or skips emission.
+ * settings file. Returns null when the flag is absent; caller falls through to
+ * the environment fallback or skips emission.
  */
 export function detectAdapter(argv: readonly string[]): Adapter | null {
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]!;
-    if (a === "--adapter" || a === "--harness") {
+    if (a === "--adapter") {
       return validate(argv[i + 1]);
     }
     if (a.startsWith("--adapter=")) {
       return validate(a.slice("--adapter=".length));
     }
-    if (a.startsWith("--harness=")) {
-      return validate(a.slice("--harness=".length));
-    }
   }
-  return validate(coordEnv("AGENT_COORD_ADAPTER") ?? coordEnv("AGENT_COORD_HARNESS"));
+  return validate(coordEnv("AGENT_COORD_ADAPTER"));
 }
 
 function validate(v: string | undefined): Adapter | null {
   if (v === "claude-code" || v === "cursor" || v === "codex") return v;
-  // Legacy: some adapters use `claude_code` (underscore). Map
-  // it through so the env-based fallback works for callers that haven't
-  // updated yet.
-  if (v === "claude_code") return "claude-code";
   return null;
 }

package/src/core/hooks/adapter/output.ts

@@ -19,7 +19,7 @@
  */
 
 import { STOP_REMEDIATION_MARKER } from "../../agents/rules/stop-hook.ts";
-import { resolveBinName } from "../../config.ts";
+import { endOfTurnStatusCommand, resolveBinName } from "../../config.ts";
 import type { Adapter } from "../events/schema.ts";
 
 export type SystemEvent = "SessionStart" | "UserPromptSubmit" | "SubagentStart";
@@ -60,7 +60,11 @@ export function emitDeny(adapter: Adapter, reason: string): void {
  *   We exit 0 so Cursor treats the run as a success and honors the output.
  *   (Confirmed against cursor.com/docs/agent/hooks.)
  */
-export function emitStopBlock(adapter: Adapter, verdict: { reason?: string; rule: string }): 0 | 2 {
+export function emitStopBlock(
+  adapter: Adapter,
+  verdict: { reason?: string; rule: string },
+  coordRoot?: string,
+): 0 | 2 {
   if (adapter === "codex") return 0;
 
   const reason = verdict.reason ?? "End-of-turn coordination ritual incomplete.";
@@ -70,11 +74,12 @@ export function emitStopBlock(adapter: Adapter, verdict: { reason?: string; rule
     // see in chat that the message came from Harnery rather than from them.
     // Both commands are named because one message that repairs the whole ritual
     // ends the chain in a single followup; the failing rule is context.
-    const bin = resolveBinName();
+    const bin = resolveBinName(coordRoot);
+    const statusCommand = endOfTurnStatusCommand(coordRoot);
     const message = [
       `${STOP_REMEDIATION_MARKER} rule=${verdict.rule}]`,
       reason,
-      `Repair the ritual in this turn: run \`${bin} agents set-task "<short focus>"\` and then \`${bin} agents status\` as your last tool call.`,
+      `Repair the ritual in this turn: run \`${bin} agents set-task "<short focus>"\` and then \`${statusCommand}\` as your last tool call.`,
     ].join("\n");
     process.stdout.write(`${JSON.stringify({ followup_message: message })}\n`);
     return 0;

package/src/core/hooks/adapter/parse.ts

@@ -43,7 +43,7 @@ export interface ParsedPayload {
  * Parse the raw stdin payload string for any adapter. Returns null when JSON
  * parse fails (Cursor occasionally fires hooks with no payload).
  */
-export function parsePayload(raw: string, _adapter: Adapter): ParsedPayload | null {
+export function parsePayload(raw: string, adapter: Adapter): ParsedPayload | null {
   if (!raw || raw.trim().length === 0) return null;
   let json: Record<string, unknown>;
   try {
@@ -52,13 +52,26 @@ export function parsePayload(raw: string, _adapter: Adapter): ParsedPayload | nu
     return null;
   }
 
+  const sessionId = normalizeSessionId(adapter, pickStr(json, "session_id"));
+  const conversationId = normalizeSessionId(adapter, pickStr(json, "conversation_id"));
+  const parentSessionId = normalizeSessionId(adapter, pickStr(json, "parent_session_id"));
+  const normalizedRaw =
+    adapter === "cursor"
+      ? {
+          ...json,
+          ...(sessionId ? { session_id: sessionId } : {}),
+          ...(conversationId ? { conversation_id: conversationId } : {}),
+          ...(parentSessionId ? { parent_session_id: parentSessionId } : {}),
+        }
+      : json;
+
   return {
     hook_event_name: pickStr(json, "hook_event_name"),
-    session_id: pickStr(json, "session_id"),
+    session_id: sessionId,
     agent_id: pickStr(json, "agent_id"),
     subagent_id: pickStr(json, "subagent_id"),
-    conversation_id: pickStr(json, "conversation_id"),
-    parent_session_id: pickStr(json, "parent_session_id"),
+    conversation_id: conversationId,
+    parent_session_id: parentSessionId,
     turn_id: pickStr(json, "turn_id"),
     parent_turn_id: pickStr(json, "parent_turn_id"),
     transcript_path: pickStr(json, "transcript_path"),
@@ -75,10 +88,16 @@ export function parsePayload(raw: string, _adapter: Adapter): ParsedPayload | nu
     clean_exit: pickBool(json, "clean_exit"),
     exit_status: pickStr(json, "exit_status"),
     reason: pickStr(json, "reason"),
-    raw: json,
+    raw: normalizedRaw,
   };
 }
 
+/** Cursor Glass prefixes conversation ids with `bc-`; coordination uses the bare id everywhere. */
+function normalizeSessionId(adapter: Adapter, value: string | undefined): string | undefined {
+  if (adapter !== "cursor" || !value?.startsWith("bc-") || value.length <= 3) return value;
+  return value.slice(3);
+}
+
 /**
  * Pull the bash command string out of a Bash/Shell tool_input. Returns
  * undefined for non-shell tools.

package/src/core/hooks/adapter/wiring.ts

@@ -200,6 +200,49 @@ export function loadAdapterWiring(projectRoot: string): AdapterWiringStatus[] {
   return out;
 }
 
+export interface AdapterWiringSummary {
+  /** Adapters carrying at least one harnery hook. */
+  wired: AdapterId[];
+  /**
+   * Adapters carrying none: no settings file at all, or a settings file with
+   * none of ours in it. An unparseable file lands in neither list, since
+   * `loadAdapterWiring` already reports that as drift.
+   */
+  unwired: AdapterId[];
+}
+
+/**
+ * Classify every known adapter as wired or unwired, without judging whether an
+ * unwired one is a problem.
+ *
+ * `loadAdapterWiring` stays deliberately silent about an adapter with zero
+ * harnery hooks, because a bare settings file is not an opt-out signal and
+ * nagging about it would false-warn every session. That silence is right in
+ * isolation and wrong once you also know the adapter's CLI is installed: then
+ * an agent can start a session here and register nothing. Splitting the fact
+ * from the judgement lets a caller holding both (doctor) tell "not used here"
+ * from "never wired" without changing what counts as drift.
+ */
+export function summarizeAdapterWiring(projectRoot: string): AdapterWiringSummary {
+  const wired: AdapterId[] = [];
+  const unwired: AdapterId[] = [];
+  for (const [id, spec] of Object.entries(ADAPTER_SPECS) as [AdapterId, AdapterSpec][]) {
+    const settingsPath = resolve(projectRoot, spec.settingsFile);
+    if (!existsSync(settingsPath)) {
+      unwired.push(id);
+      continue;
+    }
+    let settings: SettingsFile;
+    try {
+      settings = JSON.parse(readFileSync(settingsPath, "utf8")) as SettingsFile;
+    } catch {
+      continue; // unparseable → already surfaced by loadAdapterWiring
+    }
+    (diffWiring(settings, spec).present.length > 0 ? wired : unwired).push(id);
+  }
+  return { wired, unwired };
+}
+
 /**
  * Resolve the harnery package version for context in nudges/checks. Walks up
  * from this module to the package root (works under Bun from `src/` and Node

package/src/core/hooks/cli.ts

@@ -1,6 +1,5 @@
 /**
- * `agent-hook` CLI entry point. Phase 2: real canonical-event emission
- * alongside the legacy stream.
+ * `agent-hook` CLI entry point for canonical event emission.
  *
  * Flow:
  *   1. Parse argv → event-name + adapter.
@@ -25,10 +24,17 @@ import { coordEnv } from "../../lib/env.ts";
 import { replayCodexJsonl } from "../agents/codex-replay.ts";
 import { coordBinPath } from "../agents/coord-bin.ts";
 import { consumeSince, writeCursor } from "../agents/events/consume.ts";
+import {
+  type ClaimFinalizationDecision,
+  type ClaimFinalizationDescriptor,
+  classifyWriteClaimFinalization,
+  formatWriteClaimFinalizationDenial,
+} from "../agents/finalization.ts";
 import { evaluateStopHook } from "../agents/rules/stop-hook.ts";
 import { projectHeartbeats } from "../agents/state/heartbeat-projector.ts";
 import { writePidmapRow } from "../agents/state/pidmap.ts";
 import { shellMutationPaths } from "../agents/state/shell-mutation.ts";
+import { agentsRequireGitFinalization, resolveBinName } from "../config.ts";
 import {
   checkpointContext,
   completeContextRecovery,
@@ -49,6 +55,12 @@ import {
   type ParsedPayload,
   parsePayload,
 } from "./adapter/parse.ts";
+import {
+  codexWslFileLinkTelemetry,
+  inspectCodexWslBridge,
+  isWslUncPath,
+  renderCodexWslFileLinkContext,
+} from "./codex-wsl-bridge.ts";
 import {
   captureImages,
   detectPresence,
@@ -69,7 +81,14 @@ import { adapterPidFromEnv, parsePsChainLine, selectAnchorPid } from "./resolve/
 import { findCoordRoot } from "./resolve/coord-root.ts";
 import { extractIntentComment, resolveIntent } from "./resolve/intent.ts";
 import { resolveOwner } from "./resolve/owner.ts";
-import { scanStatusBoxPresent, scanTranscriptModel } from "./resolve/transcript.ts";
+import {
+  detectForkParent,
+  scanAssistantTextIncludes,
+  scanStatusBoxPresent,
+  scanTranscriptModel,
+} from "./resolve/transcript.ts";
+import { sessionNamePresence } from "./session-name-presence.ts";
+import { unsafeCrossShellReason } from "./unsafe-cross-shell.ts";
 
 interface Argv {
   eventName: string | null;
@@ -80,11 +99,11 @@ function parseArgv(argv: string[]): Argv {
   const out: Argv = { eventName: null, extra: [] };
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i]!;
-    if (arg === "--adapter" || arg === "--harness") {
+    if (arg === "--adapter") {
       i++; // detectAdapter will re-parse; just consume the value here.
       continue;
     }
-    if (arg.startsWith("--adapter=") || arg.startsWith("--harness=")) continue;
+    if (arg.startsWith("--adapter=")) continue;
     if (!out.eventName && !arg.startsWith("--")) {
       out.eventName = arg;
     } else {
@@ -160,11 +179,14 @@ function assignNameViaAgentCoord(
   coordRoot: string,
   instanceId: string,
   kind: "session" | "subagent" | "transient",
+  forkedFrom?: string,
 ): { name: string; kind: string } | null {
   const binary = coordBinPath("agent-coord", coordRoot) ?? "";
   if (!existsSync(binary)) return null;
   try {
-    const result = spawnSync(binary, ["assign-name", instanceId, kind], {
+    const args = ["assign-name", instanceId, kind];
+    if (forkedFrom) args.push("--forked-from", forkedFrom);
+    const result = spawnSync(binary, args, {
       encoding: "utf8",
       timeout: 2000,
       env: childEnv(coordRoot),
@@ -238,13 +260,26 @@ function buildEventData(
     case "session.start": {
       const adapterPlatform =
         ctx.adapter === "claude-code"
-          ? "claude_code"
+          ? "claude-code"
           : ctx.adapter === "cursor"
             ? "cursor"
             : "codex";
+      // Recorded fork lineage is NOT detected here. On claude-code a fork
+      // never fires its own session.start — SessionStart fires under the
+      // PARENT's session id (source=resume) before the fork id is minted
+      // (verified 2026-08-05) — so detection at this point can only mislabel
+      // the resumed parent. The fork's new instance is caught by the
+      // tool.pre_use heal path instead. The forkedFrom plumbing below stays
+      // for adapters that DO report a parent at session start.
+      const forkedFrom: string | undefined = undefined;
       // 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");
+      const assigned = assignNameViaAgentCoord(
+        ctx.coordRoot,
+        ctx.instanceId,
+        "session",
+        forkedFrom,
+      );
       // 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),
@@ -268,6 +303,10 @@ function buildEventData(
         name: assigned?.name,
         kind: "session",
         agent_id: ctx.instanceId,
+        // Recorded fork lineage rides the canonical event too, so full replay
+        // and derived readers converge on the same parent linkage that
+        // .name-history carries (the ADR 0017 dual-write pattern).
+        ...(forkedFrom ? { forked_from: forkedFrom } : {}),
         // 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 transcript + /workflows web view.
@@ -298,6 +337,11 @@ function buildEventData(
     }
 
     case "turn.stop": {
+      const lastAssistantMessage = (p?.raw.last_assistant_message as string | undefined) ?? "";
+      const fileLinkTelemetry =
+        ctx.adapter === "codex"
+          ? codexWslFileLinkTelemetry(ctx.coordRoot, p?.cwd, lastAssistantMessage)
+          : null;
       return {
         // Backfill the model for adapters that omit it at session.start
         // (Claude Code). The transcript is populated with assistant turns by
@@ -316,8 +360,27 @@ function buildEventData(
         // the verdict now sees because agent-hook emits this turn.stop itself
         // (the previous path passed those via the no-history fail-open).
         status_box_present:
-          scanStatusBoxPresent(p?.transcript_path) ||
-          ((p?.raw.last_assistant_message as string | undefined) ?? "").includes("┌─ agent-"),
+          scanStatusBoxPresent(p?.transcript_path) || lastAssistantMessage.includes("┌─ agent-"),
+        // Shadow measurement for the rule-2/3 detector: the loose scan above
+        // matches the box prefix ANYWHERE in the transcript tail, including
+        // the tool_result row the status command itself writes, so it can
+        // report a paste that never happened. The strict variant counts
+        // assistant text only (same window, same scanner as the session-name
+        // detection). Telemetry-only: the Stop verdict still reads
+        // status_box_present. Once the divergence rate between the two fields
+        // is known, the gate either flips to strict or the rule gets
+        // reconsidered; either way this field decides it with data.
+        status_box_present_strict:
+          scanAssistantTextIncludes(p?.transcript_path, "┌─ agent-") ||
+          lastAssistantMessage.includes("┌─ agent-"),
+        // Whether the session's suggested name is satisfied as of this turn,
+        // and which name that refers to. Reported on every stop while a name
+        // exists (the stop-hook.session_name verdict reads it per turn); the
+        // transcript scan itself stops once the name has been sighted.
+        ...sessionNamePresence(ctx.coordRoot, ctx.instanceId, lastAssistantMessage, (name) =>
+          scanAssistantTextIncludes(p?.transcript_path, name),
+        ),
+        ...(fileLinkTelemetry ?? {}),
         stop_hook_active: p?.stop_hook_active,
       };
     }
@@ -805,6 +868,7 @@ async function main(): Promise<number> {
         owner.instance_id,
         sessionId,
         adapter,
+        payload?.cwd,
         recovery?.briefing ?? "",
       );
       if (injected && recovery) {
@@ -897,7 +961,7 @@ async function main(): Promise<number> {
       // 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("./adapter/output.ts");
-      return emitStopBlock(adapter, verdict);
+      return emitStopBlock(adapter, verdict, coordRoot);
     }
   }
 
@@ -912,7 +976,21 @@ async function main(): Promise<number> {
   // call was restored here afterward.
   if (norm.event_type === "tool.pre_use") {
     try {
-      healHeartbeatViaCli(coordRoot, owner.instance_id, sessionId, adapter);
+      // Recorded fork lineage, heal-path flavor. A forked CC conversation
+      // never fires its own session.start (SessionStart fires under the
+      // PARENT's session id with source=resume, before the fork id is
+      // minted; verified 2026-08-05), so the fork's new instance first
+      // materializes right here. Gate detection on "no heartbeat yet" so the
+      // transcript scan runs once per instance lifetime, not per tool call.
+      let forkedFrom: string | undefined;
+      if (
+        adapter === "claude-code" &&
+        payload?.transcript_path &&
+        !existsSync(join(coordRoot, ".harnery", "active", `${owner.instance_id}.json`))
+      ) {
+        forkedFrom = detectForkParent(payload.transcript_path, owner.instance_id);
+      }
+      healHeartbeatViaCli(coordRoot, owner.instance_id, sessionId, adapter, forkedFrom);
       refreshPidmap(coordRoot, owner.instance_id, adapter, payload?.pid);
     } catch (err) {
       logError(coordRoot, err, { phase: "pre-tool-use-heal" });
@@ -933,6 +1011,29 @@ async function main(): Promise<number> {
       logError(coordRoot, err, { phase: "pre-tool-use-image-capture" });
     }
 
+    // Windows-native Codex + WSL UNC only: block the one cross-shell shape
+    // proven to corrupt argument boundaries. Normal WSL argv calls, literal
+    // bash -s scripts, native Linux/macOS sessions, and every other adapter
+    // pass through. The host instructions name its concrete safe bridge.
+    const unsafeShellReason = unsafeCrossShellReason({
+      adapter,
+      cwd: payload?.cwd,
+      toolName: payload?.tool_name,
+      toolInput: payload?.tool_input,
+    });
+    if (unsafeShellReason) {
+      emit(coordRoot, {
+        event_type: "decision.block",
+        instance_id: owner.instance_id,
+        session_id: sessionId,
+        adapter,
+        data: { rule: "unsafe_cross_shell", reason: unsafeShellReason },
+      });
+      const { emitDeny } = await import("./adapter/output.ts");
+      emitDeny(adapter, unsafeShellReason);
+      return 0;
+    }
+
     // 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 adapter.
@@ -1033,13 +1134,44 @@ async function runPreToolUseGuard(
   adapter: Adapter,
 ): Promise<void> {
   const toolName = (data.tool_name as string | undefined) ?? "";
-  const targets = collectGuardTargets(toolName, data)
-    .map((p) => canonicalize(coordRoot, p))
-    .filter((p): p is string => p !== null);
+  const rawTargets = collectGuardTargets(toolName, data);
+  if (rawTargets.length === 0) return;
+
+  let targets: Array<{ path: string; finalization?: ClaimFinalizationDescriptor }>;
+  if (agentsRequireGitFinalization(coordRoot)) {
+    const decisions = rawTargets.map((path) => classifyWriteClaimFinalization(coordRoot, path));
+    const denied = decisions.find((decision) => !decision.allow);
+    if (denied && !denied.allow) {
+      const { emitDeny } = await import("./adapter/output.ts");
+      emitDeny(adapter, formatWriteClaimFinalizationDenial(denied, resolveBinName(coordRoot)));
+      return;
+    }
+    const allowed = decisions.filter(
+      (decision): decision is Extract<ClaimFinalizationDecision, { allow: true }> => decision.allow,
+    );
+    targets = allowed.map((decision) => ({
+      path: decision.path,
+      finalization: decision.descriptor,
+    }));
+  } else {
+    targets = rawTargets
+      .map((path) => canonicalize(coordRoot, path))
+      .filter((path): path is string => path !== null)
+      .map((path) => ({ path }));
+  }
   if (targets.length === 0) return;
 
   const agentCoordBin = coordBinPath("agent-coord", coordRoot) ?? "";
-  if (!existsSync(agentCoordBin)) return;
+  if (!existsSync(agentCoordBin)) {
+    if (agentsRequireGitFinalization(coordRoot)) {
+      const { emitDeny } = await import("./adapter/output.ts");
+      emitDeny(
+        adapter,
+        "Harnery denied the write before mutation because the claim coordinator is unavailable; repair the project's Harnery installation and retry.",
+      );
+    }
+    return;
+  }
 
   // For apply_patch (multi-file), collect siblings so the deny reason names
   // them. For single-file tools the array has one entry.
@@ -1048,7 +1180,7 @@ async function runPreToolUseGuard(
       rule: "claim",
       instance_id: instanceId,
       session_id: sessionId,
-      path: target,
+      path: target.path,
     });
     const result = spawnSync(agentCoordBin, ["verdict"], {
       input: verdictReq,
@@ -1064,10 +1196,12 @@ async function runPreToolUseGuard(
       continue;
     }
     if (parsed.allow === false) {
-      let reason = parsed.reason ?? `Path ${target} is currently being edited by another agent.`;
+      let reason =
+        parsed.reason ?? `Path ${target.path} is currently being edited by another agent.`;
       if (targets.length > 1) {
         const siblings = targets
-          .filter((p) => p !== target)
+          .filter((candidate) => candidate !== target)
+          .map((candidate) => candidate.path)
           .slice(0, 3)
           .join(", ");
         if (siblings) {
@@ -1078,6 +1212,24 @@ async function runPreToolUseGuard(
       emitDeny(adapter, reason);
       return;
     }
+
+    // The verdict mutates the live heartbeat immediately, but that file is a
+    // projection and can be rebuilt at any later hook. Persist the acquisition
+    // in the canonical stream too. This matters most for Codex apply_patch:
+    // one tool call can claim several files, and tool.pre_use's clamped payload
+    // is not a durable ownership representation for those targets.
+    emit(coordRoot, {
+      event_type: "claim.acquire",
+      instance_id: instanceId,
+      session_id: sessionId,
+      adapter,
+      source: "agent-hooks",
+      data: {
+        path: target.path,
+        mode: "write",
+        ...(target.finalization ? { finalization: target.finalization } : {}),
+      },
+    });
   }
 }
 
@@ -1142,14 +1294,18 @@ function healHeartbeatViaCli(
   instanceId: string,
   sessionId: string,
   adapter: string,
+  forkedFrom?: string,
 ): void {
   const agentCoordBin = coordBinPath("agent-coord", coordRoot) ?? "";
   if (!existsSync(agentCoordBin)) return;
   // 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, `--adapter=${adapter}`], {
+  // claude-code and the dashboard mislabels the agent. See
+  // heartbeat-writer.healHeartbeat. --forked-from carries detected fork
+  // lineage for an instance that never session.started (the CC fork flow).
+  const args = ["heal-heartbeat", instanceId, sessionId, `--adapter=${adapter}`];
+  if (forkedFrom) args.push(`--forked-from=${forkedFrom}`);
+  spawnSync(agentCoordBin, args, {
     encoding: "utf8",
     timeout: 2000,
     env: childEnv(coordRoot),
@@ -1384,6 +1540,7 @@ async function emitUserPromptSubmitSystemMessage(
   instanceId: string,
   sessionId: string,
   adapter: Adapter,
+  workspaceCwd?: string,
   recoveryBriefing = "",
 ): Promise<boolean> {
   const agentCoordBin = coordBinPath("agent-coord", coordRoot) ?? "";
@@ -1416,6 +1573,12 @@ async function emitUserPromptSubmitSystemMessage(
     const result = spawnSync(agentCoordBin, args, { encoding: "utf8", timeout: 3000 });
     if (result.status === 0 && result.stdout) additionalContext = result.stdout.trim();
   }
+  if (adapter === "codex") {
+    const fileLinkContext = renderCodexWslFileLinkContext(coordRoot, workspaceCwd);
+    if (fileLinkContext) {
+      additionalContext = [additionalContext, fileLinkContext].filter(Boolean).join("\n\n");
+    }
+  }
   if (recoveryBriefing) {
     additionalContext = [additionalContext, recoveryBriefing].filter(Boolean).join("\n\n");
   }
@@ -1466,7 +1629,7 @@ function emitSubagentStartContext(
 }
 
 function adapterPlatform(adapter: Adapter): string {
-  if (adapter === "claude-code") return "claude_code";
+  if (adapter === "claude-code") return "claude-code";
   return adapter;
 }
 
@@ -1527,6 +1690,21 @@ async function emitSessionStartSystemMessage(
   if (recoveryBriefing) {
     additionalContext = [additionalContext, recoveryBriefing].filter(Boolean).join("\n\n");
   }
+  if (adapter === "codex" && isWslUncPath(emittedData.cwd)) {
+    const fileLinkContext = renderCodexWslFileLinkContext(coordRoot, emittedData.cwd);
+    if (fileLinkContext) {
+      additionalContext = [additionalContext, fileLinkContext].filter(Boolean).join("\n\n");
+    }
+    const bridge = inspectCodexWslBridge(process.env, { expected: true });
+    if (bridge && !bridge.ok) {
+      additionalContext = [
+        additionalContext,
+        `Harnery hybrid warning: ${bridge.detail}. Run \`${resolveBinName(coordRoot)} doctor\` for the repair hint.`,
+      ]
+        .filter(Boolean)
+        .join("\n\n");
+    }
+  }
   if (!additionalContext) return false;
 
   const { emitContext } = await import("./adapter/output.ts");