@serfab/cadre-host 0.7.1 → 0.8.1

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

@@ -26,13 +26,17 @@ import { defaultLogPath, rotateOnDisk } from './log-rotator.js';
 import { 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 Handle,
   type HostProcessConfig,
   type ManagedNodeInfo,
+  type NodePorts,
   type NodeStateListener,
+  type PushCredentialsResolver,
 } from './types.js';
 
 const log = debug('cadre:host:orchestrator');
@@ -49,6 +53,17 @@ 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';
+
+/** Endpoint + bearer for the authority node's loopback admin channel (6.6). */
+export interface AuthorityAdminEndpoint {
+  /** e.g. `http://127.0.0.1:<adminPort>`. */
+  baseUrl: string;
+  /** The child's `CADRE_STARTUP_TOKEN`, used as the admin bearer secret. */
+  token: string;
+}
+
 /**
  * Runs cadre nodes as plain Node child processes on the host.
  *
@@ -89,8 +104,12 @@ export class HostProcessOrchestrator implements Orchestrator {
   private readonly defaultMemoryLimit?: string;
   private readonly handles = new Map<string, Handle>();
   private readonly cliEntrypoint: string;
+  /** Resolves push credentials fresh on every spawn (see HostProcessConfig). */
+  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;
 
   constructor(private readonly cfg: HostProcessConfig) {
     this.rootDir = resolvePath(cfg.rootDir);
@@ -105,6 +124,7 @@ export class HostProcessOrchestrator implements Orchestrator {
     this.logMaxFiles = cfg.logMaxFiles ?? DEFAULTS.logMaxFiles;
     this.defaultMemoryLimit = cfg.defaultResources?.memoryLimit;
     this.cliEntrypoint = cfg.spawn?.entrypoint ?? resolveCadreCliBin();
+    this.pushResolver = cfg.pushResolver;
     log('HostProcessOrchestrator rootDir=%s cli=%s', this.rootDir, this.cliEntrypoint);
   }
 
@@ -115,6 +135,7 @@ export class HostProcessOrchestrator implements Orchestrator {
    */
   async init(): Promise<void> {
     const state = this.stateStore.load();
+    this.authorityConfig = state.authorityConfig;
     for (const persisted of state.handles) {
       const alive = isPidAlive(persisted.pid) && tokenMatches(persisted.workdir, persisted.startupToken);
       const handle: Handle = {
@@ -127,6 +148,7 @@ export class HostProcessOrchestrator implements Orchestrator {
         spawnedAt: persisted.spawnedAt,
         partyId: persisted.partyId,
         profile: persisted.profile,
+        ...(persisted.authority ? { authority: true } : {}),
         alive,
       };
       this.handles.set(handle.dockerId, handle);
@@ -134,6 +156,10 @@ export class HostProcessOrchestrator implements Orchestrator {
       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);
+      }
     }
     log('init: re-attached %d handles', state.handles.length);
   }
@@ -192,15 +218,178 @@ export class HostProcessOrchestrator implements Orchestrator {
   }
 
   async createContainer(request: OrchestratorCreateRequest): Promise<OrchestratorCreateResult> {
-    const healthPort = this.portAllocator.allocate();
-    const metricsPort = this.portAllocator.allocate();
-    const p2pPort = this.portAllocator.allocate();
+    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 } : {}),
+    });
+  }
+
+  /**
+   * Resolve the push credentials to inject into the node about to spawn. Called
+   * on every spawn so a re-spawn re-reads the secret store — raw private keys are
+   * never persisted. A resolver failure (e.g. a partial credential set) is
+   * logged and degrades to "no push" rather than failing the spawn: the node
+   * stays up and reachable, just without platform push-wake.
+   */
+  private async resolvePush(): Promise<PushCredentials | undefined> {
+    if (!this.pushResolver) return undefined;
+    try {
+      const push = await this.pushResolver();
+      if (push) {
+        log('resolved push credentials: fcm=%s apns=%s cooldownMs=%s', !!push.fcm, !!push.apns, push.cooldownMs);
+      }
+      return push;
+    } catch (err) {
+      log('push resolver failed; spawning node without push: %s', (err as Error).message);
+      return undefined;
+    }
+  }
+
+  /**
+   * Ensure the admin's authority 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
+   * --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;
+    if (!config) {
+      throw new Error('ensureAuthorityNode: no authority config supplied and none persisted');
+    }
+    this.authorityConfig = config;
+
+    const existing = this.findAuthorityHandle();
+    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.
+    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);
+  }
+
+  /** Endpoint + bearer for the authority node's admin channel, if spawned. */
+  getAuthorityAdminEndpoint(): AuthorityAdminEndpoint | undefined {
+    const handle = this.findAuthorityHandle();
+    if (!handle) return undefined;
+    return {
+      baseUrl: `http://127.0.0.1:${handle.ports.admin}`,
+      token: handle.startupToken,
+    };
+  }
+
+  /** Whether spawn parameters for the authority node are known (persisted). */
+  hasAuthorityConfig(): boolean {
+    return this.authorityConfig !== undefined;
+  }
+
+  /** Whether the given friendly/docker id refers to the authority node. */
+  isAuthorityNode(idOrDockerId: string): boolean {
+    if (idOrDockerId === AUTHORITY_CONTAINER_ID) return true;
+    const direct = this.handles.get(idOrDockerId);
+    if (direct?.authority) return true;
+    for (const h of this.handles.values()) {
+      if (h.authority && 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();
+    if (handle && isPidAlive(handle.pid)) {
+      await this.stopContainer(handle.dockerId);
+    }
+  }
 
-    const workdir = join(this.rootDir, request.containerId);
+  /** Stop the authority node (if running), then re-spawn it from saved config. */
+  async restartAuthorityNode(): Promise<ManagedNodeInfo> {
+    const handle = this.findAuthorityHandle();
+    if (handle && isPidAlive(handle.pid)) {
+      await this.stopContainer(handle.dockerId);
+    }
+    return this.ensureAuthorityNode();
+  }
+
+  /**
+   * Core spawn mechanics shared by `createContainer` and `ensureAuthorityNode`.
+   * The caller has already allocated `ports`. Releases the ports on a
+   * synchronous spawn failure.
+   */
+  private launchChild(opts: {
+    containerId: string;
+    partyId: string;
+    profile: 'storage' | 'transaction';
+    ports: NodePorts;
+    authority: boolean;
+    buildConfig: (workdir: string) => Record<string, unknown>;
+    extraArgs: string[];
+    memoryLimit?: string;
+  }): OrchestratorCreateResult {
+    const { containerId, ports } = opts;
+    const workdir = join(this.rootDir, containerId);
     mkdirSync(workdir, { recursive: true });
     mkdirSync(join(workdir, 'storage'), { recursive: true });
 
     const token = randomBytes(16).toString('hex');
+    // Per-container secret gating the node's `POST /seed` route. The node
+    // refuses seed delivery unless the caller presents this as a bearer token
+    // (and unregisters the route entirely when the env var is empty), so we
+    // mint a fresh high-entropy value per child and hand it back on the result
+    // for `ContainerService.applySeed` to send.
+    const seedToken = randomBytes(32).toString('base64url');
     const tokenPath = join(workdir, STARTUP_TOKEN_FILE);
     // Ensure stale token from a previous container with the same id is cleared.
     if (existsSync(tokenPath)) {
@@ -208,22 +397,19 @@ export class HostProcessOrchestrator implements Orchestrator {
     }
 
     const configPath = join(workdir, CONFIG_FILE);
-    writeFileSync(
-      configPath,
-      JSON.stringify(this.buildChildConfig(request, workdir), null, 2),
-      'utf8',
-    );
+    writeFileSync(configPath, JSON.stringify(opts.buildConfig(workdir), null, 2), 'utf8');
 
-    const memoryLimit = request.resources?.memoryLimit ?? this.defaultMemoryLimit;
+    const memoryLimit = opts.memoryLimit ?? this.defaultMemoryLimit;
     const heapBytes = parseMemoryLimit(memoryLimit);
     const heapMB = heapBytes !== undefined ? Math.max(64, Math.floor(heapBytes / (1024 * 1024))) : undefined;
 
     const env: NodeJS.ProcessEnv = {
       ...process.env,
       CADRE_STARTUP_TOKEN: token,
-      CADRE_HEALTH_PORT: String(healthPort),
-      CADRE_METRICS_PORT: String(metricsPort),
-      CADRE_LISTEN_ADDRS: `/ip4/0.0.0.0/tcp/${p2pPort}`,
+      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,
     };
     if (heapMB !== undefined) {
       env.NODE_OPTIONS = `${process.env.NODE_OPTIONS ?? ''} --max-old-space-size=${heapMB}`.trim();
@@ -236,35 +422,32 @@ export class HostProcessOrchestrator implements Orchestrator {
     maybeRotateAtSpawn(logPath, this.logMaxBytes, this.logMaxFiles);
     const logFd = openSync(logPath, 'a');
 
+    const args = [
+      this.cliEntrypoint,
+      'start',
+      '-c', configPath,
+      '--health-port', String(ports.health),
+      '--metrics-port', String(ports.metrics),
+      '--startup-token-file', tokenPath,
+      ...opts.extraArgs,
+    ];
+
     let child: ChildProcess;
     try {
-      child = spawn(
-        process.execPath,
-        [
-          this.cliEntrypoint,
-          'start',
-          '-c', configPath,
-          '--health-port', String(healthPort),
-          '--metrics-port', String(metricsPort),
-          '--startup-token-file', tokenPath,
-        ],
-        {
-          cwd: workdir,
-          detached: true,
-          // Inherit the log fd directly. OS duplicates it into the child;
-          // closing our copy below is safe and severs the parent's only
-          // tie to the child's write path.
-          stdio: ['ignore', logFd, logFd],
-          env,
-        },
-      );
+      child = spawn(process.execPath, args, {
+        cwd: workdir,
+        detached: true,
+        // Inherit the log fd directly. OS duplicates it into the child;
+        // closing our copy below is safe and severs the parent's only
+        // tie to the child's write path.
+        stdio: ['ignore', logFd, logFd],
+        env,
+      });
     } catch (err) {
       // Synchronous spawn failure — release the fd and the reserved ports
       // before propagating, so a bad-args bug doesn't leak resources.
       closeSync(logFd);
-      this.portAllocator.release(healthPort);
-      this.portAllocator.release(metricsPort);
-      this.portAllocator.release(p2pPort);
+      this.releasePorts(ports);
       throw err;
     }
     // Always release the parent's copy of the fd — the child has its own.
@@ -272,25 +455,24 @@ export class HostProcessOrchestrator implements Orchestrator {
 
     if (!child.pid) {
       // Spawn returned without a pid — release reservations and report.
-      this.portAllocator.release(healthPort);
-      this.portAllocator.release(metricsPort);
-      this.portAllocator.release(p2pPort);
-      throw new Error(`Failed to spawn child for container ${request.containerId}`);
+      this.releasePorts(ports);
+      throw new Error(`Failed to spawn child for container ${containerId}`);
     }
 
     child.unref();
 
     const dockerId = encodeDockerId(child.pid, token);
     const handle: Handle = {
-      containerId: request.containerId,
+      containerId,
       dockerId,
       pid: child.pid,
       startupToken: token,
       workdir,
-      ports: { health: healthPort, metrics: metricsPort, p2p: p2pPort },
+      ports,
       spawnedAt: new Date().toISOString(),
-      partyId: request.partyId,
-      profile: request.profile,
+      partyId: opts.partyId,
+      profile: opts.profile,
+      ...(opts.authority ? { authority: true } : {}),
       child,
       alive: true,
     };
@@ -307,16 +489,34 @@ export class HostProcessOrchestrator implements Orchestrator {
     this.persist();
     this.emitStateChange(handle);
 
-    log('created container %s -> pid %d ports=%j', request.containerId, child.pid, handle.ports);
+    log('created container %s -> pid %d ports=%j', containerId, child.pid, handle.ports);
 
     return {
       dockerId,
-      healthEndpoint: `http://localhost:${healthPort}/health`,
-      metricsEndpoint: `http://localhost:${metricsPort}/metrics`,
-      p2pPort,
+      healthEndpoint: `http://localhost:${ports.health}/health`,
+      metricsEndpoint: `http://localhost:${ports.metrics}/metrics`,
+      // The node's seed API (`POST /seed`) is bound to the same server/port as `/health`.
+      seedEndpoint: `http://localhost:${ports.health}/seed`,
+      seedToken,
+      p2pPort: ports.p2p,
     };
   }
 
+  /** Locate the authority node's handle, if one has been spawned. */
+  private findAuthorityHandle(): Handle | undefined {
+    for (const h of this.handles.values()) {
+      if (h.authority || h.containerId === AUTHORITY_CONTAINER_ID) return h;
+    }
+    return undefined;
+  }
+
+  private releasePorts(ports: NodePorts): void {
+    this.portAllocator.release(ports.health);
+    this.portAllocator.release(ports.metrics);
+    this.portAllocator.release(ports.p2p);
+    this.portAllocator.release(ports.admin);
+  }
+
   async stopContainer(dockerId: string): Promise<void> {
     const handle = this.requireHandle(dockerId);
     if (!isPidAlive(handle.pid)) {
@@ -378,9 +578,7 @@ export class HostProcessOrchestrator implements Orchestrator {
       await this.stopContainer(dockerId);
     }
 
-    this.portAllocator.release(handle.ports.health);
-    this.portAllocator.release(handle.ports.metrics);
-    this.portAllocator.release(handle.ports.p2p);
+    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.
@@ -395,7 +593,7 @@ export class HostProcessOrchestrator implements Orchestrator {
   }
 
   async isRunning(dockerId: string): Promise<boolean> {
-    let handle: Handle | undefined = this.handles.get(dockerId);
+    const handle: Handle | undefined = this.handles.get(dockerId);
     let pid: number;
     let token: string;
     let workdir: string | undefined;
@@ -459,7 +657,11 @@ export class HostProcessOrchestrator implements Orchestrator {
     return handle;
   }
 
-  private buildChildConfig(req: OrchestratorCreateRequest, workdir: string): Record<string, unknown> {
+  private buildChildConfig(
+    req: OrchestratorCreateRequest,
+    workdir: string,
+    push?: PushCredentials,
+  ): Record<string, unknown> {
     const cfg: Record<string, unknown> = {
       controlNetwork: {
         partyId: req.partyId,
@@ -478,13 +680,48 @@ export class HostProcessOrchestrator implements Orchestrator {
       }
       cfg.storage = storage;
     }
+    // Push credentials land in the child's cadre.json on the host filesystem —
+    // the same trust boundary as the control-DB storage in this workdir. The
+    // private keys are NOT logged (the resolver redacts; we log only presence).
+    if (push) cfg.push = push;
     return cfg;
   }
 
+  /**
+   * 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).
+   */
+  private buildAuthorityChildConfig(
+    cfg: AuthoritySpawnConfig,
+    profile: 'storage' | 'transaction',
+    workdir: string,
+    push?: PushCredentials,
+  ): Record<string, unknown> {
+    const config: Record<string, unknown> = {
+      controlNetwork: {
+        partyId: cfg.partyId,
+        bootstrapNodes: [],
+      },
+      profile,
+      strandFilter: 'all',
+    };
+    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.
+    if (push) config.push = push;
+    return config;
+  }
+
   private persist(): void {
     const state: PersistedState = {
       version: 1,
       handles: [...this.handles.values()].map((h) => this.toPersisted(h)),
+      ...(this.authorityConfig ? { authorityConfig: this.authorityConfig } : {}),
     };
     this.stateStore.save(state);
   }
@@ -512,6 +749,7 @@ export class HostProcessOrchestrator implements Orchestrator {
       spawnedAt: h.spawnedAt,
       partyId: h.partyId,
       profile: h.profile,
+      ...(h.authority ? { authority: true } : {}),
     };
   }
 }
@@ -526,6 +764,7 @@ function toNodeInfo(h: Handle): ManagedNodeInfo {
     spawnedAt: h.spawnedAt,
     workdir: h.workdir,
     ports: { ...h.ports },
+    ...(h.authority ? { authority: true } : {}),
   };
 }
 
@@ -542,6 +781,7 @@ function resolveCadreCliBin(): string {
       `Unable to resolve @serfab/cadre-cli bin from cadre-host. ` +
       `Ensure cadre-cli is built (yarn workspace @serfab/cadre-cli build) ` +
       `and listed as a dependency. Underlying error: ${(err as Error).message}`,
+      { cause: err },
     );
   }
 }
@@ -564,7 +804,7 @@ function tokenMatches(workdir: string, expected: string): boolean {
  */
 function maybeRotateAtSpawn(logPath: string, maxBytes: number, maxFiles: number): void {
   if (maxBytes <= 0 || maxFiles < 1) return;
-  let size = 0;
+  let size: number;
   try {
     size = statSync(logPath).size;
   } catch {

package/src/orchestrator/index.ts

@@ -1,3 +1,10 @@
-export { HostProcessOrchestrator } from './host-process-orchestrator.js';
-export type { HostProcessConfig, ManagedNodeInfo, NodeStateListener } from './types.js';
+export { HostProcessOrchestrator, AUTHORITY_CONTAINER_ID } from './host-process-orchestrator.js';
+export type { AuthorityAdminEndpoint } from './host-process-orchestrator.js';
+export type {
+  HostProcessConfig,
+  ManagedNodeInfo,
+  NodeStateListener,
+  NodePorts,
+  AuthoritySpawnConfig,
+} from './types.js';
 export type { PersistedHandle } from './state-store.js';

package/src/orchestrator/state-store.ts

@@ -2,6 +2,8 @@ import { existsSync, readFileSync, renameSync, writeFileSync, mkdirSync } from '
 import { dirname, join } from 'node:path';
 import debug from 'debug';
 
+import type { AuthoritySpawnConfig, NodePorts } from './types.js';
+
 const log = debug('cadre:host:state-store');
 
 /**
@@ -15,15 +17,19 @@ export interface PersistedHandle {
   pid: number;
   startupToken: string;
   workdir: string;
-  ports: { health: number; metrics: number; p2p: number };
+  ports: NodePorts;
   spawnedAt: string;          // ISO timestamp
   partyId: string;
   profile: 'storage' | 'transaction';
+  /** True for the admin's authority node. */
+  authority?: boolean;
 }
 
 export interface PersistedState {
   version: 1;
   handles: PersistedHandle[];
+  /** Spawn parameters for the authority node, so it can be re-spawned on demand. */
+  authorityConfig?: AuthoritySpawnConfig;
 }
 
 const STATE_VERSION = 1;
@@ -48,7 +54,11 @@ export class StateStore {
         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 };
+      return {
+        version: STATE_VERSION,
+        handles: parsed.handles,
+        ...(parsed.authorityConfig ? { authorityConfig: parsed.authorityConfig } : {}),
+      };
     } 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
@@ -60,7 +70,15 @@ export class StateStore {
 
   save(state: PersistedState): void {
     mkdirSync(dirname(this.path), { recursive: true });
-    const payload = JSON.stringify({ version: STATE_VERSION, handles: state.handles }, null, 2);
+    const payload = JSON.stringify(
+      {
+        version: STATE_VERSION,
+        handles: state.handles,
+        ...(state.authorityConfig ? { authorityConfig: state.authorityConfig } : {}),
+      },
+      null,
+      2,
+    );
     const tmp = `${this.path}.tmp`;
     writeFileSync(tmp, payload, { encoding: 'utf8' });
     renameSync(tmp, this.path);

package/src/orchestrator/types.ts

@@ -3,6 +3,7 @@
  */
 
 import type { ChildProcess } from 'node:child_process';
+import type { PushCredentials } from '@serfab/cadre-core';
 
 /** User-facing configuration for `HostProcessOrchestrator`. */
 export interface HostProcessConfig {
@@ -23,6 +24,31 @@ export interface HostProcessConfig {
    * spawns `node <entrypoint> ...` instead of resolving `@serfab/cadre-cli`.
    */
   spawn?: { entrypoint?: string };
+  /**
+   * Resolver for the platform push credentials (FCM/APNs) to inject into a
+   * spawned strand-participating node's `cadre.json` (`config.push`). Called
+   * fresh on EVERY spawn/re-spawn so the secret store stays the source of truth
+   * and no raw private key is ever persisted in `state.json`. Returns `undefined`
+   * when no push credentials are configured (the default — push is opt-in). The
+   * resolver itself is responsible for rejecting a partial credential set.
+   */
+  pushResolver?: PushCredentialsResolver;
+}
+
+/**
+ * Resolves the push credentials to inject into a node being spawned. Re-invoked
+ * per spawn so a restart re-reads the secret store rather than replaying stale
+ * (or persisted) material. See {@link HostProcessConfig.pushResolver}.
+ */
+export type PushCredentialsResolver = () => Promise<PushCredentials | undefined>;
+
+/** Per-child allocated ports. `admin` carries the loopback admin channel (6.6). */
+export interface NodePorts {
+  health: number;
+  metrics: number;
+  p2p: number;
+  /** Loopback admin-channel port. Bound only by the authority node. */
+  admin: number;
 }
 
 /** In-memory record per managed child. */
@@ -32,10 +58,12 @@ export interface Handle {
   pid: number;
   startupToken: string;
   workdir: string;
-  ports: { health: number; metrics: number; p2p: number };
+  ports: NodePorts;
   spawnedAt: string;
   partyId: string;
   profile: 'storage' | 'transaction';
+  /** True for the admin's authority node (binds the admin channel). */
+  authority?: boolean;
   /** Live ChildProcess reference; absent after re-attach via init(). */
   child?: ChildProcess;
   /** Marked false when init() finds the PID dead or token mismatched. */
@@ -54,7 +82,25 @@ export interface ManagedNodeInfo {
   status: 'running' | 'stopped';
   spawnedAt: string;
   workdir: string;
-  ports: { health: number; metrics: number; p2p: number };
+  ports: NodePorts;
+  /** True for the admin's authority node. */
+  authority?: boolean;
+}
+
+/**
+ * Persisted spawn parameters for the admin's authority node. Stored alongside
+ * the handles so an orchestrator restart can re-spawn the authority node from
+ * `/api/nodes/:id/{start,restart}` without the caller re-supplying them.
+ */
+export interface AuthoritySpawnConfig {
+  /** 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';
 }
 
 /**