npm - @openparachute/hub - Versions diffs - 0.7.7-rc.8 → 0.7.7 - Mend

@openparachute/hub 0.7.7-rc.8 → 0.7.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (80) hide show

package/README.md +7 -7
package/package.json +4 -12
package/src/__tests__/account-api.test.ts +29 -2
package/src/__tests__/account-session.test.ts +9 -1
package/src/__tests__/account-token.test.ts +26 -2
package/src/__tests__/admin-connections-credentials.test.ts +41 -0
package/src/__tests__/admin-lock.test.ts +3 -14
package/src/__tests__/admin-module-token.test.ts +10 -30
package/src/__tests__/admin-surfaces.test.ts +21 -0
package/src/__tests__/api-hub-upgrade.test.ts +11 -0
package/src/__tests__/api-mint-token.test.ts +25 -0
package/src/__tests__/api-modules-ops.test.ts +34 -29
package/src/__tests__/api-modules.test.ts +50 -58
package/src/__tests__/api-revoke-token.test.ts +23 -0
package/src/__tests__/api-settings-hub-origin.test.ts +12 -0
package/src/__tests__/api-settings-root-redirect.test.ts +159 -4
package/src/__tests__/api-tokens.test.ts +44 -0
package/src/__tests__/audience-gate.test.ts +24 -0
package/src/__tests__/bearer-scheme-casing.test.ts +110 -0
package/src/__tests__/chrome-strip.test.ts +18 -1
package/src/__tests__/doctor.test.ts +10 -17
package/src/__tests__/hub-command.test.ts +70 -2
package/src/__tests__/hub-server.test.ts +322 -1
package/src/__tests__/hub-settings.test.ts +110 -6
package/src/__tests__/hub.test.ts +29 -0
package/src/__tests__/install.test.ts +359 -5
package/src/__tests__/migrate.test.ts +3 -1
package/src/__tests__/notes-serve.test.ts +216 -0
package/src/__tests__/oauth-handlers.test.ts +19 -8
package/src/__tests__/operator-token.test.ts +1 -2
package/src/__tests__/port-assign.test.ts +37 -17
package/src/__tests__/root-serve.test.ts +139 -0
package/src/__tests__/scope-explanations.test.ts +0 -2
package/src/__tests__/serve-boot.test.ts +25 -36
package/src/__tests__/service-spec-discovery.test.ts +30 -35
package/src/__tests__/services-manifest.test.ts +372 -132
package/src/__tests__/setup-wizard.test.ts +301 -22
package/src/__tests__/setup.test.ts +13 -14
package/src/__tests__/status.test.ts +0 -5
package/src/__tests__/surface-notes-alias.test.ts +296 -0
package/src/__tests__/wizard-transcription.test.ts +35 -0
package/src/__tests__/wizard.test.ts +79 -0
package/src/account-api.ts +6 -0
package/src/admin-connections.ts +4 -2
package/src/admin-lock.ts +1 -2
package/src/admin-module-token.ts +13 -8
package/src/admin-surfaces.ts +2 -1
package/src/api-hub-upgrade.ts +2 -1
package/src/api-mint-token.ts +2 -1
package/src/api-modules-ops.ts +2 -1
package/src/api-modules.ts +10 -8
package/src/api-revoke-token.ts +2 -1
package/src/api-settings-hub-origin.ts +2 -1
package/src/api-settings-root-redirect.ts +97 -20
package/src/api-tokens.ts +2 -1
package/src/audience-gate.ts +2 -1
package/src/chrome-strip.ts +16 -4
package/src/commands/hub.ts +104 -0
package/src/commands/install.ts +97 -8
package/src/commands/migrate.ts +5 -1
package/src/commands/setup.ts +9 -6
package/src/commands/wizard-transcription.ts +24 -0
package/src/commands/wizard.ts +34 -1
package/src/help.ts +6 -6
package/src/hub-server.ts +111 -54
package/src/hub-settings.ts +147 -0
package/src/hub.ts +64 -31
package/src/module-ops-client.ts +2 -1
package/src/notes-serve.ts +73 -31
package/src/oauth-handlers.ts +1 -11
package/src/operator-token.ts +0 -1
package/src/origin-check.ts +2 -2
package/src/root-serve.ts +156 -0
package/src/scope-explanations.ts +2 -5
package/src/service-spec.ts +129 -74
package/src/services-manifest.ts +112 -52
package/src/setup-wizard.ts +144 -31
package/src/surface-notes-alias.ts +126 -0
package/src/__tests__/admin-agent-token.test.ts +0 -173
package/src/admin-agent-token.ts +0 -147

