@serfab/cadre-host 1.12.0 → 1.14.0

package/src/{installer/identity.ts → orchestrator/identity-file.ts}

@@ -1,56 +1,56 @@
-/**
- * Identity persistence for cadre-host.
- *
- * The host's libp2p peer identity is an Ed25519 keypair generated at
- * install time. The protobuf-encoded private key is written to
- * `<dataDir>/identity.key` with mode 0600 on POSIX. `cadre-host start`
- * later loads it with `privateKeyFromProtobuf`.
- *
- * We persist the protobuf form (not raw bytes) because that's the format
- * libp2p's `privateKeyFromProtobuf` consumes directly and it preserves the
- * key type tag — future migrations to a different key algorithm don't
- * require a schema change here. Raw bytes carry no type tag AND no way to tell
- * a damaged file from a valid one: `privateKeyFromRaw` accepts any 64 bytes as
- * an Ed25519 key without checking that the public half matches the private, so
- * a truncated file would load as a *different* working identity.
- *
- * This is the repo-wide identity file format, not a cadre-host-local choice:
- * `cadre enroll create` writes exactly these bytes, and `cadre-cli`'s
- * `identity.keyFile` accepts nothing else (`config/loader.ts` → `loadIdentityKey`).
- */
-
-import { chmodSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname } from 'node:path';
-import {
-  generateKeyPair,
-  privateKeyFromProtobuf,
-  privateKeyToProtobuf,
-} from '@libp2p/crypto/keys';
-import { peerIdFromPrivateKey } from '@libp2p/peer-id';
-import type { PrivateKey } from '@libp2p/interface';
-
-export interface IdentityRecord {
-  privateKey: PrivateKey;
-  /** Stringified libp2p peer ID (`12D3Koo…`). */
-  peerId: string;
-}
-
-/** Generate a fresh Ed25519 identity and persist it. Returns the in-memory record. */
-export async function generateIdentity(filePath: string): Promise<IdentityRecord> {
-  const privateKey = await generateKeyPair('Ed25519');
-  const bytes = privateKeyToProtobuf(privateKey);
-  mkdirSync(dirname(filePath), { recursive: true });
-  writeFileSync(filePath, bytes);
-  // 0600 — owner read/write only. No-op on Windows.
-  if (process.platform !== 'win32') {
-    chmodSync(filePath, 0o600);
-  }
-  return { privateKey, peerId: peerIdFromPrivateKey(privateKey).toString() };
-}
-
-/** Load an existing identity file. Throws if it doesn't decode. */
-export function loadIdentity(filePath: string): IdentityRecord {
-  const bytes = readFileSync(filePath);
-  const privateKey = privateKeyFromProtobuf(new Uint8Array(bytes));
-  return { privateKey, peerId: peerIdFromPrivateKey(privateKey).toString() };
-}
+/**
+ * Identity persistence for the nodes cadre-host runs.
+ *
+ * Each managed node's libp2p peer identity is an Ed25519 keypair generated on
+ * its first spawn (`node-identity.ts`). The protobuf-encoded
+ * private key is written with mode 0600 on POSIX and loaded with
+ * `privateKeyFromProtobuf`.
+ *
+ * We persist the protobuf form (not raw bytes) because that's the format
+ * libp2p's `privateKeyFromProtobuf` consumes directly and it preserves the
+ * key type tag — future migrations to a different key algorithm don't
+ * require a schema change here. Raw bytes carry no type tag AND no way to tell
+ * a damaged file from a valid one: `privateKeyFromRaw` accepts any 64 bytes as
+ * an Ed25519 key without checking that the public half matches the private, so
+ * a truncated file would load as a *different* working identity.
+ *
+ * This is the repo-wide identity file format, not a cadre-host-local choice:
+ * `cadre enroll create` writes exactly these bytes, and `cadre-cli`'s
+ * `identity.keyFile` accepts nothing else (`config/loader.ts` → `loadIdentityKey`).
+ */
+
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import {
+  generateKeyPair,
+  privateKeyFromProtobuf,
+  privateKeyToProtobuf,
+} from '@libp2p/crypto/keys';
+import { peerIdFromPrivateKey } from '@libp2p/peer-id';
+import type { PrivateKey } from '@libp2p/interface';
+
+export interface IdentityRecord {
+  privateKey: PrivateKey;
+  /** Stringified libp2p peer ID (`12D3Koo…`). */
+  peerId: string;
+}
+
+/** Generate a fresh Ed25519 identity and persist it. Returns the in-memory record. */
+export async function generateIdentity(filePath: string): Promise<IdentityRecord> {
+  const privateKey = await generateKeyPair('Ed25519');
+  const bytes = privateKeyToProtobuf(privateKey);
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, bytes);
+  // 0600 — owner read/write only. No-op on Windows.
+  if (process.platform !== 'win32') {
+    chmodSync(filePath, 0o600);
+  }
+  return { privateKey, peerId: peerIdFromPrivateKey(privateKey).toString() };
+}
+
+/** Load an existing identity file. Throws if it doesn't decode. */
+export function loadIdentity(filePath: string): IdentityRecord {
+  const bytes = readFileSync(filePath);
+  const privateKey = privateKeyFromProtobuf(new Uint8Array(bytes));
+  return { privateKey, peerId: peerIdFromPrivateKey(privateKey).toString() };
+}

