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

package/src/oauth-handlers.ts

@@ -294,8 +294,11 @@ export function buildServicesCatalog(
   if (audiences.has("vault")) {
     for (const entry of manifest.services) {
       if (!isVaultEntry(entry)) continue;
-      const paths = entry.paths.length > 0 ? entry.paths : ["/"];
-      for (const path of paths) {
+      // #478: an empty-paths vault row is "installed but no servable instance"
+      // — skip it so it never counts toward (or, below, fabricates) a phantom
+      // vault. Mirrors the continue in well-known.ts / admin-vaults.ts.
+      if (entry.paths.length === 0) continue;
+      for (const path of entry.paths) {
         const instance = vaultInstanceNameFor(entry.name, path);
         if (broadVaultScope || namedVaults.has(instance)) admittedVaultPathCount++;
       }
@@ -308,12 +311,16 @@ export function buildServicesCatalog(
   for (const entry of manifest.services) {
     if (isVaultEntry(entry)) {
       if (!audiences.has("vault")) continue;
+      // #478: an empty-paths vault row is "installed but no servable instance"
+      // — skip it so the catalog never offers a phantom `vault` / `vault:default`
+      // entry pointing at root before any vault exists. Mirrors well-known.ts /
+      // admin-vaults.ts / vault-names.ts.
+      if (entry.paths.length === 0) continue;
       // Walk every path the row exposes. Real multi-vault on the hub is a
       // single `parachute-vault` row with N paths (one per vault instance);
       // legacy per-vault rows (`parachute-vault-<name>`) are handled by the
       // same loop because each contributes one path.
-      const paths = entry.paths.length > 0 ? entry.paths : ["/"];
-      for (const path of paths) {
+      for (const path of entry.paths) {
         const instance = vaultInstanceNameFor(entry.name, path);
         const admit = broadVaultScope || namedVaults.has(instance);
         if (!admit) continue;
@@ -1209,9 +1216,31 @@ export function handleAuthorizeGet(db: Database, req: Request, deps: OAuthDeps):
     return issueAuthCodeRedirect(db, parsed, requestedScopes, session.userId, deps);
   }
 
+  // hub#689 — does the user hold ADMIN on every vault they could pick? Admin
+  // (isFirstAdmin) owns the whole hub. A non-admin owns a vault only if their
+  // `user_vaults` role grants admin there (today role=write does; a role=read
+  // assignment would NOT). Re-derived from the DB so the owner-verb-selector
+  // is offered only to a genuine owner — the submit path re-checks the PICKED
+  // vault and the cap is the backstop, but rendering it precisely avoids
+  // promising an admin upgrade the cap would silently demote.
+  const userHoldsAdminOnPickable =
+    userIsAdmin ||
+    (assignedVaults.length > 0 &&
+      assignedVaults.every((v) =>
+        (vaultVerbsForUserVault(db, session.userId, v) ?? []).includes("admin"),
+      ));
+
   return htmlResponse(
     renderConsent(
-      consentProps(client, parsed, vaultNames, csrf.token, assignedVaults, userIsAdmin),
+      consentProps(
+        client,
+        parsed,
+        vaultNames,
+        csrf.token,
+        assignedVaults,
+        userIsAdmin,
+        userHoldsAdminOnPickable,
+      ),
     ),
     200,
     extra,
@@ -1270,7 +1299,8 @@ function capScopesToUserAuthority(
     if (name === undefined || verb === undefined || !VAULT_VERBS.has(verb)) return true;
     // Named vault verb requested by a non-owner: admit only if the user holds
     // it. `vaultVerbsForUserVault` returns null for an unassigned vault (drop)
-    // or the held verb list (today read/write only — never admin).
+    // or the held verb list — a `write` role holds [read, write, admin], a
+    // `read` role holds [read] (see `vaultVerbsForRole`).
     const held = vaultVerbsForUserVault(db, userId, name);
     return held !== null && (held as readonly string[]).includes(verb);
   });
@@ -1682,6 +1712,44 @@ async function handleConsentSubmit(
         400,
       );
     }
+    // hub#689 — owner-on-own-vault verb widening. The consent screen offers
+    // owners a read/write/admin selector (pre-selected to admin) for an
+    // unnamed `vault:read`/`vault:write` request, so an owner whose AI client
+    // asked for read-only can grant the level it actually needs in-flow. The
+    // submitted `verb_select` is an UNTRUSTED hint — we re-derive ownership of
+    // the PICKED vault server-side here, and `capScopesToUserAuthority` (inside
+    // issueAuthCodeRedirect) is the backstop that drops any verb the user
+    // doesn't actually hold. This only ever rewrites the unnamed read/write
+    // verb(s) to the selected level on the picked vault; named scopes and every
+    // other scope are untouched. A forged `verb_select=admin` from a user who
+    // doesn't own the picked vault gets capped back to what they hold (or, for
+    // a vault outside a pinned user's assignment, never reaches here — the
+    // mismatch checks above already 400'd it).
+    const selectedVerb = String(form.get("verb_select") ?? "").trim();
+    if (selectedVerb === "read" || selectedVerb === "write" || selectedVerb === "admin") {
+      // Re-derive, server-side, whether THIS user owns (holds admin on) the
+      // PICKED vault. Owner === first admin (holds admin everywhere) OR an
+      // assigned user whose role grants admin on this vault. Never trust the
+      // client-submitted selector to establish authority.
+      const heldOnPicked = vaultVerbsForUserVault(db, session.userId, pickedVault);
+      const ownsPicked = userIsAdmin || (heldOnPicked?.includes("admin") ?? false);
+      if (ownsPicked) {
+        scopes = scopes.map((s) => {
+          const parts = s.split(":");
+          // Only widen the unnamed read/write verbs the selector was offered
+          // for — leave an unnamed `vault:admin`, named scopes, and non-vault
+          // scopes exactly as requested.
+          if (
+            parts.length === 2 &&
+            parts[0] === "vault" &&
+            (parts[1] === "read" || parts[1] === "write")
+          ) {
+            return `vault:${selectedVerb}`;
+          }
+          return s;
+        });
+      }
+    }
     scopes = narrowVaultScopes(scopes, pickedVault);
   }
 
@@ -2746,6 +2814,10 @@ function consentProps(
   csrfToken: string,
   assignedVaults: readonly string[],
   userIsAdmin: boolean,
+  // hub#689 — true when the user holds admin on every vault they could pick
+  // (admin owns the hub; an assigned non-admin only if their role grants admin
+  // on each assigned vault). Gates whether the owner-verb-selector renders.
+  userHoldsAdminOnPickable = userIsAdmin,
 ) {
   const scopes = params.scope.split(" ").filter((s) => s.length > 0);
   const unnamedVerbs = unnamedVaultVerbs(scopes);
@@ -2875,6 +2947,25 @@ function consentProps(
     const only = vaultNames[0];
     if (only) displayVault = only;
   }
+  // hub#689 — owner-on-own-vault verb selector. The client requested an
+  // unnamed `vault:read`/`vault:write` verb, and the consenting user owns
+  // (holds admin on) every vault they could pick — first admin owns the whole
+  // hub; an assigned non-admin holds admin on each of their assigned vaults
+  // (vaultVerbsForRole('write') → [read,write,admin]). Offer the selector so
+  // they can grant the level their client actually needs (or downgrade), with
+  // admin pre-selected. Suppressed when the request can't be authorized (zero-
+  // vault non-admin) or the assignment is stale (no valid vault to own).
+  //
+  // SECURITY: this only DECIDES WHETHER TO RENDER. The actual widening is
+  // re-derived server-side in `handleConsentSubmit` against the *picked* vault
+  // and capped by `capScopesToUserAuthority`. The selector value is a hint.
+  const upgradeableUnnamedVerbs = unnamedVerbs.filter((v) => v === "read" || v === "write");
+  const userOwnsEveryPickableVault =
+    !hasStaleAssignment && userCanAuthorizeRequest && userHoldsAdminOnPickable;
+  const ownerVerbSelector =
+    upgradeableUnnamedVerbs.length > 0 && userOwnsEveryPickableVault
+      ? { requestedVerbs: upgradeableUnnamedVerbs }
+      : undefined;
   return {
     params,
     clientId: client.clientId,
@@ -2883,6 +2974,7 @@ function consentProps(
     csrfToken,
     vaultPicker,
     displayVault,
+    ownerVerbSelector,
     staleAssignedVault,
     // Approve stays enabled for non-vault scopes even when assigned_vault
     // is stale — the user can still consent to e.g. `scribe:transcribe`
@@ -2892,6 +2984,11 @@ function consentProps(
     blockApproveForStaleAssignment:
       staleAssignedVault !== undefined && (unnamedVerbs.length > 0 || hasNamedStaleVaultScope),
     userCanAuthorizeRequest,
+    // hub#314 — surface the client's provenance (same-hub first-party vs
+    // external third-party DCR) so the operator sees the trust level on the
+    // consent screen. Clean DB-backed signal: the `same_hub` column written
+    // at DCR time (bearer hub:admin / same-origin session → true).
+    sameHub: client.sameHub,
   };
 }
 

package/src/oauth-ui.ts

@@ -147,6 +147,46 @@ export interface ConsentViewProps {
    * the user on an error page. Defaults to authorizable when omitted.
    */
   userCanAuthorizeRequest?: boolean;
+  /**
+   * hub#689 — owner-on-own-vault verb selector. Set when the consenting user
+   * OWNS (holds admin on) every vault they could pick AND the client requested
+   * an unnamed `vault:read`/`vault:write` verb. Renders a read/write/admin
+   * radio group, pre-selected to admin, so the owner can grant the level their
+   * AI client actually needs in-flow (the requested-scope shape was the
+   * blocker, not the user's authority) — or transparently downgrade.
+   *
+   * The submitted `verb_select` is an UNTRUSTED hint: the consent-submit
+   * handler re-derives, server-side, whether the user actually owns the picked
+   * vault before widening, and `capScopesToUserAuthority` remains the backstop
+   * that drops any verb the user doesn't hold. The selector only ever WIDENS
+   * the unnamed verb(s) on the picked vault; it never touches any other scope.
+   */
+  ownerVerbSelector?: OwnerVerbSelector;
+  /**
+   * hub#314 — same-hub vs external trust marker. True when the requesting
+   * client was registered through this hub's own flow / first-party install
+   * (`OAuthClient.sameHub` — bearer `hub:admin` OR session-cookie +
+   * same-origin DCR). False for a third-party Dynamic Client Registration
+   * (an external app, e.g. Claude.ai, that self-registered). Drives a small
+   * trust badge in the consent card header so the operator knows the trust
+   * level of the app they're approving before they click Approve.
+   *
+   * Omitted / undefined → no badge (provenance unknown; only the GET-handler
+   * call site, which always has the client row, populates it). Provenance is
+   * a clean DB-backed signal — see the `same_hub` column on `clients` and the
+   * `consentProps` call site in `oauth-handlers.ts`.
+   */
+  sameHub?: boolean;
+}
+
+export interface OwnerVerbSelector {
+  /**
+   * The unnamed read/write verb(s) the client requested. Only `read`/`write`
+   * are upgradeable here — an unnamed `vault:admin` request already renders
+   * with the admin badge and needs no selector. Used to word the selector
+   * help text ("the app asked for write access").
+   */
+  requestedVerbs: string[];
 }
 
 export interface VaultPicker {
@@ -328,6 +368,8 @@ export function renderConsent(props: ConsentViewProps): string {
     staleAssignedVault,
     blockApproveForStaleAssignment,
     userCanAuthorizeRequest,
+    ownerVerbSelector,
+    sameHub,
   } = props;
   // Substitute unnamed `vault:<verb>` rows with the resolved named form so
   // the operator sees the scope shape that will appear in the token. Raw
@@ -339,6 +381,7 @@ export function renderConsent(props: ConsentViewProps): string {
       ? `<li class="scope scope-empty">No scopes requested — the app gets a session token only.</li>`
       : displayedScopes.map(renderScopeRow).join("\n");
   const pickerSection = vaultPicker ? renderVaultPicker(vaultPicker) : "";
+  const verbSelectorSection = ownerVerbSelector ? renderOwnerVerbSelector(ownerVerbSelector) : "";
   // Approve is disabled when the picker can't yield a valid vault. The
   // empty-vault branch (no vaults registered) is the original case. A
   // locked-vault picker (multi-user Phase 1) always has a valid value via
@@ -391,6 +434,24 @@ export function renderConsent(props: ConsentViewProps): string {
             before authorizing vault access.
           </p>`
     : "";
+  // hub#314 — same-hub vs external trust marker. `sameHub === true` means the
+  // client was registered through this hub's own flow (first-party / operator-
+  // authenticated DCR); `false` means a third-party app self-registered via
+  // public Dynamic Client Registration. `undefined` → no badge (provenance
+  // unknown to the caller). The badge sits in the header so the operator sees
+  // the trust level before reading the scope list.
+  const trustMarker =
+    sameHub === undefined
+      ? ""
+      : sameHub
+        ? `<p class="trust-marker trust-marker-same-hub">
+            <span class="badge badge-trust-same-hub">First-party</span>
+            <span class="trust-marker-text">Registered through this hub.</span>
+          </p>`
+        : `<p class="trust-marker trust-marker-external">
+            <span class="badge badge-trust-external">External</span>
+            <span class="trust-marker-text">A third-party app that registered itself. Approve only if you recognise it.</span>
+          </p>`;
   const body = `
     <div class="card">
       <div class="card-header">
@@ -402,6 +463,7 @@ export function renderConsent(props: ConsentViewProps): string {
         <p class="subtitle">
           This app is requesting access to your Parachute account.
         </p>
+        ${trustMarker}
         <p class="client-meta">
           <span class="client-meta-label">client_id</span>
           <code>${escapeHtml(clientId)}</code>
@@ -418,6 +480,7 @@ export function renderConsent(props: ConsentViewProps): string {
         ${renderCsrfHiddenInput(csrfToken)}
         ${renderHiddenInputs(params)}
         ${pickerSection}
+        ${verbSelectorSection}
         <div class="button-row">
           <button type="submit" name="approve" value="yes" class="btn btn-primary"${approveDisabled}>Approve</button>
           <button type="submit" name="approve" value="no" class="btn btn-secondary">Deny</button>
@@ -492,6 +555,60 @@ function renderVaultPicker(picker: VaultPicker): string {
         </section>`;
 }
 
+/**
+ * hub#689 — owner-on-own-vault verb selector. Rendered only when the
+ * consenting user owns (holds admin on) every vault they could pick and the
+ * client requested an unnamed `vault:read`/`vault:write` verb. Three radios
+ * (read / write / admin), pre-selected to **admin** so the common case (the
+ * owner's own AI client that needs full access) is one click — but the owner
+ * sees and submits the choice, and can downgrade.
+ *
+ * The `admin` option keeps the `.scope-admin` red border + admin badge so an
+ * admin grant stays visibly flagged even when pre-selected. The submitted
+ * `verb_select` is an untrusted hint re-checked server-side (ownership
+ * re-derivation in `handleConsentSubmit` + `capScopesToUserAuthority` backstop);
+ * this template only renders the choice.
+ */
+function renderOwnerVerbSelector(selector: OwnerVerbSelector): string {
+  const requested = selector.requestedVerbs.map((v) => `<code>vault:${escapeHtml(v)}</code>`);
+  const requestedList =
+    requested.length === 1
+      ? requested[0]
+      : `${requested.slice(0, -1).join(", ")} and ${requested.at(-1)}`;
+  const option = (
+    verb: "read" | "write" | "admin",
+    title: string,
+    desc: string,
+    checked: boolean,
+  ): string => {
+    const isAdmin = verb === "admin";
+    const cls = `verb-option${isAdmin ? " verb-option-admin scope-admin" : ""}`;
+    const badge = isAdmin ? `<span class="badge badge-admin">admin</span>` : "";
+    return `
+            <label class="${cls}">
+              <input type="radio" name="verb_select" value="${verb}"${checked ? " checked" : ""} />
+              <span class="verb-option-body">
+                <span class="verb-option-head">
+                  <span class="verb-option-title">${escapeHtml(title)}</span>
+                  ${badge}
+                </span>
+                <span class="verb-option-desc">${escapeHtml(desc)}</span>
+              </span>
+            </label>`;
+  };
+  return `
+        <section class="verb-selector">
+          <h2 class="scopes-title">Access level</h2>
+          <p class="picker-help">
+            This app asked for ${requestedList} access to your vault. Because you own
+            this vault, you can grant a different level — admin is selected so your app
+            can do everything it might need; lower it if you'd rather not.
+          </p>
+          <div class="verb-options">${option("read", "Read only", "View notes, tags, attachments, and config.", false)}${option("write", "Read & write", "Create, edit, and delete notes, tags, and attachments.", false)}${option("admin", "Admin", "Full access plus config, triggers/automation, GitHub backup, and minting tokens.", true)}
+          </div>
+        </section>`;
+}
+
 /**
  * "App not yet approved" page (#74). Two branches:
  *
@@ -1282,6 +1399,47 @@ const STYLES = `
     font-size: 0.88rem;
     color: ${PALETTE.fg};
   }
+  /* hub#689 — owner-on-own-vault verb selector. Same card shell as the
+     vault picker; the admin option carries the .scope-admin red border so an
+     admin grant stays visibly flagged even when pre-selected. */
+  .verb-selector {
+    margin: 0 0 1.25rem;
+    padding: 0.75rem 0.85rem;
+    border: 1px solid ${PALETTE.borderLight};
+    border-radius: 6px;
+    background: ${PALETTE.bgSoft};
+  }
+  .verb-selector .scopes-title { margin-bottom: 0.4rem; }
+  .verb-options {
+    display: flex;
+    flex-direction: column;
+    gap: 0.4rem;
+  }
+  .verb-option {
+    display: flex;
+    align-items: flex-start;
+    gap: 0.5rem;
+    padding: 0.5rem 0.65rem;
+    border: 1px solid ${PALETTE.border};
+    border-radius: 6px;
+    background: ${PALETTE.cardBg};
+    cursor: pointer;
+    transition: border-color 0.15s ease, background 0.15s ease;
+  }
+  .verb-option:hover { border-color: ${PALETTE.accent}; }
+  .verb-option input[type=radio] { margin-top: 0.25rem; }
+  .verb-option input[type=radio]:focus { outline: 2px solid ${PALETTE.accent}; outline-offset: 2px; }
+  .verb-option-body { display: flex; flex-direction: column; gap: 0.1rem; }
+  .verb-option-head {
+    display: flex;
+    align-items: center;
+    gap: 0.4rem;
+    flex-wrap: wrap;
+  }
+  .verb-option-title { font-weight: 500; color: ${PALETTE.fg}; font-size: 0.9rem; }
+  .verb-option-desc { font-size: 0.82rem; color: ${PALETTE.fgMuted}; }
+  .verb-option-admin .verb-option-title { color: ${PALETTE.danger}; }
+
   .vault-picker-empty .picker-help { color: ${PALETTE.danger}; }
   .vault-picker-empty .picker-help code { color: ${PALETTE.fg}; }
   .vault-picker-locked .picker-help { color: ${PALETTE.fgMuted}; }
@@ -1456,6 +1614,22 @@ const STYLES = `
   .badge-send { background: ${PALETTE.accentSoft}; color: ${PALETTE.accent}; }
   .badge-admin { background: ${PALETTE.danger}; color: ${PALETTE.cardBg}; }
 
+  /* hub#314 — same-hub vs external trust marker on the consent header. The
+     first-party badge uses the accent (calm/trusted); external uses the danger
+     tint so a third-party DCR client stands out without being alarmist. */
+  .trust-marker {
+    display: flex;
+    align-items: baseline;
+    gap: 0.45rem;
+    flex-wrap: wrap;
+    margin: 0.75rem 0 0;
+    font-size: 0.85rem;
+    color: ${PALETTE.fgMuted};
+  }
+  .trust-marker-text { flex: 1; min-width: 12rem; }
+  .badge-trust-same-hub { background: ${PALETTE.accentSoft}; color: ${PALETTE.accent}; }
+  .badge-trust-external { background: ${PALETTE.dangerSoft}; color: ${PALETTE.danger}; }
+
   @media (max-width: 480px) {
     main { padding: 0.75rem; }
     .card { padding: 1.5rem 1.25rem; border-radius: 10px; }

package/src/scope-explanations.ts

@@ -42,7 +42,8 @@ export const SCOPE_EXPLANATIONS: Record<string, ScopeExplanation> = {
     level: "write",
   },
   "vault:admin": {
-    label: "Full vault access plus configuration changes (rotate tokens, change settings).",
+    label:
+      "Read and write everything, plus admin: config & settings, triggers & automation, GitHub backup, and minting access tokens.",
     level: "admin",
   },
   // Optional-module scopes (scribe / agent). These are in FIRST_PARTY_SCOPES

package/src/setup-wizard.ts

@@ -1592,14 +1592,33 @@ export function handleSetupGet(req: Request, deps: SetupWizardDeps): Response {
     // poll on the auth the wizard already carries.
     const opId = url.searchParams.get("op");
     if (opId) {
-      const op = deps.registry?.get(opId);
-      if (op) {
-        envelope.operation = {
-          id: op.id,
-          status: op.status,
-          log: op.log,
-          ...(op.error !== undefined ? { error: op.error } : {}),
-        };
+      // hub#618: post-setup this JSON `?op=` surface is unauth-reachable —
+      // `/admin/setup` is always lockout-exempt (the dispatcher's
+      // `shouldGateForSetup` lets it through so a stale bookmark resolves), and
+      // the snapshot is read BEFORE any session check. The leak is small (an
+      // in-memory op's status + install-progress log lines, behind an
+      // unguessable UUID), but it's still a post-setup admin surface, so gate
+      // it once setup is COMPLETE. During setup (no admin yet) the surface
+      // stays OPEN: the unauth CLI wizard (`parachute init`) AND the brand-new-
+      // operator browser both poll this `?op=` snapshot mid-setup before any
+      // session exists — gating then would break first-boot vault
+      // provisioning. Loopback always passes (same on-box trust as the
+      // `bootstrapToken` branch below); a valid session also passes.
+      const setupComplete = state.hasAdmin && state.hasVault && state.hasExposeMode;
+      const opSnapshotAllowed =
+        !setupComplete ||
+        deps.requestIsLoopback === true ||
+        findActiveSession(deps.db, req) !== null;
+      if (opSnapshotAllowed) {
+        const op = deps.registry?.get(opId);
+        if (op) {
+          envelope.operation = {
+            id: op.id,
+            status: op.status,
+            log: op.log,
+            ...(op.error !== undefined ? { error: op.error } : {}),
+          };
+        }
       }
     }
     // hub#576: hand the actual token to a LOOPBACK caller only. The on-box
@@ -2325,19 +2344,19 @@ export async function handleSetupVaultPost(req: Request, deps: SetupWizardDeps):
   if (registry) {
     // hub#267: thread the typed name through `PARACHUTE_VAULT_NAME` so
     // vault's first-boot path (vault#342) names the created vault
-    // accordingly. Skip the env override when the operator left the
-    // field blank — vault's `resolveFirstBootVaultName` defaults to
-    // `default` on absent env vars, so this preserves the prior
-    // behaviour for the empty-input case.
+    // accordingly.
     //
-    // If the operator typed "default" explicitly, treat the same as
-    // blank — vault's first-boot defaults to "default" anyway, so
-    // skipping the env override is correct (the comparison below
-    // catches both blank-trimmed-to-DEFAULT and typed-"default").
-    const spawnEnv: Record<string, string> = {};
-    if (vaultName !== DEFAULT_VAULT_NAME) {
-      spawnEnv.PARACHUTE_VAULT_NAME = vaultName;
-    }
+    // #478 Part 2: ALWAYS set `PARACHUTE_VAULT_NAME`, even when the name
+    // is "default". Once vault removes its silent auto-create-on-missing-env
+    // behavior, vault's first-boot will require the env var to know which
+    // vault to create — a missing `PARACHUTE_VAULT_NAME` will mean "no vault
+    // to create" rather than "create one named default". Passing it
+    // explicitly for every path (including the default) is correct and safe:
+    // vault's `resolveFirstBootVaultName` accepts "default" as a valid name
+    // and behaves identically to the prior implicit default.
+    const spawnEnv: Record<string, string> = {
+      PARACHUTE_VAULT_NAME: vaultName,
+    };
     // Capture importParams + deps in the runInstall promise chain — when
     // mode === "import", run the vault-side `/.parachute/mirror/import`
     // POST as a follow-up step once the supervised vault has come up
@@ -2358,7 +2377,7 @@ export async function handleSetupVaultPost(req: Request, deps: SetupWizardDeps):
       registry,
       ...(deps.run ? { run: deps.run } : {}),
       ...(deps.isLinked ? { isLinked: deps.isLinked } : {}),
-      ...(Object.keys(spawnEnv).length > 0 ? { spawnEnv } : {}),
+      spawnEnv,
     })
       .then(async () => {
         if (!importToRun) return;

package/src/supervisor.ts

@@ -38,6 +38,7 @@ import { spawnSync } from "node:child_process";
 import {
   MissingDependencyError,
   type MissingDependencyWire,
+  NonExecutableError,
   ensureExecutable,
   rethrowIfMissing,
 } from "@openparachute/depcheck";
@@ -263,6 +264,14 @@ export interface SupervisorOpts {
    * Tests exercising the missing-binary branch inject `which: () => null`.
    */
   readonly which?: (cmd: string) => string | null;
+  /**
+   * #634 secondary-probe seam for `ensureExecutable`: when `which` returns null,
+   * walk PATH IGNORING X_OK to detect a present-but-non-executable binary (a
+   * `bin` that lost its +x bit). Production leaves this undefined so depcheck's
+   * real PATH walk runs (gated to the real `Bun.which`); tests inject it to
+   * exercise the non-executable preflight branch through a stubbed `which`.
+   */
+  readonly findNonExecutable?: (binary: string) => string | null;
   /**
    * Pre-spawn port-squatter detection (#580 item 4). Returns the pid holding a
    * TCP LISTEN on the module's port, or undefined when the port is free /
@@ -427,8 +436,11 @@ export class LogRingBuffer {
  * boot and threads it into the API handlers.
  */
 export class Supervisor {
-  private readonly opts: Required<Omit<SupervisorOpts, "spawnFn">> & {
+  private readonly opts: Required<Omit<SupervisorOpts, "spawnFn" | "findNonExecutable">> & {
     readonly spawnFn: SpawnFn;
+    // Optional #634 probe seam — undefined on the production path so depcheck's
+    // own real PATH walk runs (gated to the real `Bun.which`).
+    readonly findNonExecutable?: (binary: string) => string | null;
   };
   private readonly modules = new Map<string, ModuleEntry>();
 
@@ -459,6 +471,9 @@ export class Supervisor {
       lateBindWatchMs: opts.lateBindWatchMs ?? DEFAULT_LATE_BIND_WATCH_MS,
       lateBindPollMs: opts.lateBindPollMs ?? DEFAULT_LATE_BIND_POLL_MS,
       which: opts.which ?? (isProductionPath ? Bun.which : () => "/stub/bin/preflight-skipped"),
+      // #634: undefined on production so depcheck's real PATH walk runs (its
+      // gate keys on the real `Bun.which`); tests inject it to drive the branch.
+      findNonExecutable: opts.findNonExecutable,
       // Squatter detection (#580 item 4): real probes on the production path;
       // the stub-spawner test path defaults to "no squatter / unknown owner" so
       // fake-proc tests (which never hold a real port) aren't tripped. Tests
@@ -509,7 +524,9 @@ export class Supervisor {
     const startBinary = req.cmd[0];
     if (startBinary) {
       try {
-        ensureExecutable(startBinary, { which: this.opts.which });
+        const ensureOpts: Parameters<typeof ensureExecutable>[1] = { which: this.opts.which };
+        if (this.opts.findNonExecutable) ensureOpts.findNonExecutable = this.opts.findNonExecutable;
+        ensureExecutable(startBinary, ensureOpts);
       } catch (err) {
         if (err instanceof MissingDependencyError) {
           entry.state = {
@@ -520,6 +537,18 @@ export class Supervisor {
           };
           return entry.state;
         }
+        // #634: the binary IS present but not executable (a `bin` that lost its
+        // +x bit). Record the actionable chmod hint instead of a misleading
+        // "not installed" — and never throw out of `start`.
+        if (err instanceof NonExecutableError) {
+          entry.state = {
+            ...entry.state,
+            status: "crashed",
+            pid: undefined,
+            startError: nonExecutableStartError(err, this.opts.now),
+          };
+          return entry.state;
+        }
         throw err;
       }
     }
@@ -1243,6 +1272,21 @@ function startErrorFromWire(wire: MissingDependencyWire, now: () => number): Mod
   };
 }
 
+/**
+ * #634: map a `NonExecutableError` (binary present on PATH but not +x) onto the
+ * `ModuleStartError` shape. `error_type: "non_executable"` so a UI can branch;
+ * `error_description` is the formatted `chmod +x` block. No install card — the
+ * fix is a permission flip, not a reinstall.
+ */
+function nonExecutableStartError(err: NonExecutableError, now: () => number): ModuleStartError {
+  return {
+    error_type: err.errorType,
+    error_description: err.message,
+    binary: err.binary,
+    at: new Date(now()).toISOString(),
+  };
+}
+
 /**
  * Production group-aware kill (hub#88). Sends `signal` to the entire process
  * group rooted at `pid` (the negative-pid syscall) so a wrapped startCmd's

package/src/vault-names.ts

@@ -23,8 +23,17 @@
  * Walks both manifest shapes: single-entry-multi-path (`parachute-vault`
  * with `paths: ["/vault/work", "/vault/personal"]`) and per-vault entries
  * (`parachute-vault-work`) by delegating each (name, path) pair to
- * `vaultInstanceNameFor`. Entries with no paths still resolve to a name via
- * the helper's manifest-suffix fallback (hub#143).
+ * `vaultInstanceNameFor`.
+ *
+ * #478: an empty-paths vault row (e.g. `parachute-vault` with `paths: []`,
+ * which vault's self-register emits at zero vaults) is "installed but no
+ * servable vault instance" and is SKIPPED entirely — it must not synthesize a
+ * name (the bare `parachute-vault` would otherwise resolve to a phantom
+ * "default"). This mirrors the empty-paths `continue` in `admin-vaults.ts`'s
+ * `findExistingVault`/`listVaultInstanceNames`, so every read path agrees: a
+ * vault instance is named only by a real `/vault/<name>` mount path. This
+ * supersedes the prior hub#143 manifest-suffix fallback for path-less entries
+ * — a registered vault carries its mount path once a vault exists.
  */
 import { type ServicesManifest, readManifestLenient } from "./services-manifest.ts";
 import { isVaultEntry, vaultInstanceNameFor } from "./well-known.ts";
@@ -39,8 +48,10 @@ export function listVaultNames(manifest: ServicesManifest): string[] {
   const names = new Set<string>();
   for (const svc of manifest.services) {
     if (!isVaultEntry(svc)) continue;
-    const paths = svc.paths.length > 0 ? svc.paths : [undefined];
-    for (const path of paths) {
+    // #478: an empty-paths vault row means "installed but no servable vault
+    // instance" — skip it so it never synthesizes a phantom "default".
+    if (svc.paths.length === 0) continue;
+    for (const path of svc.paths) {
       names.add(vaultInstanceNameFor(svc.name, path));
     }
   }

package/src/well-known.ts

@@ -247,7 +247,16 @@ export function buildWellKnown(opts: BuildWellKnownOpts): WellKnownDocument {
     // multi-path on those is treated as aliases rather than separate
     // installs.
     const isVault = isVaultEntry(s);
-    const pathsToEmit = isVault && s.paths.length > 0 ? s.paths : [s.paths[0] ?? "/"];
+    // #478: an empty-paths VAULT row means "installed but no servable vault
+    // instance" — vault's self-register emits `paths: []` at zero vaults.
+    // Skip it entirely: emitting `["/"]` here would fabricate a phantom vault
+    // entry at root in both the `services` catalog and the `vaults` array.
+    // This mirrors the empty-paths `continue` in admin-vaults.ts / vault-names.ts
+    // so every read path agrees: a vault instance exists only by a real
+    // `/vault/<name>` mount path. Non-vault services keep the `paths[0] ?? "/"`
+    // fallback (a path-less non-vault row legitimately mounts at root).
+    if (isVault && s.paths.length === 0) continue;
+    const pathsToEmit = isVault ? s.paths : [s.paths[0] ?? "/"];
     for (const path of pathsToEmit) {
       const url = new URL(path, `${base}/`).toString();
       const infoUrl = new URL(joinInfoPath(path), `${base}/`).toString();