harnery 0.41.0 → 0.43.0

package/src/commands/web-fetch.ts

@@ -16,9 +16,11 @@ import type { EmitContext } from "../commander.ts";
  * harnery repo at the *matching version tag* into a cache dir and install the
  * web app's deps. Subsequent runs reuse the cache.
  *
- * The only thing `web/` pulls from `src/` is `harnery/core/journal` (a single,
- * dependency-free module), so the install is `web/` deps only: no root install,
- * no Playwright browser download.
+ * `web/` imports readers from `src/`, and `web/next.config.ts` resolves the
+ * root `playwright` package, so the install covers the repository root and
+ * then `web/`. Installing the `playwright` package downloads no browsers.
+ * Installing `web/` alone left `harn web up` failing with
+ * `Cannot find module 'playwright/package.json'`.
  */
 
 const DEFAULT_REPO_URL = "https://github.com/ryanjkelly/harnery.git";
@@ -53,8 +55,8 @@ function webCacheRoot(ref: string): string {
 }
 
 /** bun if available (preferred), else npm. Both support `<runner> install` and `<runner> run <script>`. */
-export function webRunner(): "bun" | "npm" {
-  const r = spawnSync("bun", ["--version"], { stdio: "ignore" });
+export function webRunner(spawn: typeof spawnSync = spawnSync): "bun" | "npm" {
+  const r = spawn("bun", ["--version"], { stdio: "ignore" });
   return r.status === 0 ? "bun" : "npm";
 }
 
@@ -63,14 +65,20 @@ export function webRunner(): "bun" | "npm" {
  * its path, fetching (clone + install) on first use. Returns null on failure
  * (after emitting an actionable error).
  */
-export function lazyFetchWebRoot(emit: EmitContext): string | null {
+export function lazyFetchWebRoot(
+  emit: EmitContext,
+  spawn: typeof spawnSync = spawnSync,
+): string | null {
   const { version, repoUrl } = readPkg();
   const ref = resolveRef(version);
   const cacheRoot = webCacheRoot(ref);
   const webDir = path.join(cacheRoot, "web");
 
-  // node_modules in the cached web/ is the "fetched + installed" marker.
-  if (existsSync(path.join(webDir, "node_modules"))) {
+  // node_modules in both the cached root and web/ is the "fetched + installed" marker.
+  if (
+    existsSync(path.join(cacheRoot, "node_modules")) &&
+    existsSync(path.join(webDir, "node_modules"))
+  ) {
     emit.log(`harn web · using cached dashboard (${ref})`, "info");
     return webDir;
   }
@@ -85,7 +93,7 @@ export function lazyFetchWebRoot(emit: EmitContext): string | null {
   if (existsSync(cacheRoot)) rmSync(cacheRoot, { recursive: true, force: true });
   mkdirSync(path.dirname(cacheRoot), { recursive: true });
 
-  const clone = spawnSync("git", ["clone", "--depth", "1", "--branch", ref, repoUrl, cacheRoot], {
+  const clone = spawn("git", ["clone", "--depth", "1", "--branch", ref, repoUrl, cacheRoot], {
     stdio: "inherit",
   });
   if (clone.status !== 0) {
@@ -100,16 +108,19 @@ export function lazyFetchWebRoot(emit: EmitContext): string | null {
     return null;
   }
 
-  const runner = webRunner();
-  emit.log(`harn web · installing dashboard deps (${runner} install in web/)`, "info");
-  const install = spawnSync(runner, ["install"], { cwd: webDir, stdio: "inherit" });
-  if (install.status !== 0) {
-    emit.error({
-      code: "web_fetch_failed",
-      message: `${runner} install in ${webDir} failed (status ${install.status})`,
-      hint: `Try manually: cd ${webDir} && ${runner} install`,
-    });
-    return null;
+  const runner = webRunner(spawn);
+  for (const dir of [cacheRoot, webDir]) {
+    const where = dir === webDir ? "web/" : "the harnery root";
+    emit.log(`harn web · installing dashboard deps (${runner} install in ${where})`, "info");
+    const install = spawn(runner, ["install"], { cwd: dir, stdio: "inherit" });
+    if (install.status !== 0) {
+      emit.error({
+        code: "web_fetch_failed",
+        message: `${runner} install in ${dir} failed (status ${install.status})`,
+        hint: `Try manually: cd ${dir} && ${runner} install`,
+      });
+      return null;
+    }
   }
 
   emit.log(`harn web · dashboard ready (cached at ${webDir})`, "info");

package/src/commands/web.ts

@@ -82,11 +82,17 @@ export function nodeOptionsWithHeapCap(mb: number): string | undefined {
   return `${inherited} --max-old-space-size=${mb}`.trim();
 }
 
-/** Preload the request diagnostics hook without replacing Next's HTTP server. */
+/**
+ * Preload the dashboard's server hooks (keep-alive and request diagnostics)
+ * without replacing Next's HTTP server. NODE_OPTIONS reaches the child that
+ * `next dev` forks, but Next re-parses every `--import` into one value, so
+ * this names the single combined preload; a second, different `--import`
+ * would collapse into an unloadable path (web/server-preload.mjs).
+ */
 export function nodeOptionsWithWebDiagnostics(webDir: string, mb: number): string {
   const inherited = nodeOptionsWithHeapCap(mb) ?? "";
-  if (inherited.includes("server-performance.mjs")) return inherited;
-  const preload = pathToFileURL(path.join(webDir, "server-performance.mjs")).href;
+  if (inherited.includes("server-preload.mjs")) return inherited;
+  const preload = pathToFileURL(path.join(webDir, "server-preload.mjs")).href;
   return `${inherited} --import=${preload}`.trim();
 }
 

package/src/core/adapters/profiles.ts

@@ -45,6 +45,18 @@ export const BUILTIN_ADAPTER_PROFILES = {
     modelFamily: "claude",
     effortValues: ["low", "medium", "high", "xhigh", "max"],
     verified: { date: "2026-08-18", version: "2.1.233 (Claude Code)" },
+    // Checked against 2.1.283 (ADR 0192). Claude Code has no sandbox mode flag;
+    // its permission mode and its optional Bash sandbox are separate, so full
+    // access needs both: bypass permissions, and a settings layer that turns
+    // the Bash sandbox off in case a user or project settings file enabled it.
+    fullAccess: {
+      argv: [
+        "--permission-mode",
+        "bypassPermissions",
+        "--settings",
+        '{"sandbox":{"enabled":false}}',
+      ],
+    },
     capabilities: capabilities({
       effortSelection: supported("Mapped to `--effort <level>`."),
       maxTurns: supported("Mapped to `--max-turns <n>`."),
@@ -78,6 +90,9 @@ export const BUILTIN_ADAPTER_PROFILES = {
       modes: { "read-only": "read-only", "workspace-write": "workspace-write" },
       writableRoots: true,
     },
+    // Checked against codex-cli 0.155.1 (ADR 0192): `--sandbox` accepts
+    // danger-full-access, and `codex exec` never prompts for approval.
+    fullAccess: { argv: ["--sandbox", "danger-full-access"] },
     capabilities: capabilities({
       effortSelection: supported('Mapped to `-c model_reasoning_effort="<level>"`.'),
       filesystemPolicyProjection: supported(
@@ -107,6 +122,10 @@ export const BUILTIN_ADAPTER_PROFILES = {
     modelFamily: "multi",
     effortValues: [],
     verified: { date: "2026-09-20", version: "2026.09.18-9a7762b" },
+    // Checked against 2026.09.26-dd393fe (ADR 0192): `--sandbox disabled`
+    // overrides the configured sandbox. Cursor carries effort inside the model
+    // id, so a full-access floor for it names exact model ids.
+    fullAccess: { argv: ["--sandbox", "disabled"] },
     capabilities: capabilities({
       effortSelection: unsupported(
         "Cursor embeds effort in some parameterized model ids; Harnery does not rewrite model ids.",
@@ -136,7 +155,9 @@ export const BUILTIN_ADAPTER_PROFILES = {
     authModel: "own-auth",
     modelFamily: "multi",
     // Model reasoning is selected through the `provider/model#variant` id;
-    // OpenCode exposes no separate effort dial for Harnery to map.
+    // OpenCode exposes no separate effort dial for Harnery to map. It also has
+    // no vendor sandbox to remove, so it declares no full-access rendering and
+    // a worker on it is never granted one (ADR 0192).
     effortValues: [],
     verified: { date: "2026-09-20", version: "opencode v2.0.11" },
     capabilities: capabilities({

package/src/core/adapters/types.ts

@@ -67,6 +67,16 @@ export interface AdapterProfile {
   /** How this adapter projects host filesystem policy into the vendor's own
    * sandbox (ADR 0039). Absent means it cannot project any of it. */
   sandboxProjection?: AdapterSandboxProjection;
+  /** Vendor-native arguments that launch a worker with no vendor sandbox
+   * (ADR 0192). Absent means the adapter has no distinguishable full-access
+   * mode, so a worker on it never qualifies for one. */
+  fullAccess?: AdapterFullAccessRendering;
+}
+
+/** How an adapter renders an unsandboxed launch (ADR 0192). The spawner emits
+ * exactly these arguments, so the declaration and the argv cannot drift. */
+export interface AdapterFullAccessRendering {
+  argv: readonly string[];
 }
 
 /** Fully planned child invocation. `resultFile` is used by adapters such as

package/src/core/agents/cli.ts

@@ -309,12 +309,20 @@ async function handleStateAction(root: string, action: string, rest: string[]):
           }
         } catch (error) {
           const detail = error instanceof Error ? error.message : String(error);
-          // A missing heartbeat here means the session's generation ended
-          // while its process lived on. Name the reopen command (ADR 0088);
-          // set-task is usually the first thing such a session runs.
-          const hint = detail.includes("heartbeat_missing:")
-            ? `; run \`${resolveBinName(root)} agents lifecycle active\` to open a fresh generation for this continuing session`
-            : "";
+          // A missing heartbeat usually means the session's generation ended
+          // while its process lived on, so name the reopen command (ADR 0088).
+          // A still-live generation whose authority the ledger withholds looks
+          // the same here; name its diagnostics instead, since reopen cannot apply.
+          const { describeLiveAuthorityBlockV3, liveAuthorityBlockHintV3, liveAuthorityBlockV3 } =
+            await import("./state/live-coordination-view.ts");
+          const block = detail.includes("heartbeat_missing:")
+            ? liveAuthorityBlockV3(root, owner)
+            : null;
+          const hint = block
+            ? `; ${describeLiveAuthorityBlockV3(block)}; ${liveAuthorityBlockHintV3(resolveBinName(root))}`
+            : detail.includes("heartbeat_missing:")
+              ? `; run \`${resolveBinName(root)} agents lifecycle active\` to open a fresh generation for this continuing session`
+              : "";
           process.stderr.write(`agent-coord set-task: V3 authority refused (${detail})${hint}\n`);
           return 1;
         }

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

@@ -57,6 +57,7 @@ import {
   readLiveCoordinationRow,
   readLiveCoordinationRows,
 } from "../state/live-coordination-view.ts";
+import { forkRelationLabels } from "../state/names.ts";
 import type { AgentActivity, TaskState } from "../state/session-state.ts";
 import { formatPendingCouncils, recordDeliveredMessages } from "./session-context.ts";
 
@@ -441,7 +442,11 @@ function computePeerTableIfChanged(
   if (oldHash && oldHash === newHash) return "";
 
   // Render peer table via the same formatter used at SessionStart.
-  const local = formatPeerTable(peers, mySessionId);
+  const local = formatPeerTable(
+    peers,
+    mySessionId,
+    forkRelationLabels(coordRoot, selfInstanceId, new Set(peers.map((p) => p.instance_id ?? ""))),
+  );
   const remoteTable = formatRemoteTable(remote);
   const table = [local, remoteTable].filter(Boolean).join("\n\n");
   if (!table) return "";
@@ -580,7 +585,11 @@ function writeHashFile(path: string, value: string): void {
  * (no cross-file imports of formatting internals). If both renderers diverge,
  * pull the shared bits into a small util module. */
 
-function formatPeerTable(peers: HeartbeatRow[], mySessionId: string): string {
+function formatPeerTable(
+  peers: HeartbeatRow[],
+  mySessionId: string,
+  relations: Map<string, string> = new Map(),
+): string {
   if (peers.length === 0) return "";
   const nowSec = Math.floor(Date.now() / 1000);
 
@@ -592,16 +601,20 @@ function formatPeerTable(peers: HeartbeatRow[], mySessionId: string): string {
     }
   }
 
-  type RowExt = HeartbeatRow & { display_files: string[] };
+  type RowExt = HeartbeatRow & { display_files: string[]; relation?: string };
   const rows: RowExt[] = peers
     .filter((p) => (p.kind ?? "unknown") !== "transient")
     .map((p) => {
       const folded = fold[p.instance_id ?? ""] ?? [];
       const display = Array.from(new Set([...(p.files_touched ?? []), ...folded])).sort();
-      return { ...p, display_files: display };
+      const relation = relations.get(p.instance_id ?? "");
+      return { ...p, display_files: display, ...(relation ? { relation } : {}) };
     });
 
-  const blocking = rows.filter((p) => p.session_id !== mySessionId).sort(byStartedAt);
+  // Related sessions sort first so a fork parent never hides in "+N more".
+  const blocking = rows
+    .filter((p) => p.session_id !== mySessionId)
+    .sort((a, b) => Number(!!b.relation) - Number(!!a.relation) || byStartedAt(a, b));
   const group = rows.filter((p) => p.session_id === mySessionId).sort(byStartedAt);
 
   const out: string[] = [];
@@ -625,7 +638,7 @@ function byStartedAt(a: HeartbeatRow, b: HeartbeatRow): number {
 }
 
 function renderSubtable(
-  rows: Array<HeartbeatRow & { display_files: string[] }>,
+  rows: Array<HeartbeatRow & { display_files: string[]; relation?: string }>,
   header: string,
   nowSec: number,
 ): string {
@@ -635,7 +648,10 @@ function renderSubtable(
   return `${header}\n${first.join("\n")}${overflow}`;
 }
 
-function formatRow(r: HeartbeatRow & { display_files: string[] }, nowSec: number): string {
+function formatRow(
+  r: HeartbeatRow & { display_files: string[]; relation?: string },
+  nowSec: number,
+): string {
   const taskPart = r.task ? ` "${r.task.slice(0, 60)}"` : "";
   const statePart = formatState(r);
   // Fall back started_at → last_heartbeat; if neither is a valid timestamp,
@@ -646,7 +662,8 @@ function formatRow(r: HeartbeatRow & { display_files: string[] }, nowSec: number
   // Prefer a short instance_id over a bare "unknown" so an incomplete row is
   // still identifiable.
   const label = r.name ?? (r.instance_id ? r.instance_id.slice(0, 8) : "unknown");
-  return `  - agent-${label}${taskPart}   (${statePart}, ${ageFrom}, ${filesPart})`;
+  const relation = r.relation ? ` [${r.relation}]` : "";
+  return `  - agent-${label}${relation}${taskPart}   (${statePart}, ${ageFrom}, ${filesPart})`;
 }
 
 function formatState(r: HeartbeatRow): string {

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

@@ -16,7 +16,7 @@ import { appendEntry } from "../../journal/index.ts";
 import { readRemoteMachines } from "../../presence/index.ts";
 import { drainMailbox, formatMailboxDelivery, type MailboxMessageV1 } from "../mailbox.ts";
 import { readLiveCoordinationRows } from "../state/live-coordination-view.ts";
-import { readForkParent } from "../state/names.ts";
+import { forkRelationLabels, readForkState } from "../state/names.ts";
 import type { AgentActivity, TaskState } from "../state/session-state.ts";
 
 interface HeartbeatRow {
@@ -54,7 +54,17 @@ export function renderSessionContext(opts: RenderOpts): string {
 
   // 1. Self-name line + peer table (folded if peers present)
   const peers = readActivePeers(coordRoot, instanceId);
-  const localTable = formatPeerTable(peers, sessionId);
+  const forkState = readForkState(coordRoot, instanceId);
+  const forkParent = forkState?.parent ?? null;
+  const parentRow = forkParent
+    ? peers.find((peer) => peer.instance_id === forkParent.instance_id)
+    : undefined;
+  const relations = forkRelationLabels(
+    coordRoot,
+    instanceId,
+    new Set(peers.map((peer) => peer.instance_id ?? "")),
+  );
+  const localTable = formatPeerTable(peers, sessionId, relations);
   // Cross-machine presence (ADR 0016): sessions on other machines (advisory).
   const peerTable = [localTable, formatRemoteMachines(coordRoot)].filter(Boolean).join("\n\n");
   if (agentName) {
@@ -64,13 +74,11 @@ export function renderSessionContext(opts: RenderOpts): string {
     // 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.";
+    // fall back to the generic clause, which needs no fork detection. A live
+    // parent is the dangerous case (2026-10-07: a fork read its running
+    // parent as its own earlier self and offered to close it), so the notice
+    // names what the parent is doing and forbids ending it.
+    const authority = forkAuthorityClause(forkParent, forkState?.fork === true, parentRow);
     const selfLine = `You are agent-${agentName}${suffix}. ${authority}`;
     messages.push(peerTable ? `${selfLine}\n\n${peerTable}` : selfLine);
   } else if (peerTable) {
@@ -126,6 +134,7 @@ export function renderSessionContext(opts: RenderOpts): string {
       if (d.missing.length > 0)
         bits.push(`missing: ${d.missing.map((m) => m.subcommand).join(", ")}`);
       if (d.orphans.length > 0) bits.push(`orphaned: ${d.orphans.join(", ")}`);
+      if (d.stale.length > 0) bits.push(`outdated: ${d.stale.map((m) => m.subcommand).join(", ")}`);
       return `  - ${d.settingsFile} — ${bits.join("; ")}`;
     });
     messages.push(
@@ -193,13 +202,64 @@ function readActivePeers(coordRoot: string, selfInstanceId: string): HeartbeatRo
   );
 }
 
+const DO_NOT_END =
+  "Do not end, release, or finalize that session unless the operator explicitly tells you to.";
+
+function forkAuthorityClause(
+  parent: { instance_id: string; name: string | null } | null,
+  fork: boolean,
+  parentRow: HeartbeatRow | undefined,
+): string {
+  if (parent?.name && parentRow) {
+    const files = parentRow.files_touched ?? [];
+    const task = parentRow.task ? ` on "${parentRow.task.slice(0, 80)}"` : "";
+    const holds =
+      files.length > 0
+        ? ` and holds ${files.length} file${files.length === 1 ? "" : "s"} (${fmtFileList(files)})`
+        : "";
+    const owned =
+      files.length > 0
+        ? parentRow.task
+          ? "That name, task, and those files"
+          : "That name and those files"
+        : parentRow.task
+          ? "That name and task"
+          : "That name";
+    return (
+      `This conversation was forked from agent-${parent.name}, which is still running as a separate session${task}${holds}. ` +
+      `${owned} belong${owned === "That name" ? "s" : ""} to agent-${parent.name}, not to you. ${DO_NOT_END}`
+    );
+  }
+  if (parent?.name) {
+    return `This conversation was branched from agent-${parent.name}'s session: earlier context showing agent-${parent.name}'s name, task, or file claims belongs to the pre-fork session, not to you.`;
+  }
+  if (parent) {
+    return `This conversation was branched from another session (${parent.instance_id}); any agent name in earlier context belongs to that session, not to you.`;
+  }
+  if (fork) {
+    return `This conversation was forked from another session, which may still be running. Any agent name, task, or file claim in earlier context belongs to that session, not to you. ${DO_NOT_END}`;
+  }
+  return "Any different agent name in earlier context was inherited from another session; this one is authoritative.";
+}
+
+function fmtFileList(files: string[]): string {
+  const sorted = [...files].sort();
+  return sorted.length <= 3
+    ? sorted.join(", ")
+    : `${sorted.slice(0, 3).join(", ")}, +${sorted.length - 3} more`;
+}
+
 /**
  * Renders the peer table as
  * two subsections: "Other agent groups active" (blocking) and "Your group"
  * (subagents/siblings, no mutual block). Folds transient subagents' files
  * into their parent session.
  */
-function formatPeerTable(peers: HeartbeatRow[], mySessionId: string): string {
+function formatPeerTable(
+  peers: HeartbeatRow[],
+  mySessionId: string,
+  relations: Map<string, string> = new Map(),
+): string {
   if (peers.length === 0) return "";
   const nowSec = Math.floor(Date.now() / 1000);
 
@@ -213,16 +273,20 @@ function formatPeerTable(peers: HeartbeatRow[], mySessionId: string): string {
   }
 
   // Build rows with display_files (own files + folded transient files).
-  type RowExt = HeartbeatRow & { display_files: string[] };
+  type RowExt = HeartbeatRow & { display_files: string[]; relation?: string };
   const rows: RowExt[] = peers
     .filter((p) => (p.kind ?? "unknown") !== "transient")
     .map((p) => {
       const folded = fold[p.instance_id ?? ""] ?? [];
       const display = Array.from(new Set([...(p.files_touched ?? []), ...folded])).sort();
-      return { ...p, display_files: display };
+      const relation = relations.get(p.instance_id ?? "");
+      return { ...p, display_files: display, ...(relation ? { relation } : {}) };
     });
 
-  const blocking = rows.filter((p) => p.session_id !== mySessionId).sort(byStartedAt);
+  // Related sessions sort first so the parent never hides in "+N more".
+  const blocking = rows
+    .filter((p) => p.session_id !== mySessionId)
+    .sort((a, b) => Number(!!b.relation) - Number(!!a.relation) || byStartedAt(a, b));
   const group = rows.filter((p) => p.session_id === mySessionId).sort(byStartedAt);
 
   const sections: string[] = [];
@@ -247,7 +311,7 @@ function byStartedAt(a: HeartbeatRow, b: HeartbeatRow): number {
 }
 
 function renderSubtable(
-  rows: Array<HeartbeatRow & { display_files: string[] }>,
+  rows: Array<HeartbeatRow & { display_files: string[]; relation?: string }>,
   header: string,
   nowSec: number,
 ): string {
@@ -257,7 +321,10 @@ function renderSubtable(
   return `${header}\n${first.join("\n")}${overflow}`;
 }
 
-function formatRow(r: HeartbeatRow & { display_files: string[] }, nowSec: number): string {
+function formatRow(
+  r: HeartbeatRow & { display_files: string[]; relation?: string },
+  nowSec: number,
+): string {
   const taskPart = r.task ? ` "${r.task.slice(0, 60)}"` : "";
   const activity = r.activity ?? "unknown";
   const lifecycle = r.task_state ?? "active";
@@ -265,7 +332,8 @@ function formatRow(r: HeartbeatRow & { display_files: string[] }, nowSec: number
     lifecycle === "blocked" && r.task_state_reason ? `: ${r.task_state_reason.slice(0, 80)}` : "";
   const ageFrom = fmtAge(nowSec - parseIsoSec(r.started_at));
   const filesPart = fmtFiles(r.display_files);
-  return `  - agent-${r.name ?? "unknown"}${taskPart}   (activity=${activity}, lifecycle=${lifecycle}${reason}, ${ageFrom}, ${filesPart})`;
+  const relation = r.relation ? ` [${r.relation}]` : "";
+  return `  - agent-${r.name ?? "unknown"}${relation}${taskPart}   (activity=${activity}, lifecycle=${lifecycle}${reason}, ${ageFrom}, ${filesPart})`;
 }
 
 function fmtFiles(files: string[]): string {

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

@@ -226,3 +226,76 @@ function observedModel(generation: CoordinationGenerationViewV3): string | undef
 function isLifecycleState(value: string | undefined): value is "active" | "blocked" | "done" {
   return value === "active" || value === "blocked" || value === "done";
 }
+
+/** Why a still-live V3 generation has lost coordination authority. */
+export interface LiveAuthorityBlockV3 {
+  generation_id: string;
+  scope: "generation" | "ledger";
+  diagnostics: { code: string; event_id?: string }[];
+}
+
+/**
+ * Explain an authority refusal for a generation that is still live. Callers
+ * reach this after a lookup came back empty; without it the caller sees only
+ * "missing", which reads like an ended session and points at a reopen that
+ * cannot apply. Returns null when no live generation exists or nothing blocks.
+ */
+export function liveAuthorityBlockV3(
+  coordRoot: string,
+  nativeInstanceId: string,
+): LiveAuthorityBlockV3 | null {
+  let view: CoordinationViewV3;
+  try {
+    if (observeLiveEventLedgerRouteV3(coordRoot).state === "blocked") return null;
+    view = readCoordinationViewV3(coordRoot);
+  } catch {
+    return null;
+  }
+  const generation = view.instances[liveInstanceIdV3(nativeInstanceId)];
+  if (generation?.phase !== "live" || generation.authority_eligible) return null;
+  const own = (view.diagnostics_by_generation[generation.generation_id] ?? []).filter(
+    (diagnostic) => diagnostic.authority_blocking,
+  );
+  const blocking = own.length
+    ? own
+    : view.global_diagnostics.filter((diagnostic) => diagnostic.authority_blocking);
+  if (!blocking.length) return null;
+  return {
+    generation_id: generation.generation_id,
+    scope: own.length ? "generation" : "ledger",
+    diagnostics: blocking.map((diagnostic) => ({
+      code: diagnostic.source_code
+        ? `${diagnostic.code}:${diagnostic.source_code}`
+        : diagnostic.code,
+      ...(diagnostic.event_id ? { event_id: diagnostic.event_id } : {}),
+    })),
+  };
+}
+
+/** One-line description of a live authority block, naming codes and events. */
+export function describeLiveAuthorityBlockV3(block: LiveAuthorityBlockV3): string {
+  const byCode = new Map<string, string[]>();
+  for (const { code, event_id } of block.diagnostics) {
+    const events = byCode.get(code) ?? [];
+    if (event_id) events.push(event_id);
+    byCode.set(code, events);
+  }
+  const parts = [...byCode].map(([code, events]) => {
+    const shown = events.slice(0, 2).join(", ");
+    const more = events.length > 2 ? `, +${events.length - 2} more` : "";
+    return events.length ? `${code} ×${events.length} (${shown}${more})` : code;
+  });
+  const where =
+    block.scope === "generation"
+      ? `the event ledger holds ${block.diagnostics.length} authority-blocking diagnostic(s) for it`
+      : "the event ledger holds authority-blocking diagnostics that block every generation";
+  return `generation ${block.generation_id} is still live, but ${where}: ${parts.join("; ")}`;
+}
+
+/** Recovery pointer for a live authority block, in place of the reopen hint. */
+export function liveAuthorityBlockHintV3(binName: string): string {
+  return (
+    `\`${binName} agents lifecycle active\` cannot help because it only reopens an ended ` +
+    `generation; \`${binName} agents health\` lists the diagnostics`
+  );
+}