harnery 0.35.0 → 0.37.0

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

@@ -25,6 +25,7 @@ import { appendFileSync, existsSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { coordFreshnessSeconds } from "../../config.ts";
 import { resolveOwner } from "../../hooks/resolve/owner.ts";
+import { recordLiveClaimChangeV3 } from "../live-authority-v3.ts";
 import { readLiveCoordinationRows } from "../state/live-coordination-view.ts";
 import { instanceHasLivePid } from "../state/pidmap.ts";
 
@@ -34,6 +35,7 @@ interface PeerHeartbeat {
   name?: string;
   files_touched?: string[];
   last_heartbeat?: string;
+  platform?: string;
 }
 
 interface Conflict {
@@ -190,6 +192,15 @@ export function evaluateCommit(coordRoot: string, req: CommitVerdictRequest): Co
     };
   }
 
+  // A blocked commit proves this session has work in every staged path, even
+  // when the edit hook never acquired a claim (for example, a shell edit made
+  // just before another session claimed the same file). Keep those paths on
+  // the blocked session's durable claim set. The original holder's later
+  // commit will then see the overlap instead of silently sweeping this
+  // session's working-tree hunks. A successful later commit releases clean
+  // paths through the existing post-commit hook.
+  retainBlockedStagedPaths(coordRoot, me, mySession, req.staged_paths, peers);
+
   return {
     allow: false,
     exit_code: 1,
@@ -204,6 +215,41 @@ export function evaluateCommit(coordRoot: string, req: CommitVerdictRequest): Co
   };
 }
 
