@openparachute/hub 0.7.6-rc.4 → 0.7.7-rc.12

package/src/__tests__/bearer-scheme-casing.test.ts

@@ -0,0 +1,110 @@
+/**
+ * H1.1 (contracts-brief H1) — Bearer scheme-casing unification.
+ *
+ * RFC 7235 §2.1: the auth-scheme token ("Bearer") is case-insensitive; the
+ * credential (the token itself) is opaque and must be passed VERBATIM — never
+ * case-folded, never trimmed beyond surrounding whitespace. This mirrors
+ * parachute-vault's V1.4 (`BEARER_PREFIX`, case-insensitive) and
+ * parachute-cloud's C1.3 (`workers/vault/src/auth.ts:130-143`) — the other two
+ * door surfaces already converged on this shape; this file (plus the per-site
+ * tests below) closes the hub's half.
+ *
+ * Every converted call site (`src/api-hub-upgrade.ts`, `src/api-tokens.ts`,
+ * `src/api-revoke-token.ts`, `src/api-settings-root-redirect.ts`,
+ * `src/api-modules.ts` ×2, `src/api-modules-ops.ts`, `src/api-mint-token.ts`,
+ * `src/api-settings-hub-origin.ts`, `src/admin-surfaces.ts`,
+ * `src/admin-connections.ts` ×2, `src/audience-gate.ts`) uses the SAME
+ * two-step shape: a case-insensitive `/^Bearer\s+/i` scheme test, followed by
+ * the PRE-EXISTING `header.slice("Bearer ".length).trim()` extraction
+ * (unchanged — "Bearer ".length === "bearer ".length === 7, so the fixed-
+ * offset slice is casing-agnostic and the token substring is untouched).
+ * `src/admin-auth.ts`'s `extractBearerToken` (the documented shared helper,
+ * used by `requireScope` + several `/admin/*` and `/api/*` routes already)
+ * uses an equivalent `/^Bearer\s+(.+)$/i` regex. This file pins that shared
+ * pattern directly, independent of any one handler's DB/deps scaffolding.
+ *
+ * Live end-to-end coverage (a lowercase/mixed-case Authorization header
+ * reaching a real handler and authenticating) lives alongside each site's
+ * existing tests, NOT here:
+ *   - src/__tests__/api-hub-upgrade.test.ts
+ *   - src/__tests__/api-tokens.test.ts
+ *   - src/__tests__/api-revoke-token.test.ts
+ *   - src/__tests__/api-settings-root-redirect.test.ts
+ *   - src/__tests__/api-modules.test.ts (both handleApiModules + handleApiModulesChannel)
+ *   - src/__tests__/api-modules-ops.test.ts
+ *   - src/__tests__/api-mint-token.test.ts
+ *   - src/__tests__/api-settings-hub-origin.test.ts
+ *   - src/__tests__/admin-surfaces.test.ts
+ *   - src/__tests__/admin-connections-credentials.test.ts (renew + claim)
+ *   - src/__tests__/audience-gate.test.ts
+ */
+import { describe, expect, test } from "bun:test";
+import { extractBearerToken } from "../admin-auth.ts";
+
+/** The exact regex + slice shape used at all 12 converted call sites. */
+function siteShapeExtract(header: string | null): string | null {
+  if (!header || !/^Bearer\s+/i.test(header)) return null;
+  return header.slice("Bearer ".length).trim();
+}
+
+// A JWT-shaped token: base64url alphabet includes uppercase letters, so any
+// real access/operator token already exercises "verbatim, case preserved."
+// Use one explicitly so the pin doesn't depend on a real signer.
+const MIXED_CASE_TOKEN = "eyJhbGciOiJFZERTQSJ9.eyJzdWIiOiJBQkNkZWYxMjMifQ.SIGNATURE-Xyz";
+
+describe("H1.1 — site-shape extraction (regex test + fixed-offset slice)", () => {
+  test.each([
+    ["Bearer", `Bearer ${MIXED_CASE_TOKEN}`],
+    ["bearer", `bearer ${MIXED_CASE_TOKEN}`],
+    ["BEARER", `BEARER ${MIXED_CASE_TOKEN}`],
+    ["BeArEr", `BeArEr ${MIXED_CASE_TOKEN}`],
+    ["bEARER", `bEARER ${MIXED_CASE_TOKEN}`],
+  ])("scheme %s → token extracted verbatim, case preserved", (_label, header) => {
+    expect(siteShapeExtract(header)).toBe(MIXED_CASE_TOKEN);
+  });
+
+  test("wrong scheme keyword (not Bearer) → rejected regardless of case", () => {
+    expect(siteShapeExtract(`Basic ${MIXED_CASE_TOKEN}`)).toBeNull();
+    expect(siteShapeExtract(`Digest ${MIXED_CASE_TOKEN}`)).toBeNull();
+  });
+
+  test("missing header → rejected", () => {
+    expect(siteShapeExtract(null)).toBeNull();
+  });
+
+  test("scheme with no token → empty string (site's own 'empty bearer token' check catches this)", () => {
+    expect(siteShapeExtract("Bearer ")).toBe("");
+    expect(siteShapeExtract("bearer ")).toBe("");
+  });
+
+  test("extra internal whitespace after the scheme is tolerated (trim absorbs it), casing still ignored", () => {
+    expect(siteShapeExtract(`bearer   ${MIXED_CASE_TOKEN}`)).toBe(MIXED_CASE_TOKEN);
+    expect(siteShapeExtract(`Bearer\t${MIXED_CASE_TOKEN}`)).toBe(MIXED_CASE_TOKEN);
+  });
+});
+
+describe("H1.1 — admin-auth.ts extractBearerToken (the documented shared helper)", () => {
+  function reqWith(header: string | undefined): Request {
+    return new Request("http://127.0.0.1/admin/probe", {
+      headers: header !== undefined ? { authorization: header } : {},
+    });
+  }
+
+  test.each([
+    ["Bearer", `Bearer ${MIXED_CASE_TOKEN}`],
+    ["bearer", `bearer ${MIXED_CASE_TOKEN}`],
+    ["BeArEr", `BeArEr ${MIXED_CASE_TOKEN}`],
+  ])("scheme %s → extractBearerToken returns the token verbatim", (_label, header) => {
+    expect(extractBearerToken(reqWith(header))).toBe(MIXED_CASE_TOKEN);
+  });
+
+  test("missing Authorization header → AdminAuthError(401)", () => {
+    expect(() => extractBearerToken(reqWith(undefined))).toThrow(/missing Authorization header/);
+  });
+
+  test("non-Bearer scheme → AdminAuthError(401)", () => {
+    expect(() => extractBearerToken(reqWith(`Basic ${MIXED_CASE_TOKEN}`))).toThrow(
+      /Authorization header must be 'Bearer <token>'/,
+    );
+  });
+});

