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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.6.5-rc.1",
+  "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__/oauth-handlers.test.ts

@@ -578,6 +578,298 @@ describe("handleAuthorizeGet", () => {
   });
 });
 
+// hub#570 — open-redirect: protocol errors (unsupported_response_type,
+// invalid_request for non-S256 PKCE) MUST NOT redirect to the supplied
+// redirect_uri until the (client_id, redirect_uri) pair is confirmed
+// registered. RFC 6749 §4.1.2.1: an unvalidated redirect_uri error is shown
+// to the user, never redirected. Pre-fix, an attacker with a valid client_id
+// + crafted redirect_uri + bad response_type got an error redirect to the
+// attacker-controlled URI.
+describe("handleAuthorizeGet — error redirects gated on redirect_uri validation (hub#570)", () => {
+  test("invalid response_type + UNREGISTERED redirect_uri → HTML error, no redirect", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const reg = registerClient(db, { redirectUris: ["https://app.example/cb"] });
+      const { challenge } = makePkce();
+      const req = new Request(
+        authorizeUrl({
+          client_id: reg.client.clientId,
+          // Crafted attacker-controlled URI, NOT registered for this client.
+          redirect_uri: "https://evil.example/steal",
+          response_type: "token",
+          code_challenge: challenge,
+          code_challenge_method: "S256",
+          state: "abc",
+        }),
+      );
+      const res = handleAuthorizeGet(db, req, { issuer: ISSUER });
+      // Must be the HTML "Redirect mismatch" error page, NOT a 302 to evil.
+      expect(res.status).toBe(400);
+      expect(res.headers.get("location")).toBeNull();
+      const body = await res.text();
+      expect(body).toContain("Redirect mismatch");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("invalid code_challenge_method + UNREGISTERED redirect_uri → HTML error, no redirect", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const reg = registerClient(db, { redirectUris: ["https://app.example/cb"] });
+      const req = new Request(
+        authorizeUrl({
+          client_id: reg.client.clientId,
+          redirect_uri: "https://evil.example/steal",
+          response_type: "code",
+          code_challenge: "challenge",
+          code_challenge_method: "plain",
+          state: "abc",
+        }),
+      );
+      const res = handleAuthorizeGet(db, req, { issuer: ISSUER });
+      expect(res.status).toBe(400);
+      expect(res.headers.get("location")).toBeNull();
+      const body = await res.text();
+      expect(body).toContain("Redirect mismatch");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("invalid response_type + VALID registered redirect_uri → error redirect (spec-correct)", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const reg = registerClient(db, { redirectUris: ["https://app.example/cb"] });
+      const { challenge } = makePkce();
+      const req = new Request(
+        authorizeUrl({
+          client_id: reg.client.clientId,
+          redirect_uri: "https://app.example/cb",
+          response_type: "token",
+          code_challenge: challenge,
+          code_challenge_method: "S256",
+          state: "abc",
+        }),
+      );
+      const res = handleAuthorizeGet(db, req, { issuer: ISSUER });
+      // Pair is registered → redirecting the protocol error is RFC-correct.
+      expect(res.status).toBe(302);
+      const loc = new URL(res.headers.get("location") ?? "");
+      expect(loc.origin + loc.pathname).toBe("https://app.example/cb");
+      expect(loc.searchParams.get("error")).toBe("unsupported_response_type");
+      expect(loc.searchParams.get("state")).toBe("abc");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("invalid code_challenge_method + VALID registered redirect_uri → error redirect (spec-correct)", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const reg = registerClient(db, { redirectUris: ["https://app.example/cb"] });
+      const req = new Request(
+        authorizeUrl({
+          client_id: reg.client.clientId,
+          redirect_uri: "https://app.example/cb",
+          response_type: "code",
+          code_challenge: "challenge",
+          code_challenge_method: "plain",
+          state: "abc",
+        }),
+      );
+      const res = handleAuthorizeGet(db, req, { issuer: ISSUER });
+      expect(res.status).toBe(302);
+      const loc = new URL(res.headers.get("location") ?? "");
+      expect(loc.origin + loc.pathname).toBe("https://app.example/cb");
+      expect(loc.searchParams.get("error")).toBe("invalid_request");
+      expect(loc.searchParams.get("state")).toBe("abc");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("unknown client_id + invalid response_type → HTML error, no redirect", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const { challenge } = makePkce();
+      const req = new Request(
+        authorizeUrl({
+          client_id: "no-such-client",
+          redirect_uri: "https://evil.example/steal",
+          response_type: "token",
+          code_challenge: challenge,
+          code_challenge_method: "S256",
+        }),
+      );
+      const res = handleAuthorizeGet(db, req, { issuer: ISSUER });
+      expect(res.status).toBe(400);
+      expect(res.headers.get("location")).toBeNull();
+      const body = await res.text();
+      expect(body).toContain("Unknown application");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("valid full flow still reaches consent (regression guard)", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const user = await createUser(db, "owner", "pw");
+      const session = createSession(db, { userId: user.id });
+      const reg = registerClient(db, {
+        redirectUris: ["https://app.example/cb"],
+        clientName: "MyApp",
+      });
+      const { challenge } = makePkce();
+      const req = new Request(
+        authorizeUrl({
+          client_id: reg.client.clientId,
+          redirect_uri: "https://app.example/cb",
+          response_type: "code",
+          code_challenge: challenge,
+          code_challenge_method: "S256",
+          scope: "vault:read",
+        }),
+        {
+          headers: {
+            cookie: `${CSRF_COOKIE}; ${buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000))}`,
+          },
+        },
+      );
+      const res = handleAuthorizeGet(db, req, { issuer: ISSUER });
+      expect(res.status).toBe(200);
+      const html = await res.text();
+      expect(html).toContain("Approve");
+      expect(html).toContain('name="__action" value="consent"');
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("pending client + valid session + bad response_type → NOT promoted to approved, request rejected (#570 reviewer fold)", async () => {
+    // The pending-client auto-approve (`approveClient`) is a DB state
+    // mutation. It must not fire for a request we're about to reject — so
+    // redirect_uri validation (and, transitively, the protocol-error checks)
+    // gate it. A malformed `response_type` on a registered-but-pending
+    // client must leave the client `pending`, not silently promote it.
+    const { db, cleanup } = await makeDb();
+    try {
+      const user = await createUser(db, "owner", "pw");
+      const session = createSession(db, { userId: user.id });
+      const reg = registerClient(db, {
+        redirectUris: ["https://app.example/cb"],
+        clientName: "MyApp",
+        status: "pending",
+      });
+      // Sanity: the client starts pending.
+      expect(getClient(db, reg.client.clientId)?.status).toBe("pending");
+      const { challenge } = makePkce();
+      const req = new Request(
+        authorizeUrl({
+          client_id: reg.client.clientId,
+          // Valid REGISTERED redirect_uri — so the rejection is driven by the
+          // malformed response_type, not the redirect mismatch. This isolates
+          // the "mutation before full validation" class the fold closes.
+          redirect_uri: "https://app.example/cb",
+          response_type: "token",
+          code_challenge: challenge,
+          code_challenge_method: "S256",
+          state: "pend-1",
+        }),
+        {
+          headers: {
+            cookie: `${CSRF_COOKIE}; ${buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000))}`,
+          },
+        },
+      );
+      const res = handleAuthorizeGet(db, req, { issuer: ISSUER });
+      // Registered redirect_uri → the protocol error redirects (spec-correct).
+      expect(res.status).toBe(302);
+      const loc = new URL(res.headers.get("location") ?? "");
+      expect(loc.searchParams.get("error")).toBe("unsupported_response_type");
+      // The crux: the client must STILL be pending — no silent promotion.
+      expect(getClient(db, reg.client.clientId)?.status).toBe("pending");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("pending client + valid session + UNREGISTERED redirect_uri → HTML error, not promoted (#570 reviewer fold)", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const user = await createUser(db, "owner", "pw");
+      const session = createSession(db, { userId: user.id });
+      const reg = registerClient(db, {
+        redirectUris: ["https://app.example/cb"],
+        clientName: "MyApp",
+        status: "pending",
+      });
+      const { challenge } = makePkce();
+      const req = new Request(
+        authorizeUrl({
+          client_id: reg.client.clientId,
+          redirect_uri: "https://evil.example/steal",
+          response_type: "code",
+          code_challenge: challenge,
+          code_challenge_method: "S256",
+        }),
+        {
+          headers: {
+            cookie: `${CSRF_COOKIE}; ${buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000))}`,
+          },
+        },
+      );
+      const res = handleAuthorizeGet(db, req, { issuer: ISSUER });
+      expect(res.status).toBe(400);
+      expect(res.headers.get("location")).toBeNull();
+      expect(await res.text()).toContain("Redirect mismatch");
+      // Still pending — unregistered redirect_uri never promotes the client.
+      expect(getClient(db, reg.client.clientId)?.status).toBe("pending");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("pending client + valid session + valid request → auto-approved → consent (happy path preserved)", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const user = await createUser(db, "owner", "pw");
+      const session = createSession(db, { userId: user.id });
+      const reg = registerClient(db, {
+        redirectUris: ["https://app.example/cb"],
+        clientName: "MyApp",
+        status: "pending",
+      });
+      const { challenge } = makePkce();
+      const req = new Request(
+        authorizeUrl({
+          client_id: reg.client.clientId,
+          redirect_uri: "https://app.example/cb",
+          response_type: "code",
+          code_challenge: challenge,
+          code_challenge_method: "S256",
+          scope: "vault:read",
+        }),
+        {
+          headers: {
+            cookie: `${CSRF_COOKIE}; ${buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000))}`,
+          },
+        },
+      );
+      const res = handleAuthorizeGet(db, req, { issuer: ISSUER });
+      // Valid client + valid uri + pending → auto-approve → consent render.
+      expect(res.status).toBe(200);
+      const html = await res.text();
+      expect(html).toContain('name="__action" value="consent"');
+      // The valid request DID promote the client (auto-approve still works).
+      expect(getClient(db, reg.client.clientId)?.status).toBe("approved");
+    } finally {
+      cleanup();
+    }
+  });
+});
+
 // Q1 of 2026-04-28-vault-config-and-scopes.md: an unnamed `vault:<verb>` is
 // ambiguous, so the consent screen forces the operator to pick a vault before
 // the JWT is minted. Picked vault rewrites the scope to `vault:<picked>:<verb>`
@@ -7957,6 +8249,171 @@ describe("zero-vault non-admin privesc gate (hub#429 reviewer)", () => {
   });
 });
 
+// hub#431 — consent UX: a non-admin with zero assigned vaults requesting a
+// NAMED vault scope (`vault:<name>:read`) renders an enabled Approve button
+// pre-fix, even though the POST is correctly 400'd. (Unnamed `vault:read` was
+// already covered by the empty-picker disable; the gap was named scopes,
+// which carry no picker.) The fix disables Approve + shows explanatory copy.
+describe("handleAuthorizeGet — zero-vault non-admin named vault scope disables Approve (hub#431)", () => {
+  test("non-admin / zero vaults / named vault scope → Approve disabled + copy", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      await createUser(db, "admin-aaron", "pw");
+      const bob = await createUser(db, "bob", "pw", { allowMulti: true });
+      const session = createSession(db, { userId: bob.id });
+      const reg = registerClient(db, {
+        redirectUris: ["https://app.example/cb"],
+        status: "approved",
+      });
+      const { challenge } = makePkce();
+      const req = new Request(
+        authorizeUrl({
+          client_id: reg.client.clientId,
+          redirect_uri: "https://app.example/cb",
+          response_type: "code",
+          // NAMED vault scope — no picker, so pre-fix Approve stayed enabled.
+          scope: "vault:default:read",
+          code_challenge: challenge,
+          code_challenge_method: "S256",
+        }),
+        {
+          headers: {
+            cookie: `${CSRF_COOKIE}; ${buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000))}`,
+          },
+        },
+      );
+      const res = handleAuthorizeGet(db, req, {
+        issuer: ISSUER,
+        loadServicesManifest: fixtureLoadServicesManifest,
+      });
+      expect(res.status).toBe(200);
+      const html = await res.text();
+      expect(html).toContain("You have no assigned vaults");
+      expect(html).toMatch(/<button[^>]*name="approve"[^>]*value="yes"[^>]*disabled/);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("admin / named vault scope → Approve enabled", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const admin = await createUser(db, "admin-aaron", "pw");
+      const session = createSession(db, { userId: admin.id });
+      const reg = registerClient(db, {
+        redirectUris: ["https://app.example/cb"],
+        status: "approved",
+      });
+      const { challenge } = makePkce();
+      const req = new Request(
+        authorizeUrl({
+          client_id: reg.client.clientId,
+          redirect_uri: "https://app.example/cb",
+          response_type: "code",
+          scope: "vault:default:read",
+          code_challenge: challenge,
+          code_challenge_method: "S256",
+        }),
+        {
+          headers: {
+            cookie: `${CSRF_COOKIE}; ${buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000))}`,
+          },
+        },
+      );
+      const res = handleAuthorizeGet(db, req, {
+        issuer: ISSUER,
+        loadServicesManifest: fixtureLoadServicesManifest,
+      });
+      expect(res.status).toBe(200);
+      const html = await res.text();
+      expect(html).not.toContain("You have no assigned vaults");
+      expect(html).not.toMatch(/<button[^>]*name="approve"[^>]*value="yes"[^>]*disabled/);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("non-admin WITH an assigned vault / named vault scope → Approve enabled", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      await createUser(db, "admin-aaron", "pw");
+      const bob = await createUser(db, "bob", "pw", { allowMulti: true });
+      setUserVaults(db, bob.id, ["default"]);
+      const session = createSession(db, { userId: bob.id });
+      const reg = registerClient(db, {
+        redirectUris: ["https://app.example/cb"],
+        status: "approved",
+      });
+      const { challenge } = makePkce();
+      const req = new Request(
+        authorizeUrl({
+          client_id: reg.client.clientId,
+          redirect_uri: "https://app.example/cb",
+          response_type: "code",
+          scope: "vault:default:read",
+          code_challenge: challenge,
+          code_challenge_method: "S256",
+        }),
+        {
+          headers: {
+            cookie: `${CSRF_COOKIE}; ${buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000))}`,
+          },
+        },
+      );
+      const res = handleAuthorizeGet(db, req, {
+        issuer: ISSUER,
+        loadServicesManifest: fixtureLoadServicesManifest,
+      });
+      expect(res.status).toBe(200);
+      const html = await res.text();
+      expect(html).not.toContain("You have no assigned vaults");
+      expect(html).not.toMatch(/<button[^>]*name="approve"[^>]*value="yes"[^>]*disabled/);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("non-admin / zero vaults / NON-vault scope → Approve enabled", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      await createUser(db, "admin-aaron", "pw");
+      const bob = await createUser(db, "bob", "pw", { allowMulti: true });
+      const session = createSession(db, { userId: bob.id });
+      const reg = registerClient(db, {
+        redirectUris: ["https://app.example/cb"],
+        status: "approved",
+      });
+      const { challenge } = makePkce();
+      const req = new Request(
+        authorizeUrl({
+          client_id: reg.client.clientId,
+          redirect_uri: "https://app.example/cb",
+          response_type: "code",
+          // Non-vault scope — the user can still consent without a vault.
+          scope: "scribe:transcribe",
+          code_challenge: challenge,
+          code_challenge_method: "S256",
+        }),
+        {
+          headers: {
+            cookie: `${CSRF_COOKIE}; ${buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000))}`,
+          },
+        },
+      );
+      const res = handleAuthorizeGet(db, req, {
+        issuer: ISSUER,
+        loadServicesManifest: fixtureLoadServicesManifest,
+      });
+      expect(res.status).toBe(200);
+      const html = await res.text();
+      expect(html).not.toContain("You have no assigned vaults");
+      expect(html).not.toMatch(/<button[^>]*name="approve"[^>]*value="yes"[^>]*disabled/);
+    } finally {
+      cleanup();
+    }
+  });
+});
+
 // RFC 8707 resource binding (fix #461). A friend connecting an MCP client to
 // ONE vault (`<origin>/vault/<name>/mcp`) must see ONLY that vault's scopes on
 // consent, and the minted token must carry the narrow, NAMED scope +

package/src/__tests__/oauth-ui.test.ts

@@ -225,6 +225,33 @@ describe("renderConsent", () => {
     expect(html).toContain("no vaults exist");
     expect(html).toContain('value="yes" class="btn btn-primary" disabled');
   });
+
+  test("disables Approve + shows copy when user can't authorize (hub#431)", () => {
+    const html = renderConsent({
+      params: { ...PARAMS, scope: "vault:work:read" },
+      csrfToken: CSRF,
+      clientId: "c",
+      clientName: "App",
+      scopes: ["vault:work:read"],
+      userCanAuthorizeRequest: false,
+    });
+    expect(html).toContain("You have no assigned vaults");
+    expect(html).toContain("ask the hub admin".replace("ask", "Ask"));
+    expect(html).toContain('value="yes" class="btn btn-primary" disabled');
+  });
+
+  test("leaves Approve enabled when userCanAuthorizeRequest is true (hub#431)", () => {
+    const html = renderConsent({
+      params: { ...PARAMS, scope: "vault:work:read" },
+      csrfToken: CSRF,
+      clientId: "c",
+      clientName: "App",
+      scopes: ["vault:work:read"],
+      userCanAuthorizeRequest: true,
+    });
+    expect(html).not.toContain("You have no assigned vaults");
+    expect(html).not.toContain('value="yes" class="btn btn-primary" disabled');
+  });
 });
 
 describe("renderError", () => {

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);
+  });
+});