@serfab/cadre-host 0.8.1 → 0.10.0

package/src/orchestrator/host-process-orchestrator.ts

@@ -12,7 +12,7 @@ import {
   readSync,
   closeSync,
 } from 'node:fs';
-import { join, resolve as resolvePath } from 'node:path';
+import { join, resolve as resolvePath, sep } from 'node:path';
 import debug from 'debug';
 import pidusage from 'pidusage';
 import type {
@@ -23,14 +23,15 @@ import type {
 } from '@serfab/cadre-provider';
 
 import { defaultLogPath, rotateOnDisk } from './log-rotator.js';
-import { PortAllocator } from './port-allocator.js';
+import { ensureNodeIdentity } from './node-identity.js';
+import { allocateNodePorts, PortAllocator } from './port-allocator.js';
 import { StateStore, type PersistedHandle, type PersistedState } from './state-store.js';
 import { isPidAlive } from './pid-liveness.js';
 import type { PushCredentials } from '@serfab/cadre-core';
 import {
   decodeDockerId,
   encodeDockerId,
-  type AuthoritySpawnConfig,
+  type OwnerSpawnConfig,
   type Handle,
   type HostProcessConfig,
   type ManagedNodeInfo,
@@ -53,11 +54,32 @@ const STARTUP_TOKEN_FILE = '.startup-token';
 const CONFIG_FILE = 'cadre.json';
 const LIVENESS_POLL_MS = 100;
 
-/** Fixed friendly id for the admin's authority node. */
-export const AUTHORITY_CONTAINER_ID = 'authority';
+const CADRE_ENV_PREFIX = 'CADRE_';
 
-/** Endpoint + bearer for the authority node's loopback admin channel (6.6). */
-export interface AuthorityAdminEndpoint {
+/**
+ * Manager's own `process.env` with every `CADRE_*` key removed. A child node
+ * takes its whole configuration from the config file this orchestrator writes
+ * plus the vars set explicitly below, and `@serfab/cadre-cli` treats inherited
+ * `CADRE_*` vars as overrides that BEAT that config file — so inheriting them
+ * would let a var set on the manager (e.g. CADRE_PARTY_ID) silently
+ * reconfigure every spawned child. Scrubbing the whole prefix rather than a
+ * list of known keys means a new cli env var can't reintroduce the leak by
+ * being forgotten here. Non-CADRE vars (PATH, DEBUG, proxy/TLS settings, etc.)
+ * still pass through untouched.
+ */
+function scrubbedParentEnv(): NodeJS.ProcessEnv {
+  const env = { ...process.env };
+  for (const key of Object.keys(env)) {
+    if (key.startsWith(CADRE_ENV_PREFIX)) delete env[key];
+  }
+  return env;
+}
+
+/** Fixed friendly id for the admin's owner node. */
+export const OWNER_CONTAINER_ID = 'owner';
+
+/** Endpoint + bearer for the owner node's loopback admin channel (6.6). */
+export interface OwnerAdminEndpoint {
   /** e.g. `http://127.0.0.1:<adminPort>`. */
   baseUrl: string;
   /** The child's `CADRE_STARTUP_TOKEN`, used as the admin bearer secret. */
@@ -108,8 +130,8 @@ export class HostProcessOrchestrator implements Orchestrator {
   private readonly pushResolver?: PushCredentialsResolver;
   /** State-change listeners — invoked when a handle's alive state changes. */
   private readonly stateListeners = new Set<NodeStateListener>();
-  /** Persisted spawn config for the authority node (re-spawn on demand). */
-  private authorityConfig?: AuthoritySpawnConfig;
+  /** Persisted spawn config for the owner node (re-spawn on demand). */
+  private ownerConfig?: OwnerSpawnConfig;
 
   constructor(private readonly cfg: HostProcessConfig) {
     this.rootDir = resolvePath(cfg.rootDir);
@@ -135,7 +157,7 @@ export class HostProcessOrchestrator implements Orchestrator {
    */
   async init(): Promise<void> {
     const state = this.stateStore.load();
-    this.authorityConfig = state.authorityConfig;
+    this.ownerConfig = state.ownerConfig;
     for (const persisted of state.handles) {
       const alive = isPidAlive(persisted.pid) && tokenMatches(persisted.workdir, persisted.startupToken);
       const handle: Handle = {
@@ -148,18 +170,12 @@ export class HostProcessOrchestrator implements Orchestrator {
         spawnedAt: persisted.spawnedAt,
         partyId: persisted.partyId,
         profile: persisted.profile,
-        ...(persisted.authority ? { authority: true } : {}),
+        ...(persisted.owner ? { owner: true } : {}),
         alive,
       };
       this.handles.set(handle.dockerId, handle);
       // Always reserve ports — even for dead handles, until the caller cleans them up
-      this.portAllocator.markUsed(persisted.ports.health);
-      this.portAllocator.markUsed(persisted.ports.metrics);
-      this.portAllocator.markUsed(persisted.ports.p2p);
-      // `admin` is absent on handles persisted before this build.
-      if (typeof persisted.ports.admin === 'number') {
-        this.portAllocator.markUsed(persisted.ports.admin);
-      }
+      this.reservePorts(persisted.ports);
     }
     log('init: re-attached %d handles', state.handles.length);
   }
@@ -206,37 +222,152 @@ export class HostProcessOrchestrator implements Orchestrator {
     return () => { this.stateListeners.delete(listener); };
   }
 
-  /** Handles that init() found dead (PID gone or token mismatch). */
-  listDeadHandles(): PersistedHandle[] {
-    const dead: PersistedHandle[] = [];
-    for (const h of this.handles.values()) {
-      if (!h.alive) {
-        dead.push(this.toPersisted(h));
-      }
+  /**
+   * Spawn a generic managed node — the donated-node path (the requester's cadre,
+   * pinned to the *requester's* owner key). The node is given its own protobuf
+   * identity key inside its workdir (`ensureNodeIdentity`, reused across
+   * re-spawns of the same containerId), which is what makes its peer id stable
+   * across restarts AND what makes its node-local stores durable: `cadre-cli
+   * start` opens the file-backed bootstrap-peer and trusted-owner stores only
+   * when a protobuf identity key file is configured, and puts them beside it.
+   * Terminating the loan (`removeContainer`) deletes the workdir, so the key and
+   * both stores go with it.
+   */
+  async createContainer(request: OrchestratorCreateRequest): Promise<OrchestratorCreateResult> {
+    const workdir = this.workdirFor(request.containerId);
+    // Sampled BEFORE `ensureNodeIdentity`, which brings the directory into
+    // existence as a side effect of writing the key. Only a spawn that found
+    // nothing here may delete anything on its way out — a re-spawn is REUSING
+    // the identity key and node-local stores this directory holds, and they are
+    // the whole reason the node comes back as the same peer. `false` is
+    // therefore the safe default: a directory that exists for any reason
+    // (respawn, an earlier failed provision, an operator's file) is never
+    // touched by the unwind below.
+    const isNewWorkdir = !existsSync(workdir);
+    let dropped: Handle[] = [];
+    let ports: NodePorts | undefined;
+    try {
+      // Identity BEFORE any port is reserved: it is the one step here that can
+      // fail on its own (an unreadable or undecodable identity.key throws rather
+      // than silently re-keying), and everything past the allocation is either
+      // infallible or releases the ports itself. Allocating first would leak four
+      // ports from a bounded range on every failed provision attempt.
+      const identity = await ensureNodeIdentity(workdir);
+      log('container %s identity peerId=%s', request.containerId, identity.peerId);
+      // A node started with pinned owner keys belongs to a FOREIGN cadre (the
+      // node-donation flow: it trusts the requester's owner key, not the host's).
+      // The host's FCM/APNs credentials are minted for the host owner's own app
+      // and are meaningless to a foreign cadre — so donated nodes get NO push
+      // block. (Per-grantee push creds would be a future ticket; none in v1.)
+      const foreignParty = (request.pinnedOwnerKeys?.length ?? 0) > 0;
+      // Only storage-profile nodes participate in strands and thus fan out push
+      // wakes — a transaction-only node need not carry credentials. Resolved
+      // BEFORE the drop below: it is the last `await` on this path, which is what
+      // keeps the drop → launch window synchronous (see restoreDroppedHandles).
+      const push = request.profile === 'storage' && !foreignParty ? await this.resolvePush() : undefined;
+      // Pinned owner key(s) reach the child via CADRE_OWNER_KEYS (comma-separated);
+      // `cadre-cli start` unions it into its cold-start pinnedKeyTrustPolicy so the
+      // node will accept the foreign-authority-signed seed presented via POST /seed.
+      const extraEnv = request.pinnedOwnerKeys?.length
+        ? { CADRE_OWNER_KEYS: request.pinnedOwnerKeys.join(',') }
+        : undefined;
+
+      // Nothing from here to the launch is `await`ed — which is what keeps
+      // `restoreDroppedHandles`'s documented precondition true even though the
+      // `try` now opens further up. Do not add an `await` past this line.
+      dropped = this.dropStaleHandle(request.containerId);
+      // NOTE: the p2p port is re-allocated per spawn, so a re-spawned donated
+      // node keeps its peer id but may announce a different port. Recoverable —
+      // it dials out to its retained bootstrap peers and republishes its own
+      // CadrePeer row once connected. If that reconnect ever proves too slow,
+      // pin the p2p port per containerId (see donated-node-respawn-core).
+      ports = allocateNodePorts(this.portAllocator);
+      return this.launchChild({
+        containerId: request.containerId,
+        partyId: request.partyId,
+        profile: request.profile,
+        ports,
+        owner: false,
+        buildConfig: () => this.buildChildConfig(request, workdir, push),
+        extraArgs: ['--identity-protobuf', identity.path],
+        ...(extraEnv ? { extraEnv } : {}),
+        ...(request.resources?.memoryLimit ? { memoryLimit: request.resources.memoryLimit } : {}),
+      });
+    } catch (err) {
+      // Release BEFORE restoring: a re-spawn allocates the very ports the drop
+      // just freed, so restoring first and releasing second would hand the
+      // restored handle's own ports straight back to the allocator.
+      if (ports) this.releasePorts(ports);
+      // A no-op for the failures that happen before the drop (`dropped` is
+      // still empty).
+      this.restoreDroppedHandles(dropped);
+      // Safe because a throw out of `launchChild` means NO child is running:
+      // its throw surface ends where the child is spawned and its handle stored
+      // (everything past that line is best-effort), and the `if (!child.pid)`
+      // throw is on the no-process side too. So nothing is ever holding the
+      // directory this deletes.
+      if (isNewWorkdir) this.discardWorkdir(workdir);
+      throw err;
     }
-    return dead;
   }
 
-  async createContainer(request: OrchestratorCreateRequest): Promise<OrchestratorCreateResult> {
-    const ports: NodePorts = {
-      health: this.portAllocator.allocate(),
-      metrics: this.portAllocator.allocate(),
-      p2p: this.portAllocator.allocate(),
-      admin: this.portAllocator.allocate(),
-    };
-    // Only storage-profile nodes participate in strands and thus fan out push
-    // wakes — a transaction-only node need not carry credentials.
-    const push = request.profile === 'storage' ? await this.resolvePush() : undefined;
-    return this.launchChild({
-      containerId: request.containerId,
-      partyId: request.partyId,
-      profile: request.profile,
-      ports,
-      authority: false,
-      buildConfig: (workdir) => this.buildChildConfig(request, workdir, push),
-      extraArgs: [],
-      ...(request.resources?.memoryLimit ? { memoryLimit: request.resources.memoryLimit } : {}),
-    });
+  /**
+   * Remove the working directory a spawn created for `containerId` when no
+   * handle owns it — the cleanup of last resort for a donation record that
+   * never got a `dockerId` (the host died between `ensureNodeIdentity` and the
+   * handle write, so `createContainer`'s own unwind never ran). Returns whether
+   * anything was removed.
+   *
+   * Synchronous, mirroring {@link resolveDockerId}: nothing on this path needs
+   * to await.
+   */
+  reclaimWorkdir(containerId: string): boolean {
+    // The admin's own node is never reclaimed by this route: its workdir is a
+    // single fixed path reused by every restart and it holds the host's own
+    // control-DB storage.
+    if (containerId === OWNER_CONTAINER_ID) return false;
+    // A live handle owns that directory, and `removeContainer` — which stops
+    // the child first — is the only thing allowed to delete it.
+    if (this.resolveDockerId(containerId)) return false;
+    const workdir = this.workdirFor(containerId);
+    // Defence, not a live case: donation ids are `grn_<base64url>` and so can
+    // hold neither a path separator nor a dot. A caller that ever passes
+    // something else must not be able to walk out of `rootDir`.
+    if (!workdir.startsWith(this.rootDir + sep)) {
+      log('refusing to reclaim workdir outside rootDir: %s', workdir);
+      return false;
+    }
+    // Must be a DIRECTORY, not merely something that exists: `rootDir` also
+    // holds `state.json` (this orchestrator's own persisted handles), and
+    // `discardWorkdir`'s `rmSync` deletes files as happily as trees. Same
+    // defence class as the escape check above — no real containerId names a
+    // file — but the blast radius if one ever did is the whole handle map.
+    if (!statSync(workdir, { throwIfNoEntry: false })?.isDirectory()) return false;
+    this.discardWorkdir(workdir);
+    return true;
+  }
+
+  /**
+   * Best-effort removal of a workdir no handle owns. Logs, never throws: every
+   * caller is either unwinding a failure it must report instead of this one, or
+   * tearing a container down along a path where a surviving directory is a
+   * nuisance rather than a fault.
+   *
+   * `retries` sizes the wait for the OS to release a cwd handle — Windows drops
+   * it asynchronously after a child exits. `createContainer`'s unwind needs none
+   * of that (its throw surface ends before any child is spawned), but
+   * `reclaimWorkdir` can still meet an orphan process the previous host left
+   * running with this directory as its cwd, so it is not a *guaranteed*
+   * no-process path either — it simply logs and leaves the directory when the
+   * removal fails.
+   */
+  private discardWorkdir(workdir: string, retries = { maxRetries: 5, retryDelay: 100 }): void {
+    try {
+      rmSync(workdir, { recursive: true, force: true, ...retries });
+      log('discarded workdir %s', workdir);
+    } catch (err) {
+      log('failed to discard workdir %s: %o', workdir, err);
+    }
   }
 
   /**
@@ -261,68 +392,74 @@ export class HostProcessOrchestrator implements Orchestrator {
   }
 
   /**
-   * Ensure the admin's authority node is running, spawning it if absent or
+   * Ensure the admin's owner node is running, spawning it if absent or
    * dead. Idempotent: a second call with the node already alive returns the
    * existing handle without launching a second child. The spawn parameters
    * are persisted so a later `/api/nodes/:id/{start,restart}` (or an
    * orchestrator restart) can re-spawn it without re-supplying them.
    *
-   * The authority node is spawned as `cadre-cli start --authority
+   * The owner node is spawned as `cadre-cli start --owner
    * --admin-port <p> --identity-protobuf <identityPath>` so it carries the
    * host's libp2p identity, founds/joins the control network, and exposes the
    * loopback admin channel the manager delegates to.
    */
-  async ensureAuthorityNode(cfg?: AuthoritySpawnConfig): Promise<ManagedNodeInfo> {
-    const config = cfg ?? this.authorityConfig;
+  async ensureOwnerNode(cfg?: OwnerSpawnConfig): Promise<ManagedNodeInfo> {
+    const config = cfg ?? this.ownerConfig;
     if (!config) {
-      throw new Error('ensureAuthorityNode: no authority config supplied and none persisted');
+      throw new Error('ensureOwnerNode: no owner config supplied and none persisted');
     }
-    this.authorityConfig = config;
+    this.ownerConfig = config;
 
-    const existing = this.findAuthorityHandle();
+    const existing = this.findOwnerHandle();
     if (existing && isPidAlive(existing.pid) && tokenMatches(existing.workdir, existing.startupToken)) {
       this.persist();
       return toNodeInfo(existing);
     }
-    if (existing) {
-      // Drop the stale handle and release its ports — but DO NOT delete the
-      // workdir: the authority node's control-DB storage lives there and must
-      // survive a restart. launchChild reuses the same workdir.
-      this.releasePorts(existing.ports);
-      this.handles.delete(existing.dockerId);
-    }
 
     const profile = config.profile ?? 'storage';
     // Re-resolve push credentials from the secret store on every (re-)spawn so a
     // restart picks up rotated keys and nothing raw is replayed from state.json.
+    // Resolved BEFORE the drop below so the drop → launch window stays
+    // synchronous (see restoreDroppedHandles).
     const push = await this.resolvePush();
-    const ports: NodePorts = {
-      health: this.portAllocator.allocate(),
-      metrics: this.portAllocator.allocate(),
-      admin: this.portAllocator.allocate(),
-      // The authority node must listen on the configured libp2p port so the
-      // NAT mapping (external → internal) lands on it. That port is outside
-      // the managed range, so markUsed is a harmless no-op.
-      p2p: config.libp2pPort,
-    };
-    this.portAllocator.markUsed(config.libp2pPort);
 
-    const result = this.launchChild({
-      containerId: AUTHORITY_CONTAINER_ID,
-      partyId: config.partyId,
-      profile,
-      ports,
-      authority: true,
-      buildConfig: (workdir) => this.buildAuthorityChildConfig(config, profile, workdir, push),
-      extraArgs: ['--authority', '--admin-port', String(ports.admin), '--identity-protobuf', config.identityPath],
-    });
-    const handle = this.handles.get(result.dockerId)!;
-    return toNodeInfo(handle);
+    // NOTE: the short-circuit above matches via `findOwnerHandle` (owner flag OR
+    // containerId), this drop only by containerId. Equivalent today — every
+    // owner handle is launched with OWNER_CONTAINER_ID. If an owner spawn ever
+    // takes a different containerId, the two would disagree and the handle the
+    // short-circuit found would survive here, leaking it and its ports.
+    const dropped = this.dropStaleHandle(OWNER_CONTAINER_ID);
+    let ports: NodePorts | undefined;
+    try {
+      // The owner node must listen on the configured libp2p port so the NAT
+      // mapping (external → internal) lands on it — hence the p2p override.
+      ports = allocateNodePorts(this.portAllocator, { p2p: config.libp2pPort });
+      const result = this.launchChild({
+        containerId: OWNER_CONTAINER_ID,
+        partyId: config.partyId,
+        profile,
+        ports,
+        owner: true,
+        buildConfig: (workdir) => this.buildOwnerChildConfig(config, profile, workdir, push),
+        extraArgs: ['--owner', '--admin-port', String(ports.admin), '--identity-protobuf', config.identityPath],
+      });
+      const handle = this.handles.get(result.dockerId)!;
+      return toNodeInfo(handle);
+    } catch (err) {
+      // Release before restoring — see the same note in createContainer.
+      if (ports) this.releasePorts(ports);
+      this.restoreDroppedHandles(dropped);
+      // Deliberately NOT `discardWorkdir` — the asymmetry with createContainer
+      // is the point. `<rootDir>/owner` is a single fixed path reused by every
+      // restart and holds the host's own control-DB storage, so it neither
+      // grows without bound nor is safe to delete on a failed spawn.
+      throw err;
+    }
   }
 
-  /** Endpoint + bearer for the authority node's admin channel, if spawned. */
-  getAuthorityAdminEndpoint(): AuthorityAdminEndpoint | undefined {
-    const handle = this.findAuthorityHandle();
+  /** Endpoint + bearer for the owner node's admin channel, if spawned. */
+  getOwnerAdminEndpoint(): OwnerAdminEndpoint | undefined {
+    const handle = this.findOwnerHandle();
     if (!handle) return undefined;
     return {
       baseUrl: `http://127.0.0.1:${handle.ports.admin}`,
@@ -330,56 +467,68 @@ export class HostProcessOrchestrator implements Orchestrator {
     };
   }
 
-  /** Whether spawn parameters for the authority node are known (persisted). */
-  hasAuthorityConfig(): boolean {
-    return this.authorityConfig !== undefined;
+  /** Whether spawn parameters for the owner node are known (persisted). */
+  hasOwnerConfig(): boolean {
+    return this.ownerConfig !== undefined;
   }
 
-  /** Whether the given friendly/docker id refers to the authority node. */
-  isAuthorityNode(idOrDockerId: string): boolean {
-    if (idOrDockerId === AUTHORITY_CONTAINER_ID) return true;
+  /** Whether the given friendly/docker id refers to the owner node. */
+  isOwnerNode(idOrDockerId: string): boolean {
+    if (idOrDockerId === OWNER_CONTAINER_ID) return true;
     const direct = this.handles.get(idOrDockerId);
-    if (direct?.authority) return true;
+    if (direct?.owner) return true;
     for (const h of this.handles.values()) {
-      if (h.authority && h.containerId === idOrDockerId) return true;
+      if (h.owner && h.containerId === idOrDockerId) return true;
     }
     return false;
   }
 
-  /** Stop the authority node (if running). Used on graceful shutdown. */
-  async stopAuthorityNode(): Promise<void> {
-    const handle = this.findAuthorityHandle();
+  /** Stop the owner node (if running). Used on graceful shutdown. */
+  async stopOwnerNode(): Promise<void> {
+    const handle = this.findOwnerHandle();
     if (handle && isPidAlive(handle.pid)) {
       await this.stopContainer(handle.dockerId);
     }
   }
 
-  /** Stop the authority node (if running), then re-spawn it from saved config. */
-  async restartAuthorityNode(): Promise<ManagedNodeInfo> {
-    const handle = this.findAuthorityHandle();
+  /** Stop the owner node (if running), then re-spawn it from saved config. */
+  async restartOwnerNode(): Promise<ManagedNodeInfo> {
+    const handle = this.findOwnerHandle();
     if (handle && isPidAlive(handle.pid)) {
       await this.stopContainer(handle.dockerId);
     }
-    return this.ensureAuthorityNode();
+    return this.ensureOwnerNode();
   }
 
   /**
-   * Core spawn mechanics shared by `createContainer` and `ensureAuthorityNode`.
-   * The caller has already allocated `ports`. Releases the ports on a
-   * synchronous spawn failure.
+   * Core spawn mechanics shared by `createContainer` and `ensureOwnerNode`.
+   *
+   * The caller has already allocated `ports` and **owns their lifetime**: this
+   * method never releases them, so every caller must release on any throw out
+   * of here (it has to unwind its handle drop on the same path anyway — see
+   * `restoreDroppedHandles`).
+   *
+   * That contract holds because this method throws only *before* the child is
+   * spawned and its handle stored — everything after that point is
+   * best-effort. Anything new added at the tail must keep it that way.
+   *
+   * Entirely synchronous, which is what makes that unwind sound. Do not add an
+   * `await` here.
    */
   private launchChild(opts: {
     containerId: string;
     partyId: string;
     profile: 'storage' | 'transaction';
     ports: NodePorts;
-    authority: boolean;
+    owner: boolean;
     buildConfig: (workdir: string) => Record<string, unknown>;
     extraArgs: string[];
+    /** Extra env vars merged into the child's environment (e.g. CADRE_OWNER_KEYS). */
+    extraEnv?: Record<string, string>;
     memoryLimit?: string;
   }): OrchestratorCreateResult {
     const { containerId, ports } = opts;
-    const workdir = join(this.rootDir, containerId);
+    const workdir = this.workdirFor(containerId);
     mkdirSync(workdir, { recursive: true });
     mkdirSync(join(workdir, 'storage'), { recursive: true });
 
@@ -404,12 +553,23 @@ export class HostProcessOrchestrator implements Orchestrator {
     const heapMB = heapBytes !== undefined ? Math.max(64, Math.floor(heapBytes / (1024 * 1024))) : undefined;
 
     const env: NodeJS.ProcessEnv = {
-      ...process.env,
+      // Scrubbed, not raw process.env: every CADRE_* config-override key is
+      // stripped so a var set on the manager can't silently reconfigure every
+      // child (see scrubbedParentEnv). Caller-supplied extras come next — the
+      // fixed per-child vars below always win so extraEnv can never clobber
+      // the seed/startup tokens or port wiring.
+      ...scrubbedParentEnv(),
+      ...opts.extraEnv,
       CADRE_STARTUP_TOKEN: token,
       CADRE_HEALTH_PORT: String(ports.health),
       CADRE_METRICS_PORT: String(ports.metrics),
       CADRE_LISTEN_ADDRS: `/ip4/0.0.0.0/tcp/${ports.p2p}`,
       CADRE_SEED_TOKEN: seedToken,
+      // Pin each child's node-local state (trusted-owner anchor, retained
+      // cold-start dial targets) to its OWN workdir. This is the same value the
+      // cli would derive by default (the config file lives here too), but stated
+      // explicitly rather than relying on the scrub above (belt and suspenders).
+      CADRE_NODE_STATE_DIR: workdir,
     };
     if (heapMB !== undefined) {
       env.NODE_OPTIONS = `${process.env.NODE_OPTIONS ?? ''} --max-old-space-size=${heapMB}`.trim();
@@ -444,18 +604,17 @@ export class HostProcessOrchestrator implements Orchestrator {
         env,
       });
     } catch (err) {
-      // Synchronous spawn failure — release the fd and the reserved ports
-      // before propagating, so a bad-args bug doesn't leak resources.
+      // Synchronous spawn failure — close the fd before propagating. This is
+      // the ONLY fd-leak guard on this path: nothing between the `openSync`
+      // above and the `spawn` can throw, so no other catch is needed. Keep it
+      // that way, or add one. (The ports are the caller's to release.)
       closeSync(logFd);
-      this.releasePorts(ports);
       throw err;
     }
     // Always release the parent's copy of the fd — the child has its own.
     closeSync(logFd);
 
     if (!child.pid) {
-      // Spawn returned without a pid — release reservations and report.
-      this.releasePorts(ports);
       throw new Error(`Failed to spawn child for container ${containerId}`);
     }
 
@@ -472,7 +631,7 @@ export class HostProcessOrchestrator implements Orchestrator {
       spawnedAt: new Date().toISOString(),
       partyId: opts.partyId,
       profile: opts.profile,
-      ...(opts.authority ? { authority: true } : {}),
+      ...(opts.owner ? { owner: true } : {}),
       child,
       alive: true,
     };
@@ -486,7 +645,19 @@ export class HostProcessOrchestrator implements Orchestrator {
     });
 
     this.handles.set(dockerId, handle);
-    this.persist();
+    // Past this line the launch has SUCCEEDED: the child is running and this
+    // handle owns its ports. So the state mirror is best-effort — a throw here
+    // would reach the caller's unwind, which would release ports the live child
+    // is bound to and restore the handle this spawn just replaced, leaving two
+    // handles for one container and one of them holding unreserved ports. A
+    // lost write self-heals: the next persist() (any stop/remove/spawn)
+    // rewrites the whole map. Until then a manager restart would fail to
+    // re-attach this child, hence the log.
+    try {
+      this.persist();
+    } catch (err) {
+      log('failed to persist state after launching container %s: %o', containerId, err);
+    }
     this.emitStateChange(handle);
 
     log('created container %s -> pid %d ports=%j', containerId, child.pid, handle.ports);
@@ -502,14 +673,103 @@ export class HostProcessOrchestrator implements Orchestrator {
     };
   }
 
-  /** Locate the authority node's handle, if one has been spawned. */
-  private findAuthorityHandle(): Handle | undefined {
+  /**
+   * Drop any handle left over from a previous spawn of the same `containerId`
+   * and release its ports. Handles are keyed by the per-spawn `dockerId`, so
+   * without this a re-spawn (donated-node respawn) would strand the prior
+   * handle in the map forever, leaking four ports from a bounded range each
+   * time. Mirrors the same cleanup in `ensureOwnerNode`.
+   *
+   * DO NOT delete the workdir: the identity key and node-local stores
+   * (trusted-owner anchor, retained cold-start dial targets) live there and are
+   * the whole reason a respawn comes back as the same node. `launchChild`
+   * reuses the same workdir.
+   *
+   * NOTE: releasing the ports hands them straight back to the allocator, so a
+   * re-spawn while the *previous* child is still listening can bind-clash. Every
+   * caller today re-spawns only a container it has established is not running
+   * (`DonationService.respawn`, `ensureOwnerNode`). If a caller ever needs to
+   * replace a live child, stop it first — or hold the ports until its exit.
+   *
+   * **The drop is reversible.** It happens before the launch can fail, so the
+   * dropped handles are returned and every caller restores them via
+   * {@link restoreDroppedHandles} when the launch throws — otherwise the caller
+   * would be left holding a dockerId this orchestrator no longer knows, and the
+   * node's workdir could never be reclaimed. On a *successful* spawn the drop
+   * stands: `DonationService.abandonRespawn` depends on the old handle being
+   * gone by then.
+   */
+  private dropStaleHandle(containerId: string): Handle[] {
+    const dropped: Handle[] = [];
     for (const h of this.handles.values()) {
-      if (h.authority || h.containerId === AUTHORITY_CONTAINER_ID) return h;
+      if (h.containerId !== containerId) continue;
+      log('dropping stale handle %s for container %s', h.dockerId, containerId);
+      this.releasePorts(h.ports);
+      this.handles.delete(h.dockerId);
+      dropped.push(h);
+    }
+    return dropped;
+  }
+
+  /**
+   * Inverse of {@link dropStaleHandle}, for a spawn that then failed: put each
+   * handle back in the map and re-reserve its four ports, leaving host state
+   * exactly as the failed attempt found it.
+   *
+   * **Precondition: the drop → launch window is synchronous.** Restoring is
+   * sound only because nothing can have taken those ports or run cleanup
+   * against the handle in between — `launchChild` contains no `await` and both
+   * callers resolve push credentials *before* their drop. `launchChild`'s half
+   * is enforced: its declared return type is not a Promise, so adding an
+   * `await` there is a compile error. The callers' half is not — an `await`
+   * slipped between a drop and its launch silently breaks this.
+   *
+   * No `persist()` here: `state.json` is rewritten only by `launchChild` and
+   * only *after* the new handle is stored, so throughout the failure window the
+   * on-disk state still lists the dropped handle — this restore realigns memory
+   * to disk rather than diverging from it.
+   *
+   * NOTE: a restored handle keeps `alive: true` even if its child exited while
+   * it was out of the map (`launchChild`'s exit listener looks the handle up by
+   * dockerId and finds nothing). Only reachable by re-spawning a container
+   * whose child is still live, which `dropStaleHandle`'s note above already
+   * forbids.
+   */
+  private restoreDroppedHandles(dropped: Handle[]): void {
+    for (const h of dropped) {
+      log('restoring dropped handle %s for container %s after failed launch', h.dockerId, h.containerId);
+      this.handles.set(h.dockerId, h);
+      this.reservePorts(h.ports);
+    }
+  }
+
+  /** A managed node's own directory under `rootDir` — config, log, storage, identity. */
+  private workdirFor(containerId: string): string {
+    return join(this.rootDir, containerId);
+  }
+
+  /** Locate the owner node's handle, if one has been spawned. */
+  private findOwnerHandle(): Handle | undefined {
+    for (const h of this.handles.values()) {
+      if (h.owner || h.containerId === OWNER_CONTAINER_ID) return h;
     }
     return undefined;
   }
 
+  /**
+   * Inverse of {@link releasePorts} — hold a handle's whole port set against
+   * the allocator. Used both to rehydrate on `init` and to undo a drop whose
+   * launch then failed.
+   */
+  private reservePorts(ports: NodePorts): void {
+    this.portAllocator.markUsed(ports.health);
+    this.portAllocator.markUsed(ports.metrics);
+    this.portAllocator.markUsed(ports.p2p);
+    // `admin` is absent on handles persisted before this build; markUsed would
+    // otherwise put `undefined` in the used-set.
+    if (typeof ports.admin === 'number') this.portAllocator.markUsed(ports.admin);
+  }
+
   private releasePorts(ports: NodePorts): void {
     this.portAllocator.release(ports.health);
     this.portAllocator.release(ports.metrics);
@@ -580,13 +840,10 @@ export class HostProcessOrchestrator implements Orchestrator {
 
     this.releasePorts(handle.ports);
 
-    // On Windows the OS releases the child's cwd handle asynchronously, so
-    // retry rmSync to give the kernel a chance to drop it.
-    try {
-      rmSync(handle.workdir, { recursive: true, force: true, maxRetries: 20, retryDelay: 200 });
-    } catch (err) {
-      log('failed to remove workdir %s: %o', handle.workdir, err);
-    }
+    // Longer retries than the other callers': this is the one path that has
+    // just killed a child which held this directory as its cwd, and on Windows
+    // the OS releases that handle asynchronously.
+    this.discardWorkdir(handle.workdir, { maxRetries: 20, retryDelay: 200 });
 
     this.handles.delete(dockerId);
     this.persist();
@@ -688,12 +945,20 @@ export class HostProcessOrchestrator implements Orchestrator {
   }
 
   /**
-   * Child config for the authority node. It founds/joins the control network
-   * for `partyId` (no bootstrap peers — it is the founding node), and carries
-   * the host identity via `--identity-protobuf` (passed as a spawn arg).
+   * Child config for the **host's own personal cadre** owner node — the opt-in
+   * "founder" persona spawned only when `ownCadre.enabled` (see
+   * docs/cadre-host.md § Two roles: donor and founder). It founds/joins the
+   * control network for the host's own `partyId` (no bootstrap peers — it is the
+   * founding node of the host's *own* cadre) and carries the host identity via
+   * `--identity-protobuf` (passed as a spawn arg).
+   *
+   * This is NOT the node cadre-host donates to a requester. Donated nodes are
+   * generic (`createContainer` / `buildChildConfig`): they join the
+   * **requester's** cadre via bootstrap peers and pin the *requester's* owner
+   * key — they never run a host genesis.
    */
-  private buildAuthorityChildConfig(
-    cfg: AuthoritySpawnConfig,
+  private buildOwnerChildConfig(
+    cfg: OwnerSpawnConfig,
     profile: 'storage' | 'transaction',
     workdir: string,
     push?: PushCredentials,
@@ -709,10 +974,12 @@ export class HostProcessOrchestrator implements Orchestrator {
     if (profile === 'storage') {
       config.storage = { type: 'file', path: join(workdir, 'storage') };
     }
-    // The always-on authority/storage node participates in strands, so it owns
-    // the push-wake fan-out when credentials are configured. Written into
-    // cadre.json (same host trust boundary as the workdir's control-DB); keys
-    // are never logged — only the redacted presence line in resolvePush.
+    // The host-own-cadre owner/storage node participates in strands, so it owns
+    // the push-wake fan-out when credentials are configured. (Donated nodes
+    // belong to foreign cadres and get NO host push block — see the donor path.)
+    // Written into cadre.json (same host trust boundary as the workdir's
+    // control-DB); keys are never logged — only the redacted presence line in
+    // resolvePush.
     if (push) config.push = push;
     return config;
   }
@@ -721,7 +988,7 @@ export class HostProcessOrchestrator implements Orchestrator {
     const state: PersistedState = {
       version: 1,
       handles: [...this.handles.values()].map((h) => this.toPersisted(h)),
-      ...(this.authorityConfig ? { authorityConfig: this.authorityConfig } : {}),
+      ...(this.ownerConfig ? { ownerConfig: this.ownerConfig } : {}),
     };
     this.stateStore.save(state);
   }
@@ -749,7 +1016,7 @@ export class HostProcessOrchestrator implements Orchestrator {
       spawnedAt: h.spawnedAt,
       partyId: h.partyId,
       profile: h.profile,
-      ...(h.authority ? { authority: true } : {}),
+      ...(h.owner ? { owner: true } : {}),
     };
   }
 }
@@ -764,7 +1031,7 @@ function toNodeInfo(h: Handle): ManagedNodeInfo {
     spawnedAt: h.spawnedAt,
     workdir: h.workdir,
     ports: { ...h.ports },
-    ...(h.authority ? { authority: true } : {}),
+    ...(h.owner ? { owner: true } : {}),
   };
 }