@openparachute/hub 0.7.1 → 0.7.2

package/src/__tests__/oauth-flows-store.test.ts

@@ -0,0 +1,141 @@
+/**
+ * Tests for the in-flight OAuth consent-flow store (`oauth-flows-store.ts`, 4b-2).
+ *
+ * put / get-by-state / delete-on-use / round-trip / TTL prune / 0600 perms / the
+ * lenient-read posture. The file holds PKCE verifiers (secrets) → 0600.
+ */
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  FLOW_TTL_MS,
+  type PendingFlow,
+  deleteFlow,
+  getFlowByState,
+  pruneExpiredFlows,
+  putFlow,
+} from "../oauth-flows-store.ts";
+
+let dir: string;
+let storePath: string;
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "phub-oauth-flows-"));
+  storePath = join(dir, "agent-oauth-flows.json");
+});
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+function flow(over: Partial<PendingFlow> = {}): PendingFlow {
+  return {
+    state: over.state ?? "state-1",
+    grantId: over.grantId ?? "grant-1",
+    issuer: over.issuer ?? "https://issuer.test",
+    clientId: over.clientId ?? "cid-1",
+    tokenEndpoint: over.tokenEndpoint ?? "https://issuer.test/oauth/token",
+    verifier: over.verifier ?? "pkce-verifier-secret",
+    mcpUrl: over.mcpUrl ?? "https://remote.test/mcp",
+    redirectUri: over.redirectUri ?? "https://hub.test/oauth/agent-grant/callback",
+    createdAt: over.createdAt ?? new Date().toISOString(),
+    ...(over.revocationEndpoint ? { revocationEndpoint: over.revocationEndpoint } : {}),
+    ...(over.scope ? { scope: over.scope } : {}),
+  };
+}
+
+describe("round-trip", () => {
+  test("a missing file returns null for any state", () => {
+    expect(getFlowByState(storePath, "anything")).toBeNull();
+  });
+
+  test("put → get by state", () => {
+    const f = flow();
+    putFlow(storePath, f);
+    const back = getFlowByState(storePath, "state-1");
+    expect(back).toEqual(f);
+  });
+
+  test("put upserts by state (no duplicate)", () => {
+    putFlow(storePath, flow({ clientId: "old" }));
+    putFlow(storePath, flow({ clientId: "new" }));
+    expect(getFlowByState(storePath, "state-1")?.clientId).toBe("new");
+  });
+
+  test("delete-on-use removes the flow (single-use)", () => {
+    putFlow(storePath, flow());
+    const removed = deleteFlow(storePath, "state-1");
+    expect(removed?.state).toBe("state-1");
+    expect(getFlowByState(storePath, "state-1")).toBeNull();
+    // second delete is a no-op
+    expect(deleteFlow(storePath, "state-1")).toBeNull();
+  });
+
+  test("distinct states coexist", () => {
+    putFlow(storePath, flow({ state: "a" }));
+    putFlow(storePath, flow({ state: "b", grantId: "grant-2" }));
+    expect(getFlowByState(storePath, "a")?.grantId).toBe("grant-1");
+    expect(getFlowByState(storePath, "b")?.grantId).toBe("grant-2");
+  });
+});
+
+describe("TTL prune", () => {
+  test("an expired flow is pruned on read (returns null)", () => {
+    const old = new Date(Date.now() - (FLOW_TTL_MS + 60_000)).toISOString();
+    putFlow(storePath, flow({ createdAt: old }));
+    // The default-now read prunes it.
+    expect(getFlowByState(storePath, "state-1")).toBeNull();
+  });
+
+  test("pruneExpiredFlows drops the expired and keeps the live", () => {
+    const now = Date.now();
+    putFlow(storePath, flow({ state: "fresh", createdAt: new Date(now).toISOString() }), now);
+    putFlow(
+      storePath,
+      flow({ state: "stale", createdAt: new Date(now - FLOW_TTL_MS - 1).toISOString() }),
+      now,
+    );
+    const live = pruneExpiredFlows(storePath, now);
+    expect(live.map((f) => f.state).sort()).toEqual(["fresh"]);
+  });
+
+  test("put prunes expired flows before persisting", () => {
+    const now = Date.now();
+    // Seed an expired flow directly.
+    writeFileSync(
+      storePath,
+      JSON.stringify({
+        flows: [flow({ state: "stale", createdAt: new Date(now - FLOW_TTL_MS - 1).toISOString() })],
+      }),
+    );
+    putFlow(storePath, flow({ state: "fresh", createdAt: new Date(now).toISOString() }), now);
+    expect(getFlowByState(storePath, "stale", now)).toBeNull();
+    expect(getFlowByState(storePath, "fresh", now)).not.toBeNull();
+  });
+});
+
+describe("0600 perms (holds PKCE verifiers)", () => {
+  test("the store file is created mode 0600", () => {
+    putFlow(storePath, flow());
+    const mode = statSync(storePath).mode & 0o777;
+    expect(mode).toBe(0o600);
+  });
+});
+
+describe("lenient read", () => {
+  test("garbage JSON reads as empty", () => {
+    writeFileSync(storePath, "not json {{{");
+    expect(getFlowByState(storePath, "x")).toBeNull();
+  });
+
+  test("a malformed row is dropped, valid rows survive", () => {
+    const valid = flow({ state: "ok" });
+    writeFileSync(
+      storePath,
+      JSON.stringify({
+        flows: [valid, { state: "bad" /* missing required fields */ }],
+      }),
+    );
+    expect(getFlowByState(storePath, "ok")).not.toBeNull();
+    expect(getFlowByState(storePath, "bad")).toBeNull();
+  });
+});

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

