@openparachute/hub 0.6.5-rc.2 → 0.6.5-rc.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.6.5-rc.2",
+  "version": "0.6.5-rc.3",
   "description": "parachute — the local hub for the Parachute ecosystem (discovery, ports, lifecycle, soon OAuth).",
   "license": "AGPL-3.0",
   "publishConfig": {

package/src/__tests__/api-modules-ops.test.ts

@@ -936,6 +936,42 @@ describe("POST /api/modules/:short/start", () => {
     expect(spawns[0]?.env?.MY_CUSTOM_VAR).toBe("sentinel123");
   });
 
+  test("#519 surface orphan: start surfaces the structured port_squatter error (not a bare failure)", async () => {
+    // The #519 field signature: after a hub restart, a module (surface on the
+    // box; vault here) is orphaned — listening on its port but NOT a supervised
+    // child. The restart-surface API path (`parachute restart <svc>` → 404
+    // fallthrough → start, and the boot reconcile) calls `supervisor.start()`,
+    // whose #581 squatter detection must surface the structured `port_squatter`
+    // error in the response body so the operator gets an actionable next step,
+    // not an opaque "request failed". This pins that propagation.
+    seedVault(1940);
+    // A real Supervisor with the squatter seams injected: pid 95870 (the #519
+    // orphan) holds :1940 and is NOT one of the supervisor's children.
+    const supervisor = new Supervisor({
+      spawnFn: () => {
+        throw new Error("should not spawn — the port is squatted");
+      },
+      pidOnPort: (port) => (port === 1940 ? 95870 : undefined),
+      ownerOfPid: (pid) => (pid === 95870 ? "bun /x/.parachute/surface/server.ts" : undefined),
+    });
+    const bearer = await mintBearer(h, [API_MODULES_OPS_REQUIRED_SCOPE]);
+    const res = await handleStart(
+      postReq("/api/modules/vault/start", { authorization: `Bearer ${bearer}` }),
+      "vault",
+      { db: h.db, issuer: ISSUER, manifestPath: h.manifestPath, configDir: h.dir, supervisor },
+    );
+    // 200 with the structured error riding in state.startError — the SPA/CLI
+    // render the actionable squatter message instead of a 500 "request failed".
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      short: string;
+      state: { status: string; startError?: { error_type: string; error_description: string } };
+    };
+    expect(body.state.status).toBe("crashed");
+    expect(body.state.startError?.error_type).toBe("port_squatter");
+    expect(body.state.startError?.error_description).toContain("port 1940 is held by pid 95870");
+  });
+
   test("400 not_installed when the module isn't in services.json (no silent install)", async () => {
     // No seedVault — services.json has no vault row.
     const { supervisor, spawns } = makeIdleSupervisor();

package/src/__tests__/orphan-attribution.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, test } from "bun:test";
+import { orphanAttributable } from "../orphan-attribution.ts";
+
+describe("orphanAttributable — two attribution modes (#601 review)", () => {
+  const ownerOfPid = (cmdlines: Record<number, string | undefined>) => (pid: number) =>
+    cmdlines[pid];
+
+  test("recorded-pid match → attributable in BOTH modes (cmdline not even read)", () => {
+    // No cmdline available, but the orphan IS the recorded pid → trivially ours.
+    const probe = ownerOfPid({});
+    const broad = orphanAttributable({
+      orphan: 100,
+      recordedPid: 100,
+      short: "vault",
+      startCmdHint: undefined,
+      ownerOfPid: probe,
+    });
+    const perModule = orphanAttributable({
+      orphan: 100,
+      recordedPid: 100,
+      short: "vault",
+      startCmdHint: undefined,
+      ownerOfPid: probe,
+      moduleMarker: "parachute-vault",
+    });
+    expect(broad.attributable).toBe(true);
+    expect(perModule.attributable).toBe(true);
+  });
+
+  test("broad mode (no moduleMarker): any `parachute` cmdline is attributable", () => {
+    const res = orphanAttributable({
+      orphan: 200,
+      recordedPid: undefined,
+      short: "vault",
+      startCmdHint: undefined,
+      ownerOfPid: ownerOfPid({ 200: "parachute-scribe serve" }),
+    });
+    // Migrate-sweep width: a sibling parachute process still counts.
+    expect(res.attributable).toBe(true);
+    expect(res.cmdline).toBe("parachute-scribe serve");
+  });
+
+  test("per-module mode: own marker matches → attributable", () => {
+    const res = orphanAttributable({
+      orphan: 300,
+      recordedPid: undefined,
+      short: "vault",
+      startCmdHint: undefined,
+      ownerOfPid: ownerOfPid({ 300: "parachute-vault serve" }),
+      moduleMarker: "parachute-vault",
+    });
+    expect(res.attributable).toBe(true);
+  });
+
+  test("per-module mode: a SIBLING parachute module is NOT attributable (cross-module-kill guard)", () => {
+    const res = orphanAttributable({
+      orphan: 400,
+      recordedPid: undefined,
+      short: "vault",
+      startCmdHint: undefined,
+      // A real parachute process (carries `parachute`) — but it's SCRIBE, not
+      // vault. The broad mode would attribute it; per-module must not.
+      ownerOfPid: ownerOfPid({ 400: "parachute-scribe serve" }),
+      moduleMarker: "parachute-vault",
+    });
+    expect(res.attributable).toBe(false);
+    // The cmdline is still returned so the caller can surface it in the message.
+    expect(res.cmdline).toBe("parachute-scribe serve");
+  });
+
+  test("either mode: unreadable cmdline + non-matching pid → NOT attributable", () => {
+    for (const moduleMarker of [undefined, "parachute-vault"]) {
+      const res = orphanAttributable({
+        orphan: 500,
+        recordedPid: 999, // different from orphan
+        short: "vault",
+        startCmdHint: undefined,
+        ownerOfPid: ownerOfPid({}), // returns undefined
+        moduleMarker,
+      });
+      expect(res.attributable).toBe(false);
+      expect(res.cmdline).toBeUndefined();
+    }
+  });
+
+  test("startCmdHint is an additional needle in per-module mode", () => {
+    const res = orphanAttributable({
+      orphan: 600,
+      recordedPid: undefined,
+      short: "vault",
+      startCmdHint: "my-custom-server.ts",
+      // cmdline lacks the module binary but carries the explicit hint.
+      ownerOfPid: ownerOfPid({ 600: "node /opt/my-custom-server.ts" }),
+      moduleMarker: "parachute-vault",
+    });
+    expect(res.attributable).toBe(true);
+  });
+});

package/src/__tests__/supervisor.test.ts

@@ -478,6 +478,369 @@ describe("Supervisor restart-on-crash", () => {
   });
 });
 
