@openparachute/agent 0.1.2 → 0.2.0

package/src/hub-jwt.test.ts

@@ -0,0 +1,161 @@
+/**
+ * Tests for the agent-side hub-JWT adapter. These exercise the parts that
+ * DON'T need a live hub / JWKS endpoint: hub-origin resolution (env precedence →
+ * expose-state self-heal → loopback fallback), the audience constants, and the
+ * re-exported pure helpers (`looksLikeJwt`). Real signature/issuer/audience
+ * validation is scope-guard's own tested surface — we don't re-test it here and
+ * we never need a real JWKS.
+ *
+ * Audience constants (channel→agent rename, rule 1): the daemon now mints/
+ * validates `aud: "agent"` (`AGENT_AUDIENCE`); the pre-rename `aud: "channel"`
+ * (`CHANNEL_AUDIENCE`, deprecated) still validates during the dual-accept window
+ * via `ACCEPTED_AUDIENCES`. We assert both constants here. The dual-ACCEPT itself
+ * (a `channel`-aud token still validating) lives in `validateHubJwt`, which needs
+ * a live JWKS to exercise — that's scope-guard's tested surface, not re-tested here.
+ *
+ * The self-heal reads `<PARACHUTE_HOME>/expose-state.json`. Every case here
+ * points `PARACHUTE_HOME` at a fresh temp dir so the operator's real
+ * `~/.parachute/expose-state.json` can't leak into the loopback assertions.
+ */
+import { describe, test, expect, afterEach, beforeEach } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  getHubOrigin,
+  AGENT_AUDIENCE,
+  CHANNEL_AUDIENCE,
+  ACCEPTED_AUDIENCES,
+  looksLikeJwt,
+  HubJwtError,
+} from "./hub-jwt.ts";
+
+const savedOrigin = process.env.PARACHUTE_HUB_ORIGIN;
+const savedHome = process.env.PARACHUTE_HOME;
+
+let home: string;
+
+beforeEach(() => {
+  // Isolated, empty ecosystem root — no expose-state.json unless a case writes one.
+  home = mkdtempSync(join(tmpdir(), "agent-hubjwt-"));
+  process.env.PARACHUTE_HOME = home;
+});
+
+afterEach(() => {
+  if (savedOrigin === undefined) delete process.env.PARACHUTE_HUB_ORIGIN;
+  else process.env.PARACHUTE_HUB_ORIGIN = savedOrigin;
+  if (savedHome === undefined) delete process.env.PARACHUTE_HOME;
+  else process.env.PARACHUTE_HOME = savedHome;
+  try {
+    rmSync(home, { recursive: true, force: true });
+  } catch {}
+});
+
+function writeExposeState(obj: Record<string, unknown>): void {
+  writeFileSync(join(home, "expose-state.json"), JSON.stringify(obj));
+}
+
+describe("getHubOrigin — env precedence", () => {
+  test("uses the env value when set", () => {
+    process.env.PARACHUTE_HUB_ORIGIN = "https://hub.example.com";
+    expect(getHubOrigin()).toBe("https://hub.example.com");
+  });
+
+  test("strips a single trailing slash for a canonical form", () => {
+    process.env.PARACHUTE_HUB_ORIGIN = "https://hub.example.com/";
+    expect(getHubOrigin()).toBe("https://hub.example.com");
+  });
+
+  test("env wins over expose-state (highest precedence)", () => {
+    process.env.PARACHUTE_HUB_ORIGIN = "https://env.example.com";
+    writeExposeState({ hubOrigin: "https://exposed.example.com" });
+    expect(getHubOrigin()).toBe("https://env.example.com");
+  });
+});
+
+describe("getHubOrigin — expose-state self-heal (agent#34)", () => {
+  test("reads expose-state.hubOrigin when env is unset", () => {
+    delete process.env.PARACHUTE_HUB_ORIGIN;
+    writeExposeState({ hubOrigin: "https://exposed.example.com" });
+    expect(getHubOrigin()).toBe("https://exposed.example.com");
+  });
+
+  test("reads expose-state.hubOrigin when env is empty", () => {
+    process.env.PARACHUTE_HUB_ORIGIN = "";
+    writeExposeState({ hubOrigin: "https://exposed.example.com" });
+    expect(getHubOrigin()).toBe("https://exposed.example.com");
+  });
+
+  test("synthesizes https://<canonicalFqdn> for older state files lacking hubOrigin", () => {
+    delete process.env.PARACHUTE_HUB_ORIGIN;
+    writeExposeState({ canonicalFqdn: "box.taildf9ce2.ts.net" });
+    expect(getHubOrigin()).toBe("https://box.taildf9ce2.ts.net");
+  });
+
+  test("strips a trailing slash off the expose-state origin", () => {
+    delete process.env.PARACHUTE_HUB_ORIGIN;
+    writeExposeState({ hubOrigin: "https://exposed.example.com/" });
+    expect(getHubOrigin()).toBe("https://exposed.example.com");
+  });
+
+  test("never self-heals to a loopback expose-state origin", () => {
+    delete process.env.PARACHUTE_HUB_ORIGIN;
+    writeExposeState({ hubOrigin: "http://127.0.0.1:1939" });
+    expect(getHubOrigin()).toBe("http://127.0.0.1:1939"); // loopback default, not a self-heal
+  });
+});
+
+describe("getHubOrigin — loopback fallback", () => {
+  test("falls back to loopback when env unset AND no expose-state file", () => {
+    delete process.env.PARACHUTE_HUB_ORIGIN;
+    expect(getHubOrigin()).toBe("http://127.0.0.1:1939");
+  });
+
+  test("falls back to loopback when env empty AND no expose-state file", () => {
+    process.env.PARACHUTE_HUB_ORIGIN = "";
+    expect(getHubOrigin()).toBe("http://127.0.0.1:1939");
+  });
+
+  test("falls back to loopback when expose-state has no usable origin", () => {
+    delete process.env.PARACHUTE_HUB_ORIGIN;
+    writeExposeState({ layer: "tailnet" }); // neither hubOrigin nor canonicalFqdn
+    expect(getHubOrigin()).toBe("http://127.0.0.1:1939");
+  });
+
+  test("falls back to loopback when expose-state is malformed JSON", () => {
+    delete process.env.PARACHUTE_HUB_ORIGIN;
+    writeFileSync(join(home, "expose-state.json"), "{ not json");
+    expect(getHubOrigin()).toBe("http://127.0.0.1:1939");
+  });
+});
+
+describe("audience constants (channel→agent dual-accept, rule 1)", () => {
+  test("AGENT_AUDIENCE is the literal 'agent' (what the hub mints aud as now)", () => {
+    expect(AGENT_AUDIENCE).toBe("agent");
+  });
+
+  test("CHANNEL_AUDIENCE is the deprecated legacy literal 'channel' (pre-rename tokens)", () => {
+    expect(CHANNEL_AUDIENCE).toBe("channel");
+  });
+
+  test("ACCEPTED_AUDIENCES carries BOTH — new 'agent' + legacy 'channel' (the dual-accept set)", () => {
+    // The resource-server backstop: a token whose aud is neither (e.g. minted for
+    // a vault) is rejected; both transitional forms validate until live re-mint.
+    expect([...ACCEPTED_AUDIENCES]).toEqual(["agent", "channel"]);
+    expect(ACCEPTED_AUDIENCES).toContain(AGENT_AUDIENCE);
+    expect(ACCEPTED_AUDIENCES).toContain(CHANNEL_AUDIENCE);
+  });
+});
+
+describe("re-exported helpers", () => {
+  test("looksLikeJwt recognizes the eyJ prefix", () => {
+    expect(looksLikeJwt("eyJhbGciOiJSUzI1NiJ9.payload.sig")).toBe(true);
+    expect(looksLikeJwt("opaque-shared-secret")).toBe(false);
+  });
+
+  test("HubJwtError is the scope-guard error class", () => {
+    const err = new HubJwtError("issuer", "bad iss");
+    expect(err).toBeInstanceOf(Error);
+    expect(err.code).toBe("issuer");
+  });
+});

