@afokapu/atdd-flow 0.3.59 → 0.3.61

package/extensions/pi/index.ts

@@ -3,8 +3,9 @@ import { mkdir, readFile, rename, rm, stat, unlink, writeFile } from "node:fs/pr
 import { basename, dirname, join } from "node:path";
 import { parse, stringify } from "yaml";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { clearStaleRuntimeState, clearRuntimeState, heartbeatRuntimeState, ownsRuntimeState, registerRuntimeState, runtimeOwnerToken, withOwnedRuntimeState } from "../../src/runtime-state";
+import { clearStaleRuntimeState, clearRuntimeState, heartbeatRuntimeState, ownsRuntimeState, recordMailActivation, registerRuntimeState, runtimeOwnerToken, withOwnedRuntimeState } from "../../src/runtime-state";
 import { paths, readYaml, type Seat } from "../../src/core";
+import { activationNotice, diagnoseMailActivation, expectsNativeMail } from "../../src/mail-activation-notice";
 import { type NoticeState, createNoticeState, refreshDelivered, sendTaskDirective, shouldNotifyMail } from "../../src/next-action-notices";
 import { handoverThresholdInstruction, runtimeStartupInstruction, successorInstruction } from "../../src/collaboration-policy";
 import { type RecoveryMode, recoveryFor } from "../../src/recovery-bundle";