package/src/__tests__/notes-serve.test.ts CHANGED Viewed

@@ -149,6 +149,124 @@ describe("notesFetch with empty mount (root deployment)", () => {
   });
 });
+describe("notesFetch /health (2026-07-11, hub-parity P5)", () => {
+  test("GET /notes/health answers 2xx explicitly, not the SPA shell", async () => {
+    const h = makeHarness();
+    try {
+      const res = notesFetch(h.dir, "/notes")(req("/notes/health"));
+      expect(res.status).toBe(200);
+      // Explicit JSON, not the index.html SPA-shell fallback — proves the
+      // health path is a real handler, not an accident of the catch-all.
+      expect(res.headers.get("content-type")).toBe("application/json");
+      expect(await res.text()).not.toContain("notes spa");
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("GET /health answers 2xx at the mount root too (empty mount)", async () => {
+    const h = makeHarness();
+    try {
+      const res = notesFetch(h.dir, "")(req("/health"));
+      expect(res.status).toBe(200);
+      expect(res.headers.get("content-type")).toBe("application/json");
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("survives a missing dist/index.html — health doesn't depend on the SPA shell existing", async () => {
+    // A harness with NO index.html written — the SPA-shell fallback would
+    // throw/404 on this dist, but /health is answered before that code path
+    // is ever reached.
+    const dir = mkdtempSync(join(tmpdir(), "pcli-notes-serve-empty-"));
+    try {
+      const res = notesFetch(dir, "/app")(req("/app/health"));
+      expect(res.status).toBe(200);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+// hub-parity P5 (2026-07-11): the shim generalized beyond notes to serve
+// @openparachute/parachute-app (mount `/app`, port 1944) via the same
+// FIRST_PARTY_FALLBACKS startCmd shape (`--package @openparachute/parachute-app`).
+// These tests re-run the load-bearing PWA regression (sw.js / manifest
+// content-type, SPA fallback, mount-strip) for a NON-notes package/mount to
+// prove the generalization didn't accidentally hardcode "notes" anywhere in
+// the serving path (only `resolveNotesDistFrom`'s package resolution is
+// notes-specific, and that's parameterized separately below).
+describe("notesFetch generalized for a non-notes package (hub-parity P5 — the app mount)", () => {
+  function makeAppHarness(): Harness {
+    const dir = mkdtempSync(join(tmpdir(), "pcli-app-serve-"));
+    writeFileSync(join(dir, "index.html"), "<html><body>app spa</body></html>");
+    writeFileSync(join(dir, "sw.js"), "self.addEventListener('install', () => {});");
+    writeFileSync(join(dir, "manifest.webmanifest"), '{"name":"Parachute","start_url":"/app/"}');
+    return { dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+  }
+  test("GET /app/sw.js serves the SW with JS content-type, not text/html", async () => {
+    const h = makeAppHarness();
+    try {
+      const res = notesFetch(h.dir, "/app")(req("/app/sw.js"));
+      expect(res.status).toBe(200);
+      const ct = res.headers.get("content-type") ?? "";
+      expect(ct).not.toContain("text/html");
+      expect(ct).toMatch(/javascript/);
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("GET /app/manifest.webmanifest serves application/manifest+json", async () => {
+    const h = makeAppHarness();
+    try {
+      const res = notesFetch(h.dir, "/app")(req("/app/manifest.webmanifest"));
+      expect(res.status).toBe(200);
+      expect(res.headers.get("content-type")).toBe("application/manifest+json");
+      expect(await res.text()).toContain('"name":"Parachute"');
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("GET /app/ serves the SPA shell", async () => {
+    const h = makeAppHarness();
+    try {
+      const res = notesFetch(h.dir, "/app")(req("/app/"));
+      expect(res.status).toBe(200);
+      expect(res.headers.get("content-type")).toBe("text/html; charset=utf-8");
+      expect(await res.text()).toContain("app spa");
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("GET /app/some/deep/route falls back to the SPA shell (client-side routing)", async () => {
+    const h = makeAppHarness();
+    try {
+      const res = notesFetch(h.dir, "/app")(req("/app/some/deep/route"));
+      expect(res.status).toBe(200);
+      expect(res.headers.get("content-type")).toBe("text/html; charset=utf-8");
+      expect(await res.text()).toContain("app spa");
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("GET /appendix/foo (mount-prefix collision) is not stripped", async () => {
+    const h = makeAppHarness();
+    try {
+      const res = notesFetch(h.dir, "/app")(req("/appendix/foo"));
+      expect(res.status).toBe(200);
+      expect(res.headers.get("content-type")).toBe("text/html; charset=utf-8");
+    } finally {
+      h.cleanup();
+    }
+  });
+});
 describe("notesDistCandidates", () => {
   test("returns cwd, then global node_modules, then global root", () => {
     const cands = notesDistCandidates("/some/cwd", "/home/user");
@@ -295,3 +413,101 @@ describe("resolveNotesDistFrom (hub#194)", () => {
     ).toThrow(/has no dist\/ directory/);
   });
 });
+/**
+ * `--package` generalization (hub-parity P5, 2026-07-11). `resolveNotesDistFrom`
+ * defaults `pkg` to `@openparachute/notes` (every test above omits it and
+ * still resolves notes — back-compat), but a caller like the `app`
+ * FIRST_PARTY_FALLBACKS entry passes a different package name. These tests
+ * pin the resolver against a real on-disk fixture for a NON-notes package,
+ * proving the specifier passed to `Bun.resolveSync` (and every error message)
+ * is the caller's `pkg`, not a hardcoded "notes" string.
+ */
+describe("resolveNotesDistFrom --package (hub-parity P5)", () => {
+  const APP_PKG = "@openparachute/parachute-app";
+  function makeAppFixture(): { home: string; cleanup: () => void; dist: string } {
+    const root = realpathSync(mkdtempSync(join(tmpdir(), "pcli-app-resolve-")));
+    const home = join(root, "home");
+    const pkgRoot = join(home, ".bun/install/global/node_modules", APP_PKG);
+    mkdirSync(pkgRoot, { recursive: true });
+    const dist = join(pkgRoot, "dist");
+    mkdirSync(dist, { recursive: true });
+    writeFileSync(join(pkgRoot, "package.json"), JSON.stringify({ name: APP_PKG }));
+    return { home, dist, cleanup: () => rmSync(root, { recursive: true, force: true }) };
+  }
+  test("resolves a non-notes package's dist/ via the global node_modules fallback", () => {
+    const f = makeAppFixture();
+    try {
+      const out = resolveNotesDistFrom({
+        cwd: "/hub-repo-cwd-without-app",
+        home: f.home,
+        pkg: APP_PKG,
+        resolveSync: (specifier, base) => {
+          if (base === "/hub-repo-cwd-without-app") {
+            throw new Error(`Cannot find module '${specifier}' from '${base}'`);
+          }
+          return Bun.resolveSync(specifier, base);
+        },
+      });
+      expect(out).toBe(f.dist);
+    } finally {
+      f.cleanup();
+    }
+  });
+  test("default pkg (no --package) still resolves @openparachute/notes — back-compat", () => {
+    // Every earlier describe block already exercises this implicitly (none
+    // pass `pkg`); this test pins it explicitly against the specifier the
+    // resolver hands to `resolveSync`.
+    const specifiers: string[] = [];
+    expect(() =>
+      resolveNotesDistFrom({
+        cwd: "/cwd",
+        home: "/h",
+        resolveSync: (specifier) => {
+          specifiers.push(specifier);
+          throw new Error("not found");
+        },
+      }),
+    ).toThrow();
+    expect(specifiers).toEqual([
+      "@openparachute/notes/package.json",
+      "@openparachute/notes/package.json",
+      "@openparachute/notes/package.json",
+    ]);
+  });
+  test("error message names the caller's package, not a hardcoded 'notes'", () => {
+    let caught: unknown;
+    try {
+      resolveNotesDistFrom({
+        cwd: "/probe-cwd",
+        home: "/probe-home",
+        pkg: APP_PKG,
+        resolveSync: () => {
+          throw new Error("nope");
+        },
+      });
+    } catch (err) {
+      caught = err;
+    }
+    const msg = (caught as Error).message;
+    expect(msg).toContain(`Could not resolve ${APP_PKG}`);
+    expect(msg).toContain(`bun add -g ${APP_PKG}`);
+    expect(msg).not.toContain("@openparachute/notes");
+  });
+  test("no-dist/ hard error names the caller's package", () => {
+    expect(() =>
+      resolveNotesDistFrom({
+        cwd: "/cwd-with-app",
+        home: "/h",
+        pkg: APP_PKG,
+        resolveSync: () => "/cwd-with-app/node_modules/@openparachute/parachute-app/package.json",
+        existsSync: () => false,
+      }),
+    ).toThrow(new RegExp(`${APP_PKG.replace("/", "\\/")} resolved at .* has no dist/ directory`));
+  });
+});

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

@@ -3,6 +3,11 @@ import { createHash, randomBytes } from "node:crypto";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import {
+  checkAuthorizationServerMetadata,
+  checkProtectedResourceMetadata,
+  checkTokenResponseInvariants,
+} from "@openparachute/door-contract";
 import { handleAdminLoginPost, handleAdminLoginTotpPost } from "../admin-handlers.ts";
 import { approveClient, getClient, registerClient } from "../clients.ts";
 import { CSRF_COOKIE_NAME } from "../csrf.ts";
@@ -122,9 +127,12 @@ describe("authorizationServerMetadata", () => {
     // hub:admin + scribe:admin are operator-only (non-requestable) — never advertised (2026-06-30)
     expect(scopesSupported).not.toContain("hub:admin");
     expect(scopesSupported).not.toContain("scribe:admin");
-    // agent isn't in the fixture manifest → its scopes aren't advertised
-    // (hub#…: optional-module scopes only surface when the module is installed).
+    // Retired Agent scopes are no longer part of the first-party catalog.
     expect(scopesSupported).not.toContain("agent:send");
+    // H1.2 — door-contract conformance: the static RFC 8414 fields (endpoints,
+    // response/grant types, PKCE method, token-auth methods) match the shared
+    // contract exactly (V1.4/C1.4 twin coverage, hub half).
+    expect(checkAuthorizationServerMetadata(body, ISSUER, scopesSupported)).toEqual([]);
   });
   test("does NOT advertise non-requestable operator-only scopes", async () => {
@@ -164,7 +172,7 @@ describe("authorizationServerMetadata", () => {
     const body = (await res.json()) as Record<string, unknown>;
     const scopesSupported = body.scopes_supported as string[];
     // Third-party scopes show up (`widget:*` / `mymodule:*` aren't gated
-    // optional-module prefixes — only scribe:/agent: are, see OPTIONAL_MODULE_SCOPES).
+    // optional-module prefixes — only scribe:/surface: are, see OPTIONAL_MODULE_SCOPES).
     expect(scopesSupported).toContain("widget:read");
     expect(scopesSupported).toContain("widget:write");
     expect(scopesSupported).toContain("mymodule:do-thing");
@@ -178,10 +186,10 @@ describe("authorizationServerMetadata", () => {
   });
   test("advertises an optional module's scopes only when it's installed", async () => {
-    // FIRST_PARTY_SCOPES carries scribe:* + agent:send statically. On a
+    // FIRST_PARTY_SCOPES carries scribe:* 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 + Agent access the hub can't
+    // connecting one vault was shown Scribe access the hub can't
     // honor. Vault + hub are core and always advertised.
     const declared = new Set<string>([
       "vault:read",
@@ -189,7 +197,6 @@ describe("authorizationServerMetadata", () => {
       "vault:admin",
       "scribe:transcribe",
       "scribe:admin",
-      "agent:send",
       "hub:admin",
     ]);
     const vaultOnly = {
@@ -217,7 +224,6 @@ describe("authorizationServerMetadata", () => {
     // uninstalled optional-module scopes are dropped
     expect(scopes).not.toContain("scribe:transcribe");
     expect(scopes).not.toContain("scribe:admin");
-    expect(scopes).not.toContain("agent:send");
     // ...but once scribe is installed, its scopes ARE advertised again.
     const withScribe = {
@@ -249,7 +255,6 @@ describe("authorizationServerMetadata", () => {
     // requestability gate (non-requestable, 2026-06-30) doing the work here, not
     // the optional-module-not-installed gate that drops scribe:transcribe above.
     expect(scopes2).not.toContain("scribe:admin");
-    expect(scopes2).not.toContain("agent:send"); // agent still not installed
   });
 });
@@ -265,6 +270,8 @@ describe("protectedResourceMetadata (RFC 9728, closes hub#393)", () => {
     expect(body.resource).toBe(ISSUER);
     expect(body.authorization_servers).toEqual([ISSUER]);
     expect(body.bearer_methods_supported).toEqual(["header"]);
+    // H1.2 — door-contract conformance (V1.4/C1.4 twin coverage, hub half).
+    expect(checkProtectedResourceMetadata(body, ISSUER)).toEqual([]);
     expect(Array.isArray(body.scopes_supported)).toBe(true);
     expect(body.resource_documentation).toMatch(/parachute\.computer/);
   });
@@ -2320,6 +2327,10 @@ describe("handleToken — full OAuth dance", () => {
       expect(tokenBody.token_type).toBe("Bearer");
       expect(tokenBody.scope).toBe("vault:default:read");
       expect(tokenBody.refresh_token.length).toBeGreaterThan(20);
+      // H1.2 — door-contract conformance: token_type/expires_in/scope/access_token
+      // invariants against a REAL `POST /oauth/token` success body (V1.4/C1.4 twin
+      // coverage, hub half).
+      expect(checkTokenResponseInvariants(tokenBody, "vault:default:read")).toEqual([]);
       // JWT must verify against the hub's signing keys, with the right sub +
       // aud (named `vault:default:read` → "vault.default" — RFC 8707-style

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

@@ -66,7 +66,7 @@ describe("mintOperatorToken", () => {
     }
   });
-  test("admin scope-set includes hub:admin + parachute:host:* + vault/scribe/agent admins (#213)", () => {
+  test("admin scope-set includes hub:admin + parachute:host:* + vault/scribe admin scopes (#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,6 @@ describe("mintOperatorToken", () => {
       "parachute:host:vault",
       "vault:admin",
       "scribe:admin",
-      "agent:send",
     ]);
   });
 });

package/src/__tests__/port-assign.test.ts CHANGED Viewed

@@ -3,7 +3,26 @@ import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "no
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { assignPort, assignServicePort } from "../port-assign.ts";
-import { CANONICAL_PORT_MAX, CANONICAL_PORT_MIN } from "../service-spec.ts";
+import { CANONICAL_PORT_MAX, CANONICAL_PORT_MIN, PORT_RESERVATIONS } from "../service-spec.ts";
+describe("PORT_RESERVATIONS (registry shape)", () => {
+  test("every port in the canonical range appears exactly once", () => {
+    const ports = PORT_RESERVATIONS.map((r) => r.port);
+    expect(new Set(ports).size).toBe(ports.length);
+    expect(ports.slice().sort((a, b) => a - b)).toEqual(ports);
+    for (const p of ports) {
+      expect(p).toBeGreaterThanOrEqual(CANONICAL_PORT_MIN);
+      expect(p).toBeLessThanOrEqual(CANONICAL_PORT_MAX);
+    }
+  });
+  test("1944 (parachute-app, hub-parity P5) doesn't collide with any other reservation", () => {
+    const owners = PORT_RESERVATIONS.filter((r) => r.port === 1944);
+    expect(owners).toHaveLength(1);
+    expect(owners[0]?.name).toBe("parachute-app");
+    expect(owners[0]?.status).toBe("assigned");
+  });
+});
 function makeTempDir(): { dir: string; cleanup: () => void } {
   const dir = mkdtempSync(join(tmpdir(), "pcli-port-assign-"));
@@ -25,17 +44,18 @@ describe("assignPort (pure)", () => {
   });
   test("walks the unassigned reservation range when canonical is occupied", () => {
-    // 1940 is taken; canonical reserved range starts at 1944 → first hit.
+    // 1940 is taken. Agent retirement released 1941 as the first walkable slot.
     const result = assignPort(1940, [1940]);
-    expect(result.port).toBe(1944);
+    expect(result.port).toBe(1941);
     expect(result.source).toBe("fallback-in-range");
     expect(result.warning).toMatch(/canonical port 1940 is in use/);
-    expect(result.warning).toMatch(/1944/);
+    expect(result.warning).toMatch(/1941/);
   });
   test("skips reservations that are also occupied", () => {
-    // Canonical 1940 + the first three reserved slots are all in use.
-    const result = assignPort(1940, [1940, 1944, 1945, 1946]);
+    // Canonical 1940 and released slot 1941 are occupied. Assigned slots are
+    // skipped; 1945 is reserved-but-occupied; 1947 is reserved-and-free.
+    const result = assignPort(1940, [1940, 1941, 1945]);
     expect(result.port).toBe(1947);
     expect(result.source).toBe("fallback-in-range");
   });
@@ -60,21 +80,19 @@ describe("assignPort (pure)", () => {
   });
   test("third-party (no canonical slot) jumps straight to the reservation range", () => {
+    // Agent retirement released 1941 as the first walkable slot.
     const result = assignPort(undefined, []);
-    expect(result.port).toBe(1944);
+    expect(result.port).toBe(1941);
     expect(result.source).toBe("fallback-in-range");
     expect(result.warning).toMatch(/no canonical slot/);
-    expect(result.warning).toMatch(/1944/);
+    expect(result.warning).toMatch(/1941/);
   });
   test("third-party with reservations occupied walks further in the range", () => {
-    // PORT_RESERVATIONS post-hub#323: 1944 reserved, 1945 reserved, 1946
-    // assigned (parachute-app — KNOWN_MODULES carries the canonical slot
-    // so the fallback walker doesn't hand it to a third party), 1947
-    // reserved. With 1944 + 1945 occupied, the walker skips the assigned
-    // 1946 slot and lands on the next reserved-and-free port — 1947.
-    const result = assignPort(undefined, [1944, 1945]);
-    expect(result.port).toBe(1947);
+    // With released 1941 occupied, the walker skips assigned 1942–1944 and
+    // lands on the next reserved-and-free port, 1945.
+    const result = assignPort(undefined, [1941]);
+    expect(result.port).toBe(1945);
     expect(result.source).toBe("fallback-in-range");
   });
 });
@@ -145,7 +163,8 @@ describe("assignServicePort (hub#206 — services.json is authoritative)", () =>
         canonical: 1940,
         occupied: [1940],
       });
-      expect(result.port).toBe(1944);
+      // Agent retirement released 1941 as the first walkable slot.
+      expect(result.port).toBe(1941);
       expect(result.source).toBe("fallback-in-range");
       expect(result.warning).toMatch(/canonical port 1940 is in use/);
       // .env stays bit-for-bit identical.
@@ -162,7 +181,8 @@ describe("assignServicePort (hub#206 — services.json is authoritative)", () =>
       const result = assignServicePort({
         occupied: [],
       });
-      expect(result.port).toBe(1944);
+      // Agent retirement released 1941 as the first walkable slot.
+      expect(result.port).toBe(1941);
       expect(result.source).toBe("fallback-in-range");
       expect(existsSync(envPath)).toBe(false);
     } finally {

package/src/__tests__/root-serve.test.ts ADDED Viewed

@@ -0,0 +1,139 @@
+/**
+ * Tests for `src/root-serve.ts` — serving the Parachute app AT the origin root
+ * (`root_mode = serve-app`).
+ *
+ * Covers `serveAppAtRoot` (the static file-or-SPA-shell decision, Accept-gated,
+ * reserved-prefix-guarded, traversal-guarded) and `makeAppDistResolver` (success
+ * memoization + failure NON-caching for dynamic recovery).
+ */
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { makeAppDistResolver, serveAppAtRoot } from "../root-serve.ts";
+let dist: string;
+let root: string;
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), "phub-root-serve-"));
+  dist = join(root, "dist");
+  mkdirSync(join(dist, "assets"), { recursive: true });
+  writeFileSync(join(dist, "index.html"), "<!doctype html><title>App</title>");
+  writeFileSync(join(dist, "assets", "index-abc.js"), "console.log('app')");
+  writeFileSync(join(dist, "manifest.webmanifest"), '{"name":"Parachute"}');
+  writeFileSync(join(dist, "sw.js"), "self.addEventListener('install',()=>{})");
+});
+afterEach(() => {
+  rmSync(root, { recursive: true, force: true });
+});
+function get(pathname: string, accept?: string): Request {
+  return new Request(`http://localhost${pathname}`, {
+    method: "GET",
+    headers: accept ? { accept } : {},
+  });
+}
+describe("serveAppAtRoot", () => {
+  test("serves index.html at `/`", async () => {
+    const res = serveAppAtRoot(dist, get("/", "text/html"), "/");
+    expect(res).not.toBeNull();
+    expect(res?.headers.get("content-type")).toContain("text/html");
+    expect(await res?.text()).toContain("<title>App</title>");
+  });
+  test("serves an existing asset with an inferred content-type", async () => {
+    const res = serveAppAtRoot(dist, get("/assets/index-abc.js", "*/*"), "/assets/index-abc.js");
+    expect(res).not.toBeNull();
+    expect(res?.headers.get("content-type") ?? "").toMatch(/javascript/);
+    expect(await res?.text()).toContain("console.log");
+  });
+  test("serves the PWA manifest with the application/manifest+json override", () => {
+    const res = serveAppAtRoot(dist, get("/manifest.webmanifest", "*/*"), "/manifest.webmanifest");
+    expect(res).not.toBeNull();
+    expect(res?.headers.get("content-type")).toBe("application/manifest+json");
+  });
+  test("serves the service worker as a real file (not the SPA shell)", async () => {
+    const res = serveAppAtRoot(dist, get("/sw.js", "*/*"), "/sw.js");
+    expect(res).not.toBeNull();
+    expect(await res?.text()).toContain("addEventListener");
+  });
+  test("SPA fallback: an unclaimed HTML deep link gets index.html", async () => {
+    const res = serveAppAtRoot(dist, get("/some/app/route", "text/html"), "/some/app/route");
+    expect(res).not.toBeNull();
+    expect(await res?.text()).toContain("<title>App</title>");
+  });
+  test("non-HTML unclaimed request → null (branded 404 tail)", () => {
+    expect(serveAppAtRoot(dist, get("/nope.json", "application/json"), "/nope.json")).toBeNull();
+    // A missing asset fetched with Accept: */* is not an HTML navigation → null.
+    expect(serveAppAtRoot(dist, get("/assets/missing.js", "*/*"), "/assets/missing.js")).toBeNull();
+  });
+  test("non-GET → null (a non-GET unclaimed path keeps its default)", () => {
+    const post = new Request("http://localhost/", {
+      method: "POST",
+      headers: { accept: "text/html" },
+    });
+    expect(serveAppAtRoot(dist, post, "/")).toBeNull();
+  });
+  test("reserved hub/protocol prefixes keep the branded 404 even for HTML nav", () => {
+    for (const p of ["/api/bogus", "/oauth/typo", "/.well-known/nope"]) {
+      expect(serveAppAtRoot(dist, get(p, "text/html"), p)).toBeNull();
+    }
+  });
+  test("path traversal cannot escape dist", () => {
+    // A crafted encoded traversal joins outside dist → falls through (null).
+    const p = "/assets/..%2f..%2f..%2fetc%2fpasswd";
+    expect(serveAppAtRoot(dist, get(p, "*/*"), p)).toBeNull();
+  });
+  test("a resolved dist whose index.html vanished → null (no broken shell)", () => {
+    rmSync(join(dist, "index.html"));
+    expect(serveAppAtRoot(dist, get("/", "text/html"), "/")).toBeNull();
+  });
+  test("malformed percent-encoding → null (no URIError thrown → branded 404, not 500)", () => {
+    // decodeURIComponent throws URIError on a bad escape; the guard must swallow
+    // it and fall through so the dispatch never 500s on a garbage asset URL.
+    for (const p of ["/assets/%ZZ", "/foo%", "/%E0%A4%A", "/bar%2"]) {
+      expect(() => serveAppAtRoot(dist, get(p, "*/*"), p)).not.toThrow();
+      expect(serveAppAtRoot(dist, get(p, "*/*"), p)).toBeNull();
+    }
+    // Even an HTML navigation with bad encoding falls through (redirect-mode
+    // parity) rather than shelling.
+    expect(serveAppAtRoot(dist, get("/foo%", "text/html"), "/foo%")).toBeNull();
+  });
+});
+describe("makeAppDistResolver", () => {
+  test("returns the resolved dist and memoizes a success", () => {
+    let calls = 0;
+    const resolve = makeAppDistResolver(() => {
+      calls++;
+      return dist;
+    });
+    expect(resolve()).toBe(dist);
+    expect(resolve()).toBe(dist);
+    expect(calls).toBe(1); // success cached — only resolved once
+  });
+  test("does NOT cache a failure — recovers once the app is installed", () => {
+    let installed = false;
+    const resolve = makeAppDistResolver(() => {
+      if (!installed) throw new Error("not installed");
+      return dist;
+    });
+    expect(resolve()).toBeNull(); // not installed yet
+    expect(resolve()).toBeNull(); // still probing, still null
+    installed = true;
+    expect(resolve()).toBe(dist); // picked up without a restart
+  });
+});

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

@@ -19,7 +19,6 @@ describe("SCOPE_EXPLANATIONS", () => {
       "vault:admin",
       "scribe:transcribe",
       "scribe:admin",
-      "agent:send",
       "hub:admin",
       "parachute:host:admin",
       // Account scopes (Parachute App campaign, Phase 2).
@@ -187,7 +186,6 @@ describe("isRequestableScope", () => {
   test("true for non-admin first-party scopes", () => {
     expect(isRequestableScope("vault:read")).toBe(true);
     expect(isRequestableScope("vault:admin")).toBe(true);
-    expect(isRequestableScope("agent:send")).toBe(true);
     expect(isRequestableScope("scribe:transcribe")).toBe(true);
   });