+function retainBlockedStagedPaths(
+  coordRoot: string,
+  instanceId: string,
+  sessionId: string,
+  stagedPaths: readonly string[],
+  peers: readonly PeerHeartbeat[],
+): void {
+  if (instanceId === "__unattributed__") return;
+  const self = peers.find((peer) => peer.instance_id === instanceId);
+  if (!self) return;
+
+  for (const path of stagedPaths) {
+    try {
+      recordLiveClaimChangeV3({
+        coordRoot,
+        owner: instanceId,
+        nativeSessionId: self.session_id ?? sessionId,
+        adapter: adapterFromPlatform(self.platform),
+        operation: "acquired",
+        path,
+        access: "write",
+      });
+    } catch {
+      // The commit is already blocked. Coordination remains fail-open for
+      // authority-write failures so a damaged cache cannot brick Git.
+    }
+  }
+}
+
+function adapterFromPlatform(platform: unknown): "claude-code" | "cursor" | "codex" {
+  if (platform === "cursor") return "cursor";
+  if (platform === "codex") return "codex";
+  return "claude-code";
+}
+
 function findOverlap(
   staged: string,
   files: readonly string[],
@@ -269,6 +315,18 @@ function isHolderSelfAttributed(
   stagedSet: Set<string>,
   peers: readonly PeerHeartbeat[],
 ): boolean {
+  const holder = peers.find((p) => p.instance_id === holderId);
+
+  // Windows-hosted Codex sessions cross a process boundary into WSL, so they
+  // deliberately have no usable PID anchor. Their canonical V3 session row is
+  // the foreign-identity evidence instead. Treating that row as a transient
+  // self identity would suppress the symmetric claim retained after a blocked
+  // commit and reopen the working-tree sweep this guard is meant to stop.
+  if (holder?.platform === "codex" && holder.session_id) {
+    debugGate(coordRoot, { holder: holderId, gate: "B", reason: "canonical_codex_session" });
+    return false;
+  }
+
   // Gate B (cheaper): live foreign pid-map entry blocks self-attribution.
   if (holderHasLiveForeignPid(coordRoot, holderId)) {
     debugGate(coordRoot, { holder: holderId, gate: "B", reason: "live_pid_anchor" });
@@ -276,7 +334,6 @@ function isHolderSelfAttributed(
   }
 
   // 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) {
     debugGate(coordRoot, { holder: holderId, gate: "A", reason: "holder_not_found" });
     return false;

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

@@ -30,6 +30,8 @@ export interface StopHookRequest {
   adapter?: string;
   now_ms?: number;
   turn_window?: { start_ms: number; end_ms: number };
+  stop_hook_active?: boolean;
+  status_box_present_strict?: boolean;
   bypass?: boolean;
   workflow_child?: boolean;
 }
@@ -107,15 +109,24 @@ export function evaluateStopHookV3Events(
       "generation_id" in event.scope &&
       event.scope.generation_id === generationId,
   );
+  const fallbackStartMs = Math.max(0, endMs - 5 * 60 * 1000);
+  const claudeContinuation = req.adapter === "claude-code" && req.stop_hook_active === true;
+  const resolvedStart = resolveTurnStart(ownerEvents, endMs, claudeContinuation);
+  const resolvedStartMs = eventTimeMs(resolvedStart);
   const startMs =
     req.turn_window?.start_ms ??
-    resolveTurnStartMs(ownerEvents, endMs, Math.max(0, endMs - 5 * 60 * 1000));
+    (Number.isFinite(resolvedStartMs) ? resolvedStartMs : fallbackStartMs);
   const inTurn = ownerEvents.filter((event) => {
     const time = eventTimeMs(event);
     return Number.isFinite(time) && time >= startMs && time <= endMs;
   });
 
-  const usedTool = inTurn.some((event) => event.event_type === "tool.requested");
+  const policyEvents =
+    claudeContinuation && resolvedStart
+      ? originalTurnEvents(ownerEvents, resolvedStart, endMs)
+      : inTurn;
+  const usedTool = policyEvents.some((event) => event.event_type === "tool.requested");
+  const cycleAnchor = remediationCycleAnchor(resolvedStart, startMs);
   const statusEvents = inTurn.filter(
     (event) =>
       event.event_type === "coord.status_observed" && event.payload.subject_instance_id === owner,
@@ -139,22 +150,25 @@ export function evaluateStopHookV3Events(
   );
   const latestTerminal = turnTerminals.at(-1);
   const latestBox = observedBoolean(latestTerminal?.payload.ritual?.status_box_present_strict);
-  if (req.adapter !== "cursor" && latestBox === undefined) {
+  const strictBoxObservations = turnTerminals
+    .map((event) => observedBoolean(event.payload.ritual?.status_box_present_strict))
+    .filter((value): value is boolean => value !== undefined);
+  const currentStrictBox = claudeContinuation ? req.status_box_present_strict : undefined;
+  if (latestBox === undefined && currentStrictBox === undefined) {
     return evidenceUnavailable(
       "turn.completed has no observed V3 assistant-text status-box result; Stop remains fail-open",
     );
   }
 
-  const ackPresent = req.adapter === "cursor" ? requiredStatusChecked : latestBox === true;
-  const ackBlock =
-    req.adapter === "cursor"
-      ? () => rule13Block(coordRoot, req.session_id)
-      : () => rule23Block(coordRoot, req.session_id);
+  const ackPresent = claudeContinuation
+    ? strictBoxObservations.includes(true) || currentStrictBox === true
+    : latestBox === true;
+  const ackBlock = () => rule23Block(coordRoot, req.session_id);
 
   // Pure prose turns keep the human-visible acknowledgement but do not require
   // task or final-status mutations. This preserves the pre-V3 policy exactly.
   if (!usedTool) {
-    if (!ackPresent) return ackBlock();
+    if (!ackPresent) return withCycleAnchor(ackBlock(), cycleAnchor);
     return {
       allow: true,
       exit_code: 0,
@@ -163,9 +177,14 @@ export function evaluateStopHookV3Events(
     };
   }
 
-  if (!requiredStatusChecked) return rule13Block(coordRoot, req.session_id);
-  if (!ackPresent) return ackBlock();
-  if (!taskSet) return rule33Block(coordRoot, req.session_id);
+  // Collect EVERY missing signal before returning. Reporting them one at a
+  // time made each additional missing signal cost a whole continuation, and
+  // every continuation forks a fresh hook process: on a busy multi-agent host
+  // the ritual's own enforcement became part of the hook load it polices.
+  const pending: VerdictResult[] = [];
+  if (!requiredStatusChecked) pending.push(rule13Block(coordRoot, req.session_id));
+  if (!ackPresent) pending.push(ackBlock());
+  if (!taskSet) pending.push(rule33Block(coordRoot, req.session_id));
 
   // Claude Code can prove session-name presentation from assistant-only text.
   // Cursor cannot expose that text and Codex returned observe-only above.
@@ -178,10 +197,13 @@ export function evaluateStopHookV3Events(
       !naming.some(({ present }) => present) &&
       !sessionNameSeenStamped(coordRoot, req.instance_id)
     ) {
-      return sessionNameBlock(coordRoot, req.instance_id);
+      pending.push(sessionNameBlock(coordRoot, req.instance_id));
     }
   }
 
+  const blocked = mergeStopBlocks(pending);
+  if (blocked) return withCycleAnchor(blocked, cycleAnchor);
+
   return { allow: true, exit_code: 0, rule: "stop-hook.pass" };
 }
 
@@ -213,29 +235,65 @@ function unconditionalVerdict(req: StopHookRequest): VerdictResult | undefined {
   return undefined;
 }
 
-function resolveTurnStartMs(
+function resolveTurnStart(
   ownerEvents: readonly EventV3[],
   nowMs: number,
-  fallbackMs: number,
-): number {
+  claudeContinuation: boolean,
+): Extract<EventV3, { event_type: "turn.started" }> | undefined {
   const turns = ownerEvents.filter(
     (event): event is Extract<EventV3, { event_type: "turn.started" }> =>
       event.event_type === "turn.started" && eventTimeMs(event) <= nowMs,
   );
-  if (turns.length === 0) return fallbackMs;
+  if (turns.length === 0) return undefined;
 
   let index = turns.length - 1;
   let hops = 0;
   while (index > 0 && hops < MAX_REMEDIATION_WALK_BACK) {
     const turn = turns[index];
-    if (!turn?.payload.stop_remediation) break;
+    const continuesCycle = claudeContinuation
+      ? turn?.provenance.source_event === "claude-code.recovery" &&
+        turn.provenance.attestation === "derived"
+      : turn?.payload.stop_remediation === true;
+    if (!continuesCycle) break;
     index -= 1;
     hops += 1;
   }
-  return eventTimeMs(turns[index]!);
+  return turns[index];
+}
+
+function originalTurnEvents(
+  ownerEvents: readonly EventV3[],
+  turnStart: Extract<EventV3, { event_type: "turn.started" }> | undefined,
+  endMs: number,
+): EventV3[] {
+  if (!turnStart) return [];
+  const startMs = eventTimeMs(turnStart);
+  const terminal = ownerEvents.find(
+    (event) => event.event_type === "turn.completed" && eventTimeMs(event) >= startMs,
+  );
+  const policyEndMs = terminal ? eventTimeMs(terminal) : endMs;
+  return ownerEvents.filter((event) => {
+    const time = eventTimeMs(event);
+    return time >= startMs && time <= policyEndMs;
+  });
+}
+
+function remediationCycleAnchor(
+  turnStart: Extract<EventV3, { event_type: "turn.started" }> | undefined,
+  startMs: number,
+): string {
+  if (turnStart && "turn_id" in turnStart.scope && turnStart.scope.turn_id) {
+    return turnStart.scope.turn_id;
+  }
+  return new Date(startMs).toISOString();
 }
 
-function eventTimeMs(event: EventV3): number {
+function withCycleAnchor(verdict: VerdictResult, anchor: string): VerdictResult {
+  return { ...verdict, remediation_cycle_anchor: anchor };
+}
+
+function eventTimeMs(event: EventV3 | undefined): number {
+  if (!event) return Number.NaN;
   return Date.parse(event.time.observed_at);
 }
 
@@ -284,6 +342,33 @@ function sessionIdSuffix(sessionId?: string): string {
   return sessionId ? ` --session-id ${sessionId}` : "";
 }
 
+/**
+ * Fold every failing end-of-turn signal into ONE verdict.
+ *
+ * The verdict keeps the first failure's rule id, so the `blocked_rule`
+ * telemetry and the adapter's `rule=` stderr contract are unchanged; the
+ * reason enumerates the rest so a single continuation can repair all of them.
+ * Duplicate rules are folded so one continuation repairs every missing signal.
+ */
+function mergeStopBlocks(blocks: VerdictResult[]): VerdictResult | undefined {
+  let primary: VerdictResult | undefined;
+  const seen = new Set<string>();
+  const reasons: string[] = [];
+  for (const block of blocks) {
+    if (seen.has(block.rule)) continue;
+    seen.add(block.rule);
+    if (!primary) primary = block;
+    if (block.reason) reasons.push(block.reason);
+  }
+  if (!primary) return undefined;
+  if (reasons.length < 2) return primary;
+  const numbered = reasons.map((reason, index) => `${index + 1}. ${reason}`).join("\n");
+  return {
+    ...primary,
+    reason: `End-of-turn ritual: ${reasons.length} signals are missing from this turn. Repair ALL of them in this continuation, then stop.\n${numbered}`,
+  };
+}
+
 function rule13Block(coordRoot?: string, sessionId?: string): VerdictResult {
   const missingEvidence = agentsRequireGitFinalization(coordRoot)
     ? "no end_turn_checked coord.status_observed event found in this turn"

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

@@ -10,4 +10,5 @@ export type VerdictResult = {
   exit_code: 0 | 2;
   rule: string;
   reason?: string;
+  remediation_cycle_anchor?: string;
 };

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

@@ -102,6 +102,10 @@ function recordCommandObservation(type: SessionEventType, fields: Record<string,
       monotonic_ns: process.hrtime.bigint().toString(),
     });
     if (result.state === "generation_unavailable") {
+      const expectedLifecycleReopenGap =
+        result.reason === "turn_not_started" &&
+        hook.session_start_derivation === "approved_lifecycle_reopen";
+      if (expectedLifecycleReopenGap) return;
       writeProducerDiagnosticV3(coordRoot, "command_emit_unjoinable", {
         type,
         instance_id: instanceId,

package/src/core/agents/session-finalization-state-v3.ts

@@ -1,7 +1,7 @@
 import { existsSync, lstatSync, readdirSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import type { ApprovedSessionEndReasonV3 } from "../events/v3/producers/recorder.ts";
-import { EVENT_V3_LEDGER_RELATIVE_ROOT } from "../events/v3/writer.ts";
+import { EVENT_V3_LEDGER_RELATIVE_ROOT } from "../events/v3/reader.ts";
 
 export const SESSION_FINALIZATION_REQUEST_FORMAT_V3 =
   "harnery-v3-session-finalization-request" as const;

package/src/core/agents/session-finalizer-v3.ts

@@ -584,7 +584,10 @@ function observeCascades(
     }
     if (
       event.event_type === "lifecycle.sweep_observed" &&
-      event.payload.observation === "stale_sweep"
+      // stale-sweep.ts emits the observation as `stale_heartbeat`; the
+      // finalization request it produces is the one named `stale_sweep`.
+      // Matching the request name here made this branch unreachable.
+      event.payload.observation === "stale_heartbeat"
     ) {
       const record = records.find(
         ({ state }) => !state.terminal && state.instance_id === event.payload.subject_instance_id,
@@ -690,7 +693,10 @@ function ensureRequest(
   };
   const observation = buildObservationEvent(coordRoot, record, request, input);
   request.observation_event_id = observation.event_id as `evt_${string}`;
-  writeEventV3(coordRoot, observation);
+  const durability = writeEventV3(coordRoot, observation, {
+    expectedGenesisId: input.route.genesis_id,
+  });
+  if (durability.state === "epoch_replaced") return null;
   writeRequest(coordRoot, request, true);
   return request;
 }

package/src/core/agents/state/activity-log.ts

@@ -20,6 +20,11 @@ import { readLiveCoordinationRow } from "./live-coordination-view.ts";
 export function resolveShortName(coordRoot: string, instanceId: string | null): string {
   if (!instanceId) return "agent-unknown";
   const row = readLiveCoordinationRow(coordRoot, instanceId);
-  if (row?.name) return `agent-${row.name}`;
-  return `agent-${instanceId.slice(0, 8)}`;
+  return agentDisplayName(instanceId, row?.name);
+}
+
+/** Build a collision-resistant agent label even when identity onboarding has
+ * not produced a usable display name yet. */
+export function agentDisplayName(instanceId: string, name?: string | null): string {
+  return `agent-${name?.trim() || instanceId.slice(0, 8) || "unknown"}`;
 }

package/src/core/agents/state/heartbeat-writer.ts

@@ -108,6 +108,33 @@ export function setIdentityCache(
   return heartbeat;
 }
 
+/** Restore the pool-assigned display name on a generation that was
+ * materialized before the adapter's normal SessionStart naming path ran.
+ * The durable assignment lives in `.name-history`; this only repairs the
+ * disposable generation cache and deliberately leaves durable persona state
+ * (`agent_id`) untouched. */
+export function setAssignedNameCache(
+  coordRoot: string,
+  instanceId: string,
+  name: string,
+  kind: "session" | "subagent" | "transient" = "session",
+): Heartbeat | null {
+  return mutate(coordRoot, instanceId, (heartbeat) => {
+    const suggestedSessionName = heartbeat.suggested_session_name?.replace(
+      /^(\[DONE\]\s+)?Agent unknown( - .+)$/,
+      `$1Agent ${name}$2`,
+    );
+    return {
+      ...heartbeat,
+      name,
+      kind: heartbeat.kind ?? kind,
+      ...(suggestedSessionName && suggestedSessionName !== heartbeat.suggested_session_name
+        ? { suggested_session_name: suggestedSessionName }
+        : {}),
+    };
+  });
+}
+
 /**
  * Build the copy-pasteable session name from the coord identity + the agent's
  * description parts. Pure (no coord-state reads) so it's unit-testable; collapses

package/src/core/agents/state/live-coordination-view.ts

@@ -1,12 +1,5 @@
-import {
-  existsSync,
-  mkdirSync,
-  readdirSync,
-  readFileSync,
-  renameSync,
-  writeFileSync,
-} from "node:fs";
-import { dirname, join } from "node:path";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import type { Adapter } from "../../adapter.ts";
 import {
   type CoordinationGenerationViewV3,
@@ -17,8 +10,8 @@ import {
 import {
   liveInstanceIdV3,
   nativeInstanceIdV3,
-  resolveLiveEventLedgerRouteV3,
-} from "../../events/v3/live-routing.ts";
+  observeLiveEventLedgerRouteV3,
+} from "../../events/v3/live-route-observer.ts";
 import { type Heartbeat, readHeartbeat } from "./heartbeat-reader.ts";
 import { resolveName } from "./names.ts";
 
@@ -36,7 +29,7 @@ export interface V3HeartbeatMaterialization extends Heartbeat {
 
 /** Read the live coordination rows through the hard-cut ledger route. */
 export function readLiveCoordinationRows(coordRoot: string): V3HeartbeatMaterialization[] {
-  const route = resolveLiveEventLedgerRouteV3(coordRoot);
+  const route = observeLiveEventLedgerRouteV3(coordRoot);
   if (route.state === "blocked") return [];
   let view: CoordinationViewV3;
   try {
@@ -69,7 +62,7 @@ export function readLiveCoordinationRow(
   coordRoot: string,
   nativeInstanceId: string,
 ): V3HeartbeatMaterialization | null {
-  const route = resolveLiveEventLedgerRouteV3(coordRoot);
+  const route = observeLiveEventLedgerRouteV3(coordRoot);
   if (route.state === "blocked") return null;
   try {
     const view = requireAuthoritySafeCoordinationViewV3(readCoordinationViewV3(coordRoot));
@@ -84,7 +77,7 @@ export function readLiveCoordinationRow(
     return projectHeartbeatV3(
       coordRoot,
       generation,
-      isCurrentCache(cache, generation) ? cache : undefined,
+      isCurrentV3HeartbeatCache(cache, generation) ? cache : undefined,
       nativeInstanceId,
       parent,
     );
@@ -102,89 +95,18 @@ export function liveCoordinationAdapterV3(
   coordRoot: string,
   nativeInstanceId: string,
 ): Adapter | null {
-  const route = resolveLiveEventLedgerRouteV3(coordRoot);
+  const route = observeLiveEventLedgerRouteV3(coordRoot);
   if (route.state === "blocked") throw new Error(`event_v3_coordination_view:${route.reason}`);
   const view = requireAuthoritySafeCoordinationViewV3(readCoordinationViewV3(coordRoot));
   const generation = view.instances[liveInstanceIdV3(nativeInstanceId)];
   if (!generation?.authority_eligible) return null;
-  const adapter = observedAdapter(generation);
-  if (!isAdapter(adapter)) {
+  const adapter = observedAdapterV3(generation);
+  if (!isAdapterV3(adapter)) {
     throw new Error("event_v3_coordination_view:adapter_not_observed");
   }
   return adapter;
 }
 
-/**
- * Ensure the current V3 generation has a mutation target. The resulting file
- * is explicitly generation-bound and disposable: V3 remains the source of
- * truth, while the cache gives the crash-safe authority outbox an atomic local
- * state to reconcile.
- */
-export function ensureLiveCoordinationHeartbeat(
-  coordRoot: string,
-  nativeInstanceId: string,
-  nativeSessionId: string,
-  _adapter: Adapter,
-  model?: string,
-): Heartbeat | null {
-  const route = resolveLiveEventLedgerRouteV3(coordRoot);
-  if (route.state === "blocked") throw new Error(`event_v3_coordination_view:${route.reason}`);
-  const view = requireAuthoritySafeCoordinationViewV3(readCoordinationViewV3(coordRoot));
-  const generation = view.instances[liveInstanceIdV3(nativeInstanceId)];
-  if (!generation?.authority_eligible) return null;
-  const generationAdapter = observedAdapter(generation);
-  if (!isAdapter(generationAdapter)) {
-    throw new Error("event_v3_coordination_view:adapter_not_observed");
-  }
-  const current = readHeartbeat(coordRoot, nativeInstanceId);
-  if (isCurrentCache(current, generation) && current.platform === generationAdapter) return current;
-
-  const resolved = resolveName(coordRoot, nativeInstanceId, nativeSessionId);
-  const projected = projectHeartbeatV3(coordRoot, generation, undefined, nativeInstanceId);
-  // A generation reopen (resume, mid-flight onboarding) discards the stale
-  // cache, but the adapter tab it names is unchanged: same native session,
-  // same agent identity. Rebuilding without the naming evidence re-mints a
-  // fresh suggested name on the next set-task, so a multi-day session
-  // accumulates titles it is asked to display over and over. Carry the
-  // naming evidence across generations; everything else re-projects from V3.
-  // Same native session id means the same adapter tab; drop the carry only
-  // when the durable identity observably changed (a reassumed name would make
-  // the old "Agent <name> - …" block wrong for the new owner).
-  const identityUnchanged = !resolved?.name || !current?.name || resolved.name === current.name;
-  const carriedNaming =
-    current && current.session_id === nativeSessionId && identityUnchanged
-      ? {
-          ...(current.suggested_session_name
-            ? { suggested_session_name: current.suggested_session_name }
-            : {}),
-          ...(current.session_name_seen_for
-            ? { session_name_seen_for: current.session_name_seen_for }
-            : {}),
-          ...(current.session_name_seen_at
-            ? { session_name_seen_at: current.session_name_seen_at }
-            : {}),
-        }
-      : {};
-  const materialized: V3HeartbeatMaterialization = {
-    ...projected,
-    ...carriedNaming,
-    schema_version: 2,
-    instance_id: nativeInstanceId,
-    session_id: nativeSessionId,
-    name: resolved?.name ?? "",
-    kind: resolved?.kind ?? projected.kind,
-    agent_id: resolved?.agent_id ?? (resolved?.kind === "subagent" ? nativeInstanceId : ""),
-    model: projected.model ?? model ?? "",
-    platform: generationAdapter,
-    v3_instance_id: generation.instance_id as `inst_${string}`,
-    v3_generation_id: generation.generation_id as `gen_${string}`,
-    v3_projection_event_id: generation.last_event_id,
-    v3_task_state: generation.task_state === "set" ? "set" : "cleared",
-  };
-  writeHeartbeatCache(coordRoot, nativeInstanceId, materialized);
-  return materialized;
-}
-
 function readCacheRows(coordRoot: string): Heartbeat[] {
   const dir = join(coordRoot, ".harnery", "active");
   if (!existsSync(dir)) return [];
@@ -210,10 +132,10 @@ function matchingCache(
   caches: Heartbeat[],
   generation: CoordinationGenerationViewV3,
 ): Heartbeat | undefined {
-  return caches.find((cache) => isCurrentCache(cache, generation));
+  return caches.find((cache) => isCurrentV3HeartbeatCache(cache, generation));
 }
 
-function isCurrentCache(
+export function isCurrentV3HeartbeatCache(
   cache: Heartbeat | null | undefined,
   generation: CoordinationGenerationViewV3,
 ): cache is Heartbeat {
@@ -224,14 +146,14 @@ function isCurrentCache(
   );
 }
 
-function projectHeartbeatV3(
+export function projectHeartbeatV3(
   coordRoot: string,
   generation: CoordinationGenerationViewV3,
   cache: Heartbeat | undefined,
   nativeInstanceId: string | undefined,
   parent?: CoordinationGenerationViewV3,
 ): V3HeartbeatMaterialization {
-  const adapter = observedAdapter(generation) ?? cache?.platform ?? "unknown";
+  const adapter = observedAdapterV3(generation) ?? cache?.platform ?? "unknown";
   const model = observedModel(generation) ?? cache?.model ?? "";
   const instanceId =
     nativeInstanceId ?? cache?.instance_id ?? nativeInstanceIdV3(generation.instance_id);
@@ -285,12 +207,12 @@ function projectHeartbeatV3(
   };
 }
 
-function observedAdapter(generation: CoordinationGenerationViewV3): string | undefined {
+export function observedAdapterV3(generation: CoordinationGenerationViewV3): string | undefined {
   const observation = generation.runtime_attestation.adapter;
   return observation.state === "observed" ? observation.value.id : undefined;
 }
 
-function isAdapter(value: string | undefined): value is Adapter {
+export function isAdapterV3(value: string | undefined): value is Adapter {
   return value === "claude-code" || value === "cursor" || value === "codex";
 }
 
@@ -302,14 +224,3 @@ function observedModel(generation: CoordinationGenerationViewV3): string | undef
 function isLifecycleState(value: string | undefined): value is "active" | "blocked" | "done" {
   return value === "active" || value === "blocked" || value === "done";
 }
-
-function writeHeartbeatCache(coordRoot: string, instanceId: string, heartbeat: Heartbeat): void {
-  if (!/^[a-zA-Z0-9._-]{1,128}$/.test(instanceId)) {
-    throw new Error("instance_id is unsafe for heartbeat materialization");
-  }
-  const path = join(coordRoot, ".harnery", "active", `${instanceId}.json`);
-  mkdirSync(dirname(path), { recursive: true });
-  const temporary = `${path}.tmp.${process.pid}`;
-  writeFileSync(temporary, JSON.stringify(heartbeat, null, 2), "utf8");
-  renameSync(temporary, path);
-}