@serfab/cadre-host 1.13.0 → 1.15.0

package/src/__tests__/orchestrator-handle-contract.ts

@@ -1,134 +1,134 @@
-/**
- * The handle rules `HostProcessOrchestrator` and its test stand-in
- * `FakeOrchestrator` (`donation/__tests__/fake-orchestrator.ts`) must both obey,
- * written once and run against each: `orchestrator.test.ts` registers them over
- * the real class, `fake-orchestrator.test.ts` over the fake. A rule one of them
- * stops obeying fails in that file's run.
- *
- * Not a `.test.ts` file, so vitest does not collect it on its own.
- *
- * Only what both classes can satisfy belongs here — no ports, no files on disk,
- * none of the fake's recording arrays. Those stay in the two calling files.
- */
-
-import { describe, expect, it } from 'vitest';
-
-import type { OrchestratorCreateRequest, OrchestratorCreateResult } from '@serfab/cadre-provider';
-
-import type { HostProcessOrchestrator } from '../orchestrator/host-process-orchestrator.js';
-
-/** What the contract needs from either orchestrator. */
-export type ContractOrchestrator = Pick<
-  HostProcessOrchestrator,
-  'createContainer' | 'stopContainer' | 'removeContainer' | 'resolveDockerId'
->;
-
-export interface HandleContractHarness<O extends ContractOrchestrator> {
-  /** A fresh orchestrator. Teardown is the calling file's own afterEach. */
-  make(): O;
-  request(containerId: string): OrchestratorCreateRequest;
-  /** Resolve once the spawn named by `dockerId` reads as running. */
-  started(orch: O, dockerId: string): Promise<void>;
-  /**
-   * Make `createContainer` for `containerId` throw from here on. Only called
-   * after that container has been spawned once and stopped, and no case creates
-   * again afterwards.
-   */
-  failNextCreate(orch: O, containerId: string): void;
-}
-
-const CONTAINER = 'grn_contract_a';
-const OTHER_CONTAINER = 'grn_contract_b';
-
-export function describeHandleContract<O extends ContractOrchestrator>(
-  label: string,
-  harness: HandleContractHarness<O>,
-): void {
-  async function spawn(orch: O, containerId: string): Promise<OrchestratorCreateResult> {
-    const result = await orch.createContainer(harness.request(containerId));
-    await harness.started(orch, result.dockerId);
-    return result;
-  }
-
-  // Stops first: a container whose previous child is still running is refused.
-  async function respawn(orch: O, containerId: string, previousDockerId: string): Promise<OrchestratorCreateResult> {
-    await orch.stopContainer(previousDockerId);
-    return spawn(orch, containerId);
-  }
-
-  describe(`${label} handle contract`, () => {
-    it('rejects a dockerId it never issued', async () => {
-      const orch = harness.make();
-
-      await expectNotFound(orch.stopContainer('never-issued'), 'never-issued');
-      await expectNotFound(orch.removeContainer('never-issued'), 'never-issued');
-    });
-
-    it('rejects a dockerId once its container has been removed', async () => {
-      const orch = harness.make();
-      const { dockerId } = await spawn(orch, CONTAINER);
-      await orch.stopContainer(dockerId);
-
-      await orch.removeContainer(dockerId);
-
-      await expectNotFound(orch.stopContainer(dockerId), dockerId);
-      await expectNotFound(orch.removeContainer(dockerId), dockerId);
-    });
-
-    it('replaces the first spawn\'s dockerId when the container re-spawns', async () => {
-      const orch = harness.make();
-      const first = await spawn(orch, CONTAINER);
-
-      const second = await respawn(orch, CONTAINER, first.dockerId);
-
-      await expectNotFound(orch.stopContainer(first.dockerId), first.dockerId);
-      expect(orch.resolveDockerId(CONTAINER)).toBe(second.dockerId);
-      await expect(orch.stopContainer(second.dockerId)).resolves.toBeUndefined();
-    });
-
-    // Launching over a live child hands its ports to a second child that then
-    // dies on them, while the caller records the new dockerId and seed token.
-    it('refuses to re-spawn a container whose previous child is still running', async () => {
-      const orch = harness.make();
-      const first = await spawn(orch, CONTAINER);
-
-      await expect(orch.createContainer(harness.request(CONTAINER)))
-        .rejects.toHaveProperty('message', `container ${CONTAINER} is still running`);
-
-      expect(orch.resolveDockerId(CONTAINER)).toBe(first.dockerId);
-      await expect(orch.stopContainer(first.dockerId)).resolves.toBeUndefined();
-    });
-
-    // The drop on re-spawn filters on containerId; an orchestrator that cleared
-    // every handle would still pass the same-container case above.
-    it('leaves another container\'s dockerId alone when one container re-spawns', async () => {
-      const orch = harness.make();
-      const other = await spawn(orch, OTHER_CONTAINER);
-      const first = await spawn(orch, CONTAINER);
-
-      await respawn(orch, CONTAINER, first.dockerId);
-
-      expect(orch.resolveDockerId(OTHER_CONTAINER)).toBe(other.dockerId);
-      await expect(orch.stopContainer(other.dockerId)).resolves.toBeUndefined();
-    });
-
-    // What lets a caller still clean up the node it knows about after a re-spawn
-    // that did not happen.
-    it('keeps the first spawn\'s dockerId when the re-spawn fails', async () => {
-      const orch = harness.make();
-      const first = await spawn(orch, CONTAINER);
-      await orch.stopContainer(first.dockerId);
-
-      harness.failNextCreate(orch, CONTAINER);
-      await expect(orch.createContainer(harness.request(CONTAINER))).rejects.toThrow();
-
-      expect(orch.resolveDockerId(CONTAINER)).toBe(first.dockerId);
-      await expect(orch.removeContainer(first.dockerId)).resolves.toBeUndefined();
-    });
-  });
-}
-
-/** The whole message, not a substring, so the two classes cannot come to word it differently. */
-async function expectNotFound(call: Promise<void>, dockerId: string): Promise<void> {
-  await expect(call).rejects.toHaveProperty('message', `Container not found: ${dockerId}`);
-}
+/**
+ * The handle rules `HostProcessOrchestrator` and its test stand-in
+ * `FakeOrchestrator` (`hosted/__tests__/fake-orchestrator.ts`) must both obey,
+ * written once and run against each: `orchestrator.test.ts` registers them over
+ * the real class, `fake-orchestrator.test.ts` over the fake. A rule one of them
+ * stops obeying fails in that file's run.
+ *
+ * Not a `.test.ts` file, so vitest does not collect it on its own.
+ *
+ * Only what both classes can satisfy belongs here — no ports, no files on disk,
+ * none of the fake's recording arrays. Those stay in the two calling files.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import type { OrchestratorCreateRequest, OrchestratorCreateResult } from '@serfab/cadre-provider';
+
+import type { HostProcessOrchestrator } from '../orchestrator/host-process-orchestrator.js';
+
+/** What the contract needs from either orchestrator. */
+export type ContractOrchestrator = Pick<
+  HostProcessOrchestrator,
+  'createContainer' | 'stopContainer' | 'removeContainer' | 'resolveDockerId'
+>;
+
+export interface HandleContractHarness<O extends ContractOrchestrator> {
+  /** A fresh orchestrator. Teardown is the calling file's own afterEach. */
+  make(): O;
+  request(containerId: string): OrchestratorCreateRequest;
+  /** Resolve once the spawn named by `dockerId` reads as running. */
+  started(orch: O, dockerId: string): Promise<void>;
+  /**
+   * Make `createContainer` for `containerId` throw from here on. Only called
+   * after that container has been spawned once and stopped, and no case creates
+   * again afterwards.
+   */
+  failNextCreate(orch: O, containerId: string): void;
+}
+
+const CONTAINER = 'hn_contract_a';
+const OTHER_CONTAINER = 'hn_contract_b';
+
+export function describeHandleContract<O extends ContractOrchestrator>(
+  label: string,
+  harness: HandleContractHarness<O>,
+): void {
+  async function spawn(orch: O, containerId: string): Promise<OrchestratorCreateResult> {
+    const result = await orch.createContainer(harness.request(containerId));
+    await harness.started(orch, result.dockerId);
+    return result;
+  }
+
+  // Stops first: a container whose previous child is still running is refused.
+  async function respawn(orch: O, containerId: string, previousDockerId: string): Promise<OrchestratorCreateResult> {
+    await orch.stopContainer(previousDockerId);
+    return spawn(orch, containerId);
+  }
+
+  describe(`${label} handle contract`, () => {
+    it('rejects a dockerId it never issued', async () => {
+      const orch = harness.make();
+
+      await expectNotFound(orch.stopContainer('never-issued'), 'never-issued');
+      await expectNotFound(orch.removeContainer('never-issued'), 'never-issued');
+    });
+
+    it('rejects a dockerId once its container has been removed', async () => {
+      const orch = harness.make();
+      const { dockerId } = await spawn(orch, CONTAINER);
+      await orch.stopContainer(dockerId);
+
+      await orch.removeContainer(dockerId);
+
+      await expectNotFound(orch.stopContainer(dockerId), dockerId);
+      await expectNotFound(orch.removeContainer(dockerId), dockerId);
+    });
+
+    it('replaces the first spawn\'s dockerId when the container re-spawns', async () => {
+      const orch = harness.make();
+      const first = await spawn(orch, CONTAINER);
+
+      const second = await respawn(orch, CONTAINER, first.dockerId);
+
+      await expectNotFound(orch.stopContainer(first.dockerId), first.dockerId);
+      expect(orch.resolveDockerId(CONTAINER)).toBe(second.dockerId);
+      await expect(orch.stopContainer(second.dockerId)).resolves.toBeUndefined();
+    });
+
+    // Launching over a live child hands its ports to a second child that then
+    // dies on them, while the caller records the new dockerId.
+    it('refuses to re-spawn a container whose previous child is still running', async () => {
+      const orch = harness.make();
+      const first = await spawn(orch, CONTAINER);
+
+      await expect(orch.createContainer(harness.request(CONTAINER)))
+        .rejects.toHaveProperty('message', `container ${CONTAINER} is still running`);
+
+      expect(orch.resolveDockerId(CONTAINER)).toBe(first.dockerId);
+      await expect(orch.stopContainer(first.dockerId)).resolves.toBeUndefined();
+    });
+
+    // The drop on re-spawn filters on containerId; an orchestrator that cleared
+    // every handle would still pass the same-container case above.
+    it('leaves another container\'s dockerId alone when one container re-spawns', async () => {
+      const orch = harness.make();
+      const other = await spawn(orch, OTHER_CONTAINER);
+      const first = await spawn(orch, CONTAINER);
+
+      await respawn(orch, CONTAINER, first.dockerId);
+
+      expect(orch.resolveDockerId(OTHER_CONTAINER)).toBe(other.dockerId);
+      await expect(orch.stopContainer(other.dockerId)).resolves.toBeUndefined();
+    });
+
+    // What lets a caller still clean up the node it knows about after a re-spawn
+    // that did not happen.
+    it('keeps the first spawn\'s dockerId when the re-spawn fails', async () => {
+      const orch = harness.make();
+      const first = await spawn(orch, CONTAINER);
+      await orch.stopContainer(first.dockerId);
+
+      harness.failNextCreate(orch, CONTAINER);
+      await expect(orch.createContainer(harness.request(CONTAINER))).rejects.toThrow();
+
+      expect(orch.resolveDockerId(CONTAINER)).toBe(first.dockerId);
+      await expect(orch.removeContainer(first.dockerId)).resolves.toBeUndefined();
+    });
+  });
+}
+
+/** The whole message, not a substring, so the two classes cannot come to word it differently. */
+async function expectNotFound(call: Promise<void>, dockerId: string): Promise<void> {
+  await expect(call).rejects.toHaveProperty('message', `Container not found: ${dockerId}`);
+}