@@ -115,9 +115,9 @@ describe("authorizationServerMetadata", () => {
     expect(scopesSupported).toContain("vault:admin");
     expect(scopesSupported).toContain("scribe:transcribe"); // scribe is in the fixture manifest
     expect(scopesSupported).toContain("hub:admin");
-    // channel isn't in the fixture manifest → its scopes aren't advertised
+    // agent isn't in the fixture manifest → its scopes aren't advertised
     // (hub#…: optional-module scopes only surface when the module is installed).
-    expect(scopesSupported).not.toContain("channel:send");
+    expect(scopesSupported).not.toContain("agent:send");
   });
 
   test("does NOT advertise non-requestable operator-only scopes", async () => {
@@ -145,8 +145,8 @@ describe("authorizationServerMetadata", () => {
       "vault:admin",
       "hub:admin",
       "parachute:host:admin", // declared but operator-only — must still be filtered
-      "agent:read",
-      "agent:write",
+      "widget:read",
+      "widget:write",
       "mymodule:do-thing",
     ]);
     const res = authorizationServerMetadata({
@@ -156,9 +156,10 @@ describe("authorizationServerMetadata", () => {
     });
     const body = (await res.json()) as Record<string, unknown>;
     const scopesSupported = body.scopes_supported as string[];
-    // Third-party scopes show up
-    expect(scopesSupported).toContain("agent:read");
-    expect(scopesSupported).toContain("agent:write");
+    // Third-party scopes show up (`widget:*` / `mymodule:*` aren't gated
+    // optional-module prefixes — only scribe:/agent: are, see OPTIONAL_MODULE_SCOPES).
+    expect(scopesSupported).toContain("widget:read");
+    expect(scopesSupported).toContain("widget:write");
     expect(scopesSupported).toContain("mymodule:do-thing");
     // First-party still advertised — no regression
     expect(scopesSupported).toContain("vault:read");
@@ -169,10 +170,10 @@ describe("authorizationServerMetadata", () => {
   });
 
   test("advertises an optional module's scopes only when it's installed", async () => {
-    // FIRST_PARTY_SCOPES carries scribe:* + channel:send statically. On a
+    // FIRST_PARTY_SCOPES carries scribe:* + agent:send statically. On a
     // vault-only hub they must NOT be advertised — a discovery client (e.g.
     // claude.ai's connector UI) lists the catalog verbatim, so a friend
-    // connecting one vault was shown Scribe + Channel access the hub can't
+    // connecting one vault was shown Scribe + Agent access the hub can't
     // honor. Vault + hub are core and always advertised.
     const declared = new Set<string>([
       "vault:read",
@@ -180,7 +181,7 @@ describe("authorizationServerMetadata", () => {
       "vault:admin",
       "scribe:transcribe",
       "scribe:admin",
-      "channel:send",
+      "agent:send",
       "hub:admin",
     ]);
     const vaultOnly = {
@@ -207,7 +208,7 @@ describe("authorizationServerMetadata", () => {
     // uninstalled optional-module scopes are dropped
     expect(scopes).not.toContain("scribe:transcribe");
     expect(scopes).not.toContain("scribe:admin");
-    expect(scopes).not.toContain("channel:send");
+    expect(scopes).not.toContain("agent:send");
 
     // ...but once scribe is installed, its scopes ARE advertised again.
     const withScribe = {
@@ -235,7 +236,7 @@ describe("authorizationServerMetadata", () => {
     });
     const scopes2 = ((await res2.json()) as Record<string, unknown>).scopes_supported as string[];
     expect(scopes2).toContain("scribe:transcribe");
-    expect(scopes2).not.toContain("channel:send"); // channel still not installed
+    expect(scopes2).not.toContain("agent:send"); // agent still not installed
   });
 });
 
@@ -263,7 +264,7 @@ describe("protectedResourceMetadata (RFC 9728, closes hub#393)", () => {
       "vault:admin",
       "hub:admin",
       "parachute:host:admin",
-      "agent:read",
+      "widget:read",
     ]);
     const res = protectedResourceMetadata({
       issuer: ISSUER,
@@ -273,7 +274,7 @@ describe("protectedResourceMetadata (RFC 9728, closes hub#393)", () => {
     const body = (await res.json()) as Record<string, unknown>;
     const scopes = body.scopes_supported as string[];
     expect(scopes).toContain("vault:read");
-    expect(scopes).toContain("agent:read");
+    expect(scopes).toContain("widget:read");
     expect(scopes).not.toContain("parachute:host:admin");
   });
 });
@@ -988,13 +989,13 @@ describe("handleAuthorizeGet — vault picker", () => {
 describe("handleAuthorizeGet — RFC 8707 resource binding drops foreign scopes (scary-consent fix)", () => {
   // claude.ai connecting to ONE vault reads the hub's whole-hub AS-metadata
   // `scopes_supported` and over-requests the full catalog. Bound to the vault
-  // resource (`aud=vault.<name>`), scribe/channel/hub scopes are unusable, so
+  // resource (`aud=vault.<name>`), scribe/agent/hub scopes are unusable, so
   // they must be DROPPED before consent — Aaron hit them as "a fuck ton of
   // privileges that don't make sense" (scribe isn't even installed here).
   const FOREIGN_AND_VAULT =
-    "vault:read vault:write scribe:transcribe scribe:admin channel:send hub:admin";
+    "vault:read vault:write scribe:transcribe scribe:admin agent:send hub:admin";
 
-  test("session consent for a vault MCP resource drops scribe/channel/hub scopes", async () => {
+  test("session consent for a vault MCP resource drops scribe/agent/hub scopes", async () => {
     const { db, cleanup } = await makeDb();
     try {
       const user = await createUser(db, "owner", "pw");
@@ -1035,7 +1036,7 @@ describe("handleAuthorizeGet — RFC 8707 resource binding drops foreign scopes
       // The foreign scopes are gone.
       expect(html).not.toContain("Send audio to Scribe for transcription."); // scribe:transcribe
       expect(html).not.toContain("Manage Scribe configuration"); // scribe:admin
-      expect(html).not.toContain("Post messages to your Channel."); // channel:send
+      expect(html).not.toContain("Post messages to your Agent."); // agent:send
       expect(html).not.toContain("Manage hub identity"); // hub:admin
     } finally {
       cleanup();
@@ -1058,7 +1059,7 @@ describe("handleAuthorizeGet — RFC 8707 resource binding drops foreign scopes
           response_type: "code",
           code_challenge: challenge,
           code_challenge_method: "S256",
-          scope: "vault:read scribe:transcribe channel:send",
+          scope: "vault:read scribe:transcribe agent:send",
           resource: `${ISSUER}/vault/default/mcp`,
         }),
         // No session cookie → the unauth pending page renders.
@@ -1072,13 +1073,13 @@ describe("handleAuthorizeGet — RFC 8707 resource binding drops foreign scopes
       expect(html).toContain("App not yet approved");
       // Foreign scopes absent from the rendered rows...
       expect(html).not.toContain("Send audio to Scribe for transcription.");
-      expect(html).not.toContain("Post messages to your Channel.");
+      expect(html).not.toContain("Post messages to your Agent.");
       // ...and from the login round-trip URL embedded in the page (the
       // narrowed scope was written back onto `url` before this render).
       expect(html).not.toContain("scribe:transcribe");
-      expect(html).not.toContain("channel:send");
+      expect(html).not.toContain("agent:send");
       expect(html).not.toContain("scribe%3Atranscribe");
-      expect(html).not.toContain("channel%3Asend");
+      expect(html).not.toContain("agent%3Asend");
     } finally {
       cleanup();
     }
@@ -1105,7 +1106,7 @@ describe("handleAuthorizeGet — RFC 8707 resource binding drops foreign scopes
           response_type: "code",
           code_challenge: challenge,
           code_challenge_method: "S256",
-          scope: "scribe:transcribe channel:send",
+          scope: "scribe:transcribe agent:send",
           resource: `${ISSUER}/vault/default/mcp`,
         }),
         {
@@ -1121,7 +1122,7 @@ describe("handleAuthorizeGet — RFC 8707 resource binding drops foreign scopes
       expect(res.status).toBe(200);
       const html = await res.text();
       expect(html).not.toContain("Send audio to Scribe for transcription.");
-      expect(html).not.toContain("Post messages to your Channel.");
+      expect(html).not.toContain("Post messages to your Agent.");
     } finally {
       cleanup();
     }
@@ -1130,7 +1131,7 @@ describe("handleAuthorizeGet — RFC 8707 resource binding drops foreign scopes
   test("trust-by-client_name no longer re-prompts when the request over-asks the whole-hub catalog", async () => {
     // Before the narrowing was moved ahead of the status branch, the
     // trust-by-client_name coverage check compared the RAW request
-    // (`vault:read scribe:transcribe channel:send`) against a vault-only prior
+    // (`vault:read scribe:transcribe agent:send`) against a vault-only prior
     // grant — never matched — re-prompting consent every session for a client
     // the operator had already approved. Narrowing first makes the comparison
     // vault-only-vs-vault-only, so the silent re-link fires.
@@ -1160,7 +1161,7 @@ describe("handleAuthorizeGet — RFC 8707 resource binding drops foreign scopes
           response_type: "code",
           code_challenge: challenge,
           code_challenge_method: "S256",
-          scope: "vault:read scribe:transcribe channel:send",
+          scope: "vault:read scribe:transcribe agent:send",
           resource: `${ISSUER}/vault/default/mcp`,
         }),
         {
@@ -3279,6 +3280,103 @@ describe("handleRegister — RFC 7591 DCR", () => {
   });
 });
 
+// surface#118 — a hub-served module (surface, notes) registers at install time
+// knowing only the loopback hub origin; once exposed, the browser computes its
+// redirect_uri from the PUBLIC hub origin, which strict authorize-time matching
+// would reject. handleRegister expands hub-origin-rooted redirect_uris onto
+// every known hub origin (via deps.hubBoundOrigins). Foreign-origin URIs stay
+// verbatim — never expanded onto hub origins, never dropped (open-redirect
+// guard). Authorize-time matching is unchanged (strict exact-match).
+describe("handleRegister — cross-hub-origin redirect_uri expansion (surface#118)", () => {
+  const PUBLIC = "https://box.taildf9ce2.ts.net";
+  const LOOPBACK = "http://127.0.0.1:1939";
+  const boundOrigins = () => [ISSUER, LOOPBACK, "http://localhost:1939", PUBLIC];
+
+  test("loopback-rooted URI is stored WITH the public-origin variant", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const req = new Request(`${ISSUER}/oauth/register`, {
+        method: "POST",
+        body: JSON.stringify({
+          redirect_uris: [`${LOOPBACK}/surface/notes/oauth/callback`],
+          scope: "vault:default:read",
+          client_name: "Notes",
+        }),
+        headers: { "content-type": "application/json" },
+      });
+      const res = await handleRegister(db, req, {
+        issuer: ISSUER,
+        hubBoundOrigins: boundOrigins,
+      });
+      expect(res.status).toBe(201);
+      const body = (await res.json()) as Record<string, unknown>;
+      const stored = body.redirect_uris as string[];
+      // The submitted loopback URI is preserved...
+      expect(stored).toContain(`${LOOPBACK}/surface/notes/oauth/callback`);
+      // ...and the public-origin variant is now registered — the fix.
+      expect(stored).toContain(`${PUBLIC}/surface/notes/oauth/callback`);
+
+      // The stored set drives authorize-time matching; confirm the public
+      // variant now matches via the real client record.
+      const stored2 = getClient(db, body.client_id as string);
+      expect(stored2?.redirectUris).toContain(`${PUBLIC}/surface/notes/oauth/callback`);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("INVARIANT: a foreign-origin redirect_uri is stored verbatim, NOT expanded onto hub origins", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const foreign = "https://my-vault-ui.example/oauth/callback";
+      const req = new Request(`${ISSUER}/oauth/register`, {
+        method: "POST",
+        body: JSON.stringify({
+          redirect_uris: [foreign],
+          scope: "vault:default:read",
+          client_name: "Off-origin surface",
+        }),
+        headers: { "content-type": "application/json" },
+      });
+      const res = await handleRegister(db, req, {
+        issuer: ISSUER,
+        hubBoundOrigins: boundOrigins,
+      });
+      expect(res.status).toBe(201);
+      const body = (await res.json()) as Record<string, unknown>;
+      const stored = body.redirect_uris as string[];
+      // Stored exactly as submitted — never dropped.
+      expect(stored).toEqual([foreign]);
+      // No hub-origin variant was minted from the foreign URI (open-redirect guard).
+      for (const o of [ISSUER, LOOPBACK, "http://localhost:1939", PUBLIC]) {
+        expect(stored).not.toContain(`${o}/oauth/callback`);
+      }
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("no expansion when only one hub origin is known (single-origin hub unaffected)", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const req = new Request(`${ISSUER}/oauth/register`, {
+        method: "POST",
+        body: JSON.stringify({
+          redirect_uris: [`${ISSUER}/surface/notes/oauth/callback`],
+        }),
+        headers: { "content-type": "application/json" },
+      });
+      // hubBoundOrigins absent → resolveBoundOrigins falls back to [issuer].
+      const res = await handleRegister(db, req, { issuer: ISSUER });
+      expect(res.status).toBe(201);
+      const body = (await res.json()) as Record<string, unknown>;
+      expect(body.redirect_uris).toEqual([`${ISSUER}/surface/notes/oauth/callback`]);
+    } finally {
+      cleanup();
+    }
+  });
+});
+
 // closes #74 — DCR is now operator-gated. Self-served registrations land as
 // pending and cannot OAuth; operator-bearer (hub:admin) registrations land
 // as approved and can OAuth immediately. This block covers all four exposed

package/src/__tests__/operator-token.test.ts

@@ -66,7 +66,7 @@ describe("mintOperatorToken", () => {
     }
   });
 
-  test("admin scope-set includes hub:admin + parachute:host:* + vault/scribe/channel admins (#213)", () => {
+  test("admin scope-set includes hub:admin + parachute:host:* + vault/scribe/agent admins (#213)", () => {
     // OPERATOR_TOKEN_SCOPES === OPERATOR_TOKEN_SCOPE_SETS.admin (back-compat
     // alias). The pre-#213 set was 5 scopes; #213 added the fine-grained
     // parachute:host:install/start/expose/auth/vault scopes to the admin
@@ -81,7 +81,7 @@ describe("mintOperatorToken", () => {
       "parachute:host:vault",
       "vault:admin",
       "scribe:admin",
-      "channel:send",
+      "agent:send",
     ]);
   });
 });

package/src/__tests__/scope-explanations.test.ts

@@ -19,7 +19,7 @@ describe("SCOPE_EXPLANATIONS", () => {
       "vault:admin",
       "scribe:transcribe",
       "scribe:admin",
-      "channel:send",
+      "agent:send",
       "hub:admin",
       "parachute:host:admin",
     ];
@@ -96,7 +96,7 @@ describe("scopeIsAdmin", () => {
 
   test("false for non-admin and unknown scopes", () => {
     expect(scopeIsAdmin("vault:read")).toBe(false);
-    expect(scopeIsAdmin("channel:send")).toBe(false);
+    expect(scopeIsAdmin("agent:send")).toBe(false);
     expect(scopeIsAdmin("unknown:anything")).toBe(false);
   });
 
@@ -133,7 +133,7 @@ describe("isRequestableScope", () => {
     expect(isRequestableScope("hub:admin")).toBe(true);
     expect(isRequestableScope("vault:read")).toBe(true);
     expect(isRequestableScope("vault:admin")).toBe(true);
-    expect(isRequestableScope("channel:send")).toBe(true);
+    expect(isRequestableScope("agent:send")).toBe(true);
   });
 
   test("true for unknown scopes (third-party module scopes pass through)", () => {

package/src/__tests__/serve-boot.test.ts

@@ -290,24 +290,24 @@ describe("bootSupervisedModules", () => {
   });
 });
 
-// channel#41 — a transiently-wrong (drifted) services.json port for a
+// agent (then channel)#41 — a transiently-wrong (drifted) services.json port for a
 // fixed-port first-party module self-perpetuates: the supervisor injects PORT /
 // probes / proxies from that row, so the wrong port strands the module forever.
 // The boot path snaps it back to canonical before spawn AND persists the fix so
 // the reverse-proxy (which reads services.json) routes correctly.
-describe("reconcilePortToCanonical (channel#41)", () => {
+describe("reconcilePortToCanonical (channel#41 — module now agent)", () => {
   let h: Harness;
   beforeEach(() => {
     h = makeHarness();
   });
   afterEach(() => h.cleanup());
 
-  // The live-observed signature: channel's row carried 19415 instead of its
+  // The live-observed signature: the agent (then channel) row carried 19415 instead of its
   // canonical 1941.
   const DRIFTED_CHANNEL: ServiceEntry = {
-    name: "parachute-channel",
+    name: "parachute-agent",
     port: 19415,
-    paths: ["/channel"],
+    paths: ["/agent"],
     health: "/health",
     version: "0.1.0",
   };
@@ -320,12 +320,12 @@ describe("reconcilePortToCanonical (channel#41)", () => {
       logs.push(l),
     );
 
-    // Returned entry carries canonical (channel → 1941).
+    // Returned entry carries canonical (agent → 1941).
     expect(reconciled.port).toBe(1941);
     // And it's PERSISTED — the proxy reads services.json, so the row itself must
-    // now point at 1941 or `/channel/*` keeps routing to the dead 19415.
+    // now point at 1941 or `/agent/*` keeps routing to the dead 19415.
     const onDisk = readManifestLenient(h.manifestPath).services.find(
-      (s) => s.name === "parachute-channel",
+      (s) => s.name === "parachute-agent",
     );
     expect(onDisk?.port).toBe(1941);
     expect(
@@ -356,7 +356,7 @@ describe("reconcilePortToCanonical (channel#41)", () => {
 
   test("does NOT steal the canonical port when another row already holds it", () => {
     // Another row legitimately occupies 1941 — reconciling would trip the
-    // write-side duplicate-port guard and isn't channel's to take. Leave the
+    // write-side duplicate-port guard and isn't the agent module's to take. Leave the
     // drift; the supervisor's squatter detection surfaces it.
     const squatter: ServiceEntry = {
       name: "parachute-vault",
@@ -372,13 +372,13 @@ describe("reconcilePortToCanonical (channel#41)", () => {
 
     expect(out.port).toBe(19415); // unchanged
     const onDisk = readManifestLenient(h.manifestPath).services.find(
-      (s) => s.name === "parachute-channel",
+      (s) => s.name === "parachute-agent",
     );
     expect(onDisk?.port).toBe(19415); // not rewritten
     expect(logs.some((l) => l.includes("held by another row"))).toBe(true);
   });
 
-  test("boot path injects PORT=canonical + persists the fix for a drifted channel row", async () => {
+  test("boot path injects PORT=canonical + persists the fix for a drifted agent row", async () => {
     writeManifest({ services: [DRIFTED_CHANNEL] }, h.manifestPath);
     const recorder = makeRecorder();
     const sup = new Supervisor({ spawnFn: recorder.spawn });
@@ -390,11 +390,11 @@ describe("reconcilePortToCanonical (channel#41)", () => {
 
     // The supervisor child gets PORT=1941 (so it binds + the readiness probe
     // checks the right port), not the drifted 19415.
-    expect(recorder.calls[0]?.short).toBe("channel");
+    expect(recorder.calls[0]?.short).toBe("agent");
     expect(recorder.calls[0]?.env?.PORT).toBe("1941");
-    // services.json row is reconciled → proxy routes /channel/* to 1941.
+    // services.json row is reconciled → proxy routes /agent/* to 1941.
     const onDisk = readManifestLenient(h.manifestPath).services.find(
-      (s) => s.name === "parachute-channel",
+      (s) => s.name === "parachute-agent",
     );
     expect(onDisk?.port).toBe(1941);
   });

package/src/__tests__/serve.test.ts

@@ -8,12 +8,38 @@ import {
   formatBootstrapTokenBanner,
   formatListeningBanner,
   hubPortConflictMessage,
+  hubServeOptions,
   resolveStartupIssuer,
   seedInitialAdminIfNeeded,
 } from "../commands/serve.ts";
 import { openHubDb } from "../hub-db.ts";
 import { getUserByUsername, userCount } from "../users.ts";
 
+describe("hubServeOptions — the production listener wires the WS bridge", () => {
+  // Regression guard: the WS bridge handler was wired into hub-server.ts's
+  // Bun.serve but NOT this production `parachute serve` path, so module WS
+  // upgrades (the channel in-page terminal) 500'd through the hub
+  // ("set the websocket object in Bun.serve({})"). The listener MUST declare a
+  // websocket handler or `server.upgrade()` throws.
+  const fakeFetch = (() => new Response("ok")) as unknown as Parameters<typeof hubServeOptions>[0]["fetch"];
+
+  test("declares a websocket handler set (open/message/close)", () => {
+    const o = hubServeOptions({ port: 0, hostname: "127.0.0.1", fetch: fakeFetch });
+    expect(o.websocket).toBeDefined();
+    expect(typeof o.websocket.open).toBe("function");
+    expect(typeof o.websocket.message).toBe("function");
+    expect(typeof o.websocket.close).toBe("function");
+  });
+
+  test("preserves the port/hostname/idleTimeout + the passed fetch", () => {
+    const o = hubServeOptions({ port: 1939, hostname: "0.0.0.0", fetch: fakeFetch });
+    expect(o.port).toBe(1939);
+    expect(o.hostname).toBe("0.0.0.0");
+    expect(o.idleTimeout).toBe(255);
+    expect(o.fetch).toBe(fakeFetch);
+  });
+});
+
 describe("hubPortConflictMessage (hub#536)", () => {
   test("maps a port-in-use error to a clear duplicate-supervisor message", () => {
     // Bun surfaces a port conflict as "...Is port 1939 in use?"; node-style is