@openparachute/hub 0.7.6 → 0.7.7-rc.13

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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -19,9 +19,11 @@ describe("SCOPE_EXPLANATIONS", () => {
       "vault:admin",
       "scribe:transcribe",
       "scribe:admin",
-      "agent:send",
       "hub:admin",
       "parachute:host:admin",
+      // Account scopes (Parachute App campaign, Phase 2).
+      "account:self:admin",
+      "account:self:read",
     ];
     for (const s of expected) {
       expect(SCOPE_EXPLANATIONS[s]).toBeDefined();
@@ -156,6 +158,14 @@ describe("NON_REQUESTABLE_SCOPES (#96)", () => {
     expect(NON_REQUESTABLE_SCOPES.has("scribe:admin")).toBe(true);
   });
 
+  test("contains the account scopes (App campaign Phase 2 — cookie-minted only)", () => {
+    // account:self:{admin,read} are minted exclusively by POST /account/token
+    // (cookie→bearer), never via /oauth/authorize — a third-party app pointed at
+    // the hub AS must not be able to consent its way to account authority.
+    expect(NON_REQUESTABLE_SCOPES.has("account:self:admin")).toBe(true);
+    expect(NON_REQUESTABLE_SCOPES.has("account:self:read")).toBe(true);
+  });
+
   test("every non-requestable scope is a known first-party scope", () => {
     for (const s of NON_REQUESTABLE_SCOPES) {
       expect(FIRST_PARTY_SCOPES).toContain(s);
@@ -176,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);
   });
 
@@ -195,6 +204,17 @@ describe("isRequestableScope", () => {
     expect(isRequestableScope("vault:my-techne_2:admin")).toBe(true);
   });
 
+  test("account scopes are non-requestable (cookie-minted only, App campaign)", () => {
+    expect(isRequestableScope("account:self:admin")).toBe(false);
+    expect(isRequestableScope("account:self:read")).toBe(false);
+    // explainScope resolves them (direct SCOPE_EXPLANATIONS keys) with the
+    // right levels, so scopeIsAdmin recognizes the admin form.
+    expect(explainScope("account:self:admin")?.level).toBe("admin");
+    expect(explainScope("account:self:read")?.level).toBe("read");
+    expect(scopeIsAdmin("account:self:admin")).toBe(true);
+    expect(scopeIsAdmin("account:self:read")).toBe(false);
+  });
+
   test("host-level operator scopes stay non-requestable", () => {
     // The asymmetry the single-consent change preserved: per-vault admin is
     // now requestable (capped at mint), but host-wide operator authority is

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

@@ -395,46 +395,39 @@ describe("bootSupervisedModules", () => {
   });
 });
 
-// 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 — module now agent)", () => {
+// A transiently wrong services.json port for a fixed-port first-party module can
+// self-perpetuate through supervisor env, probes, and proxy routing. The boot path
+// snaps supported modules back to canonical and persists the fix.
+describe("reconcilePortToCanonical", () => {
   let h: Harness;
   beforeEach(() => {
     h = makeHarness();
   });
   afterEach(() => h.cleanup());
 
-  // The live-observed signature: the agent (then channel) row carried 19415 instead of its
-  // canonical 1941.
-  const DRIFTED_CHANNEL: ServiceEntry = {
-    name: "parachute-agent",
+  const DRIFTED_SCRIBE: ServiceEntry = {
+    name: "parachute-scribe",
     port: 19415,
-    paths: ["/agent"],
+    paths: ["/scribe"],
     health: "/health",
     version: "0.1.0",
   };
 
   test("snaps a drifted fixed-port row back to canonical + persists it", () => {
-    writeManifest({ services: [DRIFTED_CHANNEL] }, h.manifestPath);
+    writeManifest({ services: [DRIFTED_SCRIBE] }, h.manifestPath);
     const logs: string[] = [];
 
-    const reconciled = reconcilePortToCanonical(DRIFTED_CHANNEL, h.manifestPath, (l) =>
+    const reconciled = reconcilePortToCanonical(DRIFTED_SCRIBE, h.manifestPath, (l) =>
       logs.push(l),
     );
 
-    // 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 `/agent/*` keeps routing to the dead 19415.
+    expect(reconciled.port).toBe(1943);
     const onDisk = readManifestLenient(h.manifestPath).services.find(
-      (s) => s.name === "parachute-agent",
+      (s) => s.name === "parachute-scribe",
     );
-    expect(onDisk?.port).toBe(1941);
+    expect(onDisk?.port).toBe(1943);
     expect(
-      logs.some((l) => l.includes("reconciled") && l.includes("19415") && l.includes("1941")),
+      logs.some((l) => l.includes("reconciled") && l.includes("19415") && l.includes("1943")),
     ).toBe(true);
   });
 
@@ -460,31 +453,30 @@ describe("reconcilePortToCanonical (channel#41 — module now agent)", () => {
   });
 
   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 the agent module's to take. Leave the
-    // drift; the supervisor's squatter detection surfaces it.
+    // Another row occupies Scribe's canonical 1943, so reconciliation must not
+    // steal it; leave the drift for squatter diagnostics.
     const squatter: ServiceEntry = {
       name: "parachute-vault",
-      port: 1941, // unusual, but it owns this slot right now
+      port: 1943,
       paths: ["/vault/default"],
       health: "/vault/default/health",
       version: "0.4.5",
     };
-    writeManifest({ services: [squatter, DRIFTED_CHANNEL] }, h.manifestPath);
+    writeManifest({ services: [squatter, DRIFTED_SCRIBE] }, h.manifestPath);
     const logs: string[] = [];
 
-    const out = reconcilePortToCanonical(DRIFTED_CHANNEL, h.manifestPath, (l) => logs.push(l));
+    const out = reconcilePortToCanonical(DRIFTED_SCRIBE, h.manifestPath, (l) => logs.push(l));
 
     expect(out.port).toBe(19415); // unchanged
     const onDisk = readManifestLenient(h.manifestPath).services.find(
-      (s) => s.name === "parachute-agent",
+      (s) => s.name === "parachute-scribe",
     );
     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 agent row", async () => {
-    writeManifest({ services: [DRIFTED_CHANNEL] }, h.manifestPath);
+  test("boot path injects and persists the supported module's canonical port", async () => {
+    writeManifest({ services: [DRIFTED_SCRIBE] }, h.manifestPath);
     const recorder = makeRecorder();
     const sup = new Supervisor({ spawnFn: recorder.spawn });
 
@@ -493,15 +485,12 @@ describe("reconcilePortToCanonical (channel#41 — module now agent)", () => {
       configDir: h.dir,
     });
 
-    // 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("agent");
-    expect(recorder.calls[0]?.env?.PORT).toBe("1941");
-    // services.json row is reconciled → proxy routes /agent/* to 1941.
+    expect(recorder.calls[0]?.short).toBe("scribe");
+    expect(recorder.calls[0]?.env?.PORT).toBe("1943");
     const onDisk = readManifestLenient(h.manifestPath).services.find(
-      (s) => s.name === "parachute-agent",
+      (s) => s.name === "parachute-scribe",
     );
-    expect(onDisk?.port).toBe(1941);
+    expect(onDisk?.port).toBe(1943);
   });
 
   test("boot path leaves a non-drifted vault row's port untouched", async () => {

package/src/__tests__/service-spec-discovery.test.ts

@@ -2,6 +2,8 @@ import { describe, expect, test } from "bun:test";
 import {
   FIRST_PARTY_FALLBACKS,
   KNOWN_MODULES,
+  PORT_RESERVATIONS,
+  RETIRED_MODULES,
   discoverableShorts,
   findServiceByShort,
   focusForShort,
@@ -25,20 +27,18 @@ describe("discoverableShorts", () => {
     expect(shorts.length).toBe(new Set(shorts).size);
   });
 
-  test("includes agent (the module the whitelist used to hide) + the core set", () => {
+  test("includes the supported module set and excludes retired Agent", () => {
     const shorts = discoverableShorts();
-    for (const s of ["vault", "scribe", "surface", "agent", "notes"]) {
+    for (const s of ["vault", "scribe", "surface", "app", "notes"]) {
       expect(shorts).toContain(s);
     }
+    expect(shorts).not.toContain("agent");
   });
 
   test("FIRST_PARTY_FALLBACKS shorts lead KNOWN_MODULES shorts (registry order)", () => {
     const shorts = discoverableShorts();
-    // notes (the remaining FALLBACK — agent moved to KNOWN_MODULES in
-    // boundary D3) appears before vault (KNOWN_MODULES) in the union.
+    // notes (a FALLBACK) appears before vault (KNOWN_MODULES) in the union.
     expect(shorts.indexOf("notes")).toBeLessThan(shorts.indexOf("vault"));
-    // agent rides in KNOWN_MODULES now but is still discoverable.
-    expect(shorts).toContain("agent");
   });
 });
 
@@ -106,9 +106,30 @@ describe("runner registry removal (2026-07-01)", () => {
   });
 });
 
+describe("Agent module retirement (2026-07-15)", () => {
+  test("is no longer known, discoverable, or resolvable", () => {
+    expect(isKnownModuleShort("agent")).toBe(false);
+    expect(discoverableShorts()).not.toContain("agent");
+    expect("agent" in KNOWN_MODULES).toBe(false);
+    expect(shortNameForManifest("parachute-agent")).toBeUndefined();
+    expect(shortNameForManifest("parachute-channel")).toBeUndefined();
+  });
+
+  test("retires every historical row name and releases port 1941", () => {
+    expect(RETIRED_MODULES.agent).toBeDefined();
+    expect(RETIRED_MODULES["parachute-agent"]).toBeDefined();
+    expect(RETIRED_MODULES["parachute-channel"]).toBeDefined();
+    expect(PORT_RESERVATIONS.find((entry) => entry.port === 1941)).toEqual({
+      port: 1941,
+      name: "unassigned",
+      status: "reserved",
+    });
+  });
+});
+
 describe("isKnownModuleShort", () => {
   test("true for every known module (the install/config gate)", () => {
-    for (const s of ["vault", "scribe", "surface", "agent", "notes"]) {
+    for (const s of ["vault", "scribe", "surface", "app", "notes"]) {
       expect(isKnownModuleShort(s)).toBe(true);
     }
   });
@@ -119,12 +140,6 @@ describe("isKnownModuleShort", () => {
   });
 });
 
-// Regression: services.json rows carry the MANIFEST name (`parachute-agent`),
-// not the bare short (`agent`). The connection/channels wiring used to do
-// `services.find((s) => s.name === "agent")`, which never matched the on-disk
-// row → agentOrigin null → a spurious "agent module is not installed" when
-// linking a vault-backed channel. findServiceByShort resolves through the
-// short↔manifest map so the lookup hits the real row.
 describe("findServiceByShort", () => {
   const services = [
     { name: "parachute-vault-default", port: 1940 },
@@ -132,29 +147,9 @@ describe("findServiceByShort", () => {
     { name: "parachute-scribe", port: 1943 },
   ];
 
-  test("matches a row by its manifest name via the short↔manifest map", () => {
-    const found = findServiceByShort(services, "agent");
-    expect(found?.name).toBe("parachute-agent");
-    expect(found?.port).toBe(1941);
-  });
-
-  test("the naive `name === short` comparison would have missed it (the bug)", () => {
-    // The exact pre-fix predicate: a bare short never matches a manifest-named row.
-    expect(services.find((s) => s.name === "agent")).toBeUndefined();
-    // The fix finds it.
-    expect(findServiceByShort(services, "agent")).toBeDefined();
-  });
-
-  test("resolves a legacy parachute-channel row to short `agent` (rename back-compat)", () => {
-    // Un-upgraded operators carry a `parachute-channel` row; the
-    // LEGACY_MANIFEST_ALIASES fallback keeps it routing to the agent module
-    // until the daemon re-registers under `parachute-agent`.
-    const legacy = [{ name: "parachute-channel", port: 1941 }];
-    expect(findServiceByShort(legacy, "agent")?.port).toBe(1941);
-  });
-
-  test("resolves scribe too, and returns undefined for an absent module", () => {
+  test("resolves supported modules and not retired Agent rows", () => {
     expect(findServiceByShort(services, "scribe")?.port).toBe(1943);
+    expect(findServiceByShort(services, "agent")).toBeUndefined();
     expect(findServiceByShort(services, "runner")).toBeUndefined();
   });
 });