package/src/orchestrator/index.ts

@@ -1,10 +1,9 @@
-export { HostProcessOrchestrator, OWNER_CONTAINER_ID } from './host-process-orchestrator.js';
-export type { OwnerAdminEndpoint } from './host-process-orchestrator.js';
-export type {
-  HostProcessConfig,
-  ManagedNodeInfo,
-  NodeStateListener,
-  NodePorts,
-  OwnerSpawnConfig,
-} from './types.js';
-export type { PersistedHandle } from './state-store.js';
+export { HostProcessOrchestrator } from './host-process-orchestrator.js';
+export type {
+  HostProcessConfig,
+  HostedSpawnRequest,
+  ManagedNodeInfo,
+  NodeStateListener,
+  NodePorts,
+} from './types.js';
+export type { PersistedHandle } from './state-store.js';

package/src/orchestrator/node-identity.ts

@@ -1,41 +1,41 @@
-/**
- * Per-node identity keys for orchestrator-managed children.
- *
- * A donated node joins a *foreign* cadre: the requester approves its peer id
- * and its seed nominates dial addresses keyed to that peer id. Both bind to the
- * identity, so a node that generated a fresh libp2p keypair per process would
- * become a stranger to the cadre that admitted it on every restart. It also
- * needs a stable on-disk home for its node-local stores — `cadre-cli start`
- * opens `FileBootstrapPeerStore` / `FileTrustedOwnerStore` /
- * `FileStrandNetworkStateStore` in the node's state directory, which defaults to
- * the directory holding the config file the orchestrator writes into the workdir.
- *
- * So every managed node gets its own `identity.key` inside its workdir, written
- * once and reused thereafter. The workdir is removed when the loan is
- * terminated (`removeContainer`), so nothing the node persisted outlives it.
- */
-
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
-
-import { generateIdentity, loadIdentity, type IdentityRecord } from '../installer/identity.js';
-
-const IDENTITY_FILE = 'identity.key';
-
-/** Path to a managed node's own protobuf identity key inside its workdir. */
-export function nodeIdentityPath(workdir: string): string {
-  return join(workdir, IDENTITY_FILE);
-}
-
-/**
- * Ensure `<workdir>/identity.key` exists, generating an Ed25519 protobuf key on
- * first call and REUSING it on every later call. Reuse is the load-bearing
- * property: a re-spawn of the same container must land on the same peer id.
- */
-export async function ensureNodeIdentity(workdir: string): Promise<{ path: string; peerId: string }> {
-  const path = nodeIdentityPath(workdir);
-  const record: IdentityRecord = existsSync(path)
-    ? loadIdentity(path)
-    : await generateIdentity(path);
-  return { path, peerId: record.peerId };
-}
+/**
+ * Per-node identity keys for orchestrator-managed children.
+ *
+ * A hosted node joins the cadre whose owner claimed it: the claim named its peer
+ * id, and the owner's phone dials the addresses keyed to that peer id. Both bind
+ * to the identity, so a node that generated a fresh libp2p keypair per process
+ * would become a stranger to the cadre that claimed it on every restart. It also
+ * needs a stable on-disk home for its node-local stores — `cadre-cli start`
+ * opens `FileBootstrapPeerStore` / `FileTrustedOwnerStore` /
+ * `FileStrandNetworkStateStore` in the node's state directory, which defaults to
+ * the directory holding the config file the orchestrator writes into the workdir.
+ *
+ * So every managed node gets its own `identity.key` inside its workdir, written
+ * once and reused thereafter. The workdir is removed with the node
+ * (`removeContainer`), so nothing the node persisted outlives it.
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { generateIdentity, loadIdentity, type IdentityRecord } from './identity-file.js';
+
+const IDENTITY_FILE = 'identity.key';
+
+/** Path to a managed node's own protobuf identity key inside its workdir. */
+export function nodeIdentityPath(workdir: string): string {
+  return join(workdir, IDENTITY_FILE);
+}
+
+/**
+ * Ensure `<workdir>/identity.key` exists, generating an Ed25519 protobuf key on
+ * first call and REUSING it on every later call. Reuse is the load-bearing
+ * property: a re-spawn of the same container must land on the same peer id.
+ */
+export async function ensureNodeIdentity(workdir: string): Promise<{ path: string; peerId: string }> {
+  const path = nodeIdentityPath(workdir);
+  const record: IdentityRecord = existsSync(path)
+    ? loadIdentity(path)
+    : await generateIdentity(path);
+  return { path, peerId: record.peerId };
+}

