harnery 0.32.0 → 0.34.0

package/src/lib/docs-sweep.ts

@@ -1,6 +1,6 @@
 import { existsSync as __existsSyncForDocs } from "node:fs";
 import { resolve as __resolveForDocs } from "node:path";
-import { readDocStatus } from "./docs-frontmatter.ts";
+import { parseFrontmatter, readDocStatus } from "./docs-frontmatter.ts";
 import { sh } from "./exec.ts";
 
 // Module-level docs context, initialized by initDocsContext() before any
@@ -22,7 +22,7 @@ function isSubmoduleInitialized(name: string): boolean {
   return __existsSyncForDocs(__resolveForDocs(REPO_ROOT, name, ".git"));
 }
 
-import { existsSync, readdirSync, statSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join, relative } from "node:path";
 
 /**
@@ -141,7 +141,18 @@ function walkMdFiles(dir: string, skipReadme = false): string[] {
   return out;
 }
 
-function sweepPlans(repoName: string, repoPath: string, ages: AgeMap, items: SweepItem[]): void {
+function metadataAgeDays(file: string, field: string, nowMs = Date.now()): number | null {
+  try {
+    const value = parseFrontmatter(readFileSync(file, "utf8")).data[field];
+    if (typeof value !== "string") return null;
+    const parsed = Date.parse(value);
+    return Number.isNaN(parsed) ? null : Math.floor((nowMs - parsed) / (1000 * 60 * 60 * 24));
+  } catch {
+    return null;
+  }
+}
+
+function sweepPlans(repoName: string, repoPath: string, items: SweepItem[]): void {
   const plansDir = join(repoPath, "docs", "plans");
   if (!existsSync(plansDir)) return;
 
@@ -150,7 +161,7 @@ function sweepPlans(repoName: string, repoPath: string, ages: AgeMap, items: Swe
     const displayPath = join(repoName === "(root)" ? "" : repoName, rel);
     const isArchived = rel.includes("/archive/");
     const status = readDocStatus(full, "plan");
-    const age = ageDays(ages, rel);
+    const age = metadataAgeDays(full, "status_changed_at");
     if (age == null) continue;
 
     if (!isArchived && status === "in-progress" && age > STALLED_PLAN_DAYS) {
@@ -159,7 +170,7 @@ function sweepPlans(repoName: string, repoPath: string, ages: AgeMap, items: Swe
         repo: repoName,
         path: displayPath,
         ageDays: age,
-        message: `plan is in-progress, last touched ${age}d ago; confirm still active or bump status`,
+        message: `plan has remained in-progress for ${age}d; confirm it is still active or change status`,
       });
     }
     if (!isArchived && status === "shipped" && age > UNARCHIVED_SHIPPED_DAYS) {
@@ -174,7 +185,7 @@ function sweepPlans(repoName: string, repoPath: string, ages: AgeMap, items: Swe
   }
 }
 
-function sweepIssues(repoName: string, repoPath: string, ages: AgeMap, items: SweepItem[]): void {
+function sweepIssues(repoName: string, repoPath: string, items: SweepItem[]): void {
   const issuesDir = join(repoPath, "docs", "issues");
   if (!existsSync(issuesDir)) return;
 
@@ -185,7 +196,7 @@ function sweepIssues(repoName: string, repoPath: string, ages: AgeMap, items: Sw
     const displayPath = join(repoName === "(root)" ? "" : repoName, rel);
     const status = readDocStatus(full, "issue");
     if (status !== "open") continue;
-    const age = ageDays(ages, rel);
+    const age = metadataAgeDays(full, "status_changed_at");
     if (age == null || age <= OPEN_ISSUE_DAYS) continue;
     items.push({
       kind: "open-issue-cold",
@@ -197,7 +208,7 @@ function sweepIssues(repoName: string, repoPath: string, ages: AgeMap, items: Sw
   }
 }
 
-function sweepHandoffs(repoName: string, repoPath: string, ages: AgeMap, items: SweepItem[]): void {
+function sweepHandoffs(repoName: string, repoPath: string, items: SweepItem[]): void {
   const handoffsDir = join(repoPath, "docs", "handoffs");
   if (!existsSync(handoffsDir)) return;
 
@@ -205,7 +216,7 @@ function sweepHandoffs(repoName: string, repoPath: string, ages: AgeMap, items:
     const rel = relative(repoPath, full);
     const status = readDocStatus(full, "handoff");
     if (status !== "open") continue;
-    const age = ageDays(ages, rel);
+    const age = metadataAgeDays(full, "status_changed_at");
     if (age == null || age <= COLD_HANDOFF_DAYS) continue;
     const displayPath = join(repoName === "(root)" ? "" : repoName, rel);
     items.push({
@@ -218,19 +229,23 @@ function sweepHandoffs(repoName: string, repoPath: string, ages: AgeMap, items:
   }
 }
 
-function sweepRunbook(repoName: string, repoPath: string, ages: AgeMap, items: SweepItem[]): void {
-  const runbook = join(repoPath, "docs", "runbook.md");
-  if (!existsSync(runbook)) return;
-  const age = ageDays(ages, "docs/runbook.md");
-  if (age == null || age <= RUNBOOK_DAYS) return;
-  const displayPath = join(repoName === "(root)" ? "" : repoName, "docs/runbook.md");
-  items.push({
-    kind: "runbook-unverified",
-    repo: repoName,
-    path: displayPath,
-    ageDays: age,
-    message: `runbook hasn't been edited in ${age}d; re-verify procedures`,
-  });
+function sweepRunbooks(repoName: string, repoPath: string, items: SweepItem[]): void {
+  const docs = join(repoPath, "docs");
+  if (!existsSync(docs)) return;
+  for (const runbook of walkMdFiles(docs)) {
+    const metadata = parseFrontmatter(readFileSync(runbook, "utf8")).data;
+    if (metadata.schema !== "harnery-doc/v2" || metadata.type !== "runbook") continue;
+    const age = metadataAgeDays(runbook, "reviewed_at");
+    if (age == null || age <= RUNBOOK_DAYS) continue;
+    const rel = relative(repoPath, runbook);
+    items.push({
+      kind: "runbook-unverified",
+      repo: repoName,
+      path: join(repoName === "(root)" ? "" : repoName, rel),
+      ageDays: age,
+      message: `runbook has not been reviewed for ${age}d; verify it with docs metadata sync --reviewed`,
+    });
+  }
 }
 
 function sweepTopicDocs(
@@ -324,10 +339,10 @@ export async function runSweep(opts: SweepOpts): Promise<SweepItem[]> {
   for (let i = 0; i < filtered.length; i++) {
     const { name, path } = filtered[i]!;
     const ages = ageMaps[i]!;
-    sweepPlans(name, path, ages, items);
-    sweepIssues(name, path, ages, items);
-    sweepHandoffs(name, path, ages, items);
-    sweepRunbook(name, path, ages, items);
+    sweepPlans(name, path, items);
+    sweepIssues(name, path, items);
+    sweepHandoffs(name, path, items);
+    sweepRunbooks(name, path, items);
     sweepTopicDocs(name, path, ages, items);
     await sweepDecisions(name, path, ages, items);
   }
@@ -344,7 +359,6 @@ export async function runSweep(opts: SweepOpts): Promise<SweepItem[]> {
  */
 export async function countColdHandoffs(): Promise<number> {
   const items: SweepItem[] = [];
-  const ages = await loadDocsAges(REPO_ROOT);
-  sweepHandoffs("(root)", REPO_ROOT, ages, items);
+  sweepHandoffs("(root)", REPO_ROOT, items);
   return items.length;
 }