@@ -44,6 +45,8 @@ export type PiRuntimeOptions = {
   heartbeatMs?: number;
   staleAfterMs?: number;
   deliver: InboxOptions["deliver"];
+  /** Live Pi session id recorded on the advisory runtime state for status seat. */
+  piSession?: string;
   createTransport?: (options: InboxOptions) => FlowInboxTransport;
   /** Flow-launched Pi instances register and heartbeat before their verified launch activates inbox delivery. */
   deferActivation?: boolean;
@@ -236,7 +239,7 @@ export const createInboxReconciler = createInboxTransport;
  */
 export function createPiRuntime({
   root, seat, pid = process.pid, model = process.env.PI_MODEL ?? "pi", cwd = process.cwd(),
-  heartbeatMs = defaultHeartbeatMs, staleAfterMs = defaultStaleAfterMs, deliver, createTransport = createInboxTransport, deferActivation = false,
+  heartbeatMs = defaultHeartbeatMs, staleAfterMs = defaultStaleAfterMs, deliver, piSession, createTransport = createInboxTransport, deferActivation = false,
 }: PiRuntimeOptions) {
   const ownerToken = runtimeOwnerToken();
   let transport: FlowInboxTransport | undefined;
@@ -258,7 +261,7 @@ export function createPiRuntime({
   const activate = async () => {
     if (!await owned()) return false;
     if (activated) return true;
-    transport = createTransport({
+    const candidate = createTransport({
       root, seat, batchSize: defaultBatchSize, intervalMs: defaultIntervalMs,
       deliver: async (mail, thread, path) => {
         // The application supplies the wake action, but this shared filesystem
@@ -275,7 +278,9 @@ export function createPiRuntime({
         return ownership === true && accepted !== false;
       },
     });
-    await transport.start();
+    // The transport counts as started only after start() succeeds; a failed start is stopped and leaves no transport behind.
+    try { await candidate.start(); } catch (error) { candidate.stop(); throw error; }
+    transport = candidate;
     activated = true;
     return true;
   };
@@ -283,7 +288,7 @@ export function createPiRuntime({
     // This removes only an expired local observation. Registration itself is
     // replacement-safe and does not alter the authoritative Desk seat.
     await clearStaleRuntimeState(root, seat, staleAfterMs);
-    await registerRuntimeState(root, { seat, owner_token: ownerToken, pid, model, cwd });
+    await registerRuntimeState(root, { seat, owner_token: ownerToken, pid, model, cwd, ...(piSession ? { pi_session: piSession } : {}) });
     heartbeat = setInterval(() => {
       void heartbeatRuntimeState(root, seat, ownerToken).then((state) => {
         if (!state) void stop();
@@ -291,15 +296,21 @@ export function createPiRuntime({
     }, heartbeatMs);
     if (!deferActivation) await activate();
   };
-  return { ownerToken, start, activate, stop, reconcile, get transport() { return transport; } };
+  return { ownerToken, start, activate, stop, reconcile, get transport() { return transport; }, get active() { return activated; } };
 }
 
 type LaunchReceipt = { seat?: string; pi_session?: string; pi_session_path?: string; herdr_session?: string; pane?: string };
 
+/** The bounded window ended without a verified receipt and matching binding. */
+export class ActivationTimeout extends Error {
+  constructor() { super("Timed out waiting for verified Flow launch receipt and binding."); }
+}
+
 /** Wait only for the launcher's already-verified receipt and exact Desk binding; this never creates either record. */
 export async function awaitLaunchActivation({ root, seat, piSession, herdrSession, pane, activate, intervalMs = defaultActivationIntervalMs, timeoutMs = defaultActivationTimeoutMs }: LaunchActivationOptions) {
   const deadline = Date.now() + timeoutMs;
-  while (Date.now() <= deadline) {
+  let matched = false;
+  while (!matched && Date.now() <= deadline) {
     try {
       const record = await readYaml<Seat>(paths(root).seatFile(seat));
       const runtime = record.runtime;
@@ -307,16 +318,26 @@ export async function awaitLaunchActivation({ root, seat, piSession, herdrSessio
       if (runtime?.application === "herdr" && typeof locator !== "string" && locator?.session === herdrSession && locator.pane === pane
         && runtime.pi_session === piSession && runtime.pi_session_path && runtime.launch_receipt) {
         const receipt = await readYaml<LaunchReceipt>(runtime.launch_receipt);
-        if (receipt.seat === seat && receipt.pi_session === piSession && receipt.pi_session_path === runtime.pi_session_path
-          && receipt.herdr_session === herdrSession && receipt.pane === pane) {
-          await activate();
-          return;
-        }
+        matched = receipt.seat === seat && receipt.pi_session === piSession && receipt.pi_session_path === runtime.pi_session_path
+          && receipt.herdr_session === herdrSession && receipt.pane === pane;
       }
     } catch { /* Binding and receipt are written after Herdr verification; wait within this finite window. */ }
-    await pause(intervalMs);
+    if (!matched) await pause(intervalMs);
+  }
+  // The callback runs at most once, outside the polling try: a failing startup step is reported, never retried every poll.
+  if (matched) return activate();
+  throw new ActivationTimeout();
+}
+
+/** A transient start failure (for example a busy inbox lock under concurrent reloads) is retried a bounded number of times before it is reported. */
+export async function activateWithRetry(activate: () => Promise<boolean>, attempts = 3, delayMs = 1_000) {
+  for (let attempt = 1; ; attempt += 1) {
+    try { return await activate(); }
+    catch (error) {
+      if (attempt >= attempts) throw error;
+      await pause(delayMs);
+    }
   }
-  throw new Error("Timed out waiting for verified Flow launch receipt and binding.");
 }
 
 /**
@@ -393,7 +414,23 @@ export default function (pi: ExtensionAPI) {
     } catch { /* No validated replacement request exists for this source session. */ }
   });
   pi.on("session_start", async (_event, ctx) => {
-    runtime = createPiRuntime({ root, seat, deferActivation: true, deliver: async (mail, thread, path, sendIfOwned) => {
+    const sessionManager = (ctx as { sessionManager?: { getSessionId?: () => string; getSessionFile?: () => string | undefined } }).sessionManager;
+    const liveSession = process.env.ATDD_FLOW_PI_SESSION ?? sessionManager?.getSessionId?.();
+    // One display-only notice per session: a refused, timed-out or failed activation must never be silent, and never wakes the agent.
+    let noticed = false;
+    const noticeActivation = async (transport: "active" | "inactive", error?: string) => {
+      if (noticed) return;
+      noticed = true;
+      const live = { pi_session: liveSession, herdr_session: process.env.ATDD_FLOW_HERDR_SESSION ?? process.env.HERDR_SESSION, pane: process.env.ATDD_FLOW_HERDR_PANE ?? process.env.HERDR_PANE_ID };
+      const activation = await diagnoseMailActivation(root, seat, live, transport, error).catch(() => undefined);
+      if (!activation) return;
+      if (runtime) await recordMailActivation(root, seat, runtime.ownerToken, activation).catch(() => undefined);
+      if (transport === "active" && !error) return;
+      const content = await activationNotice(root, seat, activation).catch(() => undefined);
+      const customType = transport === "active" ? "atdd-flow-mail-startup-failed" : "atdd-flow-mail-inactive";
+      if (content) pi.sendMessage({ customType, content, display: true, details: { seat, live, authority: "binding" } }, { triggerTurn: false });
+    };
+    runtime = createPiRuntime({ root, seat, piSession: liveSession, deferActivation: true, deliver: async (mail, thread, path, sendIfOwned) => {
       if (!sendIfOwned) return false;
       if (hostActivatedAt !== undefined && Date.parse(typeof mail.created_at === "string" ? mail.created_at : "") < hostActivatedAt) return sendIfOwned(async () => undefined);
       const notify = typeof mail.id === "string" && typeof thread.id === "string" && await shouldNotifyMail(root, seat, notices, thread.id, mail.id);
@@ -412,7 +449,6 @@ export default function (pi: ExtensionAPI) {
     const herdrSession = process.env.ATDD_FLOW_HERDR_SESSION;
     const pane = process.env.ATDD_FLOW_HERDR_PANE;
     if (!piSession && !herdrSession && !pane) {
-      const sessionManager = (ctx as { sessionManager?: { getSessionId?: () => string; getSessionFile?: () => string | undefined } }).sessionManager;
       if (await hostAttachedActivation({ root, seat, herdrSession: process.env.HERDR_SESSION, pane: process.env.HERDR_PANE_ID, piSession: sessionManager?.getSessionId?.(), piSessionPath: sessionManager?.getSessionFile?.() })) {
         hostActivatedAt = Date.now();
         if (await runtime.activate()) {
@@ -420,7 +456,7 @@ export default function (pi: ExtensionAPI) {
           const notice = "Notices created before this session were not replayed; run atdd-flow status seat " + seat + " for unanswered mail.";
           pi.sendMessage({ customType: "atdd-flow-start", content: `${runtimeStartupInstruction(seat, bundle)} ${notice}`, display: true, details: { seat, root } }, { triggerTurn: true, deliverAs: "followUp" });
         }
-      }
+      } else if (await expectsNativeMail(root, seat)) await noticeActivation("inactive");
       return;
     }
     if (!piSession || !herdrSession || !pane) return;
@@ -428,7 +464,7 @@ export default function (pi: ExtensionAPI) {
     void awaitLaunchActivation({
       root, seat, piSession, herdrSession, pane,
       activate: async () => {
-        if (!await current.activate()) return;
+        if (!await activateWithRetry(() => current.activate())) return;
         const request = await readHandoverReplacement(root, seat).catch(() => undefined);
         const successor = request && request.source.pi_session !== piSession ? request : undefined;
         const bundle = await recovery(root, seat, successor ? "successor" : "start", piSession);
@@ -443,7 +479,9 @@ export default function (pi: ExtensionAPI) {
         await sendTaskDirective(host, root, seat, notices);
         if (ctx.hasUI) ctx.ui.notify(`ATDD Flow native mail active for ${seat}`, "info");
       },
-    }).catch(() => undefined);
+    }).catch((error) => error instanceof ActivationTimeout
+      ? noticeActivation("inactive")
+      : noticeActivation(current.active ? "active" : "inactive", error instanceof Error ? error.message : String(error)));
   });
   pi.on("session_shutdown", () => { void runtime?.stop(); });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afokapu/atdd-flow",
-  "version": "0.3.59",
+  "version": "0.3.61",
   "description": "Filesystem-first Desk registry for projects, seats, tasks, threads, and handoffs.",
   "type": "module",
   "bin": {

package/src/mail-activation-notice.ts

@@ -0,0 +1,75 @@
+// URN: component:flow:e009:mail-activation-notice:backend:application
+// Tested-By:
+// - test:flow:relaunched-seat-mail-activation
+// - test:flow:inactive-mail-notice-diagnosable
+// Runtime: bun
+// Purpose: Name a Pi whose native mail is inactive; it never rewrites a binding.
+
+import { existsSync } from "node:fs";
+import { paths, readYaml, type Seat } from "./core";
+import type { MailActivation } from "./runtime-state";
+import { seatTasks, terminal } from "./tasks";
+
+/** The bound and live Pi sessions of a seat whose native mail cannot activate. */
+export type InactiveMail = { bound?: string; live?: string };
+
+/** The live identifiers a Pi compared with its seat binding; an unknown value is left undefined. */
+export type LiveIdentity = { pi_session?: string; herdr_session?: string; pane?: string };
+
+async function readSeat(root: string, seat: string) {
+  try { return await readYaml<Seat>(paths(root).seatFile(seat)); } catch { return undefined; }
+}
+
+/** Only a seat bound for native wake expects Pi to deliver its mail; host-wake seats are not warned. */
+export async function expectsNativeMail(root: string, seat: string) {
+  return (await readSeat(root, seat))?.runtime?.wake === "native";
+}
+
+/** The task coordinator to ask for a relaunch, or main of the seat's project when no open task names one. */
+async function relaunchOwner(root: string, seat: string) {
+  const project = seat.slice(seat.lastIndexOf("@") + 1);
+  try {
+    const open = (await seatTasks(root, project, seat)).find((entry) => entry.task.assignee === seat && !terminal(entry.task));
+    return open?.task.coordinator ?? `main@${project}`;
+  } catch { return `main@${project}`; }
+}
+
+function boundIdentity(record: Seat | undefined): MailActivation["bound"] {
+  const runtime = record?.runtime;
+  const locator = runtime?.addresses.herdr;
+  const scoped = typeof locator === "object" ? locator : undefined;
+  const receipt = runtime?.launch_receipt ? (existsSync(runtime.launch_receipt) ? "present" : "missing") : "none";
+  return { pi_session: runtime?.pi_session, herdr_session: scoped?.session, pane: scoped?.pane, receipt };
+}
+
+/** Compares the live identity with the seat binding at call time; an unknown live value counts as differing from a bound one. */
+export async function diagnoseMailActivation(root: string, seat: string, live: LiveIdentity, transport: MailActivation["transport"], error?: string): Promise<MailActivation> {
+  const bound = boundIdentity(await readSeat(root, seat));
+  const fields = [["session", live.pi_session, bound.pi_session], ["herdr", live.herdr_session, bound.herdr_session], ["pane", live.pane, bound.pane]] as const;
+  const differs = fields.filter(([, liveValue, boundValue]) => boundValue !== undefined && liveValue !== boundValue).map(([name]) => name);
+  return { at: new Date().toISOString(), transport, live, bound, differs, ...(error ? { error } : {}) };
+}
+
+/** The exact compared values, shared by the notice and `status seat`. */
+export function describeActivation(activation: MailActivation) {
+  const value = (entry?: string) => entry ?? "unknown";
+  const { live, bound } = activation;
+  return `live session=${value(live.pi_session)} herdr=${value(live.herdr_session)} pane=${value(live.pane)}; bound session=${value(bound.pi_session)} herdr=${value(bound.herdr_session)} pane=${value(bound.pane)} receipt=${bound.receipt}`;
+}
+
+/** Display-only text: INACTIVE only when the transport never started; a failed later startup step is reported as ACTIVE. */
+export async function activationNotice(root: string, seat: string, activation: MailActivation) {
+  const values = describeActivation(activation);
+  if (activation.transport === "active") {
+    return `SYSTEM: native Flow mail is ACTIVE for ${seat}; a startup step failed: ${activation.error ?? "unknown"}. Display only; no action is required for mail delivery. ${values}.`;
+  }
+  const differs = activation.differs.length ? ` Differs: ${activation.differs.join(", ")} (live does not match the binding).` : " All compared values match.";
+  const error = activation.error ? ` Last activation error: ${activation.error}.` : "";
+  const owner = await relaunchOwner(root, seat);
+  return `SYSTEM: native Flow mail is INACTIVE for ${seat} (display only). ${values}.${differs}${error} Queued mail will not reach this pane. Run atdd-flow status seat ${seat}; ask ${owner} to relaunch via atdd-flow pi runtime launch ${seat}.`;
+}
+
+/** A fresh advisory runtime whose live session differs from the seat binding; legacy or matching records report nothing. */
+export function nativeMailInactive(bound: string | undefined, live: string | undefined): InactiveMail | undefined {
+  return bound && live && bound !== live ? { bound, live } : undefined;
+}

package/src/overview.ts

@@ -2,6 +2,7 @@ import { readdir } from "node:fs/promises";
 import { canonicalAddress, desk, exists, paths, readYaml, type Checkpoint, type Seat } from "./core";
 import { type Task, type TaskHandoff, type TaskStatus, terminal } from "./tasks";
 import { isRuntimeStateStale, readRuntimeState } from "./runtime-state";
+import { describeActivation, nativeMailInactive } from "./mail-activation-notice";
 import { type Message, type Thread } from "./threads";
 
 type ListedTask = { project: string; id: string; task: Task; waiting: string[] };
@@ -354,6 +355,10 @@ async function seatDashboard(root: string, address: string) {
   for (const [application, nativeAddress] of Object.entries(runtime?.addresses ?? {})) console.log(`  ${application}${application === runtime?.application ? " *" : "  "} ${nativeAddress}`);
   const advisory = await readRuntimeState(root, resolved);
   if (advisory) console.log(`  pi advisory  ${isRuntimeStateStale(advisory, 60_000) ? "stale" : "active"} · ${advisory.model} · pid ${advisory.pid} · heartbeat ${advisory.heartbeat_at}`);
+  const inactive = advisory && !isRuntimeStateStale(advisory, 60_000) ? nativeMailInactive(runtime?.pi_session, advisory.pi_session) : undefined;
+  if (inactive) console.log(`  ${tone("native mail inactive", "WAITING")} (bound ${inactive.bound}, live ${inactive.live})`);
+  const activation = advisory && !isRuntimeStateStale(advisory, 60_000) ? advisory.mail_activation : undefined;
+  if (activation) console.log(`  native mail ${activation.transport}: ${describeActivation(activation)}${activation.differs.length ? `; differs ${activation.differs.join(", ")}` : ""}${activation.error ? `; error: ${activation.error}` : ""}`);
   rule("RESPONSIBILITIES", String(owned.length));
   if (!owned.length) console.log(`  ${muted("No task currently names this seat.")}`);
   for (const task of owned.slice(0, 6)) console.log(`  ${tone("●", taskPhase(task))} ${task.id}  ${taskPhase(task)}${task.task.assignee === resolved ? "  owner" : "  coordinator"}`);

package/src/pi-runtime-launch.ts

@@ -38,6 +38,10 @@ export type PiRuntimeLaunchDependencies = {
   command?: (command: string[]) => Promise<string>;
   sessionId?: () => string;
   at?: () => string;
+  /** Pause between session-path polls; injectable so tests need no real delay. */
+  sleep?: (milliseconds: number) => Promise<void>;
+  /** How long Herdr may take to report the exact session path after start. */
+  sessionPathWindowMs?: number;
 };
 
 type Bind = (root: string, address: string, args: string[], selectedModel?: string, wake?: Runtime["wake"], piSession?: string, piSessionPath?: string, launchReceipt?: string) => Promise<void>;
@@ -382,18 +386,35 @@ function assertVerifiedProcess(launch: PreparedLaunch, pane: string, agent: Retu
   }
 }
 
-/** Corroborate the started runtime through agent, pane, and process reports. */
-async function verifyRuntime(launch: PreparedLaunch, pane: string, priorPath?: string) {
+const sessionPathPollMs = 250;
+const defaultSessionPathWindowMs = 10_000;
+
+async function readRuntimeReports(launch: PreparedLaunch, pane: string) {
   const { command, options, resolved } = launch;
   const [agentRaw, paneRaw, processRaw] = await Promise.all([
     command(herdr(options.herdrSession, "agent", "get", agentName(resolved))),
     command(herdr(options.herdrSession, "pane", "get", pane)),
     command(herdr(options.herdrSession, "pane", "process-info", "--pane", pane)),
   ]);
-  const agent = agentReport(JSON.parse(agentRaw)), verifiedPane = paneReport(JSON.parse(paneRaw));
-  const verifiedProcess = piProcess(processReport(JSON.parse(processRaw)).processes);
-  const sessionPath = assertVerifiedSession(launch, verifiedPane, priorPath);
-  assertVerifiedProcess(launch, pane, agent, verifiedPane, verifiedProcess);
+  return { agent: agentReport(JSON.parse(agentRaw)), verifiedPane: paneReport(JSON.parse(paneRaw)), verifiedProcess: piProcess(processReport(JSON.parse(processRaw)).processes) };
+}
+
+/**
+ * Corroborate the started runtime through agent, pane, and process reports. Only an absent session path is
+ * polled again, within a bounded window: Herdr may report it a moment after the process starts. Every other
+ * mismatch, and a path still absent when the window ends, fails closed without changing the seat binding.
+ */
+async function verifyRuntime(launch: PreparedLaunch, pane: string, priorPath?: string) {
+  const { dependencies } = launch;
+  const sleep = dependencies.sleep ?? ((milliseconds: number) => new Promise<void>((resolve) => setTimeout(resolve, milliseconds)));
+  const polls = Math.floor((dependencies.sessionPathWindowMs ?? defaultSessionPathWindowMs) / sessionPathPollMs);
+  let reports = await readRuntimeReports(launch, pane);
+  for (let poll = 0; poll < polls && !reports.verifiedPane.sessionPath; poll += 1) {
+    await sleep(sessionPathPollMs);
+    reports = await readRuntimeReports(launch, pane);
+  }
+  const sessionPath = assertVerifiedSession(launch, reports.verifiedPane, priorPath);
+  assertVerifiedProcess(launch, pane, reports.agent, reports.verifiedPane, reports.verifiedProcess);
   return sessionPath;
 }
 

package/src/runtime-state.ts

@@ -3,6 +3,16 @@ import { randomUUID } from "node:crypto";
 import { dirname, join } from "node:path";
 import { addressParts, atomicYaml, yaml } from "./core";
 
+/** The values one activation attempt compared, as recorded for `status seat`; advisory and absent on legacy records. */
+export type MailActivation = {
+  at: string;
+  transport: "active" | "inactive";
+  live: { pi_session?: string; herdr_session?: string; pane?: string };
+  bound: { pi_session?: string; herdr_session?: string; pane?: string; receipt: "present" | "missing" | "none" };
+  differs: string[];
+  error?: string;
+};
+
 /**
  * A local, advisory observation of one runtime for one already-authoritative
  * Desk seat. This record is deliberately not a registry: it cannot select a
@@ -17,9 +27,12 @@ export type RuntimeState = {
   cwd: string;
   started_at: string;
   heartbeat_at: string;
+  /** Live Pi session id when known; absent on legacy records. Advisory only: it never selects a recipient. */
+  pi_session?: string;
+  mail_activation?: MailActivation;
 };
 
-export type RuntimeStateRegistration = Pick<RuntimeState, "seat" | "owner_token" | "pid" | "model" | "cwd">;
+export type RuntimeStateRegistration = Pick<RuntimeState, "seat" | "owner_token" | "pid" | "model" | "cwd"> & Partial<Pick<RuntimeState, "pi_session">>;
 
 const schema = "atdd-flow/pi-runtime-state/v1" as const;
 const lockStaleMs = 5 * 60_000;
@@ -44,7 +57,9 @@ function valid(value: unknown): value is RuntimeState {
     && nonEmpty(record.model)
     && nonEmpty(record.cwd)
     && timestamp(record.started_at)
-    && timestamp(record.heartbeat_at);
+    && timestamp(record.heartbeat_at)
+    && (record.pi_session === undefined || nonEmpty(record.pi_session))
+    && (record.mail_activation === undefined || (typeof record.mail_activation === "object" && record.mail_activation !== null));
 }
 
 function assertRegistration(value: RuntimeStateRegistration) {
@@ -159,6 +174,18 @@ export async function heartbeatRuntimeState(root: string, seat: string, ownerTok
   });
 }
 
+/** Record the compared activation values only while this owner holds the record; the heartbeat and every other field are kept. */
+export async function recordMailActivation(root: string, seat: string, ownerToken: string, activation: MailActivation) {
+  if (!nonEmpty(ownerToken)) throw new Error("Runtime state requires a non-empty owner token.");
+  const file = runtimeStatePath(root, seat);
+  return exclusive(file, async () => {
+    const current = await readRuntimeState(root, seat);
+    if (!current || current.owner_token !== ownerToken) return false;
+    await atomicYaml(file, { ...current, mail_activation: activation });
+    return true;
+  });
+}
+
 /** Remove local advisory state only if this owner still owns it. */
 export async function clearRuntimeState(root: string, seat: string, ownerToken: string) {
   if (!nonEmpty(ownerToken)) throw new Error("Runtime state requires a non-empty owner token.");