package/src/orchestrator/port-allocator.ts

@@ -1,73 +1,71 @@
-import {
-  allocatePortSet,
-  releasePortSet,
-  reservePortSet,
-  type PortAllocator,
-} from '@serfab/cadre-provider';
-
-import type { NodePorts } from './types.js';
-
-/**
- * Allocation order for a node's port set. Fixed so that swapping a caller onto
- * {@link allocateNodePorts} does not shift the ports an existing deployment
- * already handed out — which is also why a key added later goes on the end
- * (`ws` came after the first four).
- */
-const NODE_PORT_KEYS = ['health', 'metrics', 'p2p', 'admin', 'ws'] as const satisfies readonly (keyof NodePorts)[];
-
-/**
- * Allocate a full NodePorts set atomically, in {@link NODE_PORT_KEYS} order.
- * `overrides` supply a port instead of allocating one (the owner node's p2p
- * port, which is fixed by NAT config; a re-spawn's previous ports, see
- * {@link reusedNodePorts}). Overrides are reserved before anything is allocated
- * and are trusted, not checked — see `allocatePortSet`.
- */
-export function allocateNodePorts(
-  allocator: PortAllocator,
-  overrides?: Partial<NodePorts>,
-): NodePorts {
-  return allocatePortSet(allocator, NODE_PORT_KEYS, overrides);
-}
-
-/**
- * Hold a node's whole port set against `allocator` — the inverse of
- * {@link releaseNodePorts}. A key the set lacks is skipped (see `markUsed`).
- */
-export function reserveNodePorts(allocator: PortAllocator, ports: NodePorts): void {
-  reservePortSet(allocator, NODE_PORT_KEYS, ports);
-}
-
-/**
- * Give a node's whole port set back to `allocator`. A key the set lacks releases
- * nothing: deleting a value the used-set never held is a no-op.
- */
-export function releaseNodePorts(allocator: PortAllocator, ports: NodePorts): void {
-  releasePortSet(allocator, NODE_PORT_KEYS, ports);
-}
-
-/**
- * The ports a re-spawn comes back on: the set the dropped handle held, as
- * {@link allocateNodePorts} overrides. `{}` when nothing was dropped (a first
- * spawn, or a handle lost along with `state.json`), so every port is allocated
- * fresh.
- *
- * Why a re-spawn must not simply take the lowest free ports: a requester with no
- * address of its own (a phone) reaches a lent node only by dialing the address it
- * was given, so a node that comes back on a different port is one that requester
- * can no longer find.
- *
- * A key the dropped handle lacks — `ws` on a handle persisted by an older build —
- * is left out, and so allocated fresh. When more than one handle was dropped (only
- * possible from a `state.json` that already held duplicates), the last one stored
- * wins and the others' ports stay released.
- */
-export function reusedNodePorts(dropped: readonly { ports: NodePorts }[]): Partial<NodePorts> {
-  const reused: Partial<NodePorts> = {};
-  const previous = dropped[dropped.length - 1]?.ports;
-  if (!previous) return reused;
-  for (const key of NODE_PORT_KEYS) {
-    const port = previous[key];
-    if (Number.isInteger(port)) reused[key] = port;
-  }
-  return reused;
-}
+import {
+  allocatePortSet,
+  releasePortSet,
+  reservePortSet,
+  type PortAllocator,
+} from '@serfab/cadre-provider';
+
+import type { NodePorts } from './types.js';
+
+/**
+ * Allocation order for a node's port set. A node already running keeps its
+ * ports whatever this order says ({@link reusedNodePorts}); the order decides
+ * only where a fresh allocation lands.
+ */
+const NODE_PORT_KEYS = ['health', 'metrics', 'p2p', 'ws'] as const satisfies readonly (keyof NodePorts)[];
+
+/**
+ * Allocate a full NodePorts set atomically, in {@link NODE_PORT_KEYS} order.
+ * `overrides` supply a port instead of allocating one (a re-spawn's previous
+ * ports, see {@link reusedNodePorts}). Overrides are reserved before anything is allocated
+ * and are trusted, not checked — see `allocatePortSet`.
+ */
+export function allocateNodePorts(
+  allocator: PortAllocator,
+  overrides?: Partial<NodePorts>,
+): NodePorts {
+  return allocatePortSet(allocator, NODE_PORT_KEYS, overrides);
+}
+
+/**
+ * Hold a node's whole port set against `allocator` — the inverse of
+ * {@link releaseNodePorts}. A key the set lacks is skipped (see `markUsed`).
+ */
+export function reserveNodePorts(allocator: PortAllocator, ports: NodePorts): void {
+  reservePortSet(allocator, NODE_PORT_KEYS, ports);
+}
+
+/**
+ * Give a node's whole port set back to `allocator`. A key the set lacks releases
+ * nothing: deleting a value the used-set never held is a no-op.
+ */
+export function releaseNodePorts(allocator: PortAllocator, ports: NodePorts): void {
+  releasePortSet(allocator, NODE_PORT_KEYS, ports);
+}
+
+/**
+ * The ports a re-spawn comes back on: the set the dropped handle held, as
+ * {@link allocateNodePorts} overrides. `{}` when nothing was dropped (a first
+ * spawn, or a handle lost along with `state.json`), so every port is allocated
+ * fresh.
+ *
+ * Why a re-spawn must not simply take the lowest free ports: an owner with no
+ * address of its own (a phone) reaches a hosted node only by dialing the address
+ * it scanned, so a node that comes back on a different port is one that owner
+ * can no longer find.
+ *
+ * A key the dropped handle lacks — `ws` on a handle persisted by an older build —
+ * is left out, and so allocated fresh. When more than one handle was dropped (only
+ * possible from a `state.json` that already held duplicates), the last one stored
+ * wins and the others' ports stay released.
+ */
+export function reusedNodePorts(dropped: readonly { ports: NodePorts }[]): Partial<NodePorts> {
+  const reused: Partial<NodePorts> = {};
+  const previous = dropped[dropped.length - 1]?.ports;
+  if (!previous) return reused;
+  for (const key of NODE_PORT_KEYS) {
+    const port = previous[key];
+    if (Number.isInteger(port)) reused[key] = port;
+  }
+  return reused;
+}