+describe("Supervisor crash-restart port reclamation (#522 / #582)", () => {
+  // A killFn that records its (pid, signal) calls so a test can prove an
+  // adopt-kill happened (or didn't). Does NOT forward to a fake — these tests
+  // drive the orphan's "death" by flipping the injected pidOnPort.
+  function recordingKill(): { killFn: KillFn; calls: Array<{ pid: number; signal: unknown }> } {
+    const calls: Array<{ pid: number; signal: unknown }> = [];
+    return { calls, killFn: (pid, signal) => calls.push({ pid, signal }) };
+  }
+
+  test("attributable orphan + kill frees the port → adopt-kill then respawn", async () => {
+    const first = makeFakeProc(900);
+    const second = makeFakeProc(901);
+    const spawner = makeQueueSpawner();
+    spawner.enqueue(first);
+    spawner.enqueue(second);
+    // The orphan (pid 5000) holds :1940 right after the crash; the SIGTERM
+    // adopt-kill frees it — model that by clearing the holder inside the kill
+    // stub (so the SIGKILL-escalation re-probe sees a freed port).
+    const calls: Array<{ pid: number; signal: unknown }> = [];
+    let holder: number | undefined = undefined;
+    const killFn: KillFn = (pid, signal) => {
+      calls.push({ pid, signal });
+      if (pid === 5000 && signal === "SIGTERM") holder = undefined; // the orphan died
+    };
+    const sup = new Supervisor({
+      spawnFn: spawner.spawn,
+      killFn,
+      restartDelayMs: 0,
+      sleep: () => Promise.resolve(),
+      pidOnPort: (port) => (port === 1940 ? holder : undefined),
+      // Attributable PER-MODULE: the cmdline carries THIS module's start binary
+      // (`parachute-vault`), not just a bare `parachute` marker.
+      ownerOfPid: (pid) => (pid === 5000 ? "parachute-vault serve" : undefined),
+    });
+
+    await sup.start({ short: "vault", cmd: ["parachute-vault", "serve"], env: { PORT: "1940" } });
+    // Orphan grabs the port, then the child crashes. `handleExit` detects the
+    // attributable orphan + adopt-kills it (the stub clears `holder`), then
+    // falls through to a normal restart that re-spawns onto the freed port.
+    holder = 5000;
+    first.closeStreams();
+    first.resolveExit(1);
+    await tick();
+
+    // The orphan got SIGTERM'd, and the module respawned onto the freed port.
+    expect(calls.some((c) => c.pid === 5000 && c.signal === "SIGTERM")).toBe(true);
+    expect(spawner.calls).toHaveLength(2);
+    const state = sup.get("vault");
+    expect(state?.status).toBe("running");
+    expect(state?.pid).toBe(901);
+    // It WAS counted as a normal restart (the module did crash + we reclaimed).
+    expect(state?.restartsInWindow).toBe(1);
+
+    second.closeStreams();
+    sup.stop("vault");
+    second.resolveExit(0);
+  });
+
+  test("attributable orphan + kill fails (ESRCH) → respawn still attempted", async () => {
+    const first = makeFakeProc(910);
+    const second = makeFakeProc(911);
+    const spawner = makeQueueSpawner();
+    spawner.enqueue(first);
+    spawner.enqueue(second);
+    // killFn throws ESRCH (the orphan vanished between probe + signal) — the
+    // adopt-kill swallows it and the respawn proceeds best-effort.
+    const killFn: KillFn = () => {
+      const err = new Error("no such process") as NodeJS.ErrnoException;
+      err.code = "ESRCH";
+      throw err;
+    };
+    // Port free at the initial start; the orphan appears only after the crash.
+    let holder: number | undefined = undefined;
+    const sup = new Supervisor({
+      spawnFn: spawner.spawn,
+      killFn,
+      restartDelayMs: 0,
+      sleep: () => Promise.resolve(),
+      // Holder present at crash time; the (failed) kill doesn't change it here,
+      // but the respawn is still attempted — that's the invariant under test.
+      pidOnPort: (port) => (port === 1940 ? holder : undefined),
+      // Attributable per-module: cmdline carries this module's start binary.
+      ownerOfPid: () => "parachute-vault serve",
+    });
+
+    await sup.start({ short: "vault", cmd: ["parachute-vault", "serve"], env: { PORT: "1940" } });
+    holder = 5001;
+    first.closeStreams();
+    first.resolveExit(1);
+    await tick();
+
+    // Respawn was attempted despite the kill throwing ESRCH (best-effort).
+    expect(spawner.calls).toHaveLength(2);
+    const state = sup.get("vault");
+    expect(state?.status).toBe("running");
+
+    second.closeStreams();
+    sup.stop("vault");
+    second.resolveExit(0);
+  });
+
+  test("foreign holder with readable cmdline → port_squatter error, no kill, no budget tick", async () => {
+    const first = makeFakeProc(920);
+    const spawner = makeQueueSpawner();
+    spawner.enqueue(first); // ONLY one proc — a respawn would throw "unexpected spawn".
+    const kill = recordingKill();
+    let holder: number | undefined = undefined; // free at start; orphan after crash.
+    const sup = new Supervisor({
+      spawnFn: spawner.spawn,
+      killFn: kill.killFn,
+      restartDelayMs: 0,
+      sleep: () => Promise.resolve(),
+      pidOnPort: (port) => (port === 1940 ? holder : undefined),
+      // NOT attributable: an operator's unrelated dev server (no `parachute-vault`
+      // marker in its cmdline).
+      ownerOfPid: (pid) => (pid === 6000 ? "node /home/op/my-app/server.js" : undefined),
+    });
+
+    await sup.start({ short: "vault", cmd: ["parachute-vault", "serve"], env: { PORT: "1940" } });
+    holder = 6000;
+    first.closeStreams();
+    first.resolveExit(1);
+    await tick();
+
+    const state = sup.get("vault");
+    expect(state?.status).toBe("crashed");
+    expect(state?.startError?.error_type).toBe("port_squatter");
+    expect(state?.startError?.error_description).toContain("port 1940 is held by pid 6000");
+    // No kill (foreign process), no respawn, and the crash budget was NOT
+    // ticked (the module didn't crash — a foreign process is blocking its port).
+    expect(kill.calls).toHaveLength(0);
+    expect(spawner.calls).toHaveLength(1);
+    expect(state?.restartsInWindow).toBe(0);
+  });
+
+  test("foreign holder with UNREADABLE cmdline → port_squatter error, no kill, no budget tick", async () => {
+    const first = makeFakeProc(930);
+    const spawner = makeQueueSpawner();
+    spawner.enqueue(first); // only one — no respawn expected.
+    const kill = recordingKill();
+    let holder: number | undefined = undefined; // free at start; orphan after crash.
+    const sup = new Supervisor({
+      spawnFn: spawner.spawn,
+      killFn: kill.killFn,
+      restartDelayMs: 0,
+      sleep: () => Promise.resolve(),
+      pidOnPort: (port) => (port === 1940 ? holder : undefined),
+      // Unreadable cmdline + a non-matching pid → NOT attributable (never kill).
+      ownerOfPid: () => undefined,
+    });
+
+    await sup.start({ short: "vault", cmd: ["parachute-vault", "serve"], env: { PORT: "1940" } });
+    holder = 7000;
+    first.closeStreams();
+    first.resolveExit(1);
+    await tick();
+
+    const state = sup.get("vault");
+    expect(state?.status).toBe("crashed");
+    expect(state?.startError?.error_type).toBe("port_squatter");
+    expect(kill.calls).toHaveLength(0);
+    expect(spawner.calls).toHaveLength(1);
+    expect(state?.restartsInWindow).toBe(0);
+  });
+
+  test("no squatter after a crash → normal restart (unchanged behavior)", async () => {
+    const first = makeFakeProc(940);
+    const second = makeFakeProc(941);
+    const spawner = makeQueueSpawner();
+    spawner.enqueue(first);
+    spawner.enqueue(second);
+    const kill = recordingKill();
+    const sup = new Supervisor({
+      spawnFn: spawner.spawn,
+      killFn: kill.killFn,
+      restartDelayMs: 0,
+      sleep: () => Promise.resolve(),
+      // Port free at crash time (no squatter).
+      pidOnPort: () => undefined,
+      ownerOfPid: () => undefined,
+    });
+
+    await sup.start({ short: "vault", cmd: ["bun", "vault.ts"], env: { PORT: "1940" } });
+    first.closeStreams();
+    first.resolveExit(1);
+    await tick();
+
+    expect(kill.calls).toHaveLength(0);
+    expect(spawner.calls).toHaveLength(2);
+    const state = sup.get("vault");
+    expect(state?.status).toBe("running");
+    expect(state?.restartsInWindow).toBe(1);
+
+    second.closeStreams();
+    sup.stop("vault");
+    second.resolveExit(0);
+  });
+
+  test('reclaimPolicy "prompt" → never adopt-kills, surfaces even an attributable orphan', async () => {
+    const first = makeFakeProc(950);
+    const spawner = makeQueueSpawner();
+    spawner.enqueue(first); // only one — prompt halts, no respawn.
+    const kill = recordingKill();
+    let holder: number | undefined = undefined; // free at start; orphan after crash.
+    const sup = new Supervisor({
+      spawnFn: spawner.spawn,
+      killFn: kill.killFn,
+      restartDelayMs: 0,
+      sleep: () => Promise.resolve(),
+      reclaimPolicy: "prompt",
+      pidOnPort: (port) => (port === 1940 ? holder : undefined),
+      // Attributable per-module (parachute-vault marker) — but "prompt" still refuses to kill.
+      ownerOfPid: () => "parachute-vault serve",
+    });
+
+    await sup.start({ short: "vault", cmd: ["parachute-vault", "serve"], env: { PORT: "1940" } });
+    holder = 8000;
+    first.closeStreams();
+    first.resolveExit(1);
+    await tick();
+
+    const state = sup.get("vault");
+    expect(state?.status).toBe("crashed");
+    expect(state?.startError?.error_type).toBe("port_squatter");
+    expect(kill.calls).toHaveLength(0); // prompt never kills
+    expect(spawner.calls).toHaveLength(1);
+    expect(state?.restartsInWindow).toBe(0);
+  });
+
+  test("foreign SIBLING parachute module on the port → NOT adopt-killed, port_squatter error (per-module attribution, #601 review)", async () => {
+    // The cross-module-kill hazard the per-module attribution closes: vault's
+    // crash-restart finds its port held by a SCRIBE orphan (a genuine parachute
+    // process — its cmdline carries `parachute` AND scribe's own binary — but
+    // NOT vault's). The broad `parachute` marker would have adopt-KILLED scribe;
+    // the per-module marker (`parachute-vault`) does not match scribe's cmdline,
+    // so scribe is "not attributable" → surfaced, never killed.
+    const first = makeFakeProc(960);
+    const spawner = makeQueueSpawner();
+    spawner.enqueue(first); // only one — a kill+respawn would consume a second.
+    const kill = recordingKill();
+    let holder: number | undefined = undefined; // free at start; sibling after crash.
+    const sup = new Supervisor({
+      spawnFn: spawner.spawn,
+      killFn: kill.killFn,
+      restartDelayMs: 0,
+      sleep: () => Promise.resolve(),
+      pidOnPort: (port) => (port === 1940 ? holder : undefined),
+      // A real parachute process — but it's SCRIBE, not vault. Carries the broad
+      // `parachute` marker (and `parachute-scribe`) yet NOT `parachute-vault`.
+      ownerOfPid: (pid) => (pid === 9000 ? "parachute-scribe serve" : undefined),
+    });
+
+    await sup.start({ short: "vault", cmd: ["parachute-vault", "serve"], env: { PORT: "1940" } });
+    holder = 9000;
+    first.closeStreams();
+    first.resolveExit(1);
+    await tick();
+
+    const state = sup.get("vault");
+    // The sibling was NOT killed (per-module marker mismatch), surfaced instead.
+    expect(kill.calls).toHaveLength(0);
+    expect(spawner.calls).toHaveLength(1); // no respawn — halted, no port reclaim
+    expect(state?.status).toBe("crashed");
+    expect(state?.startError?.error_type).toBe("port_squatter");
+    expect(state?.startError?.error_description).toContain("port 1940 is held by pid 9000");
+    // Sanity: the sibling WOULD have matched the broad `parachute` marker —
+    // proving the per-module marker is what spared it.
+    expect("parachute-scribe serve").toContain("parachute");
+  });
+
+  test("generic-runtime startCmd (bun server.ts): a FOREIGN bun on the port is NOT over-attributed (#601 re-review)", async () => {
+    // A custom operator startCmd whose cmd[0] is a generic runtime (`bun`). The
+    // marker must NOT be "bun" (that would adopt-KILL any bun process on the
+    // port) — it falls through to the module-specific cwd (the installDir). A
+    // foreign bun process with a DIFFERENT cwd in its cmdline is then NOT
+    // attributable → surfaced, never killed.
+    const first = makeFakeProc(970);
+    const spawner = makeQueueSpawner();
+    spawner.enqueue(first); // only one — no kill+respawn expected.
+    const kill = recordingKill();
+    let holder: number | undefined = undefined;
+    const sup = new Supervisor({
+      spawnFn: spawner.spawn,
+      killFn: kill.killFn,
+      restartDelayMs: 0,
+      sleep: () => Promise.resolve(),
+      pidOnPort: (port) => (port === 1940 ? holder : undefined),
+      // A foreign bun process — its cmdline carries `bun` (which WOULD match a
+      // naive cmd[0] marker) but NOT vault's installDir.
+      ownerOfPid: (pid) => (pid === 9100 ? "bun /home/op/other-project/server.ts" : undefined),
+    });
+
+    await sup.start({
+      short: "vault",
+      cmd: ["bun", "server.ts"],
+      cwd: "/x/.parachute/vault",
+      env: { PORT: "1940" },
+    });
+    holder = 9100;
+    first.closeStreams();
+    first.resolveExit(1);
+    await tick();
+
+    const state = sup.get("vault");
+    // Not over-attributed: no kill, no respawn — surfaced as a squatter.
+    expect(kill.calls).toHaveLength(0);
+    expect(spawner.calls).toHaveLength(1);
+    expect(state?.status).toBe("crashed");
+    expect(state?.startError?.error_type).toBe("port_squatter");
+    // Sanity: the foreign cmdline WOULD have matched a naive "bun" marker —
+    // proving the generic-runtime fall-through to the cwd marker is what spared it.
+    expect("bun /home/op/other-project/server.ts").toContain("bun");
+  });
+
+  test("generic-runtime startCmd: a GENUINE prior instance (same installDir cwd) IS adopted (positive control)", async () => {
+    // The other side of the fall-through: with cmd[0]=`bun`, the marker is the
+    // module's cwd (`/x/.parachute/vault`). A genuine prior vault instance was
+    // launched from that installDir, so its cmdline carries the path → it IS
+    // attributable and gets adopt-killed.
+    const first = makeFakeProc(980);
+    const second = makeFakeProc(981);
+    const spawner = makeQueueSpawner();
+    spawner.enqueue(first);
+    spawner.enqueue(second);
+    const calls: Array<{ pid: number; signal: unknown }> = [];
+    let holder: number | undefined = undefined;
+    const killFn: KillFn = (pid, signal) => {
+      calls.push({ pid, signal });
+      if (pid === 9200 && signal === "SIGTERM") holder = undefined; // orphan died
+    };
+    const sup = new Supervisor({
+      spawnFn: spawner.spawn,
+      killFn,
+      restartDelayMs: 0,
+      sleep: () => Promise.resolve(),
+      pidOnPort: (port) => (port === 1940 ? holder : undefined),
+      // Genuine prior vault instance — launched from vault's installDir, so the
+      // cwd marker appears in its cmdline.
+      ownerOfPid: (pid) => (pid === 9200 ? "bun /x/.parachute/vault/server.ts" : undefined),
+    });
+
+    await sup.start({
+      short: "vault",
+      cmd: ["bun", "server.ts"],
+      cwd: "/x/.parachute/vault",
+      env: { PORT: "1940" },
+    });
+    holder = 9200;
+    first.closeStreams();
+    first.resolveExit(1);
+    await tick();
+
+    // Adopted: SIGTERM'd the genuine prior instance, then respawned.
+    expect(calls.some((c) => c.pid === 9200 && c.signal === "SIGTERM")).toBe(true);
+    expect(spawner.calls).toHaveLength(2);
+    expect(sup.get("vault")?.status).toBe("running");
+
+    second.closeStreams();
+    sup.stop("vault");
+    second.resolveExit(0);
+  });
+});
+
 describe("Supervisor.stop", () => {
   test("operator stop is not a crash — does not restart", async () => {
     const proc = makeFakeProc(101);

package/src/commands/migrate-cutover.ts

@@ -82,6 +82,7 @@ import {
   installManagedUnit,
   removeManagedUnit,
 } from "../managed-unit.ts";
+import { type OwnerProbeFn, orphanAttributable } from "../orphan-attribution.ts";
 import { type PortListeningFn, defaultPortListening } from "../port-probe.ts";
 import { type AliveFn, clearPid, readPid } from "../process-state.ts";
 import { shortNameForManifest } from "../service-spec.ts";
@@ -103,12 +104,12 @@ export function defaultHubCliPath(): string {
   return fileURLToPath(new URL("../cli.ts", import.meta.url));
 }
 
-/**
- * Best-effort command-line probe for a pid (the orphan-sweep ownership check).
- * Returns the process's command line, or undefined when it can't be read. See
- * `CutoverDeps.ownerOfPid`.
- */
-export type OwnerProbeFn = (pid: number) => string | undefined;
+// `OwnerProbeFn` + the attribution heuristic (`orphanAttributable`) now live in
+// the shared `src/orphan-attribution.ts` so the migrate orphan-sweep and the
+// supervisor's crash-restart adopt-kill share ONE implementation (no drift on
+// the safety-critical "is this mine?" check). Re-exported here for the existing
+// `migrate-cutover` import surface.
+export type { OwnerProbeFn } from "../orphan-attribution.ts";
 
 /**
  * Production `ownerOfPid`: `ps -o command= -p <pid>` returns the full argv of the
@@ -454,49 +455,10 @@ async function stopDetachedModule(
   log(`  ✓ stopped ${target.short}`);
 }
 
-/**
- * Decide whether an orphan pid bound to a MODULE port is plausibly attributable
- * to that parachute module — the MUST-FIX-2 guard against blind-killing an
- * operator's unrelated process that merely squats a declared port. Attributable
- * when ANY of:
- *   - the orphan pid equals the module's RECORDED pid (services.json/pidfile);
- *   - its command line mentions `parachute` (any parachute-managed process —
- *     the `~/.parachute/...` install path and the `@openparachute/<mod>`
- *     package name both carry this marker, so it catches every genuine
- *     parachute-managed module);
- *   - its command line mentions the module's start command (when a hint is
- *     supplied — currently always unset at the call site, the seam is kept
- *     for a future services.json-derived start command).
- * An unreadable command line (probe returned undefined) + a non-matching pid is
- * NOT attributable — we refuse to kill it.
- *
- * NOTE: the bare module short-name needle (`vault`/`runner`/`scribe`/`notes`)
- * was deliberately dropped — on the most destructive command (a process KILL),
- * a bare short-name is too loose: a `runner` substring matches an unrelated CI
- * runner squatting the port. The `parachute` marker already attributes every
- * genuine parachute-managed process, so the short-name arm only widened the
- * false-positive surface.
- */
-function orphanAttributable(args: {
-  orphan: number;
-  recordedPid: number | undefined;
-  short: string;
-  startCmdHint: string | undefined;
-  ownerOfPid: OwnerProbeFn;
-}): { attributable: boolean; cmdline: string | undefined } {
-  const { orphan, recordedPid, startCmdHint, ownerOfPid } = args;
-  if (recordedPid !== undefined && orphan === recordedPid) {
-    return { attributable: true, cmdline: undefined };
-  }
-  const cmdline = ownerOfPid(orphan);
-  if (cmdline === undefined) return { attributable: false, cmdline: undefined };
-  const haystack = cmdline.toLowerCase();
-  const needles = ["parachute", ...(startCmdHint ? [startCmdHint.toLowerCase()] : [])].filter(
-    (n) => n.length > 0,
-  );
-  const attributable = needles.some((n) => haystack.includes(n));
-  return { attributable, cmdline };
-}
+// `orphanAttributable` — the safety-critical "is this orphan plausibly this
+// module?" heuristic — now lives in the shared `src/orphan-attribution.ts`
+// (imported above), so the supervisor's crash-restart adopt-kill uses the same
+// implementation. See that file for the full attribution contract.
 
 /**
  * §7.2 orphan sweep: lsof a port, and if a live process is bound to it, adopt +

package/src/orphan-attribution.ts

@@ -0,0 +1,102 @@
+/**
+ * Shared port-orphan ATTRIBUTION — the safety crux behind every adopt-kill in
+ * the hub.
+ *
+ * Two lifecycle sites reclaim a module's port from a process the supervisor
+ * doesn't directly own:
+ *   - the `parachute migrate --to-supervised` orphan sweep
+ *     (`commands/migrate-cutover.ts:sweepOrphanOnPort`), and
+ *   - the supervisor's crash-restart path
+ *     (`supervisor.ts:handleExit` → `adoptKillOrphanOnPort`).
+ *
+ * Both must answer the SAME question before sending a signal: is the process
+ * holding the module's port plausibly THIS parachute module (a leftover
+ * instance / orphan we may adopt-kill), or an UNRELATED process the operator is
+ * running on the same port (which we must never touch)? Sharing one
+ * implementation keeps the two sites from drifting — a loosened needle in one
+ * place can't widen the kill surface in the other without the other noticing.
+ *
+ * The function is intentionally CONSERVATIVE: when in any doubt (unreadable
+ * command line + a non-matching pid) it returns `attributable: false`, and the
+ * caller refuses to kill. False-negatives cost a surfaced `port_squatter`
+ * error (the operator resolves it); a false-positive costs killing someone
+ * else's process — a far worse failure, so we bias hard toward not-attributable.
+ */
+
+/**
+ * Best-effort command line of a pid. Returns the process's argv (one line) or
+ * undefined when it can't be read (pid gone, permission, no `ps`). Both
+ * supervisor + migrate wire a `ps -o command= -p <pid>` shell-out; the seam is
+ * injectable so tests drive attribution without shelling out.
+ */
+export type OwnerProbeFn = (pid: number) => string | undefined;
+
+/**
+ * Decide whether an orphan pid bound to a MODULE port is plausibly attributable
+ * to that parachute module — the guard against blind-killing an operator's
+ * unrelated process that merely squats a declared port. Attributable when ANY
+ * of:
+ *   - the orphan pid equals the module's RECORDED pid (services.json/pidfile,
+ *     or a supervisor entry's recorded pid);
+ *   - (the cmdline arm) it matches the configured needle set — see `moduleMarker`.
+ *
+ * An unreadable command line (probe returned undefined) + a non-matching pid is
+ * NOT attributable — we refuse to kill it.
+ *
+ * TWO ATTRIBUTION MODES (the `moduleMarker` knob):
+ *
+ *   - **Broad ("parachute") — the migrate orphan-sweep.** `moduleMarker`
+ *     OMITTED: the cmdline needle is the bare `parachute` marker (the
+ *     `~/.parachute/...` install path + the `@openparachute/<mod>` package name
+ *     both carry it). The sweep runs ecosystem-wide during a cutover, so
+ *     "is it ANY parachute-managed process?" is the right, field-tested width.
+ *
+ *   - **Per-module — the supervisor's crash-restart adopt-kill.** `moduleMarker`
+ *     PROVIDED (the module's own start binary / installDir, e.g.
+ *     `parachute-vault` or `~/.parachute/vault/`): the cmdline must contain THAT
+ *     marker. The supervisor is always restarting ONE specific module and knows
+ *     its identity, so a bare `parachute` match is too loose — it would let
+ *     vault's restart adopt-KILL a sibling `scribe`/`runner` orphan that happens
+ *     to hold vault's port (a cross-module kill). Requiring the module-specific
+ *     marker means the supervisor can only ever reclaim a prior instance of the
+ *     SAME module; a sibling's process is "not attributable" → surfaced, never
+ *     killed.
+ *
+ * The bare module short-NAME (`vault`/`scribe`/…) is deliberately NOT a needle
+ * in either mode — on a process KILL a bare short-name is too loose (a `runner`
+ * substring matches an unrelated CI runner). The per-module marker is the
+ * fully-qualified binary/path, not the short name.
+ *
+ * `startCmdHint` is an additional optional cmdline needle (currently unset at
+ * both call sites; a seam for a future services.json-derived start command).
+ */
+export function orphanAttributable(args: {
+  orphan: number;
+  recordedPid: number | undefined;
+  short: string;
+  startCmdHint: string | undefined;
+  ownerOfPid: OwnerProbeFn;
+  /**
+   * When provided, the cmdline arm requires THIS module-specific marker (start
+   * binary / installDir) instead of the broad `parachute` marker — see the
+   * "two attribution modes" note above. Omitted → broad `parachute` (migrate).
+   */
+  moduleMarker?: string;
+}): { attributable: boolean; cmdline: string | undefined } {
+  const { orphan, recordedPid, startCmdHint, ownerOfPid, moduleMarker } = args;
+  if (recordedPid !== undefined && orphan === recordedPid) {
+    return { attributable: true, cmdline: undefined };
+  }
+  const cmdline = ownerOfPid(orphan);
+  if (cmdline === undefined) return { attributable: false, cmdline: undefined };
+  const haystack = cmdline.toLowerCase();
+  // Per-module mode (moduleMarker set) uses the module-specific marker as the
+  // base needle; broad mode (migrate sweep) uses "parachute". `startCmdHint` is
+  // an extra needle in either mode.
+  const baseNeedle = moduleMarker ? moduleMarker.toLowerCase() : "parachute";
+  const needles = [baseNeedle, ...(startCmdHint ? [startCmdHint.toLowerCase()] : [])].filter(
+    (n) => n.length > 0,
+  );
+  const attributable = needles.some((n) => haystack.includes(n));
+  return { attributable, cmdline };
+}

package/src/supervisor.ts

@@ -42,6 +42,7 @@ import {
   rethrowIfMissing,
 } from "@openparachute/depcheck";
 import { defaultPidOnPort } from "./hub-control.ts";
+import { orphanAttributable } from "./orphan-attribution.ts";
 import { type PortListeningFn, defaultPortListening } from "./port-probe.ts";
 
 /**
@@ -285,6 +286,28 @@ export interface SupervisorOpts {
    * stub-spawner test path defaults to "unknown" (returns undefined).
    */
   readonly ownerOfPid?: OwnerProbeFn;
+  /**
+   * Port-reclamation POLICY for the CRASH-RESTART path (#522 / #582). When a
+   * supervised child crashes and a foreign process now holds its declared port,
+   * `handleExit` must decide what to do with an ATTRIBUTABLE orphan (one whose
+   * command line carries the `parachute` marker or matches a recorded module
+   * pid — see `orphan-attribution.ts`):
+   *   - `"adopt"` (default): adopt-kill the attributable orphan (SIGTERM →
+   *     SIGKILL escalation, all idempotent) and proceed to re-spawn. This
+   *     extends the migrate orphan-sweep's field-tested auto-adopt behavior to
+   *     the crash-restart path — closing the recurring "port 1940 taken"
+   *     crash-loop (#522) for good.
+   *   - `"prompt"`: NEVER auto-kill; record the structured `port_squatter`
+   *     start-error (same surface a NON-attributable squatter gets) so the
+   *     operator resolves it manually.
+   *
+   * A NON-attributable holder is ALWAYS surfaced (never killed) regardless of
+   * policy — `"adopt"` only ever escalates to a kill on a holder we can
+   * attribute to this very module. Default `"adopt"`; the flag is the one-line
+   * lever to flip the whole crash-restart behavior to detect-and-prompt if the
+   * auto-kill default is later vetoed.
+   */
+  readonly reclaimPolicy?: "adopt" | "prompt";
 }
 
 /**
@@ -322,6 +345,42 @@ const DEFAULT_START_READY_POLL_MS = 200;
 const DEFAULT_LATE_BIND_WATCH_MS = 60_000;
 const DEFAULT_LATE_BIND_POLL_MS = 1_000;
 
+/**
+ * Generic language runtimes that can front a custom operator startCmd (e.g.
+ * `bun server.ts`, `python3 -m app`). When one of these is `cmd[0]` it is NOT a
+ * module-specific marker — using it as the adopt-kill attribution needle would
+ * match ANY such process on the port (over-broad kill, #601 re-review). The
+ * per-module marker then falls through to the module's installDir/cwd instead.
+ * First-party modules (`parachute-vault`, `parachute-scribe`, …) are unaffected
+ * — their `cmd[0]` isn't in this set. Matched on the BASENAME, lowercased, with
+ * any `.exe` suffix stripped (Windows), so an absolute `/usr/bin/bun` is caught.
+ */
+const GENERIC_RUNTIMES = new Set([
+  "bun",
+  "node",
+  "nodejs",
+  "deno",
+  "python",
+  "python2",
+  "python3",
+  "ruby",
+  "sh",
+  "bash",
+  "zsh",
+  "dash",
+  "env",
+]);
+
+/**
+ * Is `cmd0` a generic language runtime rather than a module-specific binary?
+ * Strips the directory and a trailing `.exe`, lowercases, and checks the
+ * {@link GENERIC_RUNTIMES} set. See `moduleMarkerFor`.
+ */
+function isGenericRuntime(cmd0: string): boolean {
+  const base = (cmd0.split("/").pop() ?? cmd0).toLowerCase().replace(/\.exe$/, "");
+  return GENERIC_RUNTIMES.has(base);
+}
+
 /**
  * Bounded, line-oriented ring buffer (§6.5). Holds the most-recent lines of a
  * module's output up to `maxBytes`; pushing past the cap drops whole lines
@@ -406,6 +465,12 @@ export class Supervisor {
       // opt in by injecting `pidOnPort` / `ownerOfPid`.
       pidOnPort: opts.pidOnPort ?? (isProductionPath ? defaultPidOnPort : () => undefined),
       ownerOfPid: opts.ownerOfPid ?? (isProductionPath ? defaultOwnerOfPid : () => undefined),
+      // Crash-restart port-reclamation policy (#522 / #582). Default "adopt"
+      // everywhere (production + tests) — the migrate precedent already
+      // auto-kills attributable orphans, and the attribution check is
+      // conservative. The flag exists so a future veto of auto-kill is a
+      // one-line "prompt" flip.
+      reclaimPolicy: opts.reclaimPolicy ?? "adopt",
     };
   }
 
@@ -467,13 +532,13 @@ export class Supervisor {
     // spawning — the operator sees the offending pid + cmdline + a copy-paste
     // recovery in `status` / the SPA. Detection only: we never kill someone
     // else's process (it may be the operator's unrelated dev server).
-    const squatter = this.detectPortSquatter(entry);
+    const squatter = this.checkPortSquatter(entry);
     if (squatter) {
       entry.state = {
         ...entry.state,
         status: "crashed",
         pid: undefined,
-        startError: squatter,
+        startError: this.portSquatterError(entry, squatter),
       };
       return entry.state;
     }
@@ -532,9 +597,14 @@ export class Supervisor {
    * replaced) and must not vouch for whoever now holds the port. An entry with
    * no `proc` (never spawned) contributes no pid either.
    */
-  private supervisedPids(): Set<number> {
+  private supervisedPids(exclude?: ModuleEntry): Set<number> {
     const pids = new Set<number>();
     for (const entry of this.modules.values()) {
+      // The just-crashed entry on the `handleExit` path is still `running`
+      // (status hasn't been updated yet) with `entry.proc.pid` pointing at the
+      // now-DEAD child — it must not vouch for whoever holds the port (the same
+      // N1 stale-pid hazard, here for an exiting-but-not-yet-restated child).
+      if (exclude !== undefined && entry === exclude) continue;
       if (entry.state.status !== "running" && entry.state.status !== "starting") continue;
       const pid = entry.proc?.pid;
       if (typeof pid === "number" && pid > 0) pids.add(pid);
@@ -543,28 +613,52 @@ export class Supervisor {
   }
 
   /**
-   * Pre-spawn port-squatter check (#580 item 4). Returns a structured
-   * `port_squatter` start-error when the module's declared port is held by a
+   * Pure pre-spawn port-squatter PROBE (#580 item 4, refactored for #522/#582).
+   * Returns the squatter detail when the module's declared port is held by a
    * process the supervisor does NOT own; undefined when the port is free, the
    * holder is one of our own children, or detection isn't available on this
    * platform (no `lsof` → `pidOnPort` returns undefined → we degrade to the
    * existing started-but-unbound path post-spawn).
    *
+   * This is DETECTION ONLY — it records nothing and kills nothing. The two
+   * callers decide what to do with the result:
+   *   - `start()` (#581) records the structured `port_squatter` start-error and
+   *     refuses to spawn (a foreign pid on a module port may be the operator's
+   *     unrelated process — never auto-killed on the operator-initiated path);
+   *   - `handleExit` (#522/#582) additionally runs attribution and, for an
+   *     ATTRIBUTABLE orphan under the "adopt" policy, adopt-kills + re-spawns.
+   *
    * Ownership precedent mirrors `migrate-cutover.ts:sweepOrphanOnPort`'s "is
    * this mine?" check — here the discriminant is "is the holder one of my live
-   * children's pids?". We deliberately do NOT kill the holder (detection only):
-   * a foreign pid on a module port may be the operator's unrelated process.
+   * children's pids?".
    */
-  private detectPortSquatter(entry: ModuleEntry): ModuleStartError | undefined {
+  private checkPortSquatter(
+    entry: ModuleEntry,
+    excludeCrashingEntry = false,
+  ): { port: number; holder: number; cmdline: string | undefined } | undefined {
     const portStr = entry.req.env?.PORT;
     const port = portStr ? Number(portStr) : Number.NaN;
     if (!Number.isFinite(port) || port <= 0) return undefined; // No declared port.
 
     const holder = this.opts.pidOnPort(port);
     if (holder === undefined) return undefined; // Port free, or detection unavailable.
-    if (this.supervisedPids().has(holder)) return undefined; // Our own child.
+    // On the crash-restart path the crashing entry is still `running` with a
+    // stale (dead) pid — exclude it so it can't vouch for the holder.
+    if (this.supervisedPids(excludeCrashingEntry ? entry : undefined).has(holder)) return undefined;
+
+    return { port, holder, cmdline: this.opts.ownerOfPid(holder) };
+  }
 
-    const cmdline = this.opts.ownerOfPid(holder);
+  /**
+   * Build the structured, actionable `port_squatter` start-error from a probe
+   * result (#581). Shared by `start()` and the NON-attributable / "prompt"
+   * branch of `handleExit` so the wire shape stays identical.
+   */
+  private portSquatterError(
+    entry: ModuleEntry,
+    squatter: { port: number; holder: number; cmdline: string | undefined },
+  ): ModuleStartError {
+    const { port, holder, cmdline } = squatter;
     const who = cmdline ? `pid ${holder} (${cmdline})` : `pid ${holder}`;
     const short = entry.req.short;
     return {
@@ -576,6 +670,163 @@ export class Supervisor {
     };
   }
 
+  /**
+   * Adopt-kill an orphan holding a module's port on the crash-restart path
+   * (#522 / #582). Best-effort + idempotent: SIGTERM the group, brief wait, then
+   * a SIGKILL escalation if it's still bound — every signal is try-caught so an
+   * ESRCH (the orphan already exited between probe + signal) is a no-op, not a
+   * throw. Modeled on `migrate-cutover.ts:sweepOrphanOnPort`'s adopt arm, using
+   * the supervisor's group-aware `killFn`. If the kill doesn't free the port the
+   * subsequent re-spawn just EADDRINUSE-crashes again and the normal restart
+   * budget eventually halts the loop — so a failed kill degrades gracefully.
+   */
+  private async adoptKillOrphanOnPort(port: number, holder: number): Promise<void> {
+    try {
+      this.opts.killFn(holder, "SIGTERM");
+    } catch {
+      // ESRCH (already gone) or EPERM (can't signal) — best-effort: nothing
+      // more to do, the re-spawn surfaces a still-held port as a normal crash.
+      return;
+    }
+    // Give the orphan a moment to drop its listener before escalating. Reuse the
+    // restart delay (also the socket-release grace) so we don't add a new knob.
+    await this.opts.sleep(this.opts.restartDelayMs);
+    // Still holding the port? Escalate to SIGKILL (idempotent — if it already
+    // exited under the SIGTERM the port is free and we skip the escalation).
+    // N1: this re-check is deliberately NOT re-attributed — we already
+    // attributed `holder` to this module before the SIGTERM, and only escalate
+    // if the SAME pid still holds the SAME port. The TOCTOU window (the
+    // originally-attributed pid exits and the OS recycles its number onto a new,
+    // foreign holder of this port between the SIGTERM and this re-probe) is the
+    // same accepted, vanishingly-small risk the migrate sweep's SIGKILL
+    // follow-up carries (`sweepOrphanOnPort`); not worth a second `ps` round-trip.
+    if (this.opts.pidOnPort(port) === holder) {
+      try {
+        this.opts.killFn(holder, "SIGKILL");
+      } catch {
+        // Already gone / can't signal — best-effort; fall through to re-spawn.
+      }
+    }
+  }
+
+  /**
+   * Crash-restart squatter resolution (#522 / #582). Called from `handleExit`
+   * when a foreign process holds the crashed module's port. Returns:
+   *   - `true`  → the loop should HALT: we recorded a structured `port_squatter`
+   *     start-error + set status `crashed` WITHOUT touching the crash budget
+   *     (the module didn't crash — a foreign process is blocking its port, so a
+   *     budget tick would wrongly bring us closer to "giving up"). Applies to a
+   *     NON-attributable holder always, and to an attributable holder under the
+   *     `"prompt"` policy.
+   *   - `false` → we ADOPT-KILLED an attributable orphan (under the default
+   *     `"adopt"` policy); the caller falls through to the normal restart, which
+   *     re-spawns onto the now-freed port (counting as a normal restart).
+   *
+   * Attribution is the safety crux: REUSE the shared `orphanAttributable`
+   * (`orphan-attribution.ts`) — but in its PER-MODULE mode (`moduleMarker` set),
+   * NOT the migrate sweep's broad `parachute` mode. The supervisor is always
+   * restarting ONE specific module and knows its identity, so it requires the
+   * orphan's cmdline to carry THIS module's own start binary / installDir before
+   * killing — a bare `parachute` match would let vault's restart adopt-kill a
+   * sibling `scribe`/`runner` orphan on vault's port (a cross-module kill). So a
+   * sibling module's process (or an operator's unrelated process) is "not
+   * attributable" → surfaced, never killed. Only a genuine prior instance of the
+   * SAME module is reclaimable.
+   */
+  private async handleCrashRestartSquatter(
+    entry: ModuleEntry,
+    squatter: { port: number; holder: number; cmdline: string | undefined },
+    exitCode: number | null,
+  ): Promise<boolean> {
+    const { port, holder } = squatter;
+    const short = entry.req.short;
+
+    const recordSquatterError = (): true => {
+      entry.state = {
+        ...entry.state,
+        status: "crashed",
+        pid: undefined,
+        lastExitCode: exitCode,
+        // NB: restartsInWindow is left as-is — we deliberately do NOT push a
+        // crash stamp for a port-blocked module (it didn't crash).
+        startError: this.portSquatterError(entry, squatter),
+      };
+      return true;
+    };
+
+    // Policy gate: "prompt" never auto-kills — surface every squatter for the
+    // operator (the one-line lever to flip off auto-kill if it's vetoed).
+    if (this.opts.reclaimPolicy === "prompt") {
+      this.opts.output(
+        `[supervisor] ${short} crashed; port ${port} held by pid ${holder} (reclaim policy "prompt") — surfacing instead of adopting.\n`,
+      );
+      return recordSquatterError();
+    }
+
+    // "adopt": adopt-kill only an ATTRIBUTABLE orphan. The recorded pid arm uses
+    // the entry's last-known pid (the just-crashed child's) — if the SAME pid
+    // somehow still holds the port it's trivially ours to reclaim; otherwise the
+    // PER-MODULE cmdline marker (this module's own start binary / installDir)
+    // decides — NOT the broad `parachute` marker, so a sibling module's orphan
+    // on this port is not attributable.
+    const { attributable, cmdline } = orphanAttributable({
+      orphan: holder,
+      recordedPid: entry.proc?.pid,
+      short,
+      startCmdHint: undefined,
+      ownerOfPid: this.opts.ownerOfPid,
+      moduleMarker: this.moduleMarkerFor(entry),
+    });
+    if (!attributable) {
+      const desc = cmdline ?? squatter.cmdline ?? "command line unavailable";
+      this.opts.output(
+        `[supervisor] ${short} crashed; port ${port} held by an unrelated process (pid ${holder}, ${desc}) — refusing to kill it; surfacing.\n`,
+      );
+      return recordSquatterError();
+    }
+
+    // Attributable orphan under "adopt": reclaim the port, then fall through to
+    // the normal restart (return false). Best-effort — if the kill doesn't free
+    // the port, the re-spawn EADDRINUSE-crashes as a normal crash and the budget
+    // eventually halts the loop.
+    this.opts.output(
+      `[supervisor] ${short} crashed; port ${port} held by an attributable orphan (pid ${holder}${cmdline ? `, ${cmdline}` : ""}) — adopting + killing it before restart.\n`,
+    );
+    await this.adoptKillOrphanOnPort(port, holder);
+    return false;
+  }
+
+  /**
+   * The module-specific cmdline marker for the per-module adopt-kill attribution
+   * (#601 review). A genuine prior instance of THIS module was launched with
+   * this module's start binary (`req.cmd[0]`, e.g. `parachute-vault`) and from
+   * its installDir (`req.cwd`, e.g. `~/.parachute/vault/`) — both appear in the
+   * orphan's `ps` cmdline.
+   *
+   * Prefer the start binary (it's the most module-distinctive token) — BUT only
+   * when it's actually module-specific. A custom operator startCmd like
+   * `bun server.ts` has a GENERIC RUNTIME at `cmd[0]` (`bun`/`node`/`python`/…);
+   * using "bun" as the marker would attribute ANY bun process on the port — the
+   * exact over-broad adopt-kill per-module attribution exists to prevent
+   * (#601 re-review). So when `cmd[0]`'s basename is a known generic runtime,
+   * fall through to the cwd / installDir marker, which IS module-specific.
+   *
+   * Returns undefined only when neither a non-generic `cmd[0]` nor a usable cwd
+   * is available — attribution then falls back to the recorded-pid arm only (the
+   * cmdline arm can't match an empty needle → the safe, conservative degradation:
+   * never a false-positive kill).
+   *
+   * Note we pass the FULL `cmd[0]` (e.g. `parachute-vault`, or an absolute
+   * `/path/to/parachute-vault`), not a bare short name — the short name
+   * (`vault`) is deliberately too loose for a kill decision.
+   */
+  private moduleMarkerFor(entry: ModuleEntry): string | undefined {
+    const binary = entry.req.cmd[0];
+    if (binary && binary.length > 0 && !isGenericRuntime(binary)) return binary;
+    if (entry.req.cwd && entry.req.cwd.length > 0) return entry.req.cwd;
+    return undefined;
+  }
+
   /**
    * Poll the module's port until it binds or `startReadyMs` elapses (§6.5).
    * Skipped when the gate is disabled (stub-spawner test path) or the request
@@ -813,6 +1064,26 @@ export class Supervisor {
       return;
     }
 
+    // Crash-restart port reconciliation (#522 / #582). Before counting this
+    // crash and re-spawning, check whether the module's declared port is now
+    // held by a process the supervisor doesn't own. The `start()` squatter
+    // check (#581) only runs on the operator-initiated path; the crash-restart
+    // loop bypassed it, so a foreign process that grabbed the port between the
+    // crash and the auto-restart kept EADDRINUSE-crash-looping into a bare
+    // `crashed` with no clue why (#582), and a leftover-autostart orphan from a
+    // prior instance re-took the port forever (#522). `excludeCrashingEntry`
+    // drops the just-crashed child's stale pid from the "ours" set (N1).
+    const squatter = this.checkPortSquatter(entry, /* excludeCrashingEntry */ true);
+    if (squatter) {
+      const handled = await this.handleCrashRestartSquatter(entry, squatter, exitCode);
+      // `handled` true → we surfaced a structured error and halted the loop
+      // WITHOUT counting this against the crash budget (the module didn't crash
+      // — a foreign process is blocking its port). `false` → we adopt-killed an
+      // attributable orphan and fall through to the normal restart below, which
+      // re-spawns onto the now-freed port (counting as a normal restart).
+      if (handled) return;
+    }
+
     const now = this.opts.now();
     // Drop crashes older than the window before counting.
     const cutoff = now - this.opts.restartWindowMs;