package/src/hub-jwt.ts

@@ -0,0 +1,182 @@
+/**
+ * Hub-issued JWT validation. parachute-agent as a resource server: it trusts
+ * tokens the hub signs against keys fetched from the hub's
+ * `/.well-known/jwks.json`.
+ *
+ * The trust kernel — JWKS fetch + verify, issuer pin, RFC 7519 string-or-array
+ * `aud` handling, revocation — lives in the shared `@openparachute/scope-guard`
+ * library so vault, scribe, and agent can't silently drift on the worst place
+ * to drift. This file is the agent-side adapter: hub-origin resolution
+ * (env-var precedence → expose-state self-heal → loopback fallback), a
+ * process-wide guard instance, and re-exports preserving the surface the daemon
+ * imports.
+ *
+ * Audience pin + DUAL-ACCEPT (channel→agent rename,
+ * `parachute-patterns/migrations/2026-06-17-channel-to-agent.md` rule 1). New
+ * tokens carry `aud: "agent"`; tokens minted before the rename carry
+ * `aud: "channel"`. We must keep both valid until live tokens are re-minted, so
+ * instead of pinning a single `expectedAudience` we validate WITHOUT the
+ * library's strict-audience check and then assert the surfaced `aud` is in the
+ * accepted set {@link ACCEPTED_AUDIENCES}. This preserves the resource-server
+ * audience backstop (a token minted for some OTHER resource — e.g. a vault — is
+ * still rejected because its `aud` is neither `agent` nor `channel`) while
+ * accepting both transitional forms. A later contract cycle drops `channel`.
+ * The hub mints `iss: <hub public origin>`, so the resolved hub origin MUST be
+ * that public origin for `iss` validation to succeed on an exposed deployment.
+ * `PARACHUTE_HUB_ORIGIN` is the explicit contract; when it's unset,
+ * `getHubOrigin` self-heals from the hub's persisted `expose-state.json`
+ * `hubOrigin` so a manually-relaunched daemon on an exposed box doesn't 401
+ * every token — the loopback fallback is for a co-located, never-exposed dev
+ * daemon only.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import {
+  createScopeGuard,
+  HubJwtError,
+  type HubJwtClaims,
+  looksLikeJwt,
+} from "@openparachute/scope-guard";
+
+/**
+ * The audiences this resource server accepts (channel→agent dual-accept). The
+ * NEW `agent` form plus the legacy `channel` form. A token whose `aud` is neither
+ * — e.g. minted for a vault — is rejected, preserving the per-resource backstop.
+ */
+export const ACCEPTED_AUDIENCES = ["agent", "channel"] as const;
+
+const DEFAULT_HUB_LOOPBACK = "http://127.0.0.1:1939";
+
+/**
+ * Best-effort read of the hub's persisted public origin from
+ * `<root>/expose-state.json` (hub-owned; written by the Tailscale + Cloudflare
+ * expose paths). Returns the canonical public origin — preferring the explicit
+ * `hubOrigin` field (the URL the hub stamps into token `iss` claims), falling
+ * back to synthesizing `https://<canonicalFqdn>` for older state files that
+ * predate `hubOrigin`. Returns undefined on any error, when absent, or when the
+ * only origin available is loopback (there's nothing to self-heal *to*).
+ *
+ * `root` is `$PARACHUTE_HOME` if set, otherwise `~/.parachute` — re-derived
+ * per-call so tests that flip `PARACHUTE_HOME` (and sandboxed/e2e daemons) see
+ * the override rather than a value frozen at import. Mirrors hub's own
+ * `publicOriginFromExposeState` (parachute-hub/src/vault-hub-origin-env.ts) and
+ * vault's `readExposedFqdn` (parachute-vault/src/mcp-install.ts).
+ */
+function readExposeStateHubOrigin(): string | undefined {
+  try {
+    const root = process.env.PARACHUTE_HOME ?? resolve(homedir(), ".parachute");
+    const p = resolve(root, "expose-state.json");
+    if (!existsSync(p)) return undefined;
+    const raw = JSON.parse(readFileSync(p, "utf-8")) as {
+      hubOrigin?: string;
+      canonicalFqdn?: string;
+    };
+    const origin =
+      raw.hubOrigin ?? (raw.canonicalFqdn ? `https://${raw.canonicalFqdn}` : "");
+    const trimmed = origin.replace(/\/$/, "");
+    if (!trimmed) return undefined;
+    // Never self-heal to a loopback origin — that's the last-resort default, not
+    // a public issuer, and persisting it would defeat the env→loopback contract.
+    if (/^https?:\/\/(127\.0\.0\.1|localhost|\[::1\])(:|\/|$)/i.test(trimmed)) {
+      return undefined;
+    }
+    return trimmed;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The canonical audience new agent tokens are minted with. Kept as a named
+ * constant for readers + tests; the actual accept-check uses the dual-accept set
+ * {@link ACCEPTED_AUDIENCES} so pre-rename `channel` tokens also validate.
+ */
+export const AGENT_AUDIENCE = "agent" as const;
+
+/**
+ * @deprecated Legacy alias for the pre-rename audience. Retained so existing
+ * callers/tests keep compiling; new code reads {@link AGENT_AUDIENCE} or checks
+ * {@link ACCEPTED_AUDIENCES}. Both `agent` and `channel` validate during the
+ * dual-accept window.
+ */
+export const CHANNEL_AUDIENCE = "channel" as const;
+
+/**
+ * Resolve the hub origin used to fetch JWKS and validate `iss`. Strips a
+ * trailing slash so we get a single canonical form.
+ *
+ * Order: `PARACHUTE_HUB_ORIGIN` env → `expose-state.json` `hubOrigin`
+ * (self-heal) → loopback fallback. The env var stays highest precedence (the
+ * explicit operator/supervisor contract). The expose-state read is the
+ * self-heal: on an exposed deployment the hub mints `iss: <public origin>` and
+ * persists that origin to `<root>/expose-state.json`, so an agent daemon
+ * started WITHOUT the env (e.g. a manual relaunch) still recovers the hub's
+ * real public issuer and validates JWTs — instead of falling straight to
+ * loopback and 401'ing EVERY token with `unexpected "iss" claim value`. This
+ * mirrors what vault (`chooseHubOrigin`, parachute-vault/src/mcp-install.ts) and
+ * hub (`publicOriginFromExposeState`) already do; we used to deliberately skip
+ * expose-state, and that's exactly the gap this closes (agent#34). Loopback is
+ * the last resort for a co-located, never-exposed dev daemon; we never persist
+ * or self-heal *to* loopback. We still don't read `services.json` — the hub is
+ * the dispatcher, not a registered service there.
+ */
+export function getHubOrigin(): string {
+  const env = process.env.PARACHUTE_HUB_ORIGIN?.replace(/\/$/, "");
+  if (env && env.length > 0) return env;
+  const exposed = readExposeStateHubOrigin();
+  if (exposed) return exposed;
+  return DEFAULT_HUB_LOOPBACK;
+}
+
+// Process-wide guard. The resolver form lets tests flip `PARACHUTE_HUB_ORIGIN`
+// between cases — the lib re-resolves on every `validateHubJwt` and
+// `resetJwksCache` call so the env-var change picks up without a restart. The
+// JWKS cache (5min/30s defaults) lives inside the guard, shared across requests.
+const guard = createScopeGuard({ hubOrigin: () => getHubOrigin() });
+
+/**
+ * Verify a presented JWT against the hub's JWKS, accepting `aud: "agent"` OR the
+ * legacy `aud: "channel"` (dual-accept transition). Throws `HubJwtError` on any
+ * failure (bad signature, wrong issuer, wrong/unaccepted audience, expired,
+ * missing kid, JWKS unreachable, revoked). On success returns the surfaced
+ * claims plus the parsed scope list.
+ *
+ * Trust pins: `iss` MUST equal the configured hub origin AND `aud` MUST be in
+ * {@link ACCEPTED_AUDIENCES}. Without those, a token signed by any RSA key — or
+ * one minted for another resource — would pass verification. We do NOT pass the
+ * library's single-value `expectedAudience` (it can't express two accepted
+ * values); instead we validate the signature/issuer/revocation with the library,
+ * then assert the surfaced `aud` membership here — a `"shape"`-class reject that
+ * matches what a strict-audience mismatch would have produced.
+ */
+export async function validateHubJwt(token: string): Promise<HubJwtClaims> {
+  const claims = await guard.validateHubJwt(token);
+  if (!claims.aud || !ACCEPTED_AUDIENCES.includes(claims.aud as (typeof ACCEPTED_AUDIENCES)[number])) {
+    throw new HubJwtError(
+      "audience",
+      `unexpected "aud" claim value; this resource accepts ${ACCEPTED_AUDIENCES.map((a) => `"${a}"`).join(" or ")}`,
+    );
+  }
+  return claims;
+}
+
+/**
+ * Reset the cached JWKS getter. Tests use this to switch origins between cases;
+ * production callers shouldn't need it (origin is process-stable).
+ */
+export function resetJwksCache(): void {
+  guard.resetJwksCache();
+}
+
+/**
+ * Reset the cached revocation list. Tests use this to start from a clean
+ * fail-closed state between cases; production callers shouldn't need it (the
+ * cache refreshes itself on TTL expiry).
+ */
+export function resetRevocationCache(): void {
+  guard.resetRevocationCache();
+}
+
+export { HubJwtError, looksLikeJwt };
+export type { HubJwtClaims };

package/src/jobs.test.ts

@@ -0,0 +1,245 @@
+import { describe, test, expect, afterEach } from "bun:test";
+import { validateJob, VaultJobStore, vaultTransportFor, type Job } from "./jobs.ts";
+import { VaultTransport } from "./transports/vault.ts";
+import type { Channel } from "./registry.ts";
+import { TelegramTransport } from "./transports/telegram.ts";
+
+const realFetch = globalThis.fetch;
+afterEach(() => {
+  globalThis.fetch = realFetch;
+});
+
+function makeJob(over: Partial<Job> = {}): Job {
+  return {
+    id: "morning",
+    channel: "uni-dev",
+    message: "Run the morning weave",
+    schedule: { cron: "53 7 * * *", tz: "America/Los_Angeles" },
+    enabled: true,
+    createdAt: "2026-06-17T00:00:00.000Z",
+    ...over,
+  };
+}
+
+describe("validateJob (pure)", () => {
+  const isVault = (name: string): boolean | null => {
+    if (name === "uni-dev") return true;
+    if (name === "tele") return false;
+    return null;
+  };
+
+  test("a well-formed vault job validates", () => {
+    expect(validateJob(makeJob(), isVault)).toEqual({ ok: true });
+  });
+  test("bad id (not a slug) rejected", () => {
+    const r = validateJob(makeJob({ id: "has spaces" }), isVault);
+    expect(r).toMatchObject({ ok: false });
+    expect((r as { error: string }).error).toMatch(/slug/);
+  });
+  test("empty message rejected", () => {
+    const r = validateJob(makeJob({ message: "   " }), isVault);
+    expect((r as { error: string }).error).toMatch(/message/);
+  });
+  test("bad cron rejected with a field-naming message", () => {
+    const r = validateJob(makeJob({ schedule: { cron: "99 7 * * *" } }), isVault);
+    expect((r as { error: string }).error).toMatch(/invalid schedule.cron/);
+  });
+  test("missing schedule.cron rejected", () => {
+    const r = validateJob({ id: "x", channel: "uni-dev", message: "m" }, isVault);
+    expect((r as { error: string }).error).toMatch(/schedule.cron/);
+  });
+  test("bad tz rejected", () => {
+    const r = validateJob(makeJob({ schedule: { cron: "0 0 * * *", tz: "Mars/Olympus" } }), isVault);
+    expect((r as { error: string }).error).toMatch(/timezone/);
+  });
+  test("unknown channel rejected", () => {
+    const r = validateJob(makeJob({ channel: "ghost" }), isVault);
+    expect((r as { error: string }).error).toMatch(/unknown channel/);
+  });
+  test("non-vault channel rejected (the inject path needs a vault transport)", () => {
+    const r = validateJob(makeJob({ channel: "tele" }), isVault);
+    expect((r as { error: string }).error).toMatch(/not a vault channel/);
+  });
+});
+
+/** Build a live channels map with one vault channel + (optionally) a telegram one. */
+function channelsWithVault(): { channels: Map<string, Channel>; vault: VaultTransport } {
+  const vault = new VaultTransport({
+    vault: "default",
+    vaultUrl: "http://127.0.0.1:1940",
+    token: "write-token",
+  });
+  const channels = new Map<string, Channel>();
+  channels.set("uni-dev", {
+    name: "uni-dev",
+    transport: vault,
+    entry: { name: "uni-dev", transport: "vault", config: { vault: "default", token: "write-token" } },
+  });
+  const tele = new TelegramTransport({ token: "tg", name: "tele" });
+  channels.set("tele", {
+    name: "tele",
+    transport: tele,
+    entry: { name: "tele", transport: "telegram", config: { token: "tg" } },
+  });
+  return { channels, vault };
+}
+
+describe("vaultTransportFor", () => {
+  test("resolves a vault channel to its transport; null for non-vault / unknown", () => {
+    const { channels, vault } = channelsWithVault();
+    expect(vaultTransportFor(channels, "uni-dev")).toBe(vault);
+    expect(vaultTransportFor(channels, "tele")).toBeNull();
+    expect(vaultTransportFor(channels, "ghost")).toBeNull();
+  });
+});
+
+describe("VaultJobStore — vault-native CRUD", () => {
+  test("listAll queries each unique vault once + maps job notes to Jobs", async () => {
+    const { channels } = channelsWithVault();
+    const urls: string[] = [];
+    globalThis.fetch = (async (url: string | URL | Request) => {
+      urls.push(String(url));
+      return new Response(
+        JSON.stringify([
+          {
+            id: "note-1",
+            content: "Run the weave",
+            metadata: {
+              channel: "uni-dev",
+              cron: "53 7 * * *",
+              tz: "America/Los_Angeles",
+              enabled: "true",
+              createdAt: "2026-06-17T00:00:00Z",
+            },
+          },
+          {
+            id: "note-2",
+            content: "Hourly ping",
+            metadata: { channel: "uni-dev", cron: "0 * * * *", enabled: "false" },
+          },
+        ]),
+        { status: 200, headers: { "content-type": "application/json" } },
+      );
+    }) as typeof fetch;
+
+    const store = new VaultJobStore(channels);
+    const jobs = await store.listAll();
+    // Only ONE vault transport in the map → queried exactly once (telegram is skipped).
+    expect(urls.filter((u) => u.includes("/api/notes")).length).toBe(1);
+    expect(urls[0]).toContain("tag=%23agent%2Fjob");
+    expect(jobs).toHaveLength(2);
+    expect(jobs[0]).toMatchObject({
+      id: "note-1",
+      channel: "uni-dev",
+      message: "Run the weave",
+      schedule: { cron: "53 7 * * *", tz: "America/Los_Angeles" },
+      enabled: true,
+    });
+    expect(jobs[1]!.enabled).toBe(false); // "false" string → disabled
+  });
+
+  test("listAll dedups by vault IDENTITY across SEPARATE transport instances sharing one vault (regression)", async () => {
+    // Two vault channels, each with its OWN VaultTransport INSTANCE pointing at the
+    // SAME vault "default" — the real shape (each channel constructs its own
+    // transport). Instance-identity dedup misses this; vaultKey() dedup must catch it.
+    // Caught live 2026-06-18: one job listed 3x with three channels on the default vault.
+    const cfg = { vault: "default", vaultUrl: "http://127.0.0.1:1940", token: "write-token" };
+    const channels = new Map<string, Channel>();
+    for (const name of ["uni-a", "uni-b"]) {
+      channels.set(name, {
+        name,
+        transport: new VaultTransport(cfg), // a DISTINCT instance per channel
+        entry: { name, transport: "vault", config: { vault: "default", token: "write-token" } },
+      });
+    }
+    const urls: string[] = [];
+    globalThis.fetch = (async (url: string | URL | Request) => {
+      urls.push(String(url));
+      return new Response(
+        JSON.stringify([
+          { id: "Channels/uni-a/jobs/j1", content: "do it", metadata: { channel: "uni-a", cron: "0 9 * * *", enabled: "true" } },
+        ]),
+        { status: 200, headers: { "content-type": "application/json" } },
+      );
+    }) as typeof fetch;
+
+    const store = new VaultJobStore(channels);
+    const jobs = await store.listAll();
+    // Queried the shared vault EXACTLY once (not once per channel), and the job
+    // appears EXACTLY once (not duplicated per channel that shares the vault).
+    expect(urls.filter((u) => u.includes("/api/notes")).length).toBe(1);
+    expect(jobs).toHaveLength(1);
+    expect(jobs[0]!.id).toBe("Channels/uni-a/jobs/j1");
+  });
+
+  test("upsert writes a #agent/job note via the target channel's vault", async () => {
+    const { channels } = channelsWithVault();
+    const calls: { url: string; init: RequestInit }[] = [];
+    globalThis.fetch = (async (url: string | URL | Request, init?: RequestInit) => {
+      calls.push({ url: String(url), init: init ?? {} });
+      return new Response(JSON.stringify({ id: "Channels/uni-dev/jobs/morning" }), {
+        status: 201,
+        headers: { "content-type": "application/json" },
+      });
+    }) as typeof fetch;
+
+    const store = new VaultJobStore(channels);
+    const saved = await store.upsert(makeJob());
+    // `id` stays the operator slug; `noteId` is the vault note id for addressing.
+    expect(saved.id).toBe("morning");
+    expect(saved.noteId).toBe("Channels/uni-dev/jobs/morning");
+    expect(calls).toHaveLength(1);
+    const body = JSON.parse(String(calls[0]!.init.body));
+    expect(body.tags).toEqual(["#agent/job"]);
+    expect(body.path).toBe("Channels/uni-dev/jobs/morning");
+    expect(body.metadata.jobId).toBe("morning"); // slug persisted for stable display
+    expect(body.content).toBe("Run the morning weave");
+    expect(body.metadata).toMatchObject({
+      // CONTRACT: routing key under `metadata.agent` ONLY — no `channel`.
+      agent: "uni-dev",
+      cron: "53 7 * * *",
+      tz: "America/Los_Angeles",
+      enabled: "true",
+      createdAt: "2026-06-17T00:00:00.000Z",
+    });
+    expect(body.metadata.channel).toBeUndefined();
+    // nextRunAt is NEVER persisted.
+    expect(body.metadata.nextRunAt).toBeUndefined();
+    const headers = calls[0]!.init.headers as Record<string, string>;
+    expect(headers.authorization).toBe("Bearer write-token");
+  });
+
+  test("upsert to a non-vault channel throws", async () => {
+    const { channels } = channelsWithVault();
+    const store = new VaultJobStore(channels);
+    await expect(store.upsert(makeJob({ channel: "tele" }))).rejects.toThrow(/not a live vault channel/);
+  });
+
+  test("remove DELETEs the note by id via the channel's vault", async () => {
+    const { channels } = channelsWithVault();
+    const calls: { url: string; method?: string }[] = [];
+    globalThis.fetch = (async (url: string | URL | Request, init?: RequestInit) => {
+      calls.push({ url: String(url), method: init?.method });
+      return new Response(null, { status: 204 });
+    }) as typeof fetch;
+    const store = new VaultJobStore(channels);
+    await store.remove("Channels/uni-dev/jobs/morning", "uni-dev");
+    expect(calls).toHaveLength(1);
+    expect(calls[0]!.method).toBe("DELETE");
+    expect(calls[0]!.url).toContain("/api/notes/");
+  });
+
+  test("patch PATCHes bookkeeping metadata onto the note", async () => {
+    const { channels } = channelsWithVault();
+    const calls: { url: string; init: RequestInit }[] = [];
+    globalThis.fetch = (async (url: string | URL | Request, init?: RequestInit) => {
+      calls.push({ url: String(url), init: init ?? {} });
+      return new Response(null, { status: 200 });
+    }) as typeof fetch;
+    const store = new VaultJobStore(channels);
+    await store.patch("note-1", "uni-dev", { lastRunAt: "2026-06-17T11:00:00Z", lastStatus: "ok" });
+    expect(calls[0]!.init.method).toBe("PATCH");
+    const body = JSON.parse(String(calls[0]!.init.body));
+    expect(body.metadata).toEqual({ lastRunAt: "2026-06-17T11:00:00Z", lastStatus: "ok" });
+  });
+});