package/src/orchestrator/state-store.ts

@@ -1,90 +1,76 @@
-import { existsSync, readFileSync, renameSync, writeFileSync, mkdirSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import debug from 'debug';
-
-import type { OwnerSpawnConfig, NodePorts } from './types.js';
-
-const log = debug('cadre:host:state-store');
-
-/**
- * Persisted record for a single managed child. The orchestrator mirrors its
- * in-memory map to disk so that cadre-host can re-attach to surviving
- * children after a restart.
- */
-export interface PersistedHandle {
-  containerId: string;        // provider-assigned ID, passed in createContainer
-  dockerId: string;           // opaque token returned to callers (encoded "pid:token")
-  pid: number;
-  startupToken: string;
-  workdir: string;
-  ports: NodePorts;
-  spawnedAt: string;          // ISO timestamp
-  partyId: string;
-  profile: 'storage' | 'transaction';
-  /** True for the admin's owner node. */
-  owner?: boolean;
-}
-
-export interface PersistedState {
-  version: 1;
-  handles: PersistedHandle[];
-  /** Spawn parameters for the owner node, so it can be re-spawned on demand. */
-  ownerConfig?: OwnerSpawnConfig;
-}
-
-const STATE_VERSION = 1;
-
-/** JSON state file at `<rootDir>/state.json`, written atomically. */
-export class StateStore {
-  private readonly path: string;
-
-  constructor(rootDir: string) {
-    mkdirSync(rootDir, { recursive: true });
-    this.path = join(rootDir, 'state.json');
-  }
-
-  load(): PersistedState {
-    if (!existsSync(this.path)) {
-      return { version: STATE_VERSION, handles: [] };
-    }
-    try {
-      const raw = readFileSync(this.path, 'utf8');
-      const parsed = JSON.parse(raw) as PersistedState;
-      if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.handles)) {
-        log('state file at %s has unexpected shape; treating as empty', this.path);
-        return { version: STATE_VERSION, handles: [] };
-      }
-      return {
-        version: STATE_VERSION,
-        handles: parsed.handles,
-        ...(parsed.ownerConfig ? { ownerConfig: parsed.ownerConfig } : {}),
-      };
-    } catch (err) {
-      // A corrupt state file is operationally significant — surviving children
-      // may now be leaked to the OS without an in-memory handle. Make the
-      // failure visible rather than silently returning empty.
-      log('failed to load state file at %s: %o', this.path, err);
-      return { version: STATE_VERSION, handles: [] };
-    }
-  }
-
-  save(state: PersistedState): void {
-    mkdirSync(dirname(this.path), { recursive: true });
-    const payload = JSON.stringify(
-      {
-        version: STATE_VERSION,
-        handles: state.handles,
-        ...(state.ownerConfig ? { ownerConfig: state.ownerConfig } : {}),
-      },
-      null,
-      2,
-    );
-    const tmp = `${this.path}.tmp`;
-    writeFileSync(tmp, payload, { encoding: 'utf8' });
-    renameSync(tmp, this.path);
-  }
-
-  filePath(): string {
-    return this.path;
-  }
-}
+import { existsSync, readFileSync, renameSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import debug from 'debug';
+
+import type { NodePorts } from './types.js';
+
+const log = debug('cadre:host:state-store');
+
+/**
+ * Persisted record for a single managed child. The orchestrator mirrors its
+ * in-memory map to disk so that cadre-host can re-attach to surviving
+ * children after a restart.
+ */
+export interface PersistedHandle {
+  containerId: string;        // provider-assigned ID, passed in createContainer
+  dockerId: string;           // opaque token returned to callers (encoded "pid:token")
+  pid: number;
+  startupToken: string;
+  workdir: string;
+  ports: NodePorts;
+  spawnedAt: string;          // ISO timestamp
+  partyId: string;
+  profile: 'storage' | 'transaction';
+  /** The public addresses the child was started announcing. Absent in a file written before they existed. */
+  announcedAddrs?: string[];
+}
+
+export interface PersistedState {
+  version: 1;
+  handles: PersistedHandle[];
+}
+
+const STATE_VERSION = 1;
+
+/** JSON state file at `<rootDir>/state.json`, written atomically. */
+export class StateStore {
+  private readonly path: string;
+
+  constructor(rootDir: string) {
+    mkdirSync(rootDir, { recursive: true });
+    this.path = join(rootDir, 'state.json');
+  }
+
+  load(): PersistedState {
+    if (!existsSync(this.path)) {
+      return { version: STATE_VERSION, handles: [] };
+    }
+    try {
+      const raw = readFileSync(this.path, 'utf8');
+      const parsed = JSON.parse(raw) as PersistedState;
+      if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.handles)) {
+        log('state file at %s has unexpected shape; treating as empty', this.path);
+        return { version: STATE_VERSION, handles: [] };
+      }
+      return { version: STATE_VERSION, handles: parsed.handles };
+    } catch (err) {
+      // A corrupt state file is operationally significant — surviving children
+      // may now be leaked to the OS without an in-memory handle. Make the
+      // failure visible rather than silently returning empty.
+      log('failed to load state file at %s: %o', this.path, err);
+      return { version: STATE_VERSION, handles: [] };
+    }
+  }
+
+  save(state: PersistedState): void {
+    mkdirSync(dirname(this.path), { recursive: true });
+    const payload = JSON.stringify({ version: STATE_VERSION, handles: state.handles }, null, 2);
+    const tmp = `${this.path}.tmp`;
+    writeFileSync(tmp, payload, { encoding: 'utf8' });
+    renameSync(tmp, this.path);
+  }
+
+  filePath(): string {
+    return this.path;
+  }
+}

