harnery 0.43.0 → 0.44.0

package/src/commands/browse.ts

@@ -134,6 +134,7 @@ import {
 import {
   harvestDomain,
   harvestWindowsChromeCookies,
+  keepWindowsChromeSession,
   stopWindowsChromeProfile,
   windowsChromePath,
   windowsLocalAppData,
@@ -3465,15 +3466,18 @@ function useWindowsPlainLogin(): boolean {
 
 /**
  * The WSL form of `--login`: the person signs in through the Windows
- * Chrome on a dedicated Windows profile with nothing attached. When the window
- * closes, the profile's cookies for the sign-in site are read and merged into
- * the shared cookie store, which later `browse` runs attach.
+ * Chrome on a dedicated Windows profile with nothing attached. Before the
+ * window opens, the profile is set to continue where it left off, so Chrome
+ * keeps browser-session cookies when the window closes. When the window
+ * closes, the profile's cookies for the sign-in site are read and merged
+ * into the shared cookie store, which later `browse` runs attach, and the
+ * last page open on that site is reported so an agent can resume from it.
  */
 async function runWindowsPlainLogin(
   url: string,
   storePath: string,
   loginCloseFile: string | null,
-  emit: { log: (message: string, level: "info" | "warn" | "error" | "debug") => void },
+  emit: Pick<EmitContext, "log" | "data">,
 ): Promise<void> {
   const chromeLinux = windowsChromePath();
   const localAppData = windowsLocalAppData();
@@ -3484,6 +3488,13 @@ async function runWindowsPlainLogin(
   }
   const chromeWindows = wslPathToWindows(chromeLinux);
   const profileWindows = windowsPlainProfile(localAppData);
+  const keep = keepWindowsChromeSession({ chromeWindows, profileWindows });
+  if (!keep.kept) {
+    emit.log(
+      "[--login] Could not set the sign-in profile to keep browser-session cookies. A sign-in that relies on them survives only if you end it from the terminal instead of closing the window.",
+      "warn",
+    );
+  }
   const child = spawn(
     chromeLinux,
     [`--user-data-dir=${profileWindows}`, "--no-first-run", "--no-default-browser-check", url],
@@ -3507,24 +3518,49 @@ async function runWindowsPlainLogin(
   );
   await Promise.race(waits);
   lifecycleAbort.abort();
-  stopWindowsChromeProfile(profileWindows);
+  const stop = stopWindowsChromeProfile(profileWindows);
+  if (stop.forced > 0) {
+    emit.log(
+      "[--login] Chrome did not close when asked and was stopped. Cookies set in its last 30 seconds may be missing; run the sign-in again if later pages are signed out.",
+      "warn",
+    );
+  }
   await Promise.race([exited, new Promise((r) => setTimeout(r, 5000))]);
   const domain = harvestDomain(url);
-  const cookies = harvestWindowsChromeCookies({ chromeWindows, profileWindows, domain });
+  const { cookies, pages } = harvestWindowsChromeCookies({ chromeWindows, profileWindows, domain });
+  const lastPage = pages[0] ?? null;
+  const names = [...new Set(cookies.map((cookie) => cookie.name))].sort();
+  const sessionCookies = cookies.filter((cookie) => cookie.expires <= 0).length;
   if (cookies.length === 0) {
     emit.log(
       `[--login] No ${domain} cookies were found in the Windows profile; the sign-in may not have completed.`,
       "warn",
     );
-    return;
+  } else {
+    const jar = new CookieJar({ path: storePath, source: "harn-browse" });
+    jar.save(mergeCookies(jar.load(), cookies));
+    emit.log(
+      `[--login] Copied ${cookies.length} ${domain} cookies (${sessionCookies} browser-session) into ${storePath}: ${names.join(", ")}.`,
+      "info",
+    );
   }
-  const jar = new CookieJar({ path: storePath, source: "harn-browse" });
-  jar.save(mergeCookies(jar.load(), cookies));
-  const names = [...new Set(cookies.map((cookie) => cookie.name))].sort().join(", ");
-  emit.log(
-    `[--login] Copied ${cookies.length} ${domain} cookies into ${storePath}: ${names}.`,
-    "info",
-  );
+  if (lastPage) {
+    emit.log(
+      `[--login] Last page: ${lastPage} (the last page you had open on ${domain}; open it to continue where the sign-in left off, since its address may carry a sign-in token that cookies alone do not replace).`,
+      "info",
+    );
+  }
+  emit.data({
+    login: {
+      domain,
+      store: storePath,
+      cookies: cookies.length,
+      sessionCookies,
+      names,
+      lastPage,
+      pages,
+    },
+  });
 }
 
 async function waitForLoginCloseFile(path: string, signal?: AbortSignal): Promise<void> {

package/src/commands/diagnostics.ts

@@ -50,6 +50,7 @@ export function registerDiagnosticsCommand(
           findings,
           bundles,
           capability,
+          supervisor: readSupervisorStatus(repoRoot),
           total_findings: findings.length,
           total_bundles: bundles.length,
         });
@@ -68,6 +69,7 @@ export function registerDiagnosticsCommand(
             schema_version: DIAGNOSTIC_COMMAND_SCHEMA_VERSION,
             kind: "diagnostic_finding",
             finding,
+            supervisor: readSupervisorStatus(repoRoot),
             timeline:
               readSupervisorTimeline(repoRoot, finding.id) ?? buildSupervisorTimeline(finding),
             explanation:
@@ -118,6 +120,7 @@ export function registerDiagnosticsCommand(
           schema_version: DIAGNOSTIC_COMMAND_SCHEMA_VERSION,
           kind: "diagnostic_advice",
           source: { mode: "live" },
+          supervisor: readSupervisorStatus(repoRoot),
           advice: buildDiagnosticAdvice({
             assessment: published.assessment,
             priorHysteresis: published.prior_hysteresis,
@@ -204,6 +207,13 @@ function liveFindingsCapability(repoRoot: string, reportPresent: boolean): Super
   }
   const status = readSupervisorStatus(repoRoot);
   if (status.running) return { source_kind: "supervisor.findings", state: "supported" };
+  if (status.liveness === "unknown")
+    return {
+      source_kind: "supervisor.findings",
+      state: "error",
+      reason_code: "supervisor_generation_unknown",
+      detail: status.build_status,
+    };
   return {
     source_kind: "supervisor.findings",
     state: "expired",

package/src/commands/doctor.ts

@@ -421,15 +421,34 @@ function checkWorkflowAdapter(adapter: AdapterName): { check: Check; installed:
 }
 
 function checkNode(): Check {
-  const v = process.versions.node;
+  return nodeCheck(whichVersion("node"), process.versions);
+}
+
+/**
+ * Report the `node` on PATH, which is what Node-based tools run. Under Bun,
+ * `process.versions.node` is the Node version Bun emulates, not an installed
+ * Node, so it is used only when doctor itself runs on Node and PATH has none.
+ */
+export function nodeCheck(
+  onPath: { ok: boolean; out: string },
+  runtime: { node: string; bun?: string },
+): Check {
+  const hint = "https://nodejs.org/en/download";
+  let v = onPath.ok ? onPath.out.replace(/^v/, "") : "";
+  if (!v) {
+    if (runtime.bun) {
+      return {
+        name: "node",
+        severity: "warn",
+        detail: "not on PATH (Bun runs harnery; Node-based tools need it)",
+        hint,
+      };
+    }
+    v = runtime.node;
+  }
   const major = Number.parseInt(v.split(".")[0], 10);
   if (Number.isNaN(major) || major < 20) {
-    return {
-      name: "node",
-      severity: "fail",
-      detail: `${v} (need ≥ 20)`,
-      hint: "https://nodejs.org/en/download",
-    };
+    return { name: "node", severity: "fail", detail: `${v} (need ≥ 20)`, hint };
   }
   return { name: "node", severity: "ok", detail: v };
 }

package/src/commands/governor.ts

@@ -385,12 +385,13 @@ function registerServiceCommand(
     .action(async (opts: { json?: boolean }) => {
       await withGovernorRootAsync(emit, async (coordRoot) => {
         let status = requestGovernorServiceStop(coordRoot);
+        const signal = { signal_sent: status.signal_sent, signal_verdict: status.signal_verdict };
         const deadline = Date.now() + 5_000;
         while (status.running && Date.now() < deadline) {
           await delay(50);
           status = readGovernorServiceStatus(coordRoot);
         }
-        emitServiceStatus(status, opts.json, emit);
+        emitServiceStatus({ ...status, ...signal }, opts.json, emit);
       });
     });
 
@@ -534,19 +535,31 @@ function emitServiceStatus(
     emit.data(status);
     return;
   }
-  if (!status.config && !status.record) {
-    emit.text("governor service: unconfigured\n");
-    return;
-  }
-  const state = status.running
-    ? (status.record?.state ?? "running")
-    : status.stale
-      ? "stale"
-      : "stopped";
+  const state =
+    status.liveness === "unknown"
+      ? "unknown"
+      : !status.config && !status.record
+        ? "unconfigured"
+        : status.running
+          ? (status.record?.state ?? "running")
+          : status.stale
+            ? "stale"
+            : "stopped";
   const lines = [
     `governor service: ${state}`,
+    `generation: ${status.generation}`,
+    `liveness: ${status.liveness}`,
+    `running build: ${status.running_build ? `${status.running_build.version} (${status.running_build.revision})` : "unknown"}`,
+    `installed build: ${status.installed_build.version} (${status.installed_build.revision})`,
+    `build: ${status.build_status}`,
     `goals: ${status.config?.goal_ids.join(", ") || "none"}`,
   ];
+  if (status.signal_sent !== undefined) {
+    lines.push(`signal sent: ${status.signal_sent ? "yes" : "no"} (${status.signal_verdict})`);
+    if (!status.signal_sent && status.record?.state !== "stopped") {
+      lines.push("The durable stop request remains for the service to read.");
+    }
+  }
   if (status.record) {
     lines.push(`pid: ${status.record.pid} on ${status.record.host}`);
     lines.push(`heartbeat: ${status.record.heartbeat_at}`);

package/src/commands/inbox.ts

@@ -1,18 +1,21 @@
 import type { Command } from "commander";
 import type { EmitContext } from "../commander.ts";
 import type { HarneryInboxService } from "../core/inbox/service.ts";
+import { watchInbox } from "../core/inbox/watcher.ts";
 
 export function registerInboxCommand(
   program: Command,
   emit: EmitContext,
   service?: HarneryInboxService,
+  defaultRecipient?: () => string,
 ): void {
   const inbox = program.command("inbox").description("Inspect private coordination inbox state");
   inbox
-    .command("list <recipient>")
+    .command("list [recipient]")
     .option("--json", "Emit stable JSON")
-    .action((recipient: string, options: { json?: boolean }) => {
+    .action((recipient: string | undefined, options: { json?: boolean }) => {
       run(emit, () => {
+        recipient = requireRecipient(recipient, defaultRecipient);
         const rows = requireInboxService(service)
           .pending(recipient)
           .map((record) => ({
@@ -22,6 +25,7 @@ export function registerInboxCommand(
             created_at: record.created_at,
             body_bytes: record.body_bytes,
             body: record.body,
+            state: "pending",
           }));
         if (options.json) {
           emit.config({ format: "json" });
@@ -41,6 +45,52 @@ export function registerInboxCommand(
         } else emit.rows([status as unknown as Record<string, unknown>]);
       });
     });
+  inbox
+    .command("watch [recipient]")
+    .description("Surface pending messages for this instance; poll history until timeout")
+    .option("--timeout <seconds>", "Stop after this many seconds", "60")
+    .option("--json", "Emit one JSON record per surfaced message")
+    .action(async (recipient: string | undefined, options: { json?: boolean; timeout: string }) => {
+      let controller: AbortController | undefined;
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      try {
+        const instanceId = requireRecipient(recipient, defaultRecipient);
+        const inboxService = requireInboxService(service);
+        const seconds = Number(options.timeout);
+        if (!Number.isFinite(seconds) || seconds <= 0 || seconds > 3600)
+          throw new Error("--timeout must be greater than 0 and at most 3600 seconds");
+        controller = new AbortController();
+        timer = setTimeout(() => controller!.abort(), seconds * 1000);
+        if (options.json) emit.config({ format: "json" });
+        for await (const message of watchInbox(inboxService, instanceId, {
+          signal: controller.signal,
+        })) {
+          const row = { ...message, state: "surfaced" };
+          if (options.json) emit.data(row);
+          else emit.rows([row]);
+          // An output error leaves this ID pending for prompt recovery.
+          await new Promise<void>((resolve, reject) =>
+            process.stdout.write("", (error) => (error ? reject(error) : resolve())),
+          );
+          inboxService.acknowledgeSurface(instanceId, [message.message_id]);
+        }
+      } catch (error) {
+        emit.error({
+          code: "inbox_failed",
+          message: error instanceof Error ? error.message : String(error),
+        });
+        emit.setExitCode(1);
+      } finally {
+        if (timer) clearTimeout(timer);
+        controller?.abort();
+      }
+    });
+}
+
+function requireRecipient(recipient: string | undefined, fallback?: () => string): string {
+  const resolved = recipient ?? fallback?.();
+  if (!resolved) throw new Error("recipient instance is required outside an agent session");
+  return resolved;
 }
 
 function requireInboxService(service?: HarneryInboxService): HarneryInboxService {

package/src/commands/rm.ts

@@ -1,9 +1,10 @@
 import { spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
-import { isAbsolute, relative, resolve, sep } from "node:path";
+import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import type { Command } from "commander";
 import type { EmitContext, HarneryProgramContext } from "../commander.ts";
 import { resolveCoordRoot } from "../core/agents/coord-client.ts";
+import { artifactsRoot, parseArtifactManifest } from "../core/artifacts/index.ts";
 import {
   readCoordinationViewV3,
   requireAuthoritySafeCoordinationViewV3,
@@ -25,6 +26,15 @@ export function registerRmCommand(
       "Allowed directory; each target must be strictly inside it",
     )
     .option("-r, --recursive", "Permit directory removal after inspecting its complete contents")
+    .option(
+      "--clean-clone",
+      "Remove only clean standalone clones inside one owned artifact; refuse local-only commits and worktrees",
+    )
+    .option(
+      "--entry-limit <n>",
+      "Maximum inspected entries, 1-100000 (default 10000); larger limits require one current caller-owned managed artifact as --root",
+      (value: string) => Number(value),
+    )
     .option(
       "--allow-protected <path>",
       "Remove this one protected path (Git metadata, credentials, Harnery state, keys) inside a target; repeat per path",
@@ -65,7 +75,34 @@ export function registerRmCommand(
         const liveRoots = [coordRoot, gitTopLevel(process.cwd())].filter((dir): dir is string =>
           Boolean(dir),
         );
-        const report = guardedRemove(paths, { ...options, liveRoots }, checkClaims);
+        const assertOwnedArtifact = (root: string): void => {
+          if (!coordRoot || dirname(root) !== realpathSync(artifactsRoot(coordRoot)))
+            throw new Error("Copied state requires --root to name one owned managed artifact");
+          const view = requireAuthoritySafeCoordinationViewV3(readCoordinationViewV3(coordRoot));
+          const owner = resolveOwner({ payload: null, coordRoot });
+          const ownId = owner ? liveInstanceIdV3(owner.instance_id) : undefined;
+          if (!ownId || !view.instances[ownId]?.authority_eligible)
+            throw new Error("Copied state requires an authenticated current artifact owner");
+          const record = resolve(root, ".harnery-artifact.json");
+          const stat = lstatSync(record);
+          if (!stat.isFile() || stat.isSymbolicLink())
+            throw new Error("An owned artifact requires a regular manifest file");
+          const parsed = parseArtifactManifest(JSON.parse(readFileSync(record, "utf8")));
+          if (
+            !parsed.ok ||
+            parsed.manifest.released_at ||
+            !parsed.manifest.created_by?.instance_id ||
+            liveInstanceIdV3(parsed.manifest.created_by.instance_id) !== ownId
+          )
+            throw new Error(
+              "Copied state requires a valid unreleased artifact owned by the caller",
+            );
+        };
+        const report = guardedRemove(
+          paths,
+          { ...options, liveRoots, assertOwnedArtifact },
+          checkClaims,
+        );
         if (options.json) {
           emit.config({ format: "json" });
           emit.data(report);
@@ -76,7 +113,9 @@ export function registerRmCommand(
           ];
           if (report.protected.length)
             lines.push(
-              "Protected paths named with --allow-protected:",
+              options.cleanClone
+                ? "Verified clone metadata:"
+                : "Protected paths named with --allow-protected:",
               ...report.protected.map((path) => `  ${path}`),
             );
           if (report.links.length)

package/src/commands/servers.ts

@@ -120,6 +120,7 @@ export function registerServersCommand(
                   type: "unregistered",
                   label: stray.command,
                   pid: stray.pid,
+                  ...(stray.start_token ? { start_token: stray.start_token } : {}),
                   host: hostname(),
                   started_at: new Date().toISOString(),
                   registered_at: new Date().toISOString(),
@@ -207,10 +208,20 @@ export function registerServersCommand(
             emit.config({ format: "json" });
             emit.data({ applied: Boolean(options.yes), pruned: report.pruned, decisions, results });
           } else {
-            const lines = decisions.map(
-              (d) =>
-                `${d.action === "stop" ? (options.yes ? "stopped" : "would stop") : "keep"}  ${d.id}  ${d.reason}`,
-            );
+            const lines = decisions.map((decision) => {
+              const result = results.find((item) => item.id === decision.id);
+              const action =
+                decision.action === "keep"
+                  ? "keep"
+                  : !options.yes
+                    ? "would stop"
+                    : result?.stopped
+                      ? "stopped"
+                      : result?.method === "not-running"
+                        ? "already stopped"
+                        : "could not stop";
+              return `${action}  ${decision.id}  ${result?.detail ?? decision.reason}`;
+            });
             if (report.pruned.length)
               lines.push(`Removed records of exited servers: ${report.pruned.join(", ")}`);
             if (!decisions.length) lines.push("No registered servers.");
@@ -218,6 +229,7 @@ export function registerServersCommand(
               lines.push("Preview only. Re-run with --yes to stop.");
             emit.text(lines.join("\n"));
           }
+          if (results.some((result) => result.method === "refused")) emit.setExitCode(1);
         } catch (error) {
           fail(error);
         }

package/src/commands/supervisor.ts

@@ -83,11 +83,16 @@ export function registerSupervisorCommand(
     .action(async (options: { root?: string }) => {
       try {
         const root = resolve(options.root ?? coordRoot(context));
-        let status = requestSupervisorStop(root);
+        const requested = requestSupervisorStop(root);
+        let status = requested;
         const deadline = Date.now() + 5_000;
         while (status.running && Date.now() < deadline) {
           await new Promise((done) => setTimeout(done, 50));
-          status = readSupervisorStatus(root);
+          status = {
+            ...readSupervisorStatus(root),
+            signal_sent: requested.signal_sent,
+            signal_verdict: requested.signal_verdict,
+          };
         }
         emit.data(status);
       } catch (error) {

package/src/commands/toc.ts

@@ -172,17 +172,25 @@ function renderToc(r: TocResult): string {
   return lines.join("\n");
 }
 
-async function runSection(file: string, query: string, opts: SectionOpts): Promise<SectionResult> {
+export async function runSection(
+  file: string,
+  query: string,
+  opts: SectionOpts,
+): Promise<SectionResult> {
   if (!query.trim()) throw new Error("header query required");
   const tocResult = await runToc(file, {});
   const absPath = resolve(file);
   const lines = readFileSync(absPath, "utf8").split("\n");
 
-  const matches = tocResult.headers.filter((h) =>
-    opts.caseSensitive
-      ? h.text.includes(query)
-      : h.text.toLowerCase().includes(query.toLowerCase()),
-  );
+  const same = (a: string, b: string) =>
+    opts.caseSensitive ? a === b : a.toLowerCase() === b.toLowerCase();
+  const contains = (a: string, b: string) =>
+    opts.caseSensitive ? a.includes(b) : a.toLowerCase().includes(b.toLowerCase());
+  // A header that equals the query wins over headers that merely contain it,
+  // so "Media" can still select "## Media" beside "## Media recipes".
+  const exact = tocResult.headers.filter((h) => same(h.text, query.trim()));
+  const matches =
+    exact.length > 0 ? exact : tocResult.headers.filter((h) => contains(h.text, query));
   if (matches.length === 0) {
     throw new Error(
       `no header matching "${query}". Run \`${resolveBinName()} toc ${file}\` to list available headers.`,

package/src/commands/workflow.ts

@@ -618,11 +618,11 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
   workflow
     .command("reclaim <run-id>")
     .description(
-      "Resolve a workspace preserved because it was dirty: salvage the work to its branch, then release.",
+      "Preview reclaim of an inactive owned workspace, or confirm salvage or discard and release.",
     )
     .option("--yes", "Confirm that this commits or discards uncommitted work, then releases")
     .option("--discard", "Throw the uncommitted work away instead of salvaging it")
-    .option("--json", "Emit the reclaim preparation and cleanup result as JSON")
+    .option("--json", "Emit the reclaim preview or confirmed result as JSON")
     .action(async (runId: string, opts: WorkflowReclaimOpts) => {
       const coordRoot = resolveCoordRoot();
       if (!coordRoot) {
@@ -632,53 +632,53 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
         });
         process.exit(1);
       }
-      if (!opts.yes) {
-        emit.error({
-          code: "reclaim_confirmation_required",
-          message: opts.discard
-            ? "reclaim --discard permanently destroys uncommitted work; pass --yes to confirm"
-            : "workspace reclaim commits uncommitted work to its branch and then releases the worktree; pass --yes to confirm",
-        });
-        process.exit(1);
-      }
       try {
-        const { inspectWorkflowWorkspace, prepareReclaim, cleanupWorkspace } = await import(
+        const { createLocalGitWorktreeProvider, readWorkflowRunManifest } = await import(
           "../core/workflow/index.ts"
         );
-        const inspection = inspectWorkflowWorkspace(coordRoot, runId);
-        if (!inspection.ok) {
-          emit.error({ code: "workflow_reclaim_failed", message: inspection.error });
-          process.exit(1);
-        }
-        const allocation = inspection.value.allocation;
-        if (!allocation) {
+        const binding = readWorkflowRunManifest(coordRoot, runId).execution.workspace_binding;
+        if (binding?.provider.id !== "local-git-worktree") {
           emit.error({
             code: "workflow_reclaim_unavailable",
             message: `run ${runId} has no provider-owned Git workspace to reclaim`,
           });
           process.exit(1);
         }
-        const preparation = prepareReclaim({
-          worktreePath: allocation.active_root,
+        const provider = createLocalGitWorktreeProvider({ coordRoot });
+        const result = await provider.reclaim(binding, {
           mode: opts.discard ? "discard" : "salvage",
-          runId,
+          yes: opts.yes,
         });
-        // Cleanup still owns removal. Reclaim only changes whether the tree it
-        // finds is dirty, so there is one audited release path, not two.
-        const provider = await builtInProviderForRun(coordRoot, runId);
-        const cleanup = await cleanupWorkspace({ coordRoot, runId, provider });
         if (opts.json) {
           emit.config({ format: "json" });
-          emit.data({ preparation, cleanup });
+          emit.data(result);
+          return;
+        }
+        if (result.action === "preview") {
+          const holders = result.lease_holder.map(
+            (holder) =>
+              `${holder.scope}: ${holder.owner_id ?? "unknown"}${holder.pid ? ` (pid ${holder.pid})` : ""}${holder.detail ? `; ${holder.detail}` : ""}`,
+          );
+          emit.text(
+            `reclaim preview: ${result.run_id}\n` +
+              `mode: ${result.mode}\nliveness: ${result.liveness}\nownership: ${result.ownership}\n` +
+              `lease holder: ${holders.length > 0 ? holders.join(", ") : "none observed"}\n` +
+              `dirty paths: ${result.dirty_paths === null ? "unknown" : result.dirty_paths.length > 0 ? result.dirty_paths.join(", ") : "none"}\n` +
+              (result.ownership_detail ? `ownership detail: ${result.ownership_detail}\n` : "") +
+              `Pass --yes to confirm ${result.mode} and release after all checks pass.\n`,
+          );
           return;
         }
         emit.text(
-          `reclaim ${preparation.action}: ${preparation.detail}\n` +
-            `workspace cleanup ${cleanup.status}: ${cleanup.binding_id}\n`,
+          `reclaim ${result.preparation.action}: ${result.preparation.detail}\n` +
+            `workspace cleanup ${result.cleanup.status}: ${result.cleanup.binding_id}\n`,
         );
       } catch (error) {
         emit.error({
-          code: "workflow_reclaim_failed",
+          code:
+            error instanceof Error && "code" in error && typeof error.code === "string"
+              ? error.code
+              : "workflow_reclaim_failed",
           message: error instanceof Error ? error.message : String(error),
         });
         process.exit(1);

package/src/core/agents/live-authority-v3.ts

@@ -88,6 +88,7 @@ interface LiveAuthorityBaseV3 {
   nativeSessionId: string;
   adapter: Adapter;
   observationId?: string;
+  expectedGenerationId?: `gen_${string}`;
 }
 
 /**
@@ -648,6 +649,13 @@ function recordLiveAuthority<S extends CoordinationAuthoritySignalV3>(
     platform: livePlatformV3(),
     expected_prior_state_digest: coordinationAuthorityStateDigestV3(expected),
     desired_state_digest: coordinationAuthorityStateDigestV3(desired),
+    expected_generation_id:
+      input.expectedGenerationId ??
+      ((subject === input.owner
+        ? expected.v3_generation_id
+        : readLiveCoordinationRow(input.coordRoot, input.owner)?.v3_generation_id) as
+        | `gen_${string}`
+        | undefined),
     reconciler: {
       readStateDigest: () => {
         const heartbeat = readHeartbeat(input.coordRoot, subject);
@@ -681,6 +689,12 @@ export function liveCoordinationWriteModeV3(coordRoot: string): EventV3WriteMode
 }
 
 function requireHeartbeat(input: LiveAuthorityBaseV3, owner: string): Heartbeat {
+  if (
+    input.expectedGenerationId &&
+    readLiveCoordinationRow(input.coordRoot, owner)?.v3_generation_id !== input.expectedGenerationId
+  ) {
+    throw new LiveCoordinationAuthorityV3Error("expected_generation_changed");
+  }
   const heartbeat = ensureLiveCoordinationHeartbeat(
     input.coordRoot,
     owner,
@@ -688,6 +702,9 @@ function requireHeartbeat(input: LiveAuthorityBaseV3, owner: string): Heartbeat
     input.adapter,
   );
   if (!heartbeat) throw new LiveCoordinationAuthorityV3Error(`heartbeat_missing:${owner}`);
+  if (input.expectedGenerationId && heartbeat.v3_generation_id !== input.expectedGenerationId) {
+    throw new LiveCoordinationAuthorityV3Error("expected_generation_changed");
+  }
   return heartbeat;
 }