@openparachute/hub 0.7.1 → 0.7.2-rc.1

package/src/commands/upgrade.ts

@@ -44,6 +44,26 @@
  * downgrades: if `npm view <pkg>@<channel> version` resolves to something
  * lower than what's installed, we abort with an actionable message
  * (override with `--allow-downgrade`).
+ *
+ * RC-channel best-of resolution (hub#659). Channel preservation (#332) made
+ * the rc channel sticky — `parachute upgrade` follows `@rc`. But the rc
+ * channel is a *canary*: when a train ships stable-direct without cutting an
+ * rc (the common case under the post-#332 governance where trains start at
+ * stable), `@rc` doesn't advance and the box strands BELOW `@latest` with no
+ * visible path forward (the live case: friends.parachute.computer pinned at
+ * 0.6.5-rc.8 while @latest moved to 0.7.1). The fix: on the rc channel we
+ * resolve the target to the HIGHEST version above installed across BOTH `@rc`
+ * AND `@latest`.
+ *   - mid-chain (a newer rc exists) → take the rc; the canary stays ahead
+ *     (UNCHANGED — this is the #332 behavior).
+ *   - end-of-chain / skipped-rc train (no newer rc, but @latest > installed)
+ *     → CONVERGE to @latest, with a loud log line. The operator stays ON the
+ *     rc channel (the install/config notion of channel is unchanged) — only
+ *     the resolved VERSION changes; they pick up the next rc when it ships.
+ *   - nothing newer anywhere → the existing up-to-date no-op.
+ * The `@latest` (stable) channel path is UNCHANGED — stable never reaches for
+ * `@rc`. `--channel rc|latest` explicit overrides and `--allow-downgrade`
+ * keep working.
  */
 
 import { existsSync, readFileSync, realpathSync } from "node:fs";
@@ -689,10 +709,102 @@ function pickChannel(installedVersion: string | null, r: Resolved): string {
   return "latest";
 }
 
+/**
+ * The dist-tag / version `upgradeNpm` will hand to `bun add -g`, after the
+ * rc-channel best-of resolution (hub#659). `installSpec` is what follows the
+ * `@` in `bun add -g <pkg>@<installSpec>` — usually a dist-tag (`rc` /
+ * `latest`), but a pinned concrete version when we converge an rc-channel box
+ * onto stable (so a moving `@latest` can't race the resolution). `channel` is
+ * the dist-tag we resolved against, used by the downgrade-guard messaging.
+ */
+interface ResolvedNpmTarget {
+  installSpec: string;
+  channel: string;
+}
+
+/**
+ * Resolve which version the rc channel should actually move to (hub#659).
+ *
+ * Channel preservation (#332) keeps an rc operator following `@rc`. But `@rc`
+ * is a canary that only advances when a train cuts an rc; a stable-direct
+ * train leaves it stranded below `@latest`. So on the rc channel we look at
+ * BOTH dist-tags and take the highest one that's actually ABOVE installed:
+ *   - a newer `@rc` exists → stay on rc (mid-chain canary; UNCHANGED).
+ *   - no newer rc but `@latest` > installed → converge to `@latest`, pinned to
+ *     the concrete resolved version, with a LOUD log. The operator stays ON
+ *     the rc channel; only this upgrade's resolved version changes.
+ *   - neither tag is above installed → fall through to the rc tag and let the
+ *     normal "already at <v>" no-op fire after `bun add -g`.
+ *
+ * Returns the original `{ installSpec: "rc" }` unchanged whenever we can't read
+ * the installed version or can't resolve a higher stable (fail-open: never
+ * block a legitimate `@rc` upgrade on a flaky probe).
+ */
+async function resolveRcBestOf(
+  target: ResolvedTarget,
+  beforeVersion: string | null,
+  r: Resolved,
+): Promise<ResolvedNpmTarget> {
+  const rcTarget: ResolvedNpmTarget = { installSpec: "rc", channel: "rc" };
+  if (!beforeVersion) return rcTarget;
+
+  const [rcVersion, latestVersion] = await Promise.all([
+    r.resolveChannelVersion(target.packageName, "rc"),
+    r.resolveChannelVersion(target.packageName, "latest"),
+  ]);
+
+  const rcAbove = rcVersion !== null && (compareVersions(rcVersion, beforeVersion) ?? -1) > 0;
+  if (rcAbove) {
+    // A newer rc exists — the canary stays ahead (the #332 mid-chain path).
+    return rcTarget;
+  }
+
+  const latestAbove =
+    latestVersion !== null && (compareVersions(latestVersion, beforeVersion) ?? -1) > 0;
+  // (`latestVersion !== null` already guaranteed by `latestAbove`; the second
+  // term only narrows it for TS.)
+  if (latestAbove && latestVersion) {
+    // End-of-chain / skipped-rc train: nothing newer on @rc, but stable moved
+    // ahead. Converge to @latest — pinned to the concrete version so a moving
+    // dist-tag can't race us — and say so LOUDLY (the hub#659 stranding fix).
+    r.log(
+      `${target.short}: the rc channel has nothing newer than ${beforeVersion}; ` +
+        `converging to stable ${latestVersion} — you'll pick up the next rc when it ships.`,
+    );
+    return { installSpec: latestVersion, channel: "latest" };
+  }
+
+  // Neither tag is above installed — stay on @rc and let the post-install
+  // "already at <v>" no-op fire (handled in upgradeNpm). When both probes
+  // resolved and both are ≤ installed, name that explicitly.
+  if (rcVersion !== null && latestVersion !== null) {
+    r.log(
+      `${target.short}: on the rc channel — @rc (${rcVersion}) and @latest (${latestVersion}) ` +
+        `are both at or below installed ${beforeVersion}.`,
+    );
+  }
+  return rcTarget;
+}
+
 async function upgradeNpm(target: ResolvedTarget, sourceDir: string, r: Resolved): Promise<number> {
   r.log(`${target.short}: npm-installed (${sourceDir})`);
   const beforeVersion = readPackageVersion(join(sourceDir, "package.json"));
-  const channel = pickChannel(beforeVersion, r);
+  const pickedChannel = pickChannel(beforeVersion, r);
+
+  // RC-channel best-of resolution (hub#659). On the rc channel, resolve to the
+  // highest version above installed across @rc AND @latest — so an end-of-chain
+  // box converges to stable instead of stranding below it. The stable channel
+  // and explicit programmatic `--tag` are UNCHANGED: only an *auto-detected or
+  // --channel-rc* resolution reaches for stable. An explicit `--channel rc`
+  // ALSO flows through best-of (a deliberate rc operator still gets converge);
+  // `r.tag` (programmatic pin) and `--channel latest` both leave it untouched.
+  let installSpec = pickedChannel;
+  let channel = pickedChannel;
+  if (pickedChannel === "rc" && !r.tag) {
+    const resolved = await resolveRcBestOf(target, beforeVersion, r);
+    installSpec = resolved.installSpec;
+    channel = resolved.channel;
+  }
 
   // Downgrade guard: refuse to silently move backward. Only applies when
   // we can read both sides — beforeVersion from disk, targetVersion via
@@ -700,6 +812,10 @@ async function upgradeNpm(target: ResolvedTarget, sourceDir: string, r: Resolved
   // behavior: just run `bun add -g`). This is the load-bearing fix for
   // hub#332 — Aaron got `0.5.13-rc.13` → `0.5.10` because the implicit
   // `@latest` resolved to a prior stable while he was on the rc chain.
+  //
+  // After hub#659's best-of resolution `channel` is already the tag we're
+  // actually shipping (rc on the canary path, latest on the converge path), so
+  // the guard checks the version we'll really install.
   if (beforeVersion && !r.allowDowngrade) {
     const targetVersion = await r.resolveChannelVersion(target.packageName, channel);
     if (targetVersion) {
@@ -725,7 +841,7 @@ async function upgradeNpm(target: ResolvedTarget, sourceDir: string, r: Resolved
     }
   }
 
-  const spec = `${target.packageName}@${channel}`;
+  const spec = `${target.packageName}@${installSpec}`;
   r.log(`${target.short}: bun add -g ${spec}`);
   const code = await r.runner.run(["bun", "add", "-g", spec]);
   if (code !== 0) {

package/src/commands/vault-remove.ts

@@ -0,0 +1,361 @@
+/**
+ * `parachute vault remove <name>` — route the CLI vault-delete verb through the
+ * hub's identity cascade instead of the mechanics-only `parachute-vault remove`.
+ *
+ * ## Why this command exists (B3)
+ *
+ * The transparent `parachute vault <args>` passthrough (`commands/vault.ts`)
+ * forwards `remove <name>` verbatim to `parachute-vault remove` — which only
+ * does the MECHANICS of destruction (`rmSync` the vault dir + rewrite the vault
+ * module's own config). That path BYPASSES every hub-side identity artifact tied
+ * to the vault: live `vault:<name>:*` access tokens stay valid (and reachable
+ * via the polled revocation list), `user_vaults` rows linger, grants keep their
+ * `vault:<name>:*` entries, unredeemed invites pinned to the vault stay
+ * redeemable, and Connections that source/provision the vault keep their
+ * long-lived mints. Deleting a vault that way orphans all of it.
+ *
+ * The hub ALREADY ships the correct path: `DELETE /vaults/<name>`
+ * (`admin-vaults.ts:handleDeleteVault`) runs the full 7-step identity cascade
+ * (revoke tokens → rewrite grants → drop user_vaults → revoke invites → tear
+ * down connections → shell `parachute-vault remove` → restart vault) and is
+ * exactly what the vault-admin SPA drives. This command routes the CLI verb
+ * through that SAME endpoint over loopback, so `parachute vault remove` and the
+ * SPA delete are one code path.
+ *
+ * ## Credential + transport (reused from module-ops-client.ts)
+ *
+ * We drive the RUNNING hub over loopback — never open hub.db's vault registry
+ * directly (the daemon holds it). The bearer is the on-disk
+ * `~/.parachute/operator.token`, read (never minted) via
+ * `useOperatorTokenWithAutoRotate`. Its default `admin` scope-set carries
+ * `parachute:host:admin` — exactly the scope the endpoint gates on. This is the
+ * same read-never-mint credential path `parachute start/stop/restart <svc>` use.
+ *
+ * ## The 409 guardrail (load-bearing)
+ *
+ * On a `409 last_vault` the endpoint refuses (deleting the last vault would let
+ * vault's boot silently resurrect a fresh `default`). We print the endpoint's
+ * message + note the raw escape hatch (`parachute-vault remove <name> --yes`)
+ * which SKIPS the cascade, then return NON-ZERO. We MUST NOT fall through to
+ * spawning `parachute-vault` ourselves: a "helpful" fall-through would re-open
+ * the exact orphaning bug B3 closes. The test locks this invariant.
+ */
+
+import { CONFIG_DIR } from "../config.ts";
+import { readExposeState } from "../expose-state.ts";
+import { readHubPort } from "../hub-control.ts";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
+import { HUB_UNIT_DEFAULT_PORT } from "../hub-unit.ts";
+import {
+  DEFAULT_HUB_BASE_URL,
+  ModuleOpHttpError,
+  NoOperatorTokenError,
+  OperatorTokenExpiredError,
+  resolveOperatorBearer,
+} from "../module-ops-client.ts";
+
+/**
+ * Injectable seams. Production wires the real operator-token bearer resolver +
+ * the global `fetch`; tests inject fakes to assert the request shape + lock the
+ * 409 guardrail without a live hub or a real socket.
+ */
+export interface VaultRemoveDeps {
+  /**
+   * Resolve the operator-token bearer to present to the loopback hub. Default
+   * opens hub.db, reads `~/.parachute/operator.token` (auto-rotating if near
+   * expiry), and returns the JWT. Throws {@link NoOperatorTokenError} /
+   * {@link OperatorTokenExpiredError} with already-actionable messages.
+   */
+  readonly resolveBearer?: () => Promise<string>;
+  /** fetch seam — `globalThis.fetch` in production; a recorder in tests. */
+  readonly fetch?: typeof fetch;
+  /** Loopback hub base URL. Defaults to {@link DEFAULT_HUB_BASE_URL}. */
+  readonly baseUrl?: string;
+  /** Output sink. Defaults to `console.log`. */
+  readonly log?: (line: string) => void;
+  /** Error sink. Defaults to `console.error`. */
+  readonly logError?: (line: string) => void;
+}
+
+/** Wire shape of the cascade summary nested under `cascade` in the 200 body. */
+interface CascadeSummaryWire {
+  tokens_revoked?: number;
+  grants_rewritten?: number;
+  grants_dropped?: number;
+  user_vaults_removed?: number;
+  invites_invalidated?: number;
+  connections_torn_down?: number;
+  orphaned_channels?: unknown;
+  vault_removed?: boolean;
+  module_restarted?: boolean;
+}
+
+interface DeleteVaultSuccessWire {
+  ok?: boolean;
+  name?: string;
+  cascade?: CascadeSummaryWire;
+  warnings?: unknown;
+}
+
+/**
+ * Resolve the hub origin the operator token's `iss` is validated against —
+ * mirrors `lifecycle.ts:resolveOperatorTokenIssuer`. Unlike the spawn-env
+ * derivation, the operator token always carries an `iss`, so we fall back to
+ * the canonical loopback origin (never `undefined`). The known-issuer SET inside
+ * `useOperatorTokenWithAutoRotate` also accepts the public `iss` from
+ * expose-state, so a seed of loopback still validates an exposed-origin token.
+ */
+function resolveOperatorTokenIssuer(configDir: string): string {
+  const state = readExposeState(`${configDir}/expose-state.json`);
+  if (state?.hubOrigin) return state.hubOrigin;
+  const port = readHubPort(configDir) ?? HUB_UNIT_DEFAULT_PORT;
+  return `http://127.0.0.1:${port}`;
+}
+
+/**
+ * Default bearer resolver: open hub.db, read+auto-rotate the operator token,
+ * return the JWT. Closes the db before returning. Read-never-mint — no second
+ * SQLite writer racing the running hub.
+ */
+async function defaultResolveBearer(configDir: string): Promise<string> {
+  const issuer = resolveOperatorTokenIssuer(configDir);
+  const db = openHubDb(hubDbPath(configDir));
+  try {
+    return await resolveOperatorBearer({ db, issuer, configDir });
+  } finally {
+    db.close();
+  }
+}
+
+function n(v: number | undefined): number {
+  return typeof v === "number" ? v : 0;
+}
+
+function asStringArray(v: unknown): string[] {
+  return Array.isArray(v) ? v.filter((x): x is string => typeof x === "string") : [];
+}
+
+/**
+ * Render the structured cascade summary the endpoint returns — the operator's
+ * proof every identity artifact was revoked, not just the vault dir removed.
+ */
+function renderCascadeSummary(
+  name: string,
+  body: DeleteVaultSuccessWire,
+  log: (line: string) => void,
+): void {
+  const c = body.cascade ?? {};
+  log(`Removed vault "${name}" with the full identity cascade:`);
+  log(`  tokens revoked:        ${n(c.tokens_revoked)}`);
+  log(`  grants rewritten:      ${n(c.grants_rewritten)}`);
+  log(`  grants dropped:        ${n(c.grants_dropped)}`);
+  log(`  user_vaults removed:   ${n(c.user_vaults_removed)}`);
+  log(`  invites invalidated:   ${n(c.invites_invalidated)}`);
+  log(`  connections torn down: ${n(c.connections_torn_down)}`);
+  log(`  vault removed:         ${c.vault_removed === true ? "yes" : "no"}`);
+  log(`  vault module restarted:${c.module_restarted === true ? " yes" : " no"}`);
+
+  const orphaned = asStringArray(c.orphaned_channels);
+  if (orphaned.length > 0) {
+    log("");
+    log(`WARNING: ${orphaned.length} vault-backed agent channel(s) still reference "${name}":`);
+    for (const ch of orphaned) log(`  - ${ch}`);
+    log("Remove them in the agent UI — the hub does not delete the agent's config.");
+  }
+
+  // Top-level warnings[] — each a { step, detail } the cascade recorded
+  // (e.g. daemon-restart skipped, a partial connection teardown).
+  const warnings = Array.isArray(body.warnings) ? body.warnings : [];
+  if (warnings.length > 0) {
+    log("");
+    log("Warnings:");
+    for (const w of warnings) {
+      const rec = (w ?? {}) as { step?: unknown; detail?: unknown };
+      const step = typeof rec.step === "string" ? rec.step : "warning";
+      const detail = typeof rec.detail === "string" ? rec.detail : JSON.stringify(w);
+      log(`  - [${step}] ${detail}`);
+    }
+  }
+}
+
+const USAGE = "usage: parachute vault remove <name> [--yes] [--hub-origin <url>]";
+
+/**
+ * Route `parachute vault remove <name>` (and the `rm` alias) through the hub's
+ * `DELETE /vaults/<name>` identity cascade. Returns the process exit code.
+ */
+export async function vaultRemove(args: string[], deps: VaultRemoveDeps = {}): Promise<number> {
+  const log = deps.log ?? ((line: string) => console.log(line));
+  const logError = deps.logError ?? ((line: string) => console.error(line));
+
+  // --- Parse args: positional <name> + flags (--yes/-y, --hub-origin <url>). --
+  let name: string | undefined;
+  let baseUrlOverride: string | undefined = deps.baseUrl;
+  // `--yes`/`-y` is accepted for parity with `parachute-vault remove --yes` and
+  // to telegraph non-interactive intent; the endpoint's confirm guard is
+  // satisfied from the name arg, so no extra prompt is shown either way. We
+  // parse it so it isn't mistaken for a positional, but the behaviour is the
+  // same with or without it (this is an admin op that already requires the
+  // operator token + a deliberate name retype on the wire).
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--yes" || a === "-y") continue;
+    if (a === "--hub-origin") {
+      const v = args[i + 1];
+      if (!v) {
+        logError("parachute vault remove: --hub-origin requires a URL argument");
+        return 1;
+      }
+      baseUrlOverride = v;
+      i++;
+      continue;
+    }
+    if (a?.startsWith("--hub-origin=")) {
+      baseUrlOverride = a.slice("--hub-origin=".length);
+      continue;
+    }
+    if (a?.startsWith("-")) {
+      logError(`parachute vault remove: unknown flag "${a}"`);
+      logError(USAGE);
+      return 1;
+    }
+    if (name === undefined) {
+      name = a;
+      continue;
+    }
+    logError(`parachute vault remove: unexpected argument "${a}"`);
+    logError(USAGE);
+    return 1;
+  }
+
+  if (!name) {
+    logError("parachute vault remove: a vault name is required");
+    logError(USAGE);
+    return 1;
+  }
+
+  // --- Resolve the operator-token bearer (read, never mint). ------------------
+  let bearer: string;
+  try {
+    bearer = deps.resolveBearer
+      ? await deps.resolveBearer()
+      : await defaultResolveBearer(CONFIG_DIR);
+  } catch (err) {
+    if (err instanceof NoOperatorTokenError || err instanceof OperatorTokenExpiredError) {
+      // Already-actionable ("run `parachute auth rotate-operator`") — surface
+      // verbatim, never a raw 401.
+      logError(`parachute vault remove: ${err.message}`);
+      return 1;
+    }
+    logError(`parachute vault remove: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+
+  // --- DELETE /vaults/<name> with the confirm body. --------------------------
+  const doFetch = deps.fetch ?? fetch;
+  const baseUrl = (baseUrlOverride ?? DEFAULT_HUB_BASE_URL).replace(/\/+$/, "");
+  const url = `${baseUrl}/vaults/${encodeURIComponent(name)}`;
+
+  let res: Response;
+  try {
+    res = await doFetch(url, {
+      method: "DELETE",
+      headers: {
+        authorization: `Bearer ${bearer}`,
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({ confirm: name }),
+    });
+  } catch (err) {
+    // Loopback connection refused → the hub isn't running. The cascade needs
+    // the live hub; there's no DB-side fallback we'd take (that's the bug).
+    const msg = err instanceof Error ? err.message : String(err);
+    const refused = /econnrefused|connection refused|failed to fetch|unable to connect/i.test(msg);
+    if (refused) {
+      logError(
+        "parachute vault remove: the hub must be running to delete a vault with the identity cascade.",
+      );
+      logError("Run `parachute start`, then retry.");
+      logError(
+        `(The raw escape hatch \`parachute-vault remove ${name} --yes\` deletes the vault dir but SKIPS the cascade, leaving orphaned tokens.)`,
+      );
+      return 1;
+    }
+    logError(`parachute vault remove: request failed: ${msg}`);
+    return 1;
+  }
+
+  const body = await parseJsonSafe(res);
+
+  // --- Success: render the cascade summary. ----------------------------------
+  if (res.status === 200) {
+    renderCascadeSummary(name, (body ?? {}) as DeleteVaultSuccessWire, log);
+    return 0;
+  }
+
+  // --- Error mapping (actionable, never a raw status dump). -------------------
+  const { error, error_description } = asErrorBody(body, res.status);
+
+  if (res.status === 404 && error === "not_found") {
+    // Idempotent: a re-run after a successful delete lands here. Not scary.
+    log(`Vault "${name}" does not exist on this hub (already removed). Nothing to do.`);
+    return 0;
+  }
+
+  if (res.status === 409 && error === "last_vault") {
+    // CRITICAL GUARDRAIL: print + exit non-zero. Do NOT fall through to spawning
+    // `parachute-vault` — that would re-open the orphaned-identity bug B3 closes.
+    logError(`parachute vault remove: ${error_description}`);
+    logError("");
+    logError(
+      `The raw mechanics-only path \`parachute-vault remove ${name} --yes\` can delete the last vault,`,
+    );
+    logError(
+      "but it SKIPS the identity cascade — live tokens, grants, and user_vaults rows for that",
+    );
+    logError("vault would be left orphaned. Create another vault first if you can.");
+    return 1;
+  }
+
+  if (res.status === 400 && error === "confirm_mismatch") {
+    // Pass the hub's confirm message through.
+    logError(`parachute vault remove: ${error_description}`);
+    return 1;
+  }
+
+  if (res.status === 401 || res.status === 403) {
+    // The operator token was rejected by the hub — guide to re-mint rather than
+    // dumping the raw status (matches module-ops-client's posture).
+    logError(`parachute vault remove: the hub rejected the operator token (${error_description}).`);
+    logError("Run `parachute auth rotate-operator` to mint a fresh one, then retry.");
+    return 1;
+  }
+
+  // Any other non-2xx — name the failure class without a raw dump.
+  logError(`parachute vault remove: ${error}: ${error_description}`);
+  return 1;
+}
+
+async function parseJsonSafe(res: Response): Promise<unknown> {
+  try {
+    return await res.json();
+  } catch {
+    return undefined;
+  }
+}
+
+function asErrorBody(body: unknown, status: number): { error: string; error_description: string } {
+  const fallback = `hub returned HTTP ${status} with no error detail`;
+  if (body && typeof body === "object") {
+    const b = body as Record<string, unknown>;
+    const error = typeof b.error === "string" ? b.error : "error";
+    const error_description =
+      typeof b.error_description === "string" ? b.error_description : fallback;
+    return { error, error_description };
+  }
+  return { error: "error", error_description: fallback };
+}
+
+// Re-export so the test (and future CLI callers) can catch the typed errors
+// without a second import path.
+export { ModuleOpHttpError, NoOperatorTokenError, OperatorTokenExpiredError };

package/src/commands/wizard.ts

@@ -749,10 +749,10 @@ export async function runCliWizard(opts: RunCliWizardOpts): Promise<number> {
     state = await fetchWizardState(hubUrl, jar, fetchImpl);
   }
   // Done screen — fetch + show a brief summary. The browser wizard's
-  // done screen surfaces the MCP install command + auto-minted token;
-  // we mirror that by reading the same `setup_minted_token` row via
-  // the GET endpoint's JSON envelope. Best-effort: a missing token
-  // just means we point the operator at /admin/tokens instead.
+  // done screen surfaces the bare OAuth `claude mcp add` command (no
+  // token, no header — vault is OAuth-default per parachute-vault #491);
+  // the CLI path never minted a token, so we just point the operator at
+  // the admin SPA + /admin/tokens for the headless-client case.
   log("");
   log("✓ Setup complete.");
   log(`  Visit ${hubUrl}/admin/ to open the admin SPA.`);

package/src/connections-store.ts

@@ -35,7 +35,7 @@ export interface ConnectionSource {
 
 /** The sink side — an action a module accepts (the sink is ALWAYS an action). */
 export interface ConnectionSink {
-  /** Sink module short name, e.g. `channel`. */
+  /** Sink module short name, e.g. `agent`. */
   readonly module: string;
   /** Action key declared in the sink module's `module.json`, e.g. `message.deliver`. */
   readonly action: string;
@@ -103,8 +103,8 @@ export interface ConnectionRecord {
   /**
    * Provenance — WHO requested this connection (modular-UI R2, module-initiated
    * connections). A module-owned config UI that creates a connection on the
-   * operator's behalf (e.g. the channel admin page's "link to a vault" flow)
-   * labels itself here (e.g. `"channel"`); a connection built by hand in the
+   * operator's behalf (e.g. the agent module's admin page "link to a vault" flow)
+   * labels itself here (e.g. `"agent"`); a connection built by hand in the
    * hub's own Connections builder is `"custom"`. Lets the operator see which
    * connections a module initiated vs which they wired themselves. Optional for
    * back-compat: records written before R2 read back as `undefined`, which the