package/src/__tests__/chrome-strip.test.ts

@@ -99,6 +99,20 @@ describe("shouldInjectChrome", () => {
     expect(shouldInjectChrome("/surface/notes-archive/")).toBe(true);
   });
 
+  test("default: opts out the app's surface mount at /surface/parachute/* (W2-12)", () => {
+    expect(shouldInjectChrome("/surface/parachute")).toBe(false);
+    expect(shouldInjectChrome("/surface/parachute/")).toBe(false);
+    expect(shouldInjectChrome("/surface/parachute/index.html")).toBe(false);
+    expect(shouldInjectChrome("/surface/parachute/assets/index-XXX.js")).toBe(false);
+  });
+
+  test("the /surface/parachute/ opt-out does not over-match sibling paths", () => {
+    // `/surface/parachutes` must NOT match `/surface/parachute/` — the slash
+    // boundary check applies to the new entry the same as the legacy one.
+    expect(shouldInjectChrome("/surface/parachutes")).toBe(true);
+    expect(shouldInjectChrome("/surface/parachute-club/")).toBe(true);
+  });
+
   test("custom opt-out list is honored", () => {
     expect(shouldInjectChrome("/foo/bar", ["/foo/"])).toBe(false);
     expect(shouldInjectChrome("/baz", ["/foo/"])).toBe(true);
@@ -111,8 +125,11 @@ describe("shouldInjectChrome", () => {
     expect(shouldInjectChrome("/foo/bar", ["/foo"])).toBe(false);
   });
 
-  test("the canonical opt-out list contains /surface/notes/", () => {
+  test("the canonical opt-out list contains BOTH /surface/notes/ and /surface/parachute/", () => {
+    // W2-12 is additive: the legacy notes-ui mount keeps its opt-out for
+    // existing installs; the renamed app-surface mount gets its own.
     expect(CHROME_OPT_OUT_PREFIXES).toContain("/surface/notes/");
+    expect(CHROME_OPT_OUT_PREFIXES).toContain("/surface/parachute/");
   });
 });
 

package/src/__tests__/doctor.test.ts

@@ -502,7 +502,7 @@ describe("doctor — canonical-port-drift detection (read-only)", () => {
   test("a non-canonical port + a duplicate-port pair → port-drift WARNs naming the services", async () => {
     const h = makeHarness();
     try {
-      // scribe drifted off 1943 onto 1944; agent also squats 1944 (a collision).
+      // Scribe drifted off 1943 onto Surface's canonical 1946 (a collision).
       writeManifestRows(h.manifestPath, [
         {
           name: "parachute-vault",
@@ -511,21 +511,17 @@ describe("doctor — canonical-port-drift detection (read-only)", () => {
           health: "/h",
           version: "1",
         },
-        { name: "parachute-scribe", port: 1944, paths: ["/scribe"], health: "/h", version: "1" },
-        { name: "parachute-agent", port: 1944, paths: ["/agent"], health: "/h", version: "1" },
+        { name: "parachute-scribe", port: 1946, paths: ["/scribe"], health: "/h", version: "1" },
+        { name: "parachute-surface", port: 1946, paths: ["/surface"], health: "/h", version: "1" },
       ]);
       seedOperatorToken(h.configDir);
       const { code, checks } = await runDoctor(h, healthyDeps());
       const pd = byName(checks, "port-drift");
       expect(pd?.status).toBe("warn");
-      // Names the drifted service AND the colliding pair.
       expect(pd?.detail).toContain("scribe");
-      expect(pd?.detail).toContain("1944");
-      expect(pd?.detail).toContain("parachute-scribe + parachute-agent");
+      expect(pd?.detail).toContain("1946");
+      expect(pd?.detail).toContain("parachute-scribe + parachute-surface");
       expect(pd?.fix).toBe("parachute doctor --fix");
-      // Drift is advisory — exit stays 0 (a WARN, not a FAIL). The duplicate
-      // rows also trip modules-alive (both can't bind 1944) but that's expected
-      // for this fixture; we only assert on port-drift here.
       expect([0, 1]).toContain(code);
     } finally {
       h.cleanup();
@@ -732,22 +728,19 @@ describe("doctor --fix — canonical-port repair (confirm-gated, idempotent, non
   test("--fix reports a duplicate-port collision but does not auto-resolve it", async () => {
     const h = makeHarness();
     try {
-      // Two services collide on 1944; neither is on its canonical slot. The
-      // diff fixes the canonical drift; the collision is reported, not guessed.
+      // Two supported services collide on unassigned 1945; both are off canonical.
       writeManifestRows(h.manifestPath, [
-        { name: "parachute-scribe", port: 1944, paths: ["/scribe"], health: "/h", version: "1" },
-        { name: "parachute-agent", port: 1944, paths: ["/agent"], health: "/h", version: "1" },
+        { name: "parachute-scribe", port: 1945, paths: ["/scribe"], health: "/h", version: "1" },
+        { name: "parachute-surface", port: 1945, paths: ["/surface"], health: "/h", version: "1" },
       ]);
       const { code, lines } = await runFix(h, {}, { yes: true });
       const text = lines.join("\n");
       expect(text.toLowerCase()).toContain("shared by");
-      expect(text).toContain("parachute-scribe + parachute-agent");
-      // scribe → 1943 and agent → 1941 are both off 1944, so after the rewrite
-      // they no longer collide; fix applied, exit 0.
+      expect(text).toContain("parachute-scribe + parachute-surface");
       expect(code).toBe(0);
       const rows = readRows(h.manifestPath);
       expect(rows.find((r) => r.name === "parachute-scribe")?.port).toBe(1943);
-      expect(rows.find((r) => r.name === "parachute-agent")?.port).toBe(1941);
+      expect(rows.find((r) => r.name === "parachute-surface")?.port).toBe(1946);
     } finally {
       h.cleanup();
     }

package/src/__tests__/door-contract-parity.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, test } from "bun:test";
+import {
+  ACCESS_TOKEN_TTL_SECONDS as CONTRACT_ACCESS_TTL,
+  ACCOUNT_SELF_ADMIN_SCOPE as CONTRACT_ACCOUNT_ADMIN,
+  ACCOUNT_SELF_READ_SCOPE as CONTRACT_ACCOUNT_READ,
+  REFRESH_GRACE_MS as CONTRACT_REFRESH_GRACE,
+  REFRESH_TOKEN_TTL_MS as CONTRACT_REFRESH_TTL,
+  hasAccountScope,
+} from "@openparachute/door-contract";
+import { ACCESS_TOKEN_TTL_SECONDS, REFRESH_GRACE_MS, REFRESH_TOKEN_TTL_MS } from "../jwt-sign.ts";
+import { ACCOUNT_SELF_ADMIN_SCOPE, ACCOUNT_SELF_READ_SCOPE } from "../scope-explanations.ts";
+
+/**
+ * Drift detector for the shared door contract (Cloud+Hub shared-core campaign,
+ * parachute-cloud#116, Phase A). The hub's issuer constants + account-scope
+ * strings are duplicated in `@openparachute/door-contract` (the hosted cloud
+ * door duplicates them too). These assertions bind the hub's LIVE runtime values
+ * to the shared canon — no runtime code path is changed by this test, but any
+ * future divergence between the hub's issuer and the shared contract fails here,
+ * forcing the change through the shared package (and thus the cloud twin).
+ *
+ * When the hub adopts the contract at runtime (Phase B — `jwt-sign.ts` imports
+ * these constants instead of re-declaring them), these become identity checks;
+ * until then they are the guardrail.
+ */
+describe("door-contract parity — token constants", () => {
+  test("the hub's issuer TTL/grace equal the shared contract", () => {
+    expect(ACCESS_TOKEN_TTL_SECONDS).toBe(CONTRACT_ACCESS_TTL);
+    expect(REFRESH_TOKEN_TTL_MS).toBe(CONTRACT_REFRESH_TTL);
+    expect(REFRESH_GRACE_MS).toBe(CONTRACT_REFRESH_GRACE);
+  });
+});
+
+describe("door-contract parity — account scopes", () => {
+  test("the hub's account scope strings equal the shared contract", () => {
+    expect(ACCOUNT_SELF_ADMIN_SCOPE).toBe(CONTRACT_ACCOUNT_ADMIN);
+    expect(ACCOUNT_SELF_READ_SCOPE).toBe(CONTRACT_ACCOUNT_READ);
+  });
+
+  test("the shared checker agrees with the hub's admin⊇read intent", () => {
+    // The hub's `/account/*` gate treats `account:self:admin` as satisfying a
+    // read requirement (scope-explanations.ts). The shared checker must too.
+    expect(hasAccountScope([ACCOUNT_SELF_ADMIN_SCOPE], "self", "read")).toBe(true);
+    expect(hasAccountScope([ACCOUNT_SELF_READ_SCOPE], "self", "admin")).toBe(false);
+  });
+});

package/src/__tests__/hub-server.test.ts

@@ -993,6 +993,29 @@ describe("hubFetch routing", () => {
     }
   });
 
+  test("retired Agent token endpoints neither mint nor redirect", async () => {
+    const h = makeHarness();
+    try {
+      const dist = join(h.dir, "dist");
+      mkdirIfMissing(dist);
+      writeFileSync(join(dist, "index.html"), "<!doctype html><title>admin shell</title>");
+      const fetcher = hubFetch(h.dir, { spaDistDir: dist });
+
+      for (const path of ["/admin/agent-token", "/admin/channel-token"]) {
+        const post = await fetcher(req(path, { method: "POST" }));
+        expect(post.status).toBe(405);
+        expect(post.headers.get("location")).toBeNull();
+
+        const get = await fetcher(req(path));
+        expect(get.status).toBe(200);
+        expect(get.headers.get("location")).toBeNull();
+        expect(await get.text()).toContain("admin shell");
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
   // 301 back-compat redirects (closes hub#231): pre-rename SPA URLs
   // 301-redirect to the new /admin/* mount. Tests cover every entry in the
   // dispatch — operator bookmarks landing on any of these still work.
@@ -1249,6 +1272,20 @@ describe("hubFetch routing", () => {
     }
   });
 
+  test("retired /channel/* paths no longer redirect to /agent/*", async () => {
+    const h = makeHarness();
+    try {
+      writeManifest({ services: [] }, h.manifestPath);
+      const res = await hubFetch(h.dir, { manifestPath: h.manifestPath })(
+        req("/channel/mcp/default?q=1"),
+      );
+      expect(res.status).toBe(404);
+      expect(res.headers.get("location")).toBeNull();
+    } finally {
+      h.cleanup();
+    }
+  });
+
   test("/hub/<unknown> (no SPA mount anymore) → 404", async () => {
     const h = makeHarness();
     try {

package/src/__tests__/hub.test.ts

@@ -239,6 +239,35 @@ describe("renderHub — signed-out slimming (operator feedback)", () => {
   });
 });
 
+describe("renderHub — Get started tiles are uis[]-driven (W2-12)", () => {
+  // The tile logic runs client-side inside the discovery IIFE; these pins
+  // assert the emitted script's SHAPE (the JS-parses check above guards its
+  // validity). The section is uis[]-driven — one tile per active uis[]
+  // sub-unit, whichever mount identity (/surface/notes or
+  // /surface/parachute) an install serves — with the pre-W2-12 hardcoded
+  // "Open Notes" tile demoted to a fallback for surface-host rows that
+  // predate uis{} self-registration.
+  const html = renderHub({
+    session: { displayName: "operator", csrfToken: "csrf-w212" },
+  });
+
+  test("the discovery script iterates uis[] sub-units", () => {
+    expect(html).toContain("svc.uis");
+    // Inactive sub-units are skipped; absent status counts as active.
+    expect(html).toContain("ui.status");
+  });
+
+  test("the legacy 'Open Notes' hardcode survives only as the no-uis fallback", () => {
+    // Still present (pre-uis surface-host installs keep their CTA) …
+    expect(html).toContain("Open Notes");
+    expect(html).toContain("'/surface/notes/'");
+    // … but no longer keyed on the bare presence of parachute-surface as
+    // the PRIMARY path: the uis[] loop renders first, the hasSurface check
+    // only backstops an empty tile list.
+    expect(html).toContain("Legacy fallback");
+  });
+});
+
 describe("renderHub — signed-in indicator (rc.13)", () => {
   test("session user → 'Signed in as <name>' + inline POST form with CSRF", () => {
     const html = renderHub({

package/src/__tests__/install.test.ts

@@ -1,8 +1,14 @@
-import { describe, expect, test } from "bun:test";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { existsSync, mkdtempSync, readFileSync, realpathSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { defaultStartLifecycleOpts, install } from "../commands/install.ts";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
+import {
+  PARACHUTE_HUB_ROOT_REDIRECT_ENV,
+  getRootRedirect,
+  setRootRedirect,
+} from "../hub-settings.ts";
 import { findService, upsertService } from "../services-manifest.ts";
 
 function makeTempPath(): { path: string; configDir: string; cleanup: () => void } {
@@ -62,6 +68,71 @@ describe("install", () => {
     }
   });
 
+  test("refuses `install agent` without invoking bun or the deprecated binary", async () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      const calls: string[][] = [];
+      const logs: string[] = [];
+      const code = await install("agent", {
+        runner: async (cmd) => {
+          calls.push([...cmd]);
+          return 0;
+        },
+        manifestPath: path,
+        startService: async () => 0,
+        isLinked: () => false,
+        portProbe: async () => false,
+        log: (line) => logs.push(line),
+      });
+      expect(code).toBe(1);
+      expect(calls).toEqual([]);
+      expect(logs.join("\n")).toMatch(/parachute-agent was retired/);
+      expect(logs.join("\n")).toMatch(/Vault and Surface/);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("refuses explicit retired Agent npm package names before invoking bun", async () => {
+    for (const packageName of [
+      "@openparachute/agent",
+      "@openparachute/agent@0.9.0",
+      "@openparachute/channel",
+    ]) {
+      const calls: string[][] = [];
+      const logs: string[] = [];
+      const code = await install(packageName, {
+        runner: async (cmd) => {
+          calls.push([...cmd]);
+          return 0;
+        },
+        log: (line) => logs.push(line),
+      });
+      expect(code).toBe(1);
+      expect(calls).toEqual([]);
+      expect(logs.join("\n")).toMatch(/parachute-agent was retired/);
+    }
+  });
+
+  test("refuses a local checkout whose package metadata is a retired Agent package", async () => {
+    const pkgDir = mkdtempSync(join(tmpdir(), "pcli-retired-agent-"));
+    try {
+      const calls: string[][] = [];
+      const code = await install(pkgDir, {
+        runner: async (cmd) => {
+          calls.push([...cmd]);
+          return 0;
+        },
+        readPackageName: () => "@openparachute/agent",
+        log: () => {},
+      });
+      expect(code).toBe(1);
+      expect(calls).toEqual([]);
+    } finally {
+      rmSync(pkgDir, { recursive: true, force: true });
+    }
+  });
+
   test("runs bun add -g then init; seeds manifest when service didn't write one", async () => {
     const { path, cleanup } = makeTempPath();
     try {
@@ -408,7 +479,7 @@ describe("install", () => {
   test("ADOPT-KILLS an attributable same-module orphan on the canonical port + reclaims it (#609)", async () => {
     // Wipe-recovery: `rm -rf ~/.parachute` + re-`init` leaves the supervised
     // vault child running on :1940. The fresh install must reclaim the canonical
-    // port (adopt-kill the attributable orphan) rather than port-walk to 1944.
+    // port (adopt-kill the attributable orphan) rather than port-walk to 1945.
     const { path, configDir, cleanup } = makeTempPath();
     try {
       const logs: string[] = [];
@@ -1636,9 +1707,10 @@ describe("install", () => {
         log: (l) => logs.push(l),
       });
       expect(code).toBe(0);
-      // First reservation slot is 1944.
+      // Agent retirement released 1941, so it is now the first unassigned
+      // canonical slot available to the fallback walker.
       const entry = findService("parachute-vault", path);
-      expect(entry?.port).toBe(1944);
+      expect(entry?.port).toBe(1941);
       expect(logs.join("\n")).toMatch(/canonical port 1940 is in use/);
       // .env is not touched.
       const envPath = join(configDir, "vault", ".env");
@@ -1865,6 +1937,33 @@ describe("install", () => {
     }
   });
 
+  test("refuses third-party metadata that declares a retired Agent manifest identity", async () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      const logs: string[] = [];
+      const code = await install("@vendor/agent-wrapper", {
+        runner: async () => 0,
+        manifestPath: path,
+        isLinked: () => false,
+        log: (line) => logs.push(line),
+        readManifest: async () => ({
+          name: "claw",
+          manifestName: "@vendor/agent-wrapper",
+          port: 1952,
+          paths: ["/claw"],
+          health: "/claw/health",
+        }),
+        findGlobalInstall: () =>
+          "/fake/bun-globals/node_modules/@vendor/agent-wrapper/package.json",
+      });
+      expect(code).toBe(1);
+      expect(findService("claw", path)).toBeUndefined();
+      expect(logs.join("\n")).toMatch(/parachute-agent was retired/);
+    } finally {
+      cleanup();
+    }
+  });
+
   test("npm-installed third-party module persists installDir from bun globals", async () => {
     // hub#83: for `parachute install <npm-pkg>`, installDir is dirname of
     // the package.json that findGlobalInstall returns. Without this,
@@ -1940,7 +2039,8 @@ describe("install", () => {
       expect(startCalls).toEqual(["someapp"]);
       // Log lines speak in the canonical short name too. Port comes from
       // assignServicePort (third-party gets the first unassigned canonical
-      // slot, currently 1944), not the manifest's port hint.
+      // slot, currently 1945 — 1944 is parachute-app's canonical assigned
+      // slot as of hub-parity P5), not the manifest's port hint.
       const joined = logs.join("\n");
       expect(joined).toMatch(/Seeded services\.json entry for someapp/);
       expect(joined).toMatch(/someapp registered on port \d+/);
@@ -2316,3 +2416,177 @@ describe("hub#573 — install auto-start converges on supervised detection", ()
     expect(opts.log).toBe(log);
   });
 });
+
+// hub-parity P5 (2026-07-11): `parachute install app` defaults the hub's
+// bare `/` redirect to the app's front door — SET-IF-UNSET ONLY. Every test
+// here injects `rootRedirectDb` (a hub.db opened in the same disposable
+// tempdir `makeTempPath()` already isolates) so no real
+// `~/.parachute/hub.db` is ever touched — never drive this against the
+// operator's live install.
+describe("app-only root-redirect set-if-unset (hub-parity P5)", () => {
+  // The write gates on `resolveRootRedirectDetailed(db).source === "default"`,
+  // which consults `PARACHUTE_HUB_ROOT_REDIRECT`. Neutralize any ambient value
+  // (Aaron's box, CI) so the default-tier tests are deterministic; the
+  // env-set test below manages its own value inside its own body.
+  let savedEnv: string | undefined;
+  beforeEach(() => {
+    savedEnv = process.env[PARACHUTE_HUB_ROOT_REDIRECT_ENV];
+    delete process.env[PARACHUTE_HUB_ROOT_REDIRECT_ENV];
+  });
+  afterEach(() => {
+    if (savedEnv === undefined) {
+      delete process.env[PARACHUTE_HUB_ROOT_REDIRECT_ENV];
+    } else {
+      process.env[PARACHUTE_HUB_ROOT_REDIRECT_ENV] = savedEnv;
+    }
+  });
+
+  test("fresh install (no prior root_redirect) sets it to /app/", async () => {
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      const db = openHubDb(hubDbPath(configDir));
+      const logs: string[] = [];
+      try {
+        const code = await install("app", {
+          runner: async () => 0,
+          manifestPath: path,
+          configDir,
+          startService: async () => 0,
+          isLinked: () => false,
+          portProbe: async () => false,
+          rootRedirectDb: db,
+          log: (l) => logs.push(l),
+        });
+        expect(code).toBe(0);
+        expect(getRootRedirect(db)).toBe("/app/");
+        expect(logs.join("\n")).toMatch(/front page.*now opens the app at \/app\//);
+      } finally {
+        db.close();
+      }
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("a pre-set root_redirect is left alone — never clobbered", async () => {
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      const db = openHubDb(hubDbPath(configDir));
+      const logs: string[] = [];
+      try {
+        setRootRedirect(db, "/surface/reading-room");
+        const code = await install("app", {
+          runner: async () => 0,
+          manifestPath: path,
+          configDir,
+          startService: async () => 0,
+          isLinked: () => false,
+          portProbe: async () => false,
+          rootRedirectDb: db,
+          log: (l) => logs.push(l),
+        });
+        expect(code).toBe(0);
+        // The operator's prior choice survives byte-for-byte.
+        expect(getRootRedirect(db)).toBe("/surface/reading-room");
+        // The set-if-unset write's OWN log line (distinct from the static
+        // postInstallFooter boilerplate, which always prints "now opens the
+        // app too, unless you've already..." regardless of whether the write
+        // fired) must NOT appear — the write itself was skipped.
+        expect(logs.join("\n")).not.toMatch(/now opens the app at \/app\//);
+      } finally {
+        db.close();
+      }
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("installing a different module never touches root_redirect", async () => {
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      const db = openHubDb(hubDbPath(configDir));
+      try {
+        const code = await install("notes", {
+          runner: async () => 0,
+          manifestPath: path,
+          configDir,
+          startService: async () => 0,
+          isLinked: () => false,
+          portProbe: async () => false,
+          rootRedirectDb: db,
+          log: () => {},
+        });
+        expect(code).toBe(0);
+        expect(getRootRedirect(db)).toBeNull();
+      } finally {
+        db.close();
+      }
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("an ENV-configured redirect (no DB row) is left alone — never clobbered (N1)", async () => {
+    // Container deploys pin the landing page via PARACHUTE_HUB_ROOT_REDIRECT,
+    // not a DB row. Gating on `getRootRedirect(db) === null` (DB only) would
+    // miss this and write `/app/`, which — since the DB row wins over env on
+    // read — silently overrides their configured landing. The fix gates on
+    // `resolveRootRedirectDetailed(db).source === "default"`, which sees the
+    // env tier. So: env set → no DB row written.
+    const { path, configDir, cleanup } = makeTempPath();
+    const prevEnv = process.env[PARACHUTE_HUB_ROOT_REDIRECT_ENV];
+    try {
+      process.env[PARACHUTE_HUB_ROOT_REDIRECT_ENV] = "/surface/team-room";
+      const db = openHubDb(hubDbPath(configDir));
+      const logs: string[] = [];
+      try {
+        const code = await install("app", {
+          runner: async () => 0,
+          manifestPath: path,
+          configDir,
+          startService: async () => 0,
+          isLinked: () => false,
+          portProbe: async () => false,
+          rootRedirectDb: db,
+          log: (l) => logs.push(l),
+        });
+        expect(code).toBe(0);
+        // No DB row written — the env-configured landing survives.
+        expect(getRootRedirect(db)).toBeNull();
+        expect(logs.join("\n")).not.toMatch(/now opens the app at \/app\//);
+      } finally {
+        db.close();
+      }
+    } finally {
+      if (prevEnv === undefined) {
+        delete process.env[PARACHUTE_HUB_ROOT_REDIRECT_ENV];
+      } else {
+        process.env[PARACHUTE_HUB_ROOT_REDIRECT_ENV] = prevEnv;
+      }
+      cleanup();
+    }
+  });
+
+  test("production gate: without rootRedirectDb + a tempdir manifestPath, the write is skipped (not attempted)", async () => {
+    // Mirrors the existing `guidanceProbeAllowed` discriminant elsewhere in
+    // install.ts: a test with a tempdir manifestPath and no explicit opt-in
+    // must never open the real ~/.parachute/hub.db. There's nothing to open
+    // here at all — the assertion is simply that install still completes
+    // cleanly with the DB-touching branch skipped.
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      const code = await install("app", {
+        runner: async () => 0,
+        manifestPath: path,
+        configDir,
+        startService: async () => 0,
+        isLinked: () => false,
+        portProbe: async () => false,
+        log: () => {},
+      });
+      expect(code).toBe(0);
+    } finally {
+      cleanup();
+    }
+  });
+});