package/src/lib/headless/index.ts

@@ -0,0 +1,287 @@
+/**
+ * Headless harness calling — run a one-shot prompt (optionally with images)
+ * through a locally installed AI coding harness CLI and return its reply.
+ *
+ * Backends, in default preference order (subscription seats an embedding
+ * host already pays for, before any metered API a host might add on top):
+ *
+ *   1. claude-code   `claude -p`         JSON envelope on stdout
+ *   2. codex         `codex exec`        last message written to a file
+ *   3. cursor        `cursor-agent -p`   plain text on stdout
+ *
+ * Design rules, each learned from a live failure:
+ *
+ * - Every call runs from a NEUTRAL temp cwd holding only the staged images,
+ *   so the nested session loads no repo instructions, hooks, or coordination
+ *   rituals from the caller's checkout.
+ * - The child's stdin is CLOSED immediately. execFile leaves it open as a
+ *   pipe, and codex interprets that as "more prompt coming" and blocks on
+ *   it, then exits with no output.
+ * - An empty reply THROWS instead of returning "": a one-shot call that
+ *   produced nothing was inconclusive, and callers gating on the result must
+ *   fail closed rather than read silence as success.
+ * - `runHeadless` walks the backend chain PER CALL: a backend that is
+ *   installed but errors (rate limit, timeout, transient exec failure) hands
+ *   the same request to the next backend instead of failing the call. "On
+ *   PATH" is not "working", and under parallel load the first backend can
+ *   flake on a fraction of calls while the second runs clean.
+ *
+ * Env knobs (read through coordEnv, so the HARNERY_ prefix stays in one
+ * place): HARNERY_HEADLESS_BACKEND forces one backend and disables the
+ * fallback walk; HARNERY_HEADLESS_MODEL overrides the model passed to
+ * whichever backend runs.
+ */
+
+import { execFile } from "node:child_process";
+import {
+  accessSync,
+  constants,
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { delimiter, isAbsolute, join } from "node:path";
+import { promisify } from "node:util";
+import { coordEnv } from "../env.ts";
+
+const execFileAsync = promisify(execFile);
+
+/** Names accepted by `runHeadlessOn`, `runHeadless({backends})`, and the
+ * HARNERY_HEADLESS_BACKEND env knob. */
+export type HeadlessBackendName = "claude-code" | "codex" | "cursor";
+
+/** An image to stage into the call's neutral cwd. `data` is the PNG bytes
+ * (Buffer) or their base64 encoding (string). */
+export interface HeadlessImage {
+  data: Buffer | string;
+  /** Staged filename inside the neutral dir (default `image-<n>.png`). */
+  name?: string;
+}
+
+export interface HeadlessRequest {
+  /**
+   * The prompt, or a builder receiving the staged image paths. Backends that
+   * cannot attach an image natively (claude-code, cursor) rely on the prompt
+   * naming the staged paths so the harness reads them with its own tools;
+   * codex additionally attaches every image via `-i`.
+   */
+  prompt: string | ((ctx: { imagePaths: string[] }) => string);
+  images?: HeadlessImage[];
+  /** Model override for this call; HARNERY_HEADLESS_MODEL wins over it. */
+  model?: string;
+  /** Kill the child after this long (default 240_000 ms). */
+  timeoutMs?: number;
+  /** Agentic turn budget where the backend supports one (default 4). */
+  maxTurns?: number;
+}
+
+export interface HeadlessResult {
+  /** The harness's final reply text, never empty (empty replies throw). */
+  text: string;
+  /** Which backend produced it. */
+  backend: HeadlessBackendName;
+}
+
+export interface RunHeadlessOptions {
+  /** Preference order (default: HEADLESS_BACKENDS order). */
+  backends?: HeadlessBackendName[];
+  /** Walk the chain past a failing backend (default true). Forcing a backend
+   * via HARNERY_HEADLESS_BACKEND implies false. */
+  fallback?: boolean;
+}
+
+const MAX_BUFFER = 32 * 1024 * 1024;
+const DEFAULT_TIMEOUT_MS = 240_000;
+const DEFAULT_MAX_TURNS = 4;
+
+/** Cross-runtime `which`: walk PATH (and PATHEXT on Windows) for an
+ * executable. Node has no built-in and Bun.which only exists under Bun. */
+export function whichBin(bin: string): string | undefined {
+  if (isAbsolute(bin)) return isExecutable(bin) ? bin : undefined;
+  const paths = (process.env.PATH ?? "").split(delimiter).filter(Boolean);
+  const exts =
+    process.platform === "win32" ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";") : [""];
+  for (const dir of paths) {
+    for (const ext of exts) {
+      const candidate = join(dir, bin + ext.toLowerCase());
+      if (isExecutable(candidate)) return candidate;
+      if (ext) {
+        const upper = join(dir, bin + ext);
+        if (isExecutable(upper)) return upper;
+      }
+    }
+  }
+  return undefined;
+}
+
+function isExecutable(path: string): boolean {
+  try {
+    if (!statSync(path).isFile()) return false;
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+interface StagedCall {
+  dir: string;
+  imagePaths: string[];
+  prompt: string;
+  model?: string;
+  timeoutMs: number;
+  maxTurns: number;
+}
+
+/** Write the request's images into a fresh neutral dir and resolve the
+ * prompt against their staged paths. Caller must clean the dir up. */
+function stageCall(req: HeadlessRequest): StagedCall {
+  const dir = mkdtempSync(join(tmpdir(), "harnery-headless-"));
+  const imagePaths = (req.images ?? []).map((img, i) => {
+    const path = join(dir, img.name ?? `image-${i + 1}.png`);
+    writeFileSync(path, typeof img.data === "string" ? Buffer.from(img.data, "base64") : img.data);
+    return path;
+  });
+  const prompt = typeof req.prompt === "function" ? req.prompt({ imagePaths }) : req.prompt;
+  return {
+    dir,
+    imagePaths,
+    prompt,
+    model: coordEnv("HEADLESS_MODEL") ?? req.model,
+    timeoutMs: req.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    maxTurns: req.maxTurns ?? DEFAULT_MAX_TURNS,
+  };
+}
+
+/** Run a harness CLI from the neutral dir with stdin CLOSED (see module
+ * comment: an open stdin pipe deadlocks codex). */
+function execHarness(bin: string, args: string[], call: StagedCall) {
+  const pending = execFileAsync(bin, args, {
+    cwd: call.dir,
+    timeout: call.timeoutMs,
+    maxBuffer: MAX_BUFFER,
+  });
+  pending.child.stdin?.end();
+  return pending;
+}
+
+function assertReply(text: string, backend: HeadlessBackendName): HeadlessResult {
+  if (!text.trim()) throw new Error(`${backend}: empty reply (inconclusive; failing closed)`);
+  return { text, backend };
+}
+
+async function runClaudeCode(bin: string, call: StagedCall): Promise<HeadlessResult> {
+  const args = ["-p", call.prompt, "--output-format", "json", "--max-turns", String(call.maxTurns)];
+  if (call.imagePaths.length) args.push("--allowedTools", "Read");
+  if (call.model) args.push("--model", call.model);
+  const { stdout } = await execHarness(bin, args, call);
+  const envelope = JSON.parse(stdout) as { is_error?: boolean; result?: unknown };
+  if (envelope.is_error) {
+    throw new Error(
+      typeof envelope.result === "string" ? envelope.result : "claude-code: headless error",
+    );
+  }
+  return assertReply(typeof envelope.result === "string" ? envelope.result : "", "claude-code");
+}
+
+async function runCodex(bin: string, call: StagedCall): Promise<HeadlessResult> {
+  const outPath = join(call.dir, "last-message.txt");
+  const args = ["exec", "--skip-git-repo-check"];
+  for (const png of call.imagePaths) args.push("-i", png);
+  args.push("--output-last-message", outPath);
+  if (call.model) args.push("-m", call.model);
+  args.push(call.prompt);
+  await execHarness(bin, args, call);
+  return assertReply(existsSync(outPath) ? readFileSync(outPath, "utf-8") : "", "codex");
+}
+
+/** `-f` trusts the neutral dir so cursor's read tool runs without a prompt. */
+async function runCursor(bin: string, call: StagedCall): Promise<HeadlessResult> {
+  const args = ["-p", call.prompt, "--output-format", "text", "-f"];
+  if (call.model) args.push("--model", call.model);
+  const { stdout } = await execHarness(bin, args, call);
+  return assertReply(stdout, "cursor");
+}
+
+type BackendRunner = (bin: string, call: StagedCall) => Promise<HeadlessResult>;
+
+/** The backend registry in default preference order. */
+export const HEADLESS_BACKENDS: ReadonlyArray<{ name: HeadlessBackendName; bin: string }> = [
+  { name: "claude-code", bin: "claude" },
+  { name: "codex", bin: "codex" },
+  { name: "cursor", bin: "cursor-agent" },
+];
+
+const RUNNERS: Record<HeadlessBackendName, BackendRunner> = {
+  "claude-code": runClaudeCode,
+  codex: runCodex,
+  cursor: runCursor,
+};
+
+function backendBin(name: HeadlessBackendName): string | undefined {
+  const entry = HEADLESS_BACKENDS.find((b) => b.name === name);
+  return entry ? whichBin(entry.bin) : undefined;
+}
+
+/** Backends whose binary is on PATH right now, in preference order. Being
+ * listed means installed, not proven working — that is what the per-call
+ * fallback in `runHeadless` is for. */
+export function availableHeadlessBackends(): HeadlessBackendName[] {
+  return HEADLESS_BACKENDS.filter((b) => whichBin(b.bin)).map((b) => b.name);
+}
+
+/** Run the request on exactly one named backend. Throws when the backend is
+ * not installed or the call fails. */
+export async function runHeadlessOn(
+  name: HeadlessBackendName,
+  req: HeadlessRequest,
+): Promise<HeadlessResult> {
+  const bin = backendBin(name);
+  if (!bin) throw new Error(`headless backend not installed: ${name}`);
+  const call = stageCall(req);
+  try {
+    return await RUNNERS[name](bin, call);
+  } finally {
+    rmSync(call.dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Run the request on the first backend that succeeds, walking the preference
+ * order past installed-but-failing backends (unless fallback is disabled or a
+ * backend is forced via HARNERY_HEADLESS_BACKEND). Throws when no backend is
+ * installed, or every attempted backend failed — the error message carries
+ * each backend's failure so a flaky chain is diagnosable.
+ */
+export async function runHeadless(
+  req: HeadlessRequest,
+  opts: RunHeadlessOptions = {},
+): Promise<HeadlessResult> {
+  const forced = coordEnv("HEADLESS_BACKEND") as HeadlessBackendName | undefined;
+  if (forced && !opts.backends) {
+    if (!HEADLESS_BACKENDS.some((b) => b.name === forced)) {
+      throw new Error(`unknown HARNERY_HEADLESS_BACKEND: ${forced}`);
+    }
+    return runHeadlessOn(forced, req);
+  }
+  const order = opts.backends ?? HEADLESS_BACKENDS.map((b) => b.name);
+  const installed = order.filter((name) => backendBin(name));
+  if (!installed.length) {
+    throw new Error(`no headless backend installed (looked for: ${order.join(", ")})`);
+  }
+  const fallback = opts.fallback ?? true;
+  const attempts = fallback ? installed : installed.slice(0, 1);
+  const failures: string[] = [];
+  for (const name of attempts) {
+    try {
+      return await runHeadlessOn(name, req);
+    } catch (err) {
+      failures.push(`${name}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  throw new Error(`every headless backend failed:\n  ${failures.join("\n  ")}`);
+}

package/src/lib/identities/assume.ts

@@ -3,8 +3,8 @@
  *
  * The operation is serialized because "is this name live?" and "claim it"
  * must be one critical section. Authoritative state is written twice on
- * purpose: `.name-history` heals a missing heartbeat, while the canonical
- * `identity.assumed` event makes replay and derived readers converge.
+ * purpose: `.name-history` supplies display metadata, while the canonical
+ * `coord.identity_attested` event makes replay and derived readers converge.
  *
  * Local collision policy: a fresh heartbeat alone is not enough to block.
  * If the namesake has no live pid-map process (crashed session, healed
@@ -14,21 +14,17 @@
  */
 
 import { randomUUID } from "node:crypto";
-import {
-  existsSync,
-  mkdirSync,
-  readdirSync,
-  readFileSync,
-  statSync,
-  unlinkSync,
-  writeFileSync,
-} from "node:fs";
+import { existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
-import { emitAndProject } from "../../core/agents/cli-emit.ts";
-import { emit } from "../../core/agents/events/emit.ts";
-import { type Heartbeat, readHeartbeat } from "../../core/agents/state/heartbeat-writer.ts";
-import { recordNameAssumption, resolveForkAncestry } from "../../core/agents/state/names.ts";
+import { recordLiveIdentityChangeV3 } from "../../core/agents/live-authority-v3.ts";
+import { recordLiveSweepObservationV3 } from "../../core/agents/live-lifecycle-v3.ts";
+import type { Heartbeat } from "../../core/agents/state/heartbeat-writer.ts";
+import {
+  readLiveCoordinationRow,
+  readLiveCoordinationRows,
+} from "../../core/agents/state/live-coordination-view.ts";
+import { resolveForkAncestry } from "../../core/agents/state/names.ts";
 import { instanceHasLivePid, removePidmapRowsForInstance } from "../../core/agents/state/pidmap.ts";
 import { coordFreshnessSeconds } from "../../core/config.ts";
 import { readRemoteMachines } from "../../core/presence/index.ts";
@@ -44,7 +40,7 @@ export type IdentityAssumeErrorCode =
   | "identity_is_ancestor"
   | "identity_not_found"
   | "invalid_identity"
-  | "no_heartbeat"
+  | "no_live_generation"
   | "not_session"
   | "projection_failed";
 
@@ -91,22 +87,19 @@ export function findIdentityConflict(
   instanceId: string,
   name: string,
   nowMs = Date.now(),
+  excludedInstanceIds: ReadonlySet<string> = new Set(),
 ): IdentityConflict | null {
   const wanted = name.toLowerCase();
   const cutoffMs = nowMs - coordFreshnessSeconds(coordRoot) * 1000;
-  const activeDir = join(coordRoot, ".harnery", "active");
-  if (existsSync(activeDir)) {
-    for (const file of readdirSync(activeDir)) {
-      if (!file.endsWith(".json")) continue;
-      try {
-        const hb = JSON.parse(readFileSync(join(activeDir, file), "utf8")) as Heartbeat;
-        if (hb.instance_id === instanceId || !heartbeatIsFresh(hb, cutoffMs)) continue;
-        if ((hb.name ?? "").toLowerCase() === wanted) {
-          return { instance_id: hb.instance_id, name: hb.name ?? name, scope: "local" };
-        }
-      } catch {
-        // Malformed heartbeats are handled by stale sweep, not this command.
-      }
+  for (const row of readLiveCoordinationRows(coordRoot)) {
+    if (
+      row.instance_id === instanceId ||
+      excludedInstanceIds.has(row.instance_id) ||
+      !heartbeatIsFresh(row, cutoffMs)
+    )
+      continue;
+    if ((row.name ?? "").toLowerCase() === wanted) {
+      return { instance_id: row.instance_id, name: row.name ?? name, scope: "local" };
     }
   }
 
@@ -143,13 +136,20 @@ export function reclaimAbandonedLocalConflict(
   let adapter: "claude-code" | "cursor" | "codex" = "claude-code";
   let sessionId = conflict.instance_id;
   let ageSecs: number | undefined;
+  const liveRow = readLiveCoordinationRow(coordRoot, conflict.instance_id);
+  if (liveRow) {
+    adapter = adapterOf(liveRow.platform);
+    sessionId = liveRow.session_id || conflict.instance_id;
+    const ts = Date.parse(liveRow.last_heartbeat);
+    if (Number.isFinite(ts)) ageSecs = Math.max(0, Math.floor((Date.now() - ts) / 1000));
+  }
   if (existsSync(hbPath)) {
     try {
       const hb = JSON.parse(readFileSync(hbPath, "utf8")) as Heartbeat;
+      // Native producer identity is private cache metadata, not ledger authority.
+      // It is required to join the exact producer state when recording the sweep.
       adapter = adapterOf(hb.platform);
       sessionId = hb.session_id || conflict.instance_id;
-      const ts = Date.parse(hb.last_heartbeat);
-      if (Number.isFinite(ts)) ageSecs = Math.max(0, Math.floor((Date.now() - ts) / 1000));
     } catch {
       /* content unreadable — still reclaim the file */
     }
@@ -160,23 +160,14 @@ export function reclaimAbandonedLocalConflict(
     }
   }
   removePidmapRowsForInstance(coordRoot, conflict.instance_id);
-  try {
-    emit(coordRoot, {
-      event_type: "health.heartbeat_swept",
-      instance_id: conflict.instance_id,
-      session_id: sessionId,
-      adapter,
-      source: "agent-coord",
-      data: {
-        reason: "stale",
-        ...(ageSecs !== undefined ? { age_secs: ageSecs } : {}),
-        reclaimed_by: "identity.assume",
-      },
-      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-    } as Parameters<typeof emit>[1]);
-  } catch {
-    /* telemetry only */
-  }
+  recordLiveSweepObservationV3({
+    coordRoot,
+    owner: conflict.instance_id,
+    nativeSessionId: sessionId,
+    adapter,
+    observation: "stale_heartbeat",
+    ageMs: Math.max(0, (ageSecs ?? 0) * 1_000),
+  });
   return true;
 }
 
@@ -260,11 +251,11 @@ export function assumeIdentity(
 ): IdentityAssumeResult {
   const release = acquireLock(coordRoot);
   try {
-    const hb = readHeartbeat(coordRoot, instanceId);
+    const hb = readLiveCoordinationRow(coordRoot, instanceId);
     if (!hb) {
       throw new IdentityAssumeError(
-        "no_heartbeat",
-        `no live heartbeat for instance '${instanceId}'`,
+        "no_live_generation",
+        `no authority-safe live V3 generation for instance '${instanceId}'`,
       );
     }
     if (hb.kind && hb.kind !== "session") {
@@ -298,7 +289,16 @@ export function assumeIdentity(
     let conflict = findIdentityConflict(coordRoot, instanceId, targetIdentity.name);
     if (conflict && reclaimAbandonedLocalConflict(coordRoot, conflict)) {
       reclaimedInstanceId = conflict.instance_id;
-      conflict = findIdentityConflict(coordRoot, instanceId, targetIdentity.name);
+      // The V3 sweep is intentionally provisional, so the generation remains
+      // replay-visible after its disposable cache is removed. Ignore that one
+      // reclaimed holder while still checking for any additional namesake.
+      conflict = findIdentityConflict(
+        coordRoot,
+        instanceId,
+        targetIdentity.name,
+        Date.now(),
+        new Set([reclaimedInstanceId]),
+      );
     }
     if (conflict) {
       const where = conflict.scope === "remote" ? ` on ${conflict.machine}` : "";
@@ -312,15 +312,7 @@ export function assumeIdentity(
 
     const previousName = hb.name || null;
     const previousAgentId = hb.agent_id || null;
-    const history = recordNameAssumption(
-      coordRoot,
-      instanceId,
-      identity.name,
-      identity.agent_id,
-      "session",
-    );
-    const changed =
-      history.changed || previousName !== identity.name || previousAgentId !== identity.agent_id;
+    const changed = previousName !== identity.name || previousAgentId !== identity.agent_id;
     if (!changed) {
       return {
         changed: false,
@@ -336,34 +328,20 @@ export function assumeIdentity(
       };
     }
 
-    const emitted = emitAndProject(
-      {
-        event_type: "identity.assumed",
-        instance_id: instanceId,
-        session_id: hb.session_id,
-        adapter: adapterOf(hb.platform),
-        data: {
-          name: identity.name,
-          agent_id: identity.agent_id,
-          ...(previousName ? { previous_name: previousName } : {}),
-          ...(previousAgentId ? { previous_agent_id: previousAgentId } : {}),
-          ...(reclaimedInstanceId ? { reclaimed_instance_id: reclaimedInstanceId } : {}),
-        },
-      },
-      { coordRoot },
-    );
-    if (!emitted?.projected) {
-      throw new IdentityAssumeError(
-        "projection_failed",
-        "the durable name binding was recorded but event projection failed; rerun the command to heal it",
-      );
-    }
+    const emitted = recordLiveIdentityChangeV3({
+      coordRoot,
+      owner: instanceId,
+      nativeSessionId: hb.native_session_id ?? hb.session_id,
+      adapter: adapterOf(hb.platform),
+      name: identity.name,
+      identityId: identity.agent_id,
+    });
 
-    const projected = readHeartbeat(coordRoot, instanceId);
+    const projected = readLiveCoordinationRow(coordRoot, instanceId);
     if (projected?.name !== identity.name || projected.agent_id !== identity.agent_id) {
       throw new IdentityAssumeError(
         "projection_failed",
-        "identity.assumed was emitted but the heartbeat did not converge; rerun the command",
+        "coord.identity_attested was emitted but the V3 projection did not converge; rerun the command",
       );
     }
     return {
@@ -375,7 +353,10 @@ export function assumeIdentity(
       name: identity.name,
       agent_id: identity.agent_id,
       identity_created: created,
-      event_id: emitted.envelope.event_id,
+      event_id:
+        emitted.state === "recorded" && emitted.result.state === "recorded"
+          ? emitted.result.event.event_id
+          : null,
       reclaimed_instance_id: reclaimedInstanceId,
     };
   } finally {