@openparachute/hub 0.7.5 → 0.7.6-rc.1

package/src/__tests__/setup.test.ts

@@ -119,9 +119,12 @@ describe("isOfferable (fresh-install OFFER, 2026-06-25)", () => {
     expect(isOfferable({ short: "agent", installed: false })).toBe(true);
   });
 
-  test("does NOT offer a deprecated module (notes / runner) on a fresh install", () => {
+  test("does NOT offer a deprecated module (notes) on a fresh install", () => {
     expect(isOfferable({ short: "notes", installed: false })).toBe(false);
-    expect(isOfferable({ short: "runner", installed: false })).toBe(false);
+    // runner is stronger than deprecated now: it left the registries entirely
+    // (2026-07-01), so it never reaches the survey → isOfferable never sees
+    // it. (The bare predicate would say true for an unknown short — the OFFER
+    // gate for runner is `knownServices()` no longer containing it.)
   });
 
   test("never offers an already-installed module regardless of tier", () => {
@@ -137,6 +140,9 @@ describe("setup", () => {
       // Pre-seed every first-party shortname so survey returns all-installed.
       // Distinct canonical ports per service — services-manifest.ts now
       // rejects duplicate ports between distinct services (hub#195).
+      // parachute-runner rides along as a LEGACY row (runner left the
+      // registries 2026-07-01): it must neither block the all-installed exit
+      // nor crash the survey.
       const seeds: Array<{ name: string; port: number }> = [
         { name: "parachute-vault", port: 1940 },
         { name: "parachute-notes", port: 1942 },
@@ -175,12 +181,13 @@ describe("setup", () => {
     }
   });
 
-  test("fresh box: the offered 'Available to install' list excludes deprecated notes/runner (2026-06-25)", async () => {
+  test("fresh box: the offered 'Available to install' list excludes deprecated notes + removed runner", async () => {
     const h = makeHarness();
     try {
       // 'all' picks every OFFERED service. With a clean services.json the survey
-      // sees every known short; the offered filter must drop notes + runner
-      // (deprecated) while keeping vault/scribe/surface/agent. Only vault +
+      // sees every known short; the offered filter must drop notes (deprecated,
+      // 2026-06-25) while runner never even reaches the survey (registry
+      // removal, 2026-07-01) — keeping vault/scribe/surface/agent. Only vault +
       // scribe have pre-install follow-up prompts (vault name, scribe provider);
       // surface + agent have none — so the scripted answers below are complete.
       const availability = scriptedAvailability([
@@ -221,10 +228,57 @@ describe("setup", () => {
   test("an already-installed deprecated module still shows in 'Already installed' + isn't re-offered (back-compat)", async () => {
     const h = makeHarness();
     try {
-      // Legacy operator with runner (deprecated) on disk. It must surface in the
-      // "Already installed" banner (so they know it's there + can manage it via
-      // `parachute <verb> runner`), and must NOT reappear in the fresh-install
-      // OFFER list.
+      // Legacy operator with notes-daemon (deprecated) on disk. It must surface
+      // in the "Already installed" banner (so they know it's there + can manage
+      // it via `parachute <verb> notes`), and must NOT reappear in the
+      // fresh-install OFFER list.
+      upsertService(
+        {
+          name: "parachute-notes",
+          version: "0.3.15",
+          port: 1942,
+          paths: ["/notes"],
+          health: "/notes/health",
+        },
+        h.manifestPath,
+      );
+      const availability = scriptedAvailability([
+        "surface", // pick a still-offered module
+      ]);
+      const code = await setup({
+        manifestPath: h.manifestPath,
+        configDir: h.configDir,
+        log: (l) => h.logs.push(l),
+        availability,
+        installFn: async (short, opts) => {
+          h.calls.push({ short, opts });
+          return 0;
+        },
+      });
+      expect(code).toBe(0);
+      const joined = h.logs.join("\n");
+      // Banner lists notes as already installed…
+      const installedBlock = joined.slice(
+        joined.indexOf("Already installed:"),
+        joined.indexOf("Available to install:"),
+      );
+      expect(installedBlock).toMatch(/\bnotes\b/);
+      // …but notes is NOT in the fresh-install offer.
+      const availableBlock = joined.slice(joined.indexOf("Available to install:"));
+      expect(availableBlock).not.toMatch(/\bnotes\b/);
+      expect(h.calls.map((c) => c.short)).not.toContain("notes");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("a LEGACY parachute-runner row doesn't break setup and is never offered (registry removal 2026-07-01)", async () => {
+    const h = makeHarness();
+    try {
+      // runner left the registries entirely — the survey no longer knows the
+      // short, so the row is simply invisible to setup (not in "Already
+      // installed", not in the offer). The load-bearing assertions: setup
+      // still runs to completion and never tries to install runner.
       upsertService(
         {
           name: "parachute-runner",
@@ -250,16 +304,10 @@ describe("setup", () => {
       });
       expect(code).toBe(0);
       const joined = h.logs.join("\n");
-      // Banner lists runner as already installed…
-      const installedBlock = joined.slice(
-        joined.indexOf("Already installed:"),
-        joined.indexOf("Available to install:"),
-      );
-      expect(installedBlock).toMatch(/\brunner\b/);
-      // …but runner is NOT in the fresh-install offer.
       const availableBlock = joined.slice(joined.indexOf("Available to install:"));
       expect(availableBlock).not.toMatch(/\brunner\b/);
       expect(h.calls.map((c) => c.short)).not.toContain("runner");
+      expect(h.calls.map((c) => c.short)).toContain("surface");
     } finally {
       h.cleanup();
     }

package/src/__tests__/stale-module-units.test.ts

@@ -55,7 +55,7 @@ function joined(calls: string[][]): string[] {
 describe("targetModuleShorts() — known module shorts, never hub/cloudflared", () => {
   test("includes the canonical module shorts and excludes hub", () => {
     const shorts = targetModuleShorts();
-    // The canonical knownServices() set: vault / scribe / runner / surface / notes / channel.
+    // The canonical knownServices() set: vault / scribe / surface / notes / agent.
     expect(shorts).toContain("vault");
     expect(shorts).toContain("scribe");
     expect(shorts).toContain("surface");

package/src/admin-connections.ts

@@ -1797,8 +1797,12 @@ function sessionUser(req: Request, deps: ConnectionsDeps): { userId: string } {
  * the rule found this engine minting ~90-day tokens with no registry row — an
  * unrevocable-by-construction credential (`api-revoke-token` 404s unknown
  * jtis; the revocation list only carries registered jtis).
+ *
+ * Exported so other unregistered-by-policy mint sites (git-notify.ts's
+ * fire-and-forget notify/pull tokens) can statically assert their TTLs stay
+ * under this policy line instead of restating `600` in a comment.
  */
-const REGISTERED_MINT_TTL_THRESHOLD_SECONDS = 10 * 60;
+export const REGISTERED_MINT_TTL_THRESHOLD_SECONDS = 10 * 60;
 
 interface MintSpec {
   scopes: string[];

package/src/admin-module-token.ts

@@ -4,7 +4,7 @@
  *
  * Why this exists (2026-06-09 modular-UI architecture, P3): modules now own
  * their config/admin UIs and declare `configUiUrl` in `module.json` (scribe
- * `/scribe/admin`, runner `/runner/admin`, surface `/surface/admin/`, …). The
+ * `/scribe/admin`, surface `/surface/admin/`, …). The
  * hub frames/links those surfaces consistently (the Modules page "Configure"
  * action). Each module-owned config UI, served behind the hub proxy to a
  * logged-in portal operator, needs an admin-scoped hub Bearer to call its own
@@ -16,7 +16,7 @@
  *
  * Scope + audience: `<short>:admin`, audience = `<short>` (the bare service
  * prefix). Modules validate the JWT's `aud` against their literal short name
- * (`scribe`, `runner`, `surface`, `agent`) — the same shape `inferAudience`
+ * (`scribe`, `surface`, `agent`) — the same shape `inferAudience`
  * stamps for the public OAuth flow, so a hub-minted and an OAuth-minted admin
  * token are indistinguishable to the module. This mirrors the per-request
  * `<short>:admin` proxy token `api-modules-config.ts` used to mint; the

package/src/api-modules-ops.ts

@@ -354,13 +354,13 @@ async function authorize(req: Request, deps: ApiModulesOpsDeps): Promise<Respons
  * reach the same spec the API handlers use without duplicating the
  * curated-table lookup.
  *
- * Two source paths (post-FALLBACK-retirement: vault/scribe/runner in
+ * Two source paths (post-FALLBACK-retirement: vault/scribe in
  * hub#310, channel in boundary D3):
  *
  *   - **FIRST_PARTY_FALLBACKS** (notes): vendored manifest is
  *     authoritative pre-install — the embedded `manifest.startCmd` /
  *     `manifest.paths` / etc. drive the install + spawn flow.
- *   - **KNOWN_MODULES** (vault / scribe / runner / channel / surface): no
+ *   - **KNOWN_MODULES** (vault / scribe / agent / surface): no
  *     vendored manifest.
  *     Pre-install we know only the npm package + manifestName + canonical
  *     port + imperative `extras` (init, postInstallFooter, urlForEntry,
@@ -831,7 +831,7 @@ export async function runInstall(
     });
   }
 
-  // KNOWN_MODULES shorts (vault / scribe / runner / channel / surface):
+  // KNOWN_MODULES shorts (vault / scribe / agent / surface):
   // module.json is the canonical source for startCmd. Re-resolve the spec
   // from `<installDir>/.parachute/module.json` when installDir is stamped so
   // the module is authoritative for its own spawn cmd. Falls back to the

package/src/api-modules.ts

@@ -18,7 +18,7 @@
  * `focus` ("core" | "experimental" | "deprecated") comes from each module's
  * `module.json` when declared, else `focusForShort`'s default map. The SPA
  * groups core first, de-emphasizes experimental, and de-emphasizes
- * `deprecated` (notes-daemon / runner) further — it NEVER hides an installed
+ * `deprecated` (notes-daemon) further — it NEVER hides an installed
  * module (so an existing operator can still manage / uninstall a deprecated
  * one). This is what makes a running, self-registered module (channel) visible
  * + installable; the old `CURATED_MODULES = ["vault","scribe"]` whitelist made
@@ -67,7 +67,7 @@ import {
 } from "./service-spec.ts";
 // `FIRST_PARTY_FALLBACKS` and `KNOWN_MODULES` are both consulted by
 // `lookupModule` below — the former for notes (vendored manifest still
-// required) and the latter for vault/scribe/runner/agent (post-FALLBACK
+// required) and the latter for vault/scribe/agent/surface (post-FALLBACK
 // retirement, hub#310). The local helper hides the split from the rest of
 // this file. `discoverableShorts` enumerates their UNION — the
 // self-registration-driven discovery surface that replaced the old
@@ -83,7 +83,7 @@ import type { ModuleStartError, ModuleState, Supervisor } from "./supervisor.ts"
 /**
  * Resolve a known module to the display + install bootstrap data the admin SPA
  * renders. Reads from FIRST_PARTY_FALLBACKS (notes) first,
- * KNOWN_MODULES (vault / scribe / runner / channel / surface) second.
+ * KNOWN_MODULES (vault / scribe / agent / surface) second.
  *
  * Returns `undefined` if the short is in neither table — a genuinely
  * third-party module discovered only via services.json / the supervisor. The
@@ -249,10 +249,10 @@ interface ModuleWireShape {
    * Discovery tier (2026-06-09 modular-UI architecture; `deprecated` added
    * 2026-06-25). `core` modules render in the headline group; `experimental`
    * modules render in a de-emphasized "Experimental" group; `deprecated`
-   * modules (notes-daemon / runner) render in a further-de-emphasized
+   * modules (notes-daemon) render in a further-de-emphasized
    * "Deprecated" group — never hidden when installed. Resolved from the
    * module's `module.json` `focus` when declared, else `focusForShort`'s
-   * default map (vault/scribe/hub/surface → core, notes/runner → deprecated,
+   * default map (vault/scribe/hub/surface → core, notes → deprecated,
    * others → experimental).
    */
   focus: ModuleFocus;
@@ -269,7 +269,7 @@ interface ModuleWireShape {
    * The fresh-install OFFER (2026-06-25): whether the hub presents this module
    * in the "available to install fresh" set. `available && focus !==
    * "deprecated"`. The SPA's "Install a module" catalog filters on this so
-   * notes-daemon / runner aren't pushed on a fresh box; an already-installed
+   * notes-daemon isn't pushed on a fresh box; an already-installed
    * deprecated module still surfaces (in the Installed section) for management.
    */
   available_to_install: boolean;
@@ -315,8 +315,8 @@ interface ModuleWireShape {
   install_dir: string | null;
   /**
    * Hierarchical sub-units beneath this module (hub#313). Empty when the
-   * module's services.json row doesn't declare `uis` (vault, scribe, notes,
-   * runner today). Used by parachute-app to surface each hosted UI as its
+   * module's services.json row doesn't declare `uis` (vault, scribe, notes
+   * today). Used by parachute-app to surface each hosted UI as its
    * own discoverable sub-row under the App module. Per parachute-app
    * design doc §12.
    */
@@ -336,8 +336,8 @@ interface ModuleWireShape {
    *      the operator UI (App today).
    *   3. Null when the module hasn't declared either field — the SPA
    *      renders a disabled "Open" tooltip (pointing at Configure when
-   *      `config_ui_url` is set — runner's shape today — or "module
-   *      hasn't shipped an admin UI yet" otherwise).
+   *      `config_ui_url` is set — or "module hasn't shipped an admin UI
+   *      yet" otherwise).
    *
    * Always an absolute path on the hub origin (leading `/`) — the SPA
    * navigates same-origin, no need to worry about cross-origin
@@ -660,7 +660,7 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
   // module's manifest-declared `focus` (when installed + declared) wins; else
   // the `focusForShort` default map. Sort: `core` group first (with the
   // CURATED_MODULES recommended-install order floated to the top of that
-  // group), then `experimental`, then `deprecated` (notes / runner) last — the
+  // group), then `experimental`, then `deprecated` (notes) last — the
   // SPA renders the groups; `focus` never hides an installed module.
   const recommendedOrder = new Map<string, number>(
     (CURATED_MODULES as readonly string[]).map((s, i) => [s, i]),
@@ -684,7 +684,7 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
       // package) is not hub-installable → false.
       available: m !== undefined,
       // Fresh-install OFFER (2026-06-25): installable AND not deprecated. A
-      // deprecated short (notes / runner) stays `available` (re-installable
+      // deprecated short (notes) stays `available` (re-installable
       // for back-compat) but is dropped from the offer set so the SPA's
       // "Install a module" catalog doesn't push it on a fresh box.
       available_to_install: m !== undefined && focus !== "deprecated",
@@ -867,7 +867,7 @@ let warnedLegacyVaultAdminCandidate = false;
  *   - `undefined` candidate → `undefined` (the module didn't declare it).
  *   - Absolute http(s) URL → returned verbatim (off-origin escape hatch).
  *   - Leading-`/` path → ORIGIN-ABSOLUTE, returned verbatim. Single-instance
- *     modules (surface, scribe, runner, agent) declare their full hub-origin
+ *     modules (surface, scribe, agent) declare their full hub-origin
  *     path this way (`/surface/admin/`, `/scribe/admin`, `/agent/admin`);
  *     vault's daemon-level surface is `/vault/admin/`.
  *   - Relative path (no leading slash) → MOUNT-JOINED: the per-instance form

package/src/commands/install.ts

@@ -65,7 +65,7 @@ export type Runner = (cmd: readonly string[]) => Promise<number>;
  * Rationale: the canonical Render deploy ships the hub container from
  * `main` (which tracks the rc chain per governance rule 2). Without this
  * env var the supervisor's `/admin/modules` install API would still
- * resolve `@latest` for vault / app / scribe / runner — leaving a hub-on-rc
+ * resolve `@latest` for vault / surface / scribe — leaving a hub-on-rc
  * cluster bootstrapping its other modules on stable, which silently
  * fragments the cluster's version axis. Setting `PARACHUTE_INSTALL_CHANNEL=rc`
  * at the platform level cascades the rc-ness across every module install,
@@ -137,6 +137,22 @@ const SERVICE_ALIASES: Record<string, string> = {
   channel: "agent",
 };
 
+/**
+ * Former first-party shorts that were RETIRED from the registries (not
+ * renamed — no alias target). Without this guard the bare short would fall
+ * through resolveInstallTarget's "anything else is npm" arm and `bun add -g`
+ * an UNRELATED npm package that happens to share the name (`runner` is a
+ * real, non-Parachute package on npm). Install refuses with the message
+ * instead.
+ */
+const RETIRED_INSTALL_SHORTS: Record<string, string> = {
+  runner:
+    "parachute-runner was retired from the hub's module registry on 2026-07-01 " +
+    "(the module set of record is vault, hub, agent, scribe, surface). " +
+    "An existing install keeps running under `parachute serve`; to install it anyway, " +
+    "pass the explicit npm package name (@openparachute/runner) or a local checkout path.",
+};
+
 export interface InstallOpts {
   runner?: Runner;
   manifestPath?: string;
@@ -625,7 +641,8 @@ async function readInstalledManifest(
  *   - **fallback**: notes / channel still ship a vendored manifest + extras
  *     in FIRST_PARTY_FALLBACKS. Missing `module.json` is non-fatal — the
  *     embedded manifest carries the install through.
- *   - **known**: vault / scribe / runner have retired their FALLBACK entries.
+ *   - **known**: vault / scribe / agent / surface have retired their FALLBACK
+ *     entries (runner had too, before its 2026-07-01 registry removal).
  *     We know the package + manifestName + imperative extras (init,
  *     postInstallFooter, urlForEntry, hasAuth) but NOT the static manifest;
  *     `module.json` is the contract and a missing one is a hard error,
@@ -672,6 +689,15 @@ function resolveInstallTarget(
   const aliased = SERVICE_ALIASES[input];
   const candidate = aliased ?? input;
 
+  // Retired shorts refuse BEFORE the npm fallback: `install runner` must not
+  // `bun add -g` npm's unrelated `runner` package. Explicit package names /
+  // paths still pass through the arms below.
+  const retiredMessage = RETIRED_INSTALL_SHORTS[candidate];
+  if (retiredMessage !== undefined) {
+    log(`✗ ${retiredMessage}`);
+    return null;
+  }
+
   const fb = FIRST_PARTY_FALLBACKS[candidate];
   if (fb) {
     if (aliased !== undefined) {
@@ -943,7 +969,7 @@ export async function install(input: string, opts: InstallOpts = {}): Promise<nu
     manifest = installedManifest ?? target.fallback.manifest;
     extras = target.fallback.extras;
   } else if (target.kind === "known-module") {
-    // KNOWN_MODULES shorts (vault / scribe / runner) carry no vendored
+    // KNOWN_MODULES shorts (vault / scribe / agent / surface) carry no vendored
     // manifest (hub#310). The module's own `.parachute/module.json` is the
     // canonical source. When it's unreadable (legacy installs from before
     // module.json shipped, or test fixtures that mock the disk path without

package/src/commands/migrate.ts

@@ -77,6 +77,11 @@ export const ARCHIVE_PREFIX = ".archive-";
 export function safelistEntries(): Set<string> {
   return new Set<string>([
     ...knownServices(),
+    // `runner` left the registries on 2026-07-01 (module set of record:
+    // vault / hub / agent / scribe / surface) but legacy installs still have
+    // a `~/.parachute/runner/` dir — keep it safelisted so it doesn't count
+    // as unrecognized-root noise in `migrateNotice`.
+    "runner",
     "hub",
     "services.json",
     "expose-state.json",

package/src/commands/setup.ts

@@ -66,7 +66,7 @@ export interface SetupOpts {
  * Survey row. Pre-install we know manifestName + the optional
  * `urlForEntry` quirk (vault wants `/mcp`, scribe wants the bare port); the
  * full ServiceSpec only exists post-install for KNOWN_MODULES shorts
- * (vault / scribe / runner — hub#310). The survey uses just these two
+ * (vault / scribe / … — hub#310). The survey uses just these two
  * fields, so a minimal shape avoids the spec round-trip pre-install.
  */
 interface ServiceChoice {
@@ -110,17 +110,19 @@ function defaultAvailability(): InteractiveAvailability {
 
 /**
  * Survey ALL known first-party shortnames (vault / notes / scribe / agent /
- * runner / surface) regardless of tier — `installed` is true when the service
+ * surface) regardless of tier — `installed` is true when the service
  * has a row in services.json. The fresh-install OFFER is narrowed downstream
  * by `isOfferable` (drops already-installed + `deprecated`-tier shorts —
- * notes / runner); agent (`experimental`) is flagged exploratory in its blurb
+ * notes); agent (`experimental`) is flagged exploratory in its blurb
  * but stays offered. Surveying everything keeps `installed` detection complete
  * (the "already installed" banner still lists a deprecated module an operator
- * has on disk).
+ * has on disk). A legacy `parachute-runner` row is NOT surveyed (runner left
+ * the registries 2026-07-01 — see the KNOWN_MODULES note in service-spec.ts);
+ * like any unknown row it neither blocks setup nor appears in the offer.
  *
  * The full ServiceSpec is only available pre-install for FIRST_PARTY_FALLBACKS
  * shorts (notes — it carries a vendored manifest). KNOWN_MODULES shorts
- * (vault / scribe / runner / agent / surface) ship `.parachute/module.json`
+ * (vault / scribe / agent / surface) ship `.parachute/module.json`
  * and self-register; pre-install we know manifestName + the urlForEntry quirk
  * from `KNOWN_MODULES[short].extras`, which is all the survey/summary needs.
  */
@@ -157,7 +159,7 @@ function surveyServices(manifestPath: string): ServiceChoice[] {
 /**
  * A surveyed service is OFFERED on a fresh setup iff it is not already
  * installed AND its discovery tier is not `deprecated` (2026-06-25). The
- * deprecated tier (notes-daemon, runner) stays resolvable + manageable for an
+ * deprecated tier (notes-daemon) stays resolvable + manageable for an
  * existing install — it just isn't pushed on a fresh box. `agent`
  * (`experimental`) is still offered. Exported so the setup tests can pin the
  * exclusion directly.
@@ -175,11 +177,10 @@ const BLURBS: Record<string, string> = {
   surface: "Parachute UI host — auto-installs Notes on first boot (the recommended UI path)",
   // `app` is the pre-2026-05-27 name for `surface`; kept for any legacy survey row.
   app: "Parachute UI host — auto-installs Notes on first boot (recommended over notes-daemon)",
-  // notes / runner are `deprecated` (not offered on a fresh setup) — these
-  // blurbs only render if a legacy install surfaces them in the survey.
+  // notes is `deprecated` (not offered on a fresh setup) — this blurb only
+  // renders if a legacy install surfaces it in the survey.
   notes: "Notes PWA — web/mobile UI on top of vault (notes-daemon; superseded by `surface`)",
   scribe: "audio transcription for dictation + recordings",
-  runner: "vault-as-job-substrate — scheduled claude -p against vault job notes",
   agent:
     "(exploratory) chat with your Claude Code sessions — a channel per session (renamed from channel)",
 };

package/src/connections-store.ts

@@ -113,12 +113,22 @@ export interface ConnectionRecord {
   readonly requestedBy?: string;
 }
 
+/**
+ * On-disk schema version stamped on every write (2026-07-01). Readers treat a
+ * file WITHOUT a `version` field as v1 — every connections.json written before
+ * this field existed is a v1 file, so absence tolerance is the whole
+ * back-compat story. No migration logic exists today; the field is here so a
+ * FUTURE shape change can branch on it instead of sniffing record shapes.
+ */
+export const CONNECTIONS_FILE_VERSION = 1;
+
 interface ConnectionsFile {
+  version: number;
   connections: ConnectionRecord[];
 }
 
 function emptyFile(): ConnectionsFile {
-  return { connections: [] };
+  return { version: CONNECTIONS_FILE_VERSION, connections: [] };
 }
 
 /** Read the store. A missing/garbage file reads as empty (fresh hub). */
@@ -136,6 +146,9 @@ export function readConnections(storePath: string): ConnectionRecord[] {
     return [];
   }
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return [];
+  // `version` is deliberately NOT validated here: an absent field is a legacy
+  // v1 file (see CONNECTIONS_FILE_VERSION) and there is only one version
+  // today. When v2 lands, this is where the migration branches.
   const arr = (parsed as { connections?: unknown }).connections;
   if (!Array.isArray(arr)) return [];
   // Lenient: drop any malformed row rather than failing the whole read, so one
@@ -156,7 +169,7 @@ export function readConnections(storePath: string): ConnectionRecord[] {
 
 function writeAll(storePath: string, records: ConnectionRecord[]): void {
   mkdirSync(dirname(storePath), { recursive: true });
-  const file: ConnectionsFile = { connections: records };
+  const file: ConnectionsFile = { version: CONNECTIONS_FILE_VERSION, connections: records };
   // Written WITHOUT 0o600 because this file holds NO secrets — the provisioned
   // webhook bearer lives only in the vault trigger's row, never here; records
   // carry source/sink/trigger-name metadata only. Consistent with the default

package/src/git-notify.ts

@@ -31,6 +31,7 @@
  * validates when it comes back in over loopback.
  */
 import type { Database } from "bun:sqlite";
+import { REGISTERED_MINT_TTL_THRESHOLD_SECONDS } from "./admin-connections.ts";
 import { signAccessToken } from "./jwt-sign.ts";
 
 /** Provenance identity stamped on the hub-internal notify + pull tokens. */
@@ -43,18 +44,46 @@ const SURFACE_AUDIENCE = "surface";
 /**
  * notify-auth TTL. The POST is fired immediately; a small window covers a
  * momentarily-busy loopback without leaving a usable credential lying around.
+ *
+ * Exported for the TTL-policy guard test only.
  */
-const NOTIFY_TTL_SECONDS = 120;
+export const NOTIFY_TTL_SECONDS = 120;
 
 /**
  * pull-token TTL. Long enough for surface-host to `git clone --depth 1` a
  * source surface right after the notify lands, short enough that a leaked
  * token is near-useless. Both TTLs here MUST stay well under the hub's
- * registered-mint threshold (admin-connections REGISTERED_MINT_TTL_THRESHOLD,
- * 600s) so these fire-and-forget tokens remain unregistered-by-policy — bumping
- * either past it without registering them would leak unrevocable tokens.
+ * registered-mint threshold (`REGISTERED_MINT_TTL_THRESHOLD_SECONDS`, 600s —
+ * imported from admin-connections.ts, where the policy lives) so these
+ * fire-and-forget tokens remain unregistered-by-policy — bumping either past
+ * it without registering them would leak unrevocable tokens. Enforced by
+ * {@link assertUnregisteredMintTtl} at module load, not just this comment.
+ *
+ * Exported for the TTL-policy guard test only.
  */
-const PULL_TTL_SECONDS = 300;
+export const PULL_TTL_SECONDS = 300;
+
+/**
+ * Registered-mint policy guard (hub-module-boundary charter): a TTL minted
+ * WITHOUT a tokens-table registration must stay strictly under the
+ * registered-mint threshold. Throws at module load when a future edit bumps
+ * one of this file's fire-and-forget TTLs to/past the line — turning a silent
+ * "unrevocable token" policy leak into an immediate boot failure.
+ *
+ * Exported for tests; not for reuse as a general validator (registered mint
+ * sites legitimately exceed the threshold — they register the jti instead).
+ */
+export function assertUnregisteredMintTtl(name: string, ttlSeconds: number): void {
+  if (ttlSeconds >= REGISTERED_MINT_TTL_THRESHOLD_SECONDS) {
+    throw new Error(
+      `git-notify: ${name} (${ttlSeconds}s) must stay under the registered-mint threshold (${REGISTERED_MINT_TTL_THRESHOLD_SECONDS}s). Tokens minted here are fire-and-forget and never registered in the tokens table — at/above the threshold they'd be long-lived AND unrevocable. Either shorten the TTL or register the mint (see admin-connections.ts registered-mint rule).`,
+    );
+  }
+}
+
+// Module-load enforcement of the policy the comments above describe.
+assertUnregisteredMintTtl("NOTIFY_TTL_SECONDS", NOTIFY_TTL_SECONDS);
+assertUnregisteredMintTtl("PULL_TTL_SECONDS", PULL_TTL_SECONDS);
 
 /** Bound the notify HTTP call so a wedged surface-host can't hang the caller. */
 const NOTIFY_FETCH_TIMEOUT_MS = 10_000;

package/src/grants-store.ts

@@ -143,7 +143,17 @@ export interface GrantRecord {
   readonly approvedAt?: string;
 }
 
+/**
+ * On-disk schema version stamped on every write (2026-07-01). Readers treat a
+ * file WITHOUT a `version` field as v1 — every agent-grants.json written
+ * before this field existed is a v1 file, so absence tolerance is the whole
+ * back-compat story. No migration logic exists today; the field is here so a
+ * FUTURE shape change can branch on it instead of sniffing record shapes.
+ */
+export const GRANTS_FILE_VERSION = 1;
+
 interface GrantsFile {
+  version: number;
   grants: GrantRecord[];
 }
 
@@ -194,7 +204,7 @@ export function grantId(agent: string, spec: ConnectionSpec): string {
 }
 
 function emptyFile(): GrantsFile {
-  return { grants: [] };
+  return { version: GRANTS_FILE_VERSION, grants: [] };
 }
 
 function isConnectionSpec(v: unknown): v is ConnectionSpec {
@@ -221,6 +231,9 @@ export function readGrants(storePath: string): GrantRecord[] {
     return [];
   }
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return [];
+  // `version` is deliberately NOT validated here: an absent field is a legacy
+  // v1 file (see GRANTS_FILE_VERSION) and there is only one version today.
+  // When v2 lands, this is where the migration branches.
   const arr = (parsed as { grants?: unknown }).grants;
   if (!Array.isArray(arr)) return [];
   // Lenient: drop a malformed row rather than failing the whole read (mirrors
@@ -245,7 +258,7 @@ export function readGrants(storePath: string): GrantRecord[] {
 
 function writeAll(storePath: string, records: GrantRecord[]): void {
   mkdirSync(dirname(storePath), { recursive: true });
-  const file: GrantsFile = { grants: records };
+  const file: GrantsFile = { version: GRANTS_FILE_VERSION, grants: records };
   // 0600 — UNLIKE connections.json, this file holds the granted secrets
   // (minted vault tokens + pasted service creds in `material`). `writeFileSync`'s
   // `mode` applies at CREATE time (passed to open(O_CREAT)), so a fresh file is

package/src/help.ts

@@ -103,8 +103,8 @@ Flags:
 Environment:
   PARACHUTE_INSTALL_CHANNEL=rc|latest
                             cluster-wide default channel. Lets a Render deploy
-                            running the hub at \`@rc\` cascade rc to vault / app /
-                            scribe / runner installed via the admin SPA — without
+                            running the hub at \`@rc\` cascade rc to vault / surface /
+                            scribe installed via the admin SPA — without
                             an explicit \`--channel\` per call. Loses to \`--channel\`
                             and \`--tag\`. Defaults to \`latest\` when unset.
 
@@ -144,7 +144,7 @@ What it does:
   Fresh-install front door, one command for both laptops AND remote
   servers (EC2, DigitalOcean, Hetzner, any VPS). The admin SPA already
   walks operators through the rest (install vault, set up the admin
-  user, install scribe / runner / app); this command's only job is to
+  user, install scribe / surface); this command's only job is to
   get you to that wizard.
 
   Idempotent — every re-run is safe:

package/src/install-source.ts

@@ -123,7 +123,7 @@ function packageNameFor(entryName: string): string | undefined {
   if (short === undefined) return undefined;
   const fb = FIRST_PARTY_FALLBACKS[short];
   if (fb) return fb.package;
-  // KNOWN_MODULES (vault / scribe / runner — post hub#310 FALLBACK
+  // KNOWN_MODULES (vault / scribe / agent / surface — post hub#310 FALLBACK
   // retirement) carries the package name without an embedded manifest.
   return KNOWN_MODULES[short]?.package;
 }