package/src/__tests__/orchestrator-node-identity.test.ts

@@ -1,203 +1,177 @@
-/**
- * HostProcessOrchestrator per-node identity tests.
- *
- * A donated node must keep the peer id its host cadre approved across restarts,
- * and needs a durable on-disk home for its node-local stores (`cadre-cli start`
- * opens the file-backed bootstrap-peer / trusted-owner stores only when a
- * protobuf identity key file is configured). The orchestrator therefore writes
- * `<workdir>/identity.key` once per container and passes it as
- * `--identity-file`.
- *
- * A fake CLI records the `--identity-file` argument it was launched with, so
- * the spawn wiring is observable without a real cadre node.
- */
-
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-
-import { HostProcessOrchestrator, OWNER_CONTAINER_ID } from '../orchestrator/host-process-orchestrator.js';
-import { loadIdentity } from '../installer/identity.js';
-import { removeAllNodes } from './orchestrator-teardown.js';
-
-// Writes the --identity-file argument (as seen on its own command line) next
-// to the startup token, then behaves like a minimal long-lived node.
-const FAKE_CLI = `
-import fs from 'node:fs';
-import path from 'node:path';
-const args = process.argv.slice(2);
-const get = (flag) => { const i = args.indexOf(flag); return i >= 0 ? args[i + 1] : undefined; };
-const tokenPath = get('--startup-token-file');
-const token = process.env.CADRE_STARTUP_TOKEN ?? '';
-if (tokenPath) {
-  const dir = path.dirname(tokenPath);
-  try { fs.writeFileSync(path.join(dir, 'identity-arg.txt'), get('--identity-file') ?? '', 'utf8'); } catch (e) { console.error(e); }
-  if (token) { try { fs.writeFileSync(tokenPath, token, 'utf8'); } catch (e) { console.error(e); } }
-}
-process.on('SIGTERM', () => process.exit(0));
-setInterval(() => {}, 1 << 30);
-`;
-
-let tmpRoot: string;
-let scriptPath: string;
-const orchestrators: HostProcessOrchestrator[] = [];
-
-beforeEach(() => {
-  tmpRoot = mkdtempSync(join(tmpdir(), 'cadre-host-nodeid-'));
-  scriptPath = join(tmpRoot, 'fake-cli.mjs');
-  writeFileSync(scriptPath, FAKE_CLI, 'utf8');
-});
-
-afterEach(async () => {
-  try {
-    await removeAllNodes(orchestrators);
-  } finally {
-    await sleep(50);
-    try { rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* ignore */ }
-  }
-});
-
-function makeOrchestrator(
-  rootDir: string,
-  portRange: { start: number; end: number } = { start: 17500, end: 17999 },
-): HostProcessOrchestrator {
-  mkdirSync(rootDir, { recursive: true });
-  const orch = new HostProcessOrchestrator({
-    rootDir,
-    portRange,
-    stopTimeoutMs: 1500,
-    spawn: { entrypoint: scriptPath },
-  });
-  orchestrators.push(orch);
-  return orch;
-}
-
-async function waitForFile(path: string, timeoutMs = 5000): Promise<string> {
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
-    if (existsSync(path)) return readFileSync(path, 'utf8');
-    await sleep(50);
-  }
-  throw new Error(`file never appeared: ${path}`);
-}
-
-function sleep(ms: number): Promise<void> {
-  return new Promise((res) => setTimeout(res, ms));
-}
-
-describe('HostProcessOrchestrator node identity', () => {
-  it('passes --identity-file pointing at a real key inside the node workdir', async () => {
-    const rootDir = join(tmpRoot, 'a');
-    const orch = makeOrchestrator(rootDir);
-    await orch.init();
-
-    await orch.createContainer({
-      containerId: 'donated-1',
-      partyId: 'foreign-P',
-      bootstrapNodes: [],
-      profile: 'storage',
-      pinnedOwnerKeys: ['key-a'],
-    });
-
-    const workdir = join(rootDir, 'donated-1');
-    const arg = await waitForFile(join(workdir, 'identity-arg.txt'));
-    expect(arg).toBe(join(workdir, 'identity.key'));
-    // Decodes as a libp2p protobuf private key → the child gets a usable identity.
-    expect(loadIdentity(arg).peerId).toMatch(/^12D3Koo/);
-  });
-
-  it('reuses the same identity when the same containerId is spawned again', async () => {
-    const rootDir = join(tmpRoot, 'b');
-    const orch = makeOrchestrator(rootDir);
-    await orch.init();
-
-    const first = await orch.createContainer({
-      containerId: 'donated-2',
-      partyId: 'foreign-P',
-      bootstrapNodes: [],
-      profile: 'storage',
-      pinnedOwnerKeys: ['key-a'],
-    });
-    const workdir = join(rootDir, 'donated-2');
-    await waitForFile(join(workdir, 'identity-arg.txt'));
-    const before = loadIdentity(join(workdir, 'identity.key')).peerId;
-
-    // Stop (not remove — removal deletes the workdir) and re-spawn, as a restart
-    // of a live loan would.
-    await orch.stopContainer(first.dockerId);
-    await orch.createContainer({
-      containerId: 'donated-2',
-      partyId: 'foreign-P',
-      bootstrapNodes: [],
-      profile: 'storage',
-      pinnedOwnerKeys: ['key-a'],
-    });
-
-    const after = loadIdentity(join(workdir, 'identity.key')).peerId;
-    expect(after).toBe(before);
-  });
-
-  it('destroys the identity with the workdir when the loan is terminated', async () => {
-    const rootDir = join(tmpRoot, 'c');
-    const orch = makeOrchestrator(rootDir);
-    await orch.init();
-
-    const created = await orch.createContainer({
-      containerId: 'donated-3',
-      partyId: 'foreign-P',
-      bootstrapNodes: [],
-      profile: 'storage',
-      pinnedOwnerKeys: ['key-a'],
-    });
-    const identityPath = join(rootDir, 'donated-3', 'identity.key');
-    await waitForFile(identityPath);
-
-    await orch.removeContainer(created.dockerId);
-    expect(existsSync(identityPath)).toBe(false);
-    expect(existsSync(join(rootDir, 'donated-3'))).toBe(false);
-  });
-
-  // The failure the identity step can actually produce is a damaged key file,
-  // and `DonationService.provision` turns every such throw into an `error`
-  // record and lets the grantee retry. If the spawn path reserved its ports
-  // before the step that throws, each retry would burn five more ports out of a
-  // bounded range until provisioning stopped working altogether.
-  it('reserves no ports when the identity step fails', async () => {
-    const rootDir = join(tmpRoot, 'd');
-    // Exactly one node's worth of ports (health, metrics, p2p, admin, ws).
-    const orch = makeOrchestrator(rootDir, { start: 18100, end: 18104 });
-    await orch.init();
-
-    mkdirSync(join(rootDir, 'donated-bad'), { recursive: true });
-    writeFileSync(join(rootDir, 'donated-bad', 'identity.key'), 'not a protobuf private key', 'utf8');
-
-    const request = {
-      partyId: 'foreign-P',
-      bootstrapNodes: [],
-      profile: 'storage' as const,
-      pinnedOwnerKeys: ['key-a'],
-    };
-    await expect(orch.createContainer({ ...request, containerId: 'donated-bad' })).rejects.toThrow();
-
-    // The whole range is still free, so a healthy container still gets its five.
-    const ok = await orch.createContainer({ ...request, containerId: 'donated-good' });
-    expect(ok.p2pPort).toBeGreaterThanOrEqual(18100);
-  });
-
-  // The owner node carries the HOST's installer identity from <dataDir>, not a
-  // per-workdir key — a second key in its workdir would mean the host's own
-  // cadre node quietly changed peer id.
-  it('leaves the owner node on its own installer identity', async () => {
-    const rootDir = join(tmpRoot, 'e');
-    const orch = makeOrchestrator(rootDir);
-    await orch.init();
-
-    const hostIdentity = join(tmpRoot, 'host-identity.key');
-    await orch.ensureOwnerNode({ identityPath: hostIdentity, partyId: 'host-P', libp2pPort: 4101 });
-
-    const ownerWorkdir = join(rootDir, OWNER_CONTAINER_ID);
-    expect(await waitForFile(join(ownerWorkdir, 'identity-arg.txt'))).toBe(hostIdentity);
-    expect(existsSync(join(ownerWorkdir, 'identity.key'))).toBe(false);
-  });
-});
+/**
+ * HostProcessOrchestrator per-node identity tests.
+ *
+ * A hosted node must keep the peer id the claim named across restarts,
+ * and needs a durable on-disk home for its node-local stores (`cadre-cli start`
+ * opens the file-backed bootstrap-peer / trusted-owner stores only when a
+ * protobuf identity key file is configured). The orchestrator therefore writes
+ * `<workdir>/identity.key` once per container and passes it as
+ * `--identity-file`.
+ *
+ * A fake CLI records the `--identity-file` argument it was launched with, so
+ * the spawn wiring is observable without a real cadre node.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { HostProcessOrchestrator } from '../orchestrator/host-process-orchestrator.js';
+import { loadIdentity } from '../orchestrator/identity-file.js';
+import { removeAllNodes } from './orchestrator-teardown.js';
+
+// Writes the --identity-file argument (as seen on its own command line) next
+// to the startup token, then behaves like a minimal long-lived node.
+const FAKE_CLI = `
+import fs from 'node:fs';
+import path from 'node:path';
+const args = process.argv.slice(2);
+const get = (flag) => { const i = args.indexOf(flag); return i >= 0 ? args[i + 1] : undefined; };
+const tokenPath = get('--startup-token-file');
+const token = process.env.CADRE_STARTUP_TOKEN ?? '';
+if (tokenPath) {
+  const dir = path.dirname(tokenPath);
+  try { fs.writeFileSync(path.join(dir, 'identity-arg.txt'), get('--identity-file') ?? '', 'utf8'); } catch (e) { console.error(e); }
+  if (token) { try { fs.writeFileSync(tokenPath, token, 'utf8'); } catch (e) { console.error(e); } }
+}
+process.on('SIGTERM', () => process.exit(0));
+setInterval(() => {}, 1 << 30);
+`;
+
+let tmpRoot: string;
+let scriptPath: string;
+const orchestrators: HostProcessOrchestrator[] = [];
+
+beforeEach(() => {
+  tmpRoot = mkdtempSync(join(tmpdir(), 'cadre-host-nodeid-'));
+  scriptPath = join(tmpRoot, 'fake-cli.mjs');
+  writeFileSync(scriptPath, FAKE_CLI, 'utf8');
+});
+
+afterEach(async () => {
+  try {
+    await removeAllNodes(orchestrators);
+  } finally {
+    await sleep(50);
+    try { rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* ignore */ }
+  }
+});
+
+function makeOrchestrator(
+  rootDir: string,
+  portRange: { start: number; end: number } = { start: 17500, end: 17999 },
+): HostProcessOrchestrator {
+  mkdirSync(rootDir, { recursive: true });
+  const orch = new HostProcessOrchestrator({
+    rootDir,
+    portRange,
+    stopTimeoutMs: 1500,
+    spawn: { entrypoint: scriptPath },
+  });
+  orchestrators.push(orch);
+  return orch;
+}
+
+async function waitForFile(path: string, timeoutMs = 5000): Promise<string> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (existsSync(path)) return readFileSync(path, 'utf8');
+    await sleep(50);
+  }
+  throw new Error(`file never appeared: ${path}`);
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((res) => setTimeout(res, ms));
+}
+
+describe('HostProcessOrchestrator node identity', () => {
+  it('passes --identity-file pointing at a real key inside the node workdir', async () => {
+    const rootDir = join(tmpRoot, 'a');
+    const orch = makeOrchestrator(rootDir);
+    await orch.init();
+
+    await orch.createContainer({
+      containerId: 'hosted-1',
+      partyId: 'party-P',
+      profile: 'storage',
+    });
+
+    const workdir = join(rootDir, 'hosted-1');
+    const arg = await waitForFile(join(workdir, 'identity-arg.txt'));
+    expect(arg).toBe(join(workdir, 'identity.key'));
+    // Decodes as a libp2p protobuf private key → the child gets a usable identity.
+    expect(loadIdentity(arg).peerId).toMatch(/^12D3Koo/);
+  });
+
+  it('reuses the same identity when the same containerId is spawned again', async () => {
+    const rootDir = join(tmpRoot, 'b');
+    const orch = makeOrchestrator(rootDir);
+    await orch.init();
+
+    const first = await orch.createContainer({
+      containerId: 'hosted-2',
+      partyId: 'party-P',
+      profile: 'storage',
+    });
+    const workdir = join(rootDir, 'hosted-2');
+    await waitForFile(join(workdir, 'identity-arg.txt'));
+    const before = loadIdentity(join(workdir, 'identity.key')).peerId;
+
+    // Stop (not remove — removal deletes the workdir) and re-spawn, as a restart
+    // of a live hosted node would.
+    await orch.stopContainer(first.dockerId);
+    await orch.createContainer({
+      containerId: 'hosted-2',
+      partyId: 'party-P',
+      profile: 'storage',
+    });
+
+    const after = loadIdentity(join(workdir, 'identity.key')).peerId;
+    expect(after).toBe(before);
+  });
+
+  it('destroys the identity with the workdir when the node is removed', async () => {
+    const rootDir = join(tmpRoot, 'c');
+    const orch = makeOrchestrator(rootDir);
+    await orch.init();
+
+    const created = await orch.createContainer({
+      containerId: 'hosted-3',
+      partyId: 'party-P',
+      profile: 'storage',
+    });
+    const identityPath = join(rootDir, 'hosted-3', 'identity.key');
+    await waitForFile(identityPath);
+
+    await orch.removeContainer(created.dockerId);
+    expect(existsSync(identityPath)).toBe(false);
+    expect(existsSync(join(rootDir, 'hosted-3'))).toBe(false);
+  });
+
+  // The failure the identity step can actually produce is a damaged key file,
+  // and `HostedNodeService.join` turns every such throw into an `error`
+  // record and lets the admin retry. If the spawn path reserved its ports
+  // before the step that throws, each retry would burn four more ports out of a
+  // bounded range until provisioning stopped working altogether.
+  it('reserves no ports when the identity step fails', async () => {
+    const rootDir = join(tmpRoot, 'd');
+    // Exactly one node's worth of ports (health, metrics, p2p, ws).
+    const orch = makeOrchestrator(rootDir, { start: 18100, end: 18103 });
+    await orch.init();
+
+    mkdirSync(join(rootDir, 'hosted-bad'), { recursive: true });
+    writeFileSync(join(rootDir, 'hosted-bad', 'identity.key'), 'not a protobuf private key', 'utf8');
+
+    const request = {
+      partyId: 'party-P',
+      profile: 'storage' as const,
+    };
+    await expect(orch.createContainer({ ...request, containerId: 'hosted-bad' })).rejects.toThrow();
+
+    // The whole range is still free, so a healthy container still gets its four.
+    const ok = await orch.createContainer({ ...request, containerId: 'hosted-good' });
+    expect(ok.p2pPort).toBeGreaterThanOrEqual(18100);
+  });
+});