package/src/orchestrator/types.ts

@@ -4,6 +4,22 @@
 
 import type { ChildProcess } from 'node:child_process';
 import type { PushCredentials } from '@serfab/cadre-core';
+import type { OrchestratorCreateRequest } from '@serfab/cadre-provider';
+
+/**
+ * What `HostProcessOrchestrator.createContainer` takes: the shared create request plus how
+ * the node gets into its cadre — the claim secret of a node started waiting to be claimed
+ * (`cadre-cli start` with `CADRE_CLAIM_SECRET`), or the cadre invitation it redeems
+ * (`CADRE_INVITATION`). At most one of the two. Each is a credential and reaches the child
+ * through its environment only: never as an argument (an argument shows in the process
+ * list), never in `state.json`, never in a log line.
+ */
+export type HostedSpawnRequest = OrchestratorCreateRequest & {
+  /** The node's one-time claim secret, base64url. Absent, the child starts with no claim. */
+  claimSecret?: string;
+  /** An encoded cadre invitation the child redeems right after it starts. */
+  invitation?: string;
+};
 
 /** User-facing configuration for `HostProcessOrchestrator`. */
 export interface HostProcessConfig {
@@ -33,6 +49,15 @@ export interface HostProcessConfig {
    * resolver itself is responsible for rejecting a partial credential set.
    */
   pushResolver?: PushCredentialsResolver;
+  /**
+   * The public multiaddrs a node about to spawn should announce beside its listen
+   * addresses (`CADRE_APPEND_ANNOUNCE_ADDRS`), given its container id and the ports just
+   * allocated to it. Synchronous on purpose: both spawn paths allocate ports inside a
+   * window that must contain no `await` (see `restoreDroppedHandles`), and the addresses
+   * depend on those ports. A throw is logged and the node starts announcing nothing extra.
+   * Absent, no node announces anything beyond what libp2p reports.
+   */
+  announceAddrs?: (containerId: string, ports: NodePorts) => string[];
 }
 
 /**
@@ -43,7 +68,7 @@ export interface HostProcessConfig {
 export type PushCredentialsResolver = () => Promise<PushCredentials | undefined>;
 
 /**
- * Per-child allocated ports. `admin` carries the loopback admin channel (6.6).
+ * Per-child allocated ports.
  *
  * A handle read back from a `state.json` written by an older build lacks every key
  * added since, whatever this type says — the node-set helpers in `port-allocator.ts`
@@ -54,8 +79,6 @@ export interface NodePorts {
   metrics: number;
   /** libp2p TCP listener. */
   p2p: number;
-  /** Loopback admin-channel port. Bound only by the owner node. */
-  admin: number;
   /**
    * libp2p WebSocket listener. The one a phone dials: a phone's node has no TCP
    * transport, so the `p2p` port is unreachable to it.
@@ -74,8 +97,8 @@ export interface Handle {
   spawnedAt: string;
   partyId: string;
   profile: 'storage' | 'transaction';
-  /** True for the admin's owner node (binds the admin channel). */
-  owner?: boolean;
+  /** The public addresses the child was started announcing ({@link HostProcessConfig.announceAddrs}). */
+  announcedAddrs: string[];
   /** Live ChildProcess reference; absent after re-attach via init(). */
   child?: ChildProcess;
   /** Marked false when init() finds the PID dead or token mismatched. */
@@ -95,24 +118,12 @@ export interface ManagedNodeInfo {
   spawnedAt: string;
   workdir: string;
   ports: NodePorts;
-  /** True for the admin's owner node. */
-  owner?: boolean;
-}
-
-/**
- * Persisted spawn parameters for the admin's owner node. Stored alongside
- * the handles so an orchestrator restart can re-spawn the owner node from
- * `/api/nodes/:id/{start,restart}` without the caller re-supplying them.
- */
-export interface OwnerSpawnConfig {
-  /** Absolute path to the host's libp2p protobuf identity (`identity.key`). */
-  identityPath: string;
-  /** Control-network partyId (the host's installId). */
-  partyId: string;
-  /** External libp2p port — mapped to the child's listen address. */
-  libp2pPort: number;
-  /** Node profile. Defaults to `storage` (the household node holds strands). */
-  profile?: 'storage' | 'transaction';
+  /**
+   * The public addresses the node was started announcing. It learns them only at start,
+   * so `NatService` compares this with the node's current public addresses and asks for
+   * a restart when they differ.
+   */
+  announcedAddrs: string[];
 }
 
 /**