@openparachute/hub 0.7.4-rc.1 → 0.7.4-rc.11

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

@@ -116,7 +116,8 @@ describe("renderConsent", () => {
     expect(html).toContain("vault:admin");
     // Scope explanations from the registry
     expect(html).toContain("Read your notes");
-    expect(html).toContain("Full vault access");
+    // hub#689 Leg 1: the admin label now enumerates the concrete grants.
+    expect(html).toContain("Read and write everything, plus admin");
   });
 
   test("highlights admin scopes with a danger color and badge", () => {
@@ -252,6 +253,111 @@ describe("renderConsent", () => {
     expect(html).not.toContain("You have no assigned vaults");
     expect(html).not.toContain('value="yes" class="btn btn-primary" disabled');
   });
+
+  // hub#689 — owner-on-own-vault verb selector rendering.
+  test("renders the owner verb selector (read/write/admin), pre-selected to admin", () => {
+    const html = renderConsent({
+      params: { ...PARAMS, scope: "vault:read" },
+      csrfToken: CSRF,
+      clientId: "c",
+      clientName: "App",
+      scopes: ["vault:read"],
+      vaultPicker: { unnamedVerbs: ["read"], availableVaults: ["work"], lockedVault: "work" },
+      ownerVerbSelector: { requestedVerbs: ["read"] },
+    });
+    expect(html).toContain("Access level");
+    expect(html).toContain('name="verb_select" value="read"');
+    expect(html).toContain('name="verb_select" value="write"');
+    expect(html).toContain('name="verb_select" value="admin"');
+    // Admin is the pre-selected (checked) option.
+    expect(html).toMatch(/name="verb_select" value="admin"[^>]*checked/);
+    // read/write are NOT pre-checked.
+    expect(html).not.toMatch(/name="verb_select" value="read"[^>]*checked/);
+    expect(html).not.toMatch(/name="verb_select" value="write"[^>]*checked/);
+  });
+
+  test("owner verb selector keeps the admin option visibly flagged (admin badge + red border)", () => {
+    const html = renderConsent({
+      params: { ...PARAMS, scope: "vault:read" },
+      csrfToken: CSRF,
+      clientId: "c",
+      clientName: "App",
+      scopes: ["vault:read"],
+      vaultPicker: { unnamedVerbs: ["read"], availableVaults: ["work"], lockedVault: "work" },
+      ownerVerbSelector: { requestedVerbs: ["read"] },
+    });
+    // The .scope-admin red-border class + the admin badge ride on the admin
+    // radio option so a pre-selected admin grant stays transparent.
+    expect(html).toContain("verb-option-admin");
+    expect(html).toContain("scope-admin");
+    expect(html).toContain("badge-admin");
+  });
+
+  test("does NOT render the verb selector when ownerVerbSelector is absent (non-owner)", () => {
+    const html = renderConsent({
+      params: { ...PARAMS, scope: "vault:read" },
+      csrfToken: CSRF,
+      clientId: "c",
+      clientName: "App",
+      scopes: ["vault:read"],
+      vaultPicker: { unnamedVerbs: ["read"], availableVaults: ["work"], lockedVault: "work" },
+      // ownerVerbSelector omitted → no selector
+    });
+    expect(html).not.toContain("Access level");
+    expect(html).not.toContain('name="verb_select"');
+  });
+
+  // hub#314 — same-hub vs external trust marker. The `.badge-trust-*` class
+  // names are always present in the inlined <style> block, so assertions target
+  // the RENDERED ELEMENT form (`class="badge badge-trust-*"`) + the copy text,
+  // which only appear in the consent body when the marker actually renders.
+  test("renders the first-party trust marker for a same-hub client", () => {
+    const html = renderConsent({
+      params: PARAMS,
+      csrfToken: CSRF,
+      clientId: "c",
+      clientName: "App",
+      scopes: ["vault:read"],
+      sameHub: true,
+    });
+    expect(html).toContain('class="badge badge-trust-same-hub"');
+    expect(html).toContain(">First-party<");
+    expect(html).toContain("Registered through this hub");
+    // The external badge / copy must NOT appear for a same-hub client.
+    expect(html).not.toContain('class="badge badge-trust-external"');
+    expect(html).not.toContain("third-party app that registered itself");
+  });
+
+  test("renders the external trust marker for a third-party DCR client", () => {
+    const html = renderConsent({
+      params: PARAMS,
+      csrfToken: CSRF,
+      clientId: "c",
+      clientName: "App",
+      scopes: ["vault:read"],
+      sameHub: false,
+    });
+    expect(html).toContain('class="badge badge-trust-external"');
+    expect(html).toContain(">External<");
+    expect(html).toContain("third-party app that registered itself");
+    // The first-party badge / copy must NOT appear for an external client.
+    expect(html).not.toContain('class="badge badge-trust-same-hub"');
+    expect(html).not.toContain("Registered through this hub");
+  });
+
+  test("renders no trust marker when provenance is unknown (sameHub omitted)", () => {
+    const html = renderConsent({
+      params: PARAMS,
+      csrfToken: CSRF,
+      clientId: "c",
+      clientName: "App",
+      scopes: ["vault:read"],
+      // sameHub omitted → undefined → no badge
+    });
+    expect(html).not.toContain('class="trust-marker');
+    expect(html).not.toContain('class="badge badge-trust-same-hub"');
+    expect(html).not.toContain('class="badge badge-trust-external"');
+  });
 });
 
 describe("renderError", () => {

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

@@ -29,6 +29,25 @@ describe("SCOPE_EXPLANATIONS", () => {
     }
   });
 
+  // hub#689 Leg 1: the vault:admin consent copy must enumerate what
+  // admin actually grants (config/settings, triggers/automation, GitHub
+  // backup, token minting) on top of read/write — so the consent screen
+  // is honest about the admin blast radius, not a vague "configuration
+  // changes" hand-wave.
+  test("vault:admin label enumerates the concrete admin grants (hub#689 Leg 1)", () => {
+    const label = SCOPE_EXPLANATIONS["vault:admin"]?.label ?? "";
+    const lower = label.toLowerCase();
+    expect(SCOPE_EXPLANATIONS["vault:admin"]?.level).toBe("admin");
+    // Read + write are still part of what admin grants.
+    expect(lower).toContain("read");
+    expect(lower).toContain("write");
+    // The four enumerated admin powers.
+    expect(lower).toContain("config");
+    expect(lower).toContain("trigger");
+    expect(lower).toContain("github");
+    expect(lower).toContain("token");
+  });
+
   test("FIRST_PARTY_SCOPES is sorted and matches the keys of SCOPE_EXPLANATIONS", () => {
     expect(FIRST_PARTY_SCOPES).toEqual([...FIRST_PARTY_SCOPES].sort());
     expect(new Set(FIRST_PARTY_SCOPES)).toEqual(new Set(Object.keys(SCOPE_EXPLANATIONS)));

package/src/__tests__/setup-wizard.test.ts

@@ -990,6 +990,123 @@ describe("handleSetupGet", () => {
       db.close();
     }
   });
+
+  // hub#618: gate the JSON `?op=` op-snapshot once setup is complete.
+  // Mid-setup it stays OPEN (the unauth CLI wizard + brand-new-operator
+  // browser both poll it before any session exists); post-complete it
+  // requires a session or loopback (it's a post-setup admin surface, and
+  // `/admin/setup` is always lockout-exempt so it's otherwise unauth-reachable).
+
+  test("mid-setup unauth ?op= still returns the op snapshot (hub#618 regression guard)", async () => {
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      // No admin yet → setup INCOMPLETE → the surface stays open.
+      const reg = getDefaultOperationsRegistry();
+      const op = reg.create("install", "vault");
+      reg.update(op.id, { status: "running" }, "running bun add -g @openparachute/vault@latest");
+      const res = handleSetupGet(
+        req(`/admin/setup?op=${op.id}`, { headers: { accept: "application/json" } }),
+        {
+          db,
+          manifestPath: h.manifestPath,
+          configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
+          issuer: "https://hub.example",
+          registry: reg,
+          // No loopback flag, no session — the unauth first-boot poll.
+        },
+      );
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as {
+        hasAdmin: boolean;
+        operation?: { id: string; status: string; log: readonly string[] };
+      };
+      expect(body.hasAdmin).toBe(false);
+      expect(body.operation).toBeDefined();
+      expect(body.operation?.id).toBe(op.id);
+      expect(body.operation?.status).toBe("running");
+    } finally {
+      db.close();
+    }
+  });
+
+  test("post-complete unauth ?op= omits the op snapshot; session OR loopback restores it (hub#618)", async () => {
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      // Drive state to COMPLETE: admin + vault + expose mode.
+      const user = await createUser(db, "owner", "pw");
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault",
+              version: "0.1.0",
+              port: 1940,
+              paths: ["/vault/default"],
+              health: "/health",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      setSetting(db, "setup_expose_mode", "localhost");
+      const reg = getDefaultOperationsRegistry();
+      const op = reg.create("install", "vault");
+      reg.update(op.id, { status: "running" }, "still running");
+
+      const deps = {
+        db,
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
+        issuer: "https://hub.example",
+        registry: reg,
+      };
+
+      // (a) Unauth, non-loopback → operation omitted.
+      const unauth = handleSetupGet(
+        req(`/admin/setup?op=${op.id}`, { headers: { accept: "application/json" } }),
+        deps,
+      );
+      expect(unauth.status).toBe(200);
+      const unauthBody = (await unauth.json()) as {
+        hasAdmin: boolean;
+        hasVault: boolean;
+        hasExposeMode: boolean;
+        operation?: unknown;
+      };
+      // Confirm setup actually derived as complete (else the gate is vacuous).
+      expect(unauthBody.hasAdmin).toBe(true);
+      expect(unauthBody.hasVault).toBe(true);
+      expect(unauthBody.hasExposeMode).toBe(true);
+      expect(unauthBody.operation).toBeUndefined();
+
+      // (b) Valid session → operation restored.
+      const { createSession } = await import("../sessions.ts");
+      const session = createSession(db, { userId: user.id });
+      const authed = handleSetupGet(
+        req(`/admin/setup?op=${op.id}`, {
+          headers: {
+            accept: "application/json",
+            cookie: `${SESSION_COOKIE_NAME}=${session.id}`,
+          },
+        }),
+        deps,
+      );
+      const authedBody = (await authed.json()) as { operation?: { id: string } };
+      expect(authedBody.operation?.id).toBe(op.id);
+
+      // (c) Loopback (no session) → operation restored.
+      const loopback = handleSetupGet(
+        req(`/admin/setup?op=${op.id}`, { headers: { accept: "application/json" } }),
+        { ...deps, requestIsLoopback: true },
+      );
+      const loopbackBody = (await loopback.json()) as { operation?: { id: string } };
+      expect(loopbackBody.operation?.id).toBe(op.id);
+    } finally {
+      db.close();
+    }
+  });
 });
 
 // --- POST /admin/setup/account -------------------------------------------
@@ -3150,7 +3267,7 @@ describe("typed vault name (hub#267)", () => {
     }
   });
 
-  test("vault POST with empty name falls back to 'default' + omits the env override", async () => {
+  test("vault POST with empty name falls back to 'default' + ALWAYS passes PARACHUTE_VAULT_NAME (#478 Part 2)", async () => {
     const db = openHubDb(hubDbPath(h.dir));
     try {
       const user = await createUser(db, "owner", "pw");
@@ -3213,12 +3330,12 @@ describe("typed vault name (hub#267)", () => {
       await new Promise((r) => setTimeout(r, 50));
       const vaultSpawn = spawnRequests.find((s) => s.short === "vault");
       expect(vaultSpawn).toBeDefined();
-      // No PARACHUTE_VAULT_NAME override on the default-name path (vault's
-      // resolveFirstBootVaultName already defaults to "default" when the
-      // env var is absent). PORT is set by the supervisor (hub#356) for
-      // every supervised child regardless — assert the empty-name path
-      // doesn't add PARACHUTE_VAULT_NAME.
-      expect(vaultSpawn?.env?.PARACHUTE_VAULT_NAME).toBeUndefined();
+      // #478 Part 2: wizard ALWAYS passes PARACHUTE_VAULT_NAME so vault's
+      // first-boot knows which vault to create once silent auto-create is
+      // removed. Even for the default name, the env var must be set to
+      // "default" — not omitted. PORT is set by the supervisor (hub#356)
+      // for every supervised child regardless.
+      expect(vaultSpawn?.env?.PARACHUTE_VAULT_NAME).toBe("default");
       expect(vaultSpawn?.env?.PORT).toBe("1940");
     } finally {
       db.close();

package/src/__tests__/status-supervisor.test.ts

@@ -80,6 +80,12 @@ interface SupervisorArmOpts {
   hubHealthy: boolean;
   moduleStates?: ModuleStatesResult;
   fetchModuleStatesImpl?: () => Promise<ModuleStatesResult>;
+  /**
+   * Inject the unauthenticated module-liveness probe (#700). Defaults to "every
+   * module is down" so the degraded-read tests don't accidentally hit the
+   * network; specific tests override to mark a module live.
+   */
+  probeModuleHealth?: (port: number, health: string) => Promise<boolean>;
 }
 
 /** Drive `status` through the supervisor arm with fully stubbed seams. */
@@ -96,6 +102,7 @@ function supervisorOpts(configDir: string, path: string, o: SupervisorArmOpts) {
       fetchModuleStates:
         o.fetchModuleStatesImpl ??
         (async () => o.moduleStates ?? { supervisorAvailable: true, modules: [] }),
+      probeModuleHealth: o.probeModuleHealth ?? (async () => false),
       openDb: fakeOpenDb as unknown as (configDir: string) => import("bun:sqlite").Database,
     },
   };
@@ -377,7 +384,7 @@ describe("status — Phase 3c supervisor arm: module rows", () => {
     }
   });
 
-  test("no operator token → graceful degrade (manifest rows + actionable hint), no 401 crash", async () => {
+  test("no operator token (fresh box, no admin) → note targets set-password, NOT rotate-operator (#700)", async () => {
     const { path, configDir, cleanup } = makeTempPath();
     try {
       upsertService(
@@ -392,15 +399,121 @@ describe("status — Phase 3c supervisor arm: module rows", () => {
           fetchModuleStatesImpl: async () => {
             throw new NoOperatorTokenError();
           },
+          // No probe-live module here → row stays inactive (exit 0).
+          probeModuleHealth: async () => false,
         }),
         print: (l) => lines.push(l),
       });
       // We could not read run-state, but didn't crash. The module row falls back
-      // to `inactive` (no supervisor snapshot) — a stopped row is exit 0.
+      // to `inactive` (no supervisor snapshot, probe down) — a stopped row is exit 0.
       expect(code).toBe(0);
       const out = lines.join("\n");
       expect(out).toMatch(/parachute-vault/);
-      expect(out).toMatch(/run `parachute auth rotate-operator`/);
+      // #700: a fresh box has no admin, so rotate-operator would itself error.
+      // The note must point at set-password and must NOT be the bare
+      // rotate-operator guidance.
+      expect(out).toMatch(/parachute auth set-password/);
+      expect(out).not.toMatch(/run `parachute auth rotate-operator` to mint an operator token/);
+      const vaultLine = lines.find((l) => l.includes("parachute-vault"));
+      expect(vaultLine).toMatch(/\binactive\b/);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("no operator token + module answers /health probe → LIVE (active), not inactive (#700)", async () => {
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      upsertService(
+        { name: "parachute-vault", port: 1940, paths: ["/"], health: "/health", version: "0.6.2" },
+        path,
+      );
+      const probed: Array<{ port: number; health: string }> = [];
+      const lines: string[] = [];
+      const code = await status({
+        ...supervisorOpts(configDir, path, {
+          managerState: { state: "active" },
+          hubHealthy: true,
+          fetchModuleStatesImpl: async () => {
+            throw new NoOperatorTokenError();
+          },
+          // vault is genuinely up — its /health answers (2xx or 401 → live).
+          probeModuleHealth: async (port, health) => {
+            probed.push({ port, health });
+            return true;
+          },
+        }),
+        print: (l) => lines.push(l),
+      });
+      expect(code).toBe(0);
+      // The probe targeted the module's own port + health path from the manifest.
+      expect(probed).toEqual([{ port: 1940, health: "/health" }]);
+      const vaultLine = lines.find((l) => l.includes("parachute-vault"));
+      expect(vaultLine).toMatch(/\bactive\b/);
+      expect(vaultLine).not.toMatch(/\binactive\b/);
+      const out = lines.join("\n");
+      // The row is labelled as probe-derived so the operator knows it's thin.
+      expect(out).toMatch(/live via unauthenticated health probe/);
+      // The degraded-read hint still appears (why PID/uptime are absent).
+      expect(out).toMatch(/parachute auth set-password/);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("degraded read + module probe FAILS → row stays inactive (#700)", async () => {
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      upsertService(
+        { name: "parachute-vault", port: 1940, paths: ["/"], health: "/health", version: "0.6.2" },
+        path,
+      );
+      const lines: string[] = [];
+      const code = await status({
+        ...supervisorOpts(configDir, path, {
+          managerState: { state: "active" },
+          hubHealthy: true,
+          fetchModuleStatesImpl: async () => {
+            throw new NoOperatorTokenError();
+          },
+          probeModuleHealth: async () => false,
+        }),
+        print: (l) => lines.push(l),
+      });
+      expect(code).toBe(0);
+      const vaultLine = lines.find((l) => l.includes("parachute-vault"));
+      expect(vaultLine).toMatch(/\binactive\b/);
+      const out = lines.join("\n");
+      expect(out).not.toMatch(/live via unauthenticated health probe/);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("a throwing module probe never crashes status — row degrades to inactive (#700)", async () => {
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      upsertService(
+        { name: "parachute-vault", port: 1940, paths: ["/"], health: "/health", version: "0.6.2" },
+        path,
+      );
+      const lines: string[] = [];
+      const code = await status({
+        ...supervisorOpts(configDir, path, {
+          managerState: { state: "active" },
+          hubHealthy: true,
+          fetchModuleStatesImpl: async () => {
+            throw new NoOperatorTokenError();
+          },
+          probeModuleHealth: async () => {
+            throw new Error("probe exploded");
+          },
+        }),
+        print: (l) => lines.push(l),
+      });
+      expect(code).toBe(0);
+      const vaultLine = lines.find((l) => l.includes("parachute-vault"));
+      expect(vaultLine).toMatch(/\binactive\b/);
     } finally {
       cleanup();
     }
@@ -433,6 +546,42 @@ describe("status — Phase 3c supervisor arm: module rows", () => {
     }
   });
 
+  test("expired operator token + module answers /health probe → LIVE (active) (#700)", async () => {
+    // Symmetry with the no-token case: the unauthenticated probe fallback fires
+    // on ANY degraded read where the hub is up + run-state is missing, so an
+    // expired-token box still shows a genuinely-serving module as `active`.
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      upsertService(
+        { name: "parachute-vault", port: 1940, paths: ["/"], health: "/health", version: "0.6.2" },
+        path,
+      );
+      const lines: string[] = [];
+      const code = await status({
+        ...supervisorOpts(configDir, path, {
+          managerState: { state: "active" },
+          hubHealthy: true,
+          fetchModuleStatesImpl: async () => {
+            throw new OperatorTokenExpiredError(
+              "token expired — run `parachute auth rotate-operator`",
+            );
+          },
+          probeModuleHealth: async () => true,
+        }),
+        print: (l) => lines.push(l),
+      });
+      expect(code).toBe(0);
+      const vaultLine = lines.find((l) => l.includes("parachute-vault"));
+      expect(vaultLine).toMatch(/\bactive\b/);
+      const out = lines.join("\n");
+      expect(out).toMatch(/live via unauthenticated health probe/);
+      // The expired-token degraded-read hint still points at rotate-operator.
+      expect(out).toMatch(/rotate-operator/);
+    } finally {
+      cleanup();
+    }
+  });
+
   test("API error reading module states → degrade with the message, no crash", async () => {
     const { path, configDir, cleanup } = makeTempPath();
     try {

package/src/__tests__/supervisor.test.ts

@@ -1591,6 +1591,31 @@ describe("Supervisor port-readiness + structured start-error (§6.5)", () => {
     expect(spawner.calls).toHaveLength(0);
   });
 
+  test("(#634) preflight non-executable binary → non_executable start-error, NO spawn", async () => {
+    const spawner = makeQueueSpawner();
+    const sup = new Supervisor({
+      spawnFn: spawner.spawn,
+      killFn: noopKill,
+      // `which` requires X_OK so it returns null for a 100644 bin...
+      which: () => null,
+      // ...but the secondary probe finds it present-but-non-executable.
+      findNonExecutable: () => "/x/vault/bin/parachute-vault",
+      portListening: async () => true,
+      startReadyMs: 50,
+      sleep: () => Promise.resolve(),
+    });
+    const state = await sup.start(reqWithPort("vault", 1940));
+
+    expect(state.status).toBe("crashed");
+    expect(state.startError?.error_type).toBe("non_executable");
+    expect(state.startError?.error_description).toContain(
+      "but is not executable — run chmod +x /x/vault/bin/parachute-vault",
+    );
+    // No misleading "not installed" install card, and never spawned.
+    expect(state.startError?.binary).toBe("parachute-vault");
+    expect(spawner.calls).toHaveLength(0);
+  });
+
   test("a clean re-start clears a prior started-but-unbound start-error", async () => {
     const first = makeFakeProc(201);
     const second = makeFakeProc(202);

package/src/__tests__/vault-names.test.ts

@@ -68,11 +68,16 @@ describe("listVaultNames", () => {
     expect(listVaultNames(manifest)).toEqual(["personal", "work"]);
   });
 
-  test("entry with no paths falls back to the manifest-suffix name (hub#143)", () => {
+  test("#478: bare empty-paths `parachute-vault` row yields NO name (no phantom 'default')", () => {
+    // What vault's self-register emits at zero vaults: the row stays present
+    // (installed-detection) but advertises no `/vault/<name>` path. It must not
+    // leak a selectable/assignable "default" before any vault exists. Mirrors
+    // the empty-paths skip in admin-vaults.ts (findExistingVault /
+    // listVaultInstanceNames).
     const manifest: ServicesManifest = {
       services: [
         {
-          name: "parachute-vault-archived",
+          name: "parachute-vault",
           port: 1940,
           paths: [],
           health: "/h",
@@ -80,7 +85,31 @@ describe("listVaultNames", () => {
         },
       ],
     };
-    expect(listVaultNames(manifest)).toEqual(["archived"]);
+    expect(listVaultNames(manifest)).toEqual([]);
+  });
+
+  test("#478: empty-paths row is skipped; real-paths vault rows are unchanged (positive control)", () => {
+    // An empty-paths row alongside a real-paths row: the real instance still
+    // resolves, the empty one contributes nothing.
+    const manifest: ServicesManifest = {
+      services: [
+        {
+          name: "parachute-vault",
+          port: 1940,
+          paths: [],
+          health: "/h",
+          version: "0.1.0",
+        },
+        {
+          name: "parachute-vault-work",
+          port: 1941,
+          paths: ["/vault/work"],
+          health: "/h",
+          version: "0.1.0",
+        },
+      ],
+    };
+    expect(listVaultNames(manifest)).toEqual(["work"]);
   });
 
   test("deduplicates collisions across single-entry + per-vault shapes", () => {

package/src/__tests__/well-known.test.ts

@@ -472,13 +472,48 @@ describe("buildWellKnown", () => {
     );
   });
 
-  test("falls back to / for empty paths", () => {
+  test("an empty-paths VAULT row is skipped entirely — no phantom default (#478)", () => {
+    // A vault services row with `paths: []` means "module installed but no
+    // servable vault instance" (vault's self-register emits this at zero
+    // vaults). It must NOT fabricate a vault entry at root in either the
+    // `vaults` array or the flat `services` catalog. Mirrors the empty-paths
+    // skip in admin-vaults.ts / vault-names.ts / oauth-handlers.ts.
     const entry: ServiceEntry = { ...vault, paths: [] };
     const doc = buildWellKnown({
       services: [entry],
       canonicalOrigin: "https://x.example",
     });
-    expect(doc.vaults[0]?.url).toBe("https://x.example/");
+    expect(doc.vaults).toEqual([]);
+    // The row contributes nothing to the flat services list either — no
+    // phantom `/` mount advertised.
+    expect(doc.services).toEqual([]);
+  });
+
+  test("positive control: a vault row WITH a path still emits its vault + services entries (#478)", () => {
+    const doc = buildWellKnown({
+      services: [{ ...vault, paths: ["/vault/default"] }],
+      canonicalOrigin: "https://x.example",
+    });
+    expect(doc.vaults).toEqual([
+      {
+        name: "default",
+        url: "https://x.example/vault/default",
+        version: "0.2.4",
+      },
+    ]);
+    expect(doc.services.map((s) => s.name)).toEqual(["parachute-vault"]);
+  });
+
+  test("a NON-vault row with empty paths still falls back to / (#478 scope guard)", () => {
+    // The empty-paths skip is vault-only. A non-vault service legitimately
+    // mounts at root when path-less — that behavior is unchanged.
+    const entry: ServiceEntry = { ...notes, paths: [] };
+    const doc = buildWellKnown({
+      services: [entry],
+      canonicalOrigin: "https://x.example",
+    });
+    expect(doc.services.map((s) => s.path)).toEqual(["/"]);
+    expect(doc.notes).toEqual([{ url: "https://x.example/", version: "0.0.1" }]);
   });
 
   // Hierarchical sub-units (hub#313 — parachute-app design doc §12). Each

package/src/admin-vaults.ts

@@ -207,15 +207,11 @@ function findExistingVault(
   } catch {
     return null;
   }
-  const target = `/vault/${name}`;
   for (const svc of manifest.services) {
     if (!isVaultEntry(svc)) continue;
-    if (svc.paths.length === 0) {
-      if (vaultInstanceNameFor(svc.name, undefined) === name) {
-        return { url: target, version: svc.version, path: target };
-      }
-      continue;
-    }
+    // #478: an empty-paths vault row means "installed but no servable vault
+    // instance" — skip it entirely so it never resolves to a phantom "default".
+    if (svc.paths.length === 0) continue;
     for (const path of svc.paths) {
       if (vaultInstanceNameFor(svc.name, path) === name) {
         return { url: path, version: svc.version, path };
@@ -607,7 +603,7 @@ function emptyCascadeSummary(): CascadeSummary {
 }
 
 /** Every vault instance name currently registered in services.json. */
-function listVaultInstanceNames(manifestPath: string): Set<string> {
+export function listVaultInstanceNames(manifestPath: string): Set<string> {
   const names = new Set<string>();
   let manifest: ReturnType<typeof readManifest>;
   try {
@@ -617,10 +613,9 @@ function listVaultInstanceNames(manifestPath: string): Set<string> {
   }
   for (const svc of manifest.services) {
     if (!isVaultEntry(svc)) continue;
-    if (svc.paths.length === 0) {
-      names.add(vaultInstanceNameFor(svc.name, undefined));
-      continue;
-    }
+    // #478: an empty-paths vault row means "installed but no servable vault
+    // instance" — skip it so no phantom "default" is synthesized.
+    if (svc.paths.length === 0) continue;
     for (const path of svc.paths) names.add(vaultInstanceNameFor(svc.name, path));
   }
   return names;