@openparachute/hub 0.7.1 → 0.7.2-rc.1

package/src/__tests__/admin-vaults.test.ts

@@ -735,7 +735,7 @@ import { findTokenRowByJti, listActiveRevocations, recordTokenMint } from "../jw
 import { createUser, setUserVaults } from "../users.ts";
 
 const VAULT_ORIGIN = "http://127.0.0.1:19400";
-const CHANNEL_ORIGIN = "http://127.0.0.1:19410";
+const AGENT_ORIGIN = "http://127.0.0.1:19410";
 
 /** Successful no-op runner — records the commands it was asked to run. */
 function stubRun(
@@ -788,7 +788,7 @@ interface DeleteCallOpts {
   connectionsStorePath: string;
   runCommand?: (cmd: readonly string[]) => Promise<RunResult>;
   restartVaultModule?: () => Promise<void>;
-  channelOrigin?: string | null;
+  agentOrigin?: string | null;
   fetchImpl?: typeof fetch;
   resolveVaultOrigin?: (v: string) => string | null;
 }
@@ -810,7 +810,7 @@ async function callDelete(opts: DeleteCallOpts): Promise<Response> {
     issuer: ISSUER,
     manifestPath: opts.manifestPath,
     connectionsStorePath: opts.connectionsStorePath,
-    channelOrigin: opts.channelOrigin ?? null,
+    agentOrigin: opts.agentOrigin ?? null,
     resolveVaultOrigin: opts.resolveVaultOrigin ?? (() => VAULT_ORIGIN),
     runCommand: opts.runCommand ?? stubRun().run,
     ...(opts.restartVaultModule ? { restartVaultModule: opts.restartVaultModule } : {}),
@@ -1002,7 +1002,7 @@ describe("DELETE /vaults/<name> — the identity cascade", () => {
         // 1. Registry rows: two naming "work" (one standalone + the
         //    connection's registered mint below), one naming "default".
         registryRow(db, "jti-work-1", ["vault:work:write"]);
-        registryRow(db, "jti-conn-1", ["channel:send"]); // connection webhook bearer (non-vault scope)
+        registryRow(db, "jti-conn-1", ["agent:send"]); // connection webhook bearer (non-vault scope)
         registryRow(db, "jti-default-1", ["vault:default:read"]);
 
         // 2. Grants: one spanning both vaults (rewrite), one work-only (drop).
@@ -1036,7 +1036,7 @@ describe("DELETE /vaults/<name> — the identity cascade", () => {
         putConnection(store, {
           id: "conn-work",
           source: { module: "vault", vault: "work", event: "note.created" },
-          sink: { module: "channel", action: "message.deliver", params: { channel: "eng" } },
+          sink: { module: "agent", action: "message.deliver", params: { channel: "eng" } },
           provisioned: {
             type: "vault-trigger",
             vault: "work",
@@ -1048,7 +1048,7 @@ describe("DELETE /vaults/<name> — the identity cascade", () => {
         putConnection(store, {
           id: "conn-default",
           source: { module: "vault", vault: "default", event: "note.created" },
-          sink: { module: "channel", action: "message.deliver", params: { channel: "ops" } },
+          sink: { module: "agent", action: "message.deliver", params: { channel: "ops" } },
           provisioned: { type: "vault-trigger", vault: "default", triggerName: "conn_d" },
           createdAt: new Date().toISOString(),
         });
@@ -1078,7 +1078,7 @@ describe("DELETE /vaults/<name> — the identity cascade", () => {
           restartVaultModule: async () => {
             restarted = true;
           },
-          channelOrigin: CHANNEL_ORIGIN,
+          agentOrigin: AGENT_ORIGIN,
           fetchImpl,
           resolveVaultOrigin: (v) => (v === "work" ? VAULT_ORIGIN : null),
         });
@@ -1102,7 +1102,7 @@ describe("DELETE /vaults/<name> — the identity cascade", () => {
         expect(out.name).toBe("work");
 
         // 1. Registry sweep: the work-scoped row revoked; default untouched.
-        //    The connection's webhook-bearer row (channel:send — names no
+        //    The connection's webhook-bearer row (agent:send — names no
         //    vault) is revoked by the CONNECTION teardown, not the sweep.
         expect(out.cascade.tokens_revoked).toBe(1);
         expect(findTokenRowByJti(db, "jti-work-1")?.revokedAt).not.toBeNull();

package/src/__tests__/api-modules-ops.test.ts

@@ -208,13 +208,14 @@ describe("parseModulesPath", () => {
     });
   });
 
-  test("accepts any KNOWN module short — channel install now resolves (was the bug)", () => {
+  test("accepts any KNOWN module short — agent install now resolves (was the bug)", () => {
     // Post-2026-06-09 (modular-UI architecture, P2) the install-path gate is
     // `isKnownModuleShort` (KNOWN_MODULES ∪ FIRST_PARTY_FALLBACKS), NOT the old
-    // CURATED_MODULES whitelist. channel is in FIRST_PARTY_FALLBACKS, so its
-    // install path now resolves — fixing the running-but-uninstallable bug.
-    expect(parseModulesPath("/api/modules/channel/install")).toEqual({
-      short: "channel",
+    // CURATED_MODULES whitelist. agent (renamed from channel 2026-06-17) is in
+    // KNOWN_MODULES, so its install path now resolves — fixing the
+    // running-but-uninstallable bug.
+    expect(parseModulesPath("/api/modules/agent/install")).toEqual({
+      short: "agent",
       rest: "install",
     });
     // Other known modules (runner / surface) resolve too.
@@ -1014,15 +1015,15 @@ describe("POST /api/modules/:short/start", () => {
   });
 
   test("channel#41: start reconciles a drifted services.json port back to canonical (API path)", async () => {
-    // The live signature: channel's row carried 19415 instead of canonical 1941.
-    // The API start path (admin SPA / `parachute start channel`) must apply the
-    // SAME reconcile the boot path does — otherwise an operator-triggered start
-    // re-strands the module on the dead port.
+    // The live signature: the agent (then channel) row carried 19415 instead of
+    // canonical 1941. The API start path (admin SPA / `parachute start agent`)
+    // must apply the SAME reconcile the boot path does — otherwise an
+    // operator-triggered start re-strands the module on the dead port.
     writeManifest(h.manifestPath, [
       {
-        name: "parachute-channel",
+        name: "parachute-agent",
         port: 19415,
-        paths: ["/channel"],
+        paths: ["/agent"],
         health: "/health",
         version: "0.0.0-linked",
       },
@@ -1032,8 +1033,8 @@ describe("POST /api/modules/:short/start", () => {
     const bearer = await mintBearer(h, [API_MODULES_OPS_REQUIRED_SCOPE]);
 
     const res = await handleStart(
-      postReq("/api/modules/channel/start", { authorization: `Bearer ${bearer}` }),
-      "channel",
+      postReq("/api/modules/agent/start", { authorization: `Bearer ${bearer}` }),
+      "agent",
       {
         db: h.db,
         issuer: ISSUER,
@@ -1048,14 +1049,14 @@ describe("POST /api/modules/:short/start", () => {
     // The supervisor child gets PORT=1941 (canonical), not the drifted 19415 —
     // so it binds + the readiness probe checks the right port.
     expect(spawns.length).toBe(1);
-    expect(spawns[0]?.short).toBe("channel");
+    expect(spawns[0]?.short).toBe("agent");
     expect(spawns[0]?.env?.PORT).toBe("1941");
     // services.json row is rewritten to 1941 → the reverse-proxy (which reads
-    // services.json) routes /channel/* to the live port.
+    // services.json) routes /agent/* to the live port.
     const onDisk = JSON.parse(readFileSync(h.manifestPath, "utf8")) as {
       services: { name: string; port: number }[];
     };
-    expect(onDisk.services.find((s) => s.name === "parachute-channel")?.port).toBe(1941);
+    expect(onDisk.services.find((s) => s.name === "parachute-agent")?.port).toBe(1941);
     // The reconcile event logged on the API path too (deps.log wired — #41 review).
     expect(
       logs.some((l) => l.includes("reconciled") && l.includes("19415") && l.includes("1941")),

package/src/__tests__/api-modules.test.ts

@@ -220,7 +220,7 @@ describe("GET /api/modules", () => {
     // by the UNION of the bootstrap registries (KNOWN_MODULES ∪
     // FIRST_PARTY_FALLBACKS), NOT a curated whitelist. Every known module
     // surfaces — core (vault/scribe/surface) in the headline tier, the rest
-    // (channel/runner/notes) as `experimental` — so the channel-not-installed
+    // (agent/runner/notes) as `experimental` — so the agent-not-installed
     // class (running but invisible) can't recur.
     const bearer = await mintBearer(h, [API_MODULES_REQUIRED_SCOPE]);
     const res = await handleApiModules(getReq({ authorization: `Bearer ${bearer}` }), {
@@ -244,11 +244,11 @@ describe("GET /api/modules", () => {
     // The core tier leads, in the recommended install order (vault → scribe),
     // ahead of every experimental module.
     expect(shorts.indexOf("vault")).toBeLessThan(shorts.indexOf("scribe"));
-    expect(shorts.indexOf("scribe")).toBeLessThan(shorts.indexOf("channel"));
+    expect(shorts.indexOf("scribe")).toBeLessThan(shorts.indexOf("agent"));
     expect(shorts.indexOf("scribe")).toBeLessThan(shorts.indexOf("runner"));
     // Every known module is discoverable — vault/scribe/surface (core) +
-    // channel/runner/notes (experimental).
-    for (const s of ["vault", "scribe", "surface", "channel", "runner", "notes"]) {
+    // agent/runner/notes (experimental).
+    for (const s of ["vault", "scribe", "surface", "agent", "runner", "notes"]) {
       expect(shorts).toContain(s);
     }
     // Focus tier resolves from the default map.
@@ -256,7 +256,7 @@ describe("GET /api/modules", () => {
     expect(byShort.get("vault")?.focus).toBe("core");
     expect(byShort.get("scribe")?.focus).toBe("core");
     expect(byShort.get("surface")?.focus).toBe("core");
-    expect(byShort.get("channel")?.focus).toBe("experimental");
+    expect(byShort.get("agent")?.focus).toBe("experimental");
     expect(byShort.get("runner")?.focus).toBe("experimental");
     expect(byShort.get("notes")?.focus).toBe("experimental");
     expect(body.modules.every((m) => m.available)).toBe(true);
@@ -304,24 +304,24 @@ describe("GET /api/modules", () => {
     expect(scribe?.available).toBe(true);
   });
 
-  test("channel (running + self-registered) appears as installed + experimental — regression for the channel-not-installed bug", async () => {
-    // THE bug this PR fixes (2026-06-09 modular-UI architecture, P2): channel
+  test("agent (running + self-registered) appears as installed + experimental — regression for the channel-not-installed bug", async () => {
+    // THE bug this PR fixes (2026-06-09 modular-UI architecture, P2): agent (renamed from channel 2026-06-17)
     // was running, proxied, supervised, and self-registered in services.json
     // yet invisible on the Modules screen — because the old CURATED_MODULES =
     // ["vault","scribe"] whitelist gated discovery. Now discovery is driven by
-    // self-registration ∪ the known registries, so a self-registered channel
+    // self-registration ∪ the known registries, so a self-registered agent
     // row surfaces as installed, in the experimental tier, with its run-state.
     writeManifest(h.manifestPath, [
       {
-        name: "parachute-channel",
+        name: "parachute-agent",
         port: 1941,
-        paths: ["/channel"],
-        health: "/channel/health",
+        paths: ["/agent"],
+        health: "/agent/health",
         version: "0.3.1",
       },
     ]);
     const { supervisor } = makeIdleSupervisor();
-    await supervisor.start({ short: "channel", cmd: ["parachute-channel", "daemon"] });
+    await supervisor.start({ short: "agent", cmd: ["parachute-agent"] });
 
     const bearer = await mintBearer(h, [API_MODULES_REQUIRED_SCOPE]);
     const res = await handleApiModules(getReq({ authorization: `Bearer ${bearer}` }), {
@@ -340,18 +340,17 @@ describe("GET /api/modules", () => {
         supervisor_status: string | null;
       }>;
     };
-    const channel = body.modules.find((m) => m.short === "channel");
-    expect(channel).toBeDefined();
-    expect(channel?.installed).toBe(true);
-    expect(channel?.installed_version).toBe("0.3.1");
-    expect(channel?.focus).toBe("experimental");
-    expect(channel?.supervisor_status).toBe("running");
+    const agent = body.modules.find((m) => m.short === "agent");
+    expect(agent).toBeDefined();
+    expect(agent?.installed).toBe(true);
+    expect(agent?.installed_version).toBe("0.3.1");
+    expect(agent?.focus).toBe("experimental");
+    expect(agent?.supervisor_status).toBe("running");
   });
 
   test("every self-registered + known module appears in `modules` — no running-but-invisible class", async () => {
     // The two-registry-disagreement (services.json says installed, the curated
-    // whitelist says invisible) is gone: a self-registered surface row + a
-    // supervised channel both surface in `modules` (2026-06-09 modular-UI
+    // whitelist says invisible) is gone: a self-registered surface row + a    // supervised agent both surface in `modules` (2026-06-09 modular-UI
     // architecture). `supervised` still mirrors the run-state for every
     // tracked module (hub#539) — consumers dedupe by short.
     writeManifest(h.manifestPath, [
@@ -630,19 +629,19 @@ describe("GET /api/modules", () => {
   });
 
   test("populates config_ui_url from a module's configUiUrl (2026-06-09 modular-UI P3)", async () => {
-    // Channel declares `configUiUrl: "/channel/admin"` (a single-instance,
-    // origin-absolute path) + `uiUrl: "/channel/ui"`. The hub surfaces
+    // Agent declares `configUiUrl: "/agent/admin"` (a single-instance,
+    // origin-absolute path) + `uiUrl: "/agent/ui"`. The hub surfaces
     // both: `config_ui_url` drives the Modules page Configure action,
     // `management_url` drives Open. configUiUrl resolves identically to
     // managementUrl (same B4 unified semantics).
     writeManifest(h.manifestPath, [
       {
-        name: "channel",
+        name: "agent",
         port: 1941,
-        paths: ["/channel"],
+        paths: ["/agent"],
         health: "/health",
         version: "0.1.0",
-        installDir: "/install/dir/channel",
+        installDir: "/install/dir/agent",
       },
     ]);
     const bearer = await mintBearer(h, [API_MODULES_REQUIRED_SCOPE]);
@@ -652,17 +651,17 @@ describe("GET /api/modules", () => {
       manifestPath: h.manifestPath,
       fetchLatestVersion: async () => null,
       readModuleManifest: async (installDir) => {
-        if (installDir === "/install/dir/channel") {
+        if (installDir === "/install/dir/agent") {
           return {
-            name: "channel",
-            manifestName: "parachute-channel",
-            displayName: "Channel",
+            name: "agent",
+            manifestName: "parachute-agent",
+            displayName: "Agent",
             tagline: "",
             port: 1941,
-            paths: ["/channel"],
+            paths: ["/agent"],
             health: "/health",
-            uiUrl: "/channel/ui",
-            configUiUrl: "/channel/admin",
+            uiUrl: "/agent/ui",
+            configUiUrl: "/agent/admin",
           } as unknown as Awaited<
             ReturnType<typeof import("../module-manifest.ts").readModuleManifest>
           >;
@@ -678,11 +677,11 @@ describe("GET /api/modules", () => {
         management_url: string | null;
       }>;
     };
-    const channel = body.modules.find((m) => m.short === "channel");
-    // Origin-absolute — verbatim, never double-prepends `/channel`.
-    expect(channel?.config_ui_url).toBe("/channel/admin");
+    const agent = body.modules.find((m) => m.short === "agent");
+    // Origin-absolute — verbatim, never double-prepends `/agent`.
+    expect(agent?.config_ui_url).toBe("/agent/admin");
     // uiUrl (no managementUrl) drives the Open action's management_url.
-    expect(channel?.management_url).toBe("/channel/ui");
+    expect(agent?.management_url).toBe("/agent/ui");
   });
 
   test("config_ui_url is null when the module declares no configUiUrl", async () => {

package/src/__tests__/api-ready.test.ts

@@ -92,7 +92,7 @@ describe("handleApiReady — supervisor mode", () => {
       moduleState({ short: "vault", status: "starting" }),
       moduleState({ short: "scribe", status: "restarting" }),
       moduleState({ short: "notes", status: "crashed" }),
-      moduleState({ short: "channel", status: "stopped" }),
+      moduleState({ short: "agent", status: "stopped" }),
       moduleState({
         short: "runner",
         status: "running",
@@ -109,7 +109,7 @@ describe("handleApiReady — supervisor mode", () => {
     expect(body.ready).toBe(false);
     expect(body.ready_modules).toEqual(["runner"]);
     expect(body.transient_modules.sort()).toEqual(["scribe", "vault"]);
-    expect(body.persistent_modules.sort()).toEqual(["channel", "notes"]);
+    expect(body.persistent_modules.sort()).toEqual(["agent", "notes"]);
   });
 
   test("only crashed/stopped + nothing transient → ready=false (still failing)", async () => {

package/src/__tests__/clients.test.ts

@@ -5,6 +5,7 @@ import { join } from "node:path";
 import {
   InvalidRedirectUriError,
   approveClient,
+  expandRedirectUrisForHubOrigins,
   getClient,
   isValidRedirectUri,
   listClientsByStatus,
@@ -144,6 +145,96 @@ describe("requireRegisteredRedirectUri", () => {
   });
 });
 
+describe("expandRedirectUrisForHubOrigins (surface#118 cross-hub-origin DCR expansion)", () => {
+  const LOOPBACK = "http://127.0.0.1:1939";
+  const PUBLIC = "https://box.taildf9ce2.ts.net";
+  const hubOrigins = [LOOPBACK, "http://localhost:1939", PUBLIC];
+
+  test("expands a loopback-rooted URI onto every other hub origin", () => {
+    const out = expandRedirectUrisForHubOrigins([`${LOOPBACK}/surface/notes/oauth/callback`], hubOrigins);
+    // Original is preserved + the public + localhost variants are added.
+    expect(out).toContain(`${LOOPBACK}/surface/notes/oauth/callback`);
+    expect(out).toContain(`${PUBLIC}/surface/notes/oauth/callback`);
+    expect(out).toContain("http://localhost:1939/surface/notes/oauth/callback");
+    // The submitted URI comes first (order-preserving).
+    expect(out[0]).toBe(`${LOOPBACK}/surface/notes/oauth/callback`);
+  });
+
+  test("INVARIANT: a foreign-origin URI is stored verbatim — not expanded, not dropped", () => {
+    const foreign = "https://my-vault-ui.example/oauth/callback";
+    const out = expandRedirectUrisForHubOrigins([foreign], hubOrigins);
+    // Stored exactly as submitted...
+    expect(out).toContain(foreign);
+    // ...and NOTHING was minted on any hub origin from it (no open redirect).
+    expect(out).toEqual([foreign]);
+    for (const o of hubOrigins) {
+      expect(out).not.toContain(`${o}/oauth/callback`);
+    }
+  });
+
+  test("mixed submit: hub-origin URI expands, foreign URI rides verbatim alongside", () => {
+    const foreign = "https://evil.example/cb";
+    const out = expandRedirectUrisForHubOrigins(
+      [`${LOOPBACK}/surface/notes/`, foreign],
+      hubOrigins,
+    );
+    // Hub-origin URI fanned out to the public origin.
+    expect(out).toContain(`${PUBLIC}/surface/notes/`);
+    // Foreign URI present, but no hub-origin variant of it exists.
+    expect(out).toContain(foreign);
+    for (const o of hubOrigins) {
+      expect(out).not.toContain(`${o}/cb`);
+    }
+  });
+
+  test("single known hub origin → no expansion (submitted set returned as-is)", () => {
+    const out = expandRedirectUrisForHubOrigins(
+      [`${LOOPBACK}/surface/notes/`],
+      [LOOPBACK],
+    );
+    expect(out).toEqual([`${LOOPBACK}/surface/notes/`]);
+  });
+
+  test("dedupes — already-public + loopback submit doesn't double-register", () => {
+    const out = expandRedirectUrisForHubOrigins(
+      [`${LOOPBACK}/surface/notes/`, `${PUBLIC}/surface/notes/`],
+      hubOrigins,
+    );
+    const publicCount = out.filter((u) => u === `${PUBLIC}/surface/notes/`).length;
+    expect(publicCount).toBe(1);
+  });
+
+  test("path + query + hash are preserved across origins", () => {
+    const out = expandRedirectUrisForHubOrigins(
+      [`${LOOPBACK}/surface/notes/oauth-callback?foo=bar`],
+      hubOrigins,
+    );
+    expect(out).toContain(`${PUBLIC}/surface/notes/oauth-callback?foo=bar`);
+  });
+
+  test("expanded URIs survive registerClient → requireRegisteredRedirectUri strict match", () => {
+    const { db, cleanup } = makeDb();
+    try {
+      const expanded = expandRedirectUrisForHubOrigins(
+        [`${LOOPBACK}/surface/notes/oauth/callback`],
+        hubOrigins,
+      );
+      const r = registerClient(db, { redirectUris: expanded });
+      // The public-origin variant now matches exactly at authorize time — the
+      // off-localhost sign-in that surface#118 broke.
+      expect(
+        requireRegisteredRedirectUri(r.client, `${PUBLIC}/surface/notes/oauth/callback`),
+      ).toBe(`${PUBLIC}/surface/notes/oauth/callback`);
+      // A truly-unregistered URI is still rejected — strict match unchanged.
+      expect(() =>
+        requireRegisteredRedirectUri(r.client, "https://evil.example/surface/notes/oauth/callback"),
+      ).toThrow(InvalidRedirectUriError);
+    } finally {
+      cleanup();
+    }
+  });
+});
+
 describe("verifyClientSecret", () => {
   test("matches the issued secret, rejects others", () => {
     const { db, cleanup } = makeDb();

package/src/__tests__/grants-store.test.ts

@@ -0,0 +1,219 @@
+/**
+ * Tests for the agent-connector grant store (`grants-store.ts`, 4b-1).
+ *
+ * Distinct from `grants.test.ts` (the OAuth consent skip-list in SQLite). This
+ * is the on-disk JSON store for approval-gated agent grants: round-trip, 0600
+ * perms (the file holds the granted secrets), idempotency-key derivation, and
+ * the lenient-read posture.
+ */
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  type ConnectionSpec,
+  type GrantRecord,
+  connectionKey,
+  getGrant,
+  grantId,
+  listGrantsForAgent,
+  putGrant,
+  readGrants,
+  removeGrant,
+} from "../grants-store.ts";
+
+let dir: string;
+let storePath: string;
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "phub-grants-store-"));
+  storePath = join(dir, "agent-grants.json");
+});
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+function vaultSpec(over: Partial<ConnectionSpec> = {}): ConnectionSpec {
+  return { kind: "vault", target: "research", access: "read", ...over };
+}
+
+function rec(over: Partial<GrantRecord> = {}): GrantRecord {
+  const connection = over.connection ?? vaultSpec();
+  return {
+    id: over.id ?? grantId("agent1", connection),
+    agent: over.agent ?? "agent1",
+    connection,
+    status: over.status ?? "pending",
+    createdAt: over.createdAt ?? "2026-06-17T00:00:00.000Z",
+    ...(over.reason ? { reason: over.reason } : {}),
+    ...(over.material ? { material: over.material } : {}),
+    ...(over.approvedAt ? { approvedAt: over.approvedAt } : {}),
+  };
+}
+
+describe("round-trip", () => {
+  test("a missing file reads as empty", () => {
+    expect(readGrants(storePath)).toEqual([]);
+  });
+
+  test("put → read returns the record", () => {
+    const r = rec();
+    putGrant(storePath, r);
+    const back = readGrants(storePath);
+    expect(back).toHaveLength(1);
+    expect(back[0]).toEqual(r);
+  });
+
+  test("put upserts by id (no duplicate row)", () => {
+    const r = rec();
+    putGrant(storePath, r);
+    putGrant(storePath, { ...r, status: "approved", approvedAt: "2026-06-18T00:00:00.000Z" });
+    const back = readGrants(storePath);
+    expect(back).toHaveLength(1);
+    expect(back[0]?.status).toBe("approved");
+  });
+
+  test("getGrant + removeGrant", () => {
+    const r = rec();
+    putGrant(storePath, r);
+    expect(getGrant(storePath, r.id)?.id).toBe(r.id);
+    const removed = removeGrant(storePath, r.id);
+    expect(removed?.id).toBe(r.id);
+    expect(getGrant(storePath, r.id)).toBeNull();
+  });
+
+  test("listGrantsForAgent filters by agent (case-insensitive)", () => {
+    putGrant(storePath, rec({ id: "a", agent: "AgentOne" }));
+    putGrant(
+      storePath,
+      rec({ id: "b", agent: "agenttwo", connection: vaultSpec({ target: "x" }) }),
+    );
+    expect(listGrantsForAgent(storePath, "agentone")).toHaveLength(1);
+    expect(listGrantsForAgent(storePath, "AGENTTWO")).toHaveLength(1);
+    expect(listGrantsForAgent(storePath, "nope")).toHaveLength(0);
+  });
+});
+
+describe("0600 perms (the file holds secrets)", () => {
+  test("the store file is created mode 0600", () => {
+    putGrant(
+      storePath,
+      rec({
+        status: "approved",
+        material: { kind: "service", token: "ghp_secret" },
+        connection: { kind: "service", target: "github" },
+      }),
+    );
+    const mode = statSync(storePath).mode & 0o777;
+    expect(mode).toBe(0o600);
+  });
+});
+
+describe("lenient read", () => {
+  test("garbage JSON reads as empty", () => {
+    writeFileSync(storePath, "not json {{{");
+    expect(readGrants(storePath)).toEqual([]);
+  });
+
+  test("a top-level array (wrong shape) reads as empty", () => {
+    writeFileSync(storePath, JSON.stringify([{ id: "x" }]));
+    expect(readGrants(storePath)).toEqual([]);
+  });
+
+  test("a malformed row is dropped, valid rows survive", () => {
+    const valid = rec();
+    writeFileSync(
+      storePath,
+      JSON.stringify({
+        grants: [
+          valid,
+          { id: "missing-agent" }, // no agent/connection/status → dropped
+          { id: "bad-status", agent: "a", connection: vaultSpec(), status: "weird" }, // bad status → dropped
+        ],
+      }),
+    );
+    const back = readGrants(storePath);
+    expect(back).toHaveLength(1);
+    expect(back[0]?.id).toBe(valid.id);
+  });
+});
+
+describe("4b-2 mcp material + needs_consent (regression)", () => {
+  test("mcp material round-trips (OAuth shape)", () => {
+    const r = rec({
+      status: "approved",
+      connection: { kind: "mcp", target: "https://remote.test/mcp" },
+      material: {
+        kind: "mcp",
+        access_token: "at-1",
+        refresh_token: "rt-1",
+        expiresAt: "2026-06-18T13:00:00.000Z",
+        issuer: "https://issuer.test",
+        clientId: "cid-1",
+        tokenEndpoint: "https://issuer.test/oauth/token",
+        revocationEndpoint: "https://issuer.test/oauth/revoke",
+        mcpUrl: "https://remote.test/mcp",
+      },
+    });
+    putGrant(storePath, r);
+    const back = readGrants(storePath);
+    expect(back).toHaveLength(1);
+    expect(back[0]).toEqual(r);
+  });
+
+  test("mcp static-bearer material round-trips (no refresh)", () => {
+    const r = rec({
+      status: "approved",
+      connection: { kind: "mcp", target: "https://remote.test/mcp" },
+      material: { kind: "mcp", access_token: "static-paste", mcpUrl: "https://remote.test/mcp" },
+    });
+    putGrant(storePath, r);
+    expect(readGrants(storePath)[0]).toEqual(r);
+  });
+
+  test("a needs_consent row SURVIVES readGrants (the 4b-2 blocker regression)", () => {
+    const r = rec({
+      status: "needs_consent",
+      reason: "refresh failed: invalid_grant",
+      connection: { kind: "mcp", target: "https://remote.test/mcp" },
+    });
+    putGrant(storePath, r);
+    const back = readGrants(storePath);
+    expect(back).toHaveLength(1);
+    expect(back[0]?.status).toBe("needs_consent");
+    expect(getGrant(storePath, r.id)?.status).toBe("needs_consent");
+  });
+});
+
+describe("connectionKey / grantId derivation (idempotency)", () => {
+  test("vault key includes access + sorted tags", () => {
+    expect(connectionKey(vaultSpec())).toBe("vault:research:read");
+    expect(connectionKey(vaultSpec({ access: "write" }))).toBe("vault:research:write");
+    // tag order doesn't change the key
+    const a = connectionKey(vaultSpec({ tags: ["#b", "#a"] }));
+    const b = connectionKey(vaultSpec({ tags: ["#a", "#b"] }));
+    expect(a).toBe(b);
+    expect(a).toBe("vault:research:read##a,#b");
+  });
+
+  test("service key ignores inject (re-declare with new inject → same key)", () => {
+    const k1 = connectionKey({ kind: "service", target: "github", inject: ["env"] });
+    const k2 = connectionKey({ kind: "service", target: "github", inject: ["env", "mcp"] });
+    expect(k1).toBe(k2);
+    expect(k1).toBe("service:github");
+  });
+
+  test("mcp key is the url target", () => {
+    expect(connectionKey({ kind: "mcp", target: "https://x.test/mcp" })).toBe(
+      "mcp:https://x.test/mcp",
+    );
+  });
+
+  test("grantId is a stable URL-safe slug from agent + key", () => {
+    const id = grantId("agent1", vaultSpec());
+    expect(id).toMatch(/^[a-z0-9][a-z0-9-]*$/);
+    // deterministic
+    expect(grantId("agent1", vaultSpec())).toBe(id);
+    // different connection → different id
+    expect(grantId("agent1", vaultSpec({ access: "write" }))).not.toBe(id);
+  });
+});