@openparachute/agent 0.1.2 → 0.2.0

package/src/def-vaults.test.ts

@@ -0,0 +1,136 @@
+/**
+ * Unit tests for the def-vault config (design 2026-06-17-vault-native-agents,
+ * Phase 4a "Commit 3"). Sandboxed to a throwaway state dir (NEVER the operator's
+ * ~/.parachute); the mint is driven by an injected fetch — deterministic, no real hub.
+ */
+
+import { describe, test, expect, afterEach } from "bun:test";
+import { mkdtempSync, rmSync, existsSync, readFileSync, writeFileSync, statSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import {
+  readDefVaultsFile,
+  writeDefVaultsFile,
+  defVaultsFilePath,
+  resolveDefVaults,
+  DEFAULT_DEF_VAULT_NAME,
+} from "./def-vaults.ts";
+
+const dirs: string[] = [];
+function freshDir(): string {
+  const d = mkdtempSync(join(tmpdir(), "agent-defvaults-"));
+  dirs.push(d);
+  return d;
+}
+afterEach(() => {
+  for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true });
+});
+
+/** A fake hub mint endpoint returning a scripted token. */
+function fakeMint(token: string): { fetchFn: typeof fetch; calls: Array<Record<string, unknown>> } {
+  const calls: Array<Record<string, unknown>> = [];
+  const fetchFn = (async (_url: string | URL | Request, init?: RequestInit) => {
+    calls.push(JSON.parse(String(init?.body ?? "{}")));
+    return new Response(JSON.stringify({ token, jti: "j", expires_at: "", scope: "vault:default:write" }), {
+      status: 200,
+      headers: { "content-type": "application/json" },
+    });
+  }) as typeof fetch;
+  return { fetchFn, calls };
+}
+
+describe("agent-vaults.json read/write", () => {
+  test("readDefVaultsFile returns null when absent", () => {
+    expect(readDefVaultsFile(freshDir())).toBeNull();
+  });
+
+  test("write then read round-trips; file is 0600", () => {
+    const dir = freshDir();
+    writeDefVaultsFile({ vaults: [{ vault: "default", vaultUrl: "http://x", token: "t" }] }, dir);
+    const back = readDefVaultsFile(dir);
+    expect(back?.vaults).toEqual([{ vault: "default", vaultUrl: "http://x", token: "t" }]);
+    const mode = statSync(defVaultsFilePath(dir)).mode & 0o777;
+    expect(mode).toBe(0o600);
+  });
+
+  test("a malformed file throws (operator error, not silently defaulted)", () => {
+    const dir = freshDir();
+    writeFileSync(defVaultsFilePath(dir), JSON.stringify({ nope: true }));
+    expect(() => readDefVaultsFile(dir)).toThrow(/"vaults" array/);
+  });
+
+  test("an entry missing vault throws", () => {
+    const dir = freshDir();
+    writeFileSync(defVaultsFilePath(dir), JSON.stringify({ vaults: [{ token: "t" }] }));
+    expect(() => readDefVaultsFile(dir)).toThrow(/non-empty "vault"/);
+  });
+});
+
+describe("resolveDefVaults", () => {
+  test("explicit agent-vaults.json wins (multi-vault, verbatim tokens, no mint)", async () => {
+    const dir = freshDir();
+    writeDefVaultsFile(
+      {
+        vaults: [
+          { vault: "default", vaultUrl: "http://127.0.0.1:1940", token: "tok-default" },
+          { vault: "research", vaultUrl: "http://127.0.0.1:1940", token: "tok-research" },
+        ],
+      },
+      dir,
+    );
+    const { fetchFn, calls } = fakeMint("SHOULD-NOT-BE-USED");
+    const bindings = await resolveDefVaults({ stateDir: dir, managerBearer: "op", fetchFn });
+    expect(bindings.map((b) => b.vault)).toEqual(["default", "research"]);
+    expect(bindings[0]!.token).toBe("tok-default");
+    expect(bindings[1]!.token).toBe("tok-research");
+    // No mint when the file carries tokens.
+    expect(calls).toHaveLength(0);
+  });
+
+  test("no file + a manager bearer → mints a default vault:default:write token + persists", async () => {
+    const dir = freshDir();
+    const { fetchFn, calls } = fakeMint("minted-token");
+    const bindings = await resolveDefVaults({
+      stateDir: dir,
+      hubOrigin: "http://127.0.0.1:1939",
+      managerBearer: "operator-bearer",
+      fetchFn,
+    });
+    expect(bindings).toHaveLength(1);
+    expect(bindings[0]).toMatchObject({ vault: DEFAULT_DEF_VAULT_NAME, token: "minted-token" });
+    // Minted with the vault:default:write scope, attenuated to the operator bearer.
+    expect(calls[0]!.scope).toBe("vault:default:write");
+    // Persisted so a restart reuses it (no re-mint).
+    expect(existsSync(defVaultsFilePath(dir))).toBe(true);
+    const persisted = readDefVaultsFile(dir);
+    expect(persisted?.vaults[0]!.token).toBe("minted-token");
+  });
+
+  test("persist:false → mints but does NOT write the file", async () => {
+    const dir = freshDir();
+    const { fetchFn } = fakeMint("minted");
+    const bindings = await resolveDefVaults({
+      stateDir: dir,
+      managerBearer: "op",
+      fetchFn,
+      persist: false,
+    });
+    expect(bindings).toHaveLength(1);
+    expect(existsSync(defVaultsFilePath(dir))).toBe(false);
+  });
+
+  test("no file + no manager bearer → NO bindings (vault-native path idle; channels.json unaffected)", async () => {
+    const bindings = await resolveDefVaults({ stateDir: freshDir(), managerBearer: null });
+    expect(bindings).toEqual([]);
+  });
+
+  test("a mint failure → no bindings (best-effort; boot is not crashed)", async () => {
+    const dir = freshDir();
+    const fetchFn = (async () =>
+      new Response(JSON.stringify({ error: "invalid_scope" }), { status: 400 })) as unknown as typeof fetch;
+    const bindings = await resolveDefVaults({ stateDir: dir, managerBearer: "op", fetchFn });
+    expect(bindings).toEqual([]);
+    // Nothing persisted on a failed mint.
+    expect(existsSync(defVaultsFilePath(dir))).toBe(false);
+  });
+});

package/src/def-vaults.ts

@@ -0,0 +1,165 @@
+/**
+ * Def-vault binding/config — which vault(s) the module reads `#agent/definition`
+ * notes from, and the token it uses (design `2026-06-17-vault-native-agents.md`,
+ * Phase 4a "Commit 3").
+ *
+ * Modelled on `channels.json`: a small JSON file in the agent state dir
+ * (`agent-vaults.json`) holding a LIST of def-vaults. The architecture is a list
+ * (NOT single-vault) so opening up multi-vault later is appending an entry, not a
+ * refactor (design "Decided: multi-vault — any vault can define agents"). It
+ * DEFAULTS to a single entry for the local `default` vault when no file exists.
+ *
+ * The token is a `vault:<name>:write` hub JWT — read (query the defs) + write (stamp
+ * the `status` field + the agents' message/job notes). For the default local vault,
+ * when the file carries no token we MINT one at boot the same way channels/jobs get
+ * theirs (`mint-token.ts`, attenuated to the operator bearer). PER-VAULT SCOPING
+ * (load-bearing, 4a): the token is scoped to its own vault only — an agent defined in
+ * vault X reaches only X. The file is read 0600 (it can carry a token).
+ *
+ * This path is ADDITIVE to `channels.json` — both coexist. channels.json defines
+ * channels the old way; def-vaults define vault-native agents. Neither replaces the
+ * other.
+ */
+
+import { readFileSync, existsSync, writeFileSync, chmodSync, mkdirSync } from "fs";
+import { join } from "path";
+import { defaultStateDir } from "./registry.ts";
+import { mintScopedToken, vaultScope, MintError } from "./mint-token.ts";
+import type { DefVaultBinding } from "./agent-defs.ts";
+
+/** The local vault every install has by default — the design's `default` vault. */
+export const DEFAULT_DEF_VAULT_NAME = "default";
+/** The loopback vault REST origin (the local vault daemon). */
+export const DEFAULT_DEF_VAULT_URL = "http://127.0.0.1:1940";
+/** The loopback HUB origin (the mint-token endpoint lives on the hub, NOT the vault). */
+export const DEFAULT_HUB_ORIGIN = "http://127.0.0.1:1939";
+
+/** The on-disk shape of `agent-vaults.json`. */
+export interface DefVaultsFile {
+  /** The def-vaults this install reads agent definitions from (default: one). */
+  vaults: DefVaultBinding[];
+}
+
+/** Absolute path to `agent-vaults.json` in a state dir. */
+export function defVaultsFilePath(stateDir?: string): string {
+  return join(stateDir ?? defaultStateDir(), "agent-vaults.json");
+}
+
+/**
+ * Read `agent-vaults.json` as a plain {@link DefVaultsFile}. Returns null if the
+ * file is absent (the caller then applies the single-`default` default). Throws on a
+ * malformed file (a present-but-broken config is an operator error worth surfacing,
+ * not silently defaulting away).
+ */
+export function readDefVaultsFile(stateDir?: string): DefVaultsFile | null {
+  const file = defVaultsFilePath(stateDir);
+  if (!existsSync(file)) return null;
+  const parsed = JSON.parse(readFileSync(file, "utf8")) as DefVaultsFile;
+  if (!parsed || !Array.isArray(parsed.vaults)) {
+    throw new Error(`def-vaults: ${file} must have a "vaults" array`);
+  }
+  for (const v of parsed.vaults) {
+    if (!v || typeof v.vault !== "string" || v.vault.length === 0) {
+      throw new Error(`def-vaults: each entry needs a non-empty "vault" (got ${JSON.stringify(v)})`);
+    }
+  }
+  return parsed;
+}
+
+/**
+ * Persist `agent-vaults.json` (0600 — it can carry a token). Creates the state dir
+ * if needed. Used to materialize the default config after a boot mint so a restart
+ * reuses the same binding instead of re-minting.
+ */
+export function writeDefVaultsFile(file: DefVaultsFile, stateDir?: string): void {
+  const dir = stateDir ?? defaultStateDir();
+  mkdirSync(dir, { recursive: true });
+  const path = defVaultsFilePath(dir);
+  writeFileSync(path, JSON.stringify(file, null, 2) + "\n", { mode: 0o600 });
+  chmodSync(path, 0o600);
+}
+
+/** Wiring for the boot resolve (injected for tests — no real hub/mint/fs). */
+export interface ResolveDefVaultsDeps {
+  /** Agent state dir (default: the resolved state dir). */
+  stateDir?: string;
+  /** Hub origin for the default-vault token mint. */
+  hubOrigin?: string;
+  /** The operator bearer the default-vault mint is attenuated against. null = no mint. */
+  managerBearer?: string | null;
+  /** fetch override for the mint client (tests). */
+  fetchFn?: typeof fetch;
+  /** Persist the minted default config back to disk so a restart reuses it. Default true. */
+  persist?: boolean;
+}
+
+/**
+ * Resolve the def-vault bindings for this install. Order:
+ *
+ *   1. `agent-vaults.json` present → use its entries verbatim (each carries its own
+ *      token). This is the multi-vault + explicit-token path.
+ *   2. Absent → the SINGLE-`default` default: a binding for the local `default`
+ *      vault. If a `managerBearer` is available, MINT a `vault:default:write` token
+ *      (attenuated to the operator bearer) and — when `persist` — write the resulting
+ *      config so a restart reuses it (no re-mint). With no manager bearer (hub not
+ *      provisioned yet), we return NO bindings (the module starts idle on the
+ *      vault-native path; channels.json still works) rather than a tokenless binding
+ *      that would 401 on every query.
+ *
+ * Returns the bindings to hand the {@link AgentDefRegistry}. Best-effort on the mint:
+ * a mint failure is logged + yields no bindings (don't crash boot — the channels.json
+ * path is unaffected).
+ */
+export async function resolveDefVaults(deps: ResolveDefVaultsDeps = {}): Promise<DefVaultBinding[]> {
+  const stateDir = deps.stateDir ?? defaultStateDir();
+
+  // 1. Explicit config file wins.
+  const file = readDefVaultsFile(stateDir);
+  if (file) {
+    return file.vaults.map((v) => ({
+      vault: v.vault,
+      ...(v.vaultUrl ? { vaultUrl: v.vaultUrl } : {}),
+      token: v.token,
+    }));
+  }
+
+  // 2. Default: the local `default` vault. Mint its write token if we can.
+  if (!deps.managerBearer) {
+    console.warn(
+      "agent-defs: no operator token — skipping the default def-vault (the vault-native " +
+        "agent path is idle until the hub is provisioned; channels.json is unaffected).",
+    );
+    return [];
+  }
+  let token: string;
+  try {
+    const minted = await mintScopedToken(
+      { scope: vaultScope(DEFAULT_DEF_VAULT_NAME, "write") },
+      {
+        hubOrigin: deps.hubOrigin ?? DEFAULT_HUB_ORIGIN,
+        managerBearer: deps.managerBearer,
+        ...(deps.fetchFn ? { fetchFn: deps.fetchFn } : {}),
+      },
+    );
+    token = minted.token;
+  } catch (err) {
+    const detail = err instanceof MintError ? err.message : (err as Error).message;
+    console.error(`agent-defs: minting the default def-vault token failed (continuing): ${detail}`);
+    return [];
+  }
+
+  const binding: DefVaultBinding = {
+    vault: DEFAULT_DEF_VAULT_NAME,
+    vaultUrl: DEFAULT_DEF_VAULT_URL,
+    token,
+  };
+  // Materialize the config so a restart reuses this binding (no re-mint each boot).
+  if (deps.persist !== false) {
+    try {
+      writeDefVaultsFile({ vaults: [binding] }, stateDir);
+    } catch (err) {
+      console.warn(`agent-defs: persisting the default def-vault config failed (continuing): ${(err as Error).message}`);
+    }
+  }
+  return [binding];
+}

package/src/delivery-state.test.ts

@@ -0,0 +1,110 @@
+/**
+ * DeliveryState tests — the per-channel high-water-mark that gates backlog replay.
+ *
+ * Covered:
+ *  - monotonic advance (never rewinds; reports whether it moved);
+ *  - default-to-bootTime for an unknown channel (so a first connect never replays
+ *    ancient history);
+ *  - persist + reload across a simulated restart (a new instance reads the file);
+ *  - blank-ts advance is a no-op (we never mark to an empty ts).
+ *
+ * Each test points the store at a throwaway temp dir, so there's no shared global
+ * state and no touch of the real `~/.parachute/agent/`.
+ */
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdtempSync, rmSync, existsSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { DeliveryState } from "./delivery-state.ts";
+
+let dir: string;
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "channel-delivery-"));
+});
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+describe("getLastDelivered default", () => {
+  test("an unknown channel returns the boot-time default mark, not epoch", () => {
+    const boot = "2026-06-16T12:00:00.000Z";
+    const ds = new DeliveryState({ stateDir: dir, defaultMark: boot });
+    expect(ds.getLastDelivered("never-seen")).toBe(boot);
+  });
+
+  test("defaultMark defaults to ~now when omitted", () => {
+    const before = Date.now();
+    const ds = new DeliveryState({ stateDir: dir });
+    const mark = Date.parse(ds.getLastDelivered("x"));
+    const after = Date.now();
+    expect(mark).toBeGreaterThanOrEqual(before);
+    expect(mark).toBeLessThanOrEqual(after + 1000);
+  });
+});
+
+describe("advance is monotonic", () => {
+  test("moves forward + reports true; a stale/equal ts is a no-op reporting false", () => {
+    const ds = new DeliveryState({ stateDir: dir, defaultMark: "2026-01-01T00:00:00.000Z" });
+    expect(ds.advance("c", "2026-06-16T10:00:00.000Z")).toBe(true);
+    expect(ds.getLastDelivered("c")).toBe("2026-06-16T10:00:00.000Z");
+
+    // An OLDER ts must not rewind the mark.
+    expect(ds.advance("c", "2026-06-16T09:00:00.000Z")).toBe(false);
+    expect(ds.getLastDelivered("c")).toBe("2026-06-16T10:00:00.000Z");
+
+    // The SAME ts is also a no-op (strictly-greater advance).
+    expect(ds.advance("c", "2026-06-16T10:00:00.000Z")).toBe(false);
+    expect(ds.getLastDelivered("c")).toBe("2026-06-16T10:00:00.000Z");
+
+    // A NEWER ts advances again.
+    expect(ds.advance("c", "2026-06-16T11:00:00.000Z")).toBe(true);
+    expect(ds.getLastDelivered("c")).toBe("2026-06-16T11:00:00.000Z");
+  });
+
+  test("a blank ts never advances the mark", () => {
+    const ds = new DeliveryState({ stateDir: dir, defaultMark: "2026-01-01T00:00:00.000Z" });
+    expect(ds.advance("c", "")).toBe(false);
+    expect(ds.getLastDelivered("c")).toBe("2026-01-01T00:00:00.000Z");
+  });
+
+  test("per-channel marks are independent", () => {
+    const ds = new DeliveryState({ stateDir: dir, defaultMark: "2026-01-01T00:00:00.000Z" });
+    ds.advance("a", "2026-06-16T10:00:00.000Z");
+    expect(ds.getLastDelivered("a")).toBe("2026-06-16T10:00:00.000Z");
+    // b is untouched — still the default.
+    expect(ds.getLastDelivered("b")).toBe("2026-01-01T00:00:00.000Z");
+  });
+});
+
+describe("persist + reload (simulated restart)", () => {
+  test("a fresh instance reads the persisted marks (the restart case)", () => {
+    const ds1 = new DeliveryState({ stateDir: dir, defaultMark: "2026-01-01T00:00:00.000Z" });
+    ds1.advance("eng", "2026-06-16T10:00:00.000Z");
+    ds1.advance("ops", "2026-06-16T11:00:00.000Z");
+    expect(existsSync(join(dir, "delivery-state.json"))).toBe(true);
+
+    // Simulate a daemon restart: a brand-new instance with a LATER boot default.
+    // The persisted per-channel marks must win over the new default — that's what
+    // makes the replay-the-gap behavior work across a bounce.
+    const ds2 = new DeliveryState({ stateDir: dir, defaultMark: "2026-06-16T12:00:00.000Z" });
+    expect(ds2.getLastDelivered("eng")).toBe("2026-06-16T10:00:00.000Z");
+    expect(ds2.getLastDelivered("ops")).toBe("2026-06-16T11:00:00.000Z");
+    // A channel with no persisted mark still falls back to the new boot default.
+    expect(ds2.getLastDelivered("brand-new")).toBe("2026-06-16T12:00:00.000Z");
+  });
+
+  test("the persisted file is valid JSON of channel→ts", () => {
+    const ds = new DeliveryState({ stateDir: dir, defaultMark: "2026-01-01T00:00:00.000Z" });
+    ds.advance("eng", "2026-06-16T10:00:00.000Z");
+    const onDisk = JSON.parse(readFileSync(join(dir, "delivery-state.json"), "utf8"));
+    expect(onDisk).toEqual({ eng: "2026-06-16T10:00:00.000Z" });
+  });
+
+  test("a corrupt file is tolerated — starts empty, the default covers unknowns", () => {
+    writeFileSync(join(dir, "delivery-state.json"), "{ not json");
+    const ds = new DeliveryState({ stateDir: dir, defaultMark: "2026-06-16T12:00:00.000Z" });
+    expect(ds.getLastDelivered("eng")).toBe("2026-06-16T12:00:00.000Z");
+    // Still usable: advance + persist overwrites the corrupt file.
+    expect(ds.advance("eng", "2026-06-16T13:00:00.000Z")).toBe(true);
+  });
+});

package/src/delivery-state.ts

@@ -0,0 +1,154 @@
+/**
+ * Per-channel delivery high-water-mark — the spine of the no-silent-loss fix.
+ *
+ * THE PROBLEM. The vault-backed inbound pipeline wakes a session by `ctx.emit`
+ * fanning a new `#agent/message/inbound` note to whatever SSE bridges + HTTP
+ * MCP sessions are live on the channel. But:
+ *  - the daemon acks the vault trigger `{ok:true}` regardless of how many
+ *    subscribers actually received it, and the vault stamps `..._rendered_at` on
+ *    the note so the trigger never re-fires — so a note delivered to ZERO live
+ *    subscribers is lost from the live path (it stays durable in the vault, but
+ *    no session is ever woken on it); and
+ *  - MCP sessions drop on every daemon restart and only reconnect on the next
+ *    interaction, so any inbound that lands during that deaf window reaches no
+ *    one.
+ *
+ * THE FIX. Track, per channel, the timestamp of the last inbound message we
+ * actually DELIVERED to at least one live subscriber (the high-water-mark). On
+ * (re)connect, a session replays the backlog of inbound notes with `ts` newer
+ * than that mark — so messages that arrived while nobody was listening get
+ * delivered the moment a session attaches. `emit` advances the mark only on a
+ * real delivery (≥1 subscriber); a 0-subscriber emit leaves the mark behind so
+ * the message replays later.
+ *
+ * THE MARK IS MONOTONIC. `advance` only ever moves the mark FORWARD. Out-of-order
+ * or duplicate deliveries can never rewind it (which would re-replay already-seen
+ * messages). ISO-8601 timestamps compare correctly as strings (lexicographic ==
+ * chronological for the `Z`-suffixed UTC form the vault writes), so the compare is
+ * a plain string `>`.
+ *
+ * DEFAULT = BOOT TIME. A channel with no persisted mark defaults to the daemon's
+ * boot time — NOT epoch. This is deliberate: on a FIRST connect we must not
+ * replay the channel's entire (possibly ancient) vault history as if it were all
+ * unread. The only messages a fresh mark replays are ones that arrived AFTER the
+ * daemon started (the genuine deaf-window case). Persisted marks survive restarts,
+ * so a channel that has been delivering keeps its real high-water-mark across a
+ * bounce and replays exactly the restart gap.
+ *
+ * PERSISTENCE. The marks live in a single small JSON file under the channel state
+ * dir (`<PARACHUTE_AGENT_STATE_DIR>/delivery-state.json`, default
+ * `~/.parachute/agent/delivery-state.json`). Writes are write-through but
+ * resilient: a failed write is logged and swallowed — losing a mark only costs a
+ * bounded re-replay, never a crash. Load-on-construct reads the file once.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync } from "fs";
+import { join, dirname } from "path";
+import { defaultStateDir } from "./registry.ts";
+
+/** The on-disk shape: `{ "<channel>": "<iso-ts>", ... }`. */
+type DeliveryStateFile = Record<string, string>;
+
+export interface DeliveryStateOptions {
+  /** State dir for the persisted file. Defaults to the channel state dir. */
+  stateDir?: string;
+  /**
+   * The default mark for a channel with no persisted entry — an ISO timestamp.
+   * The daemon passes its boot time so a first connect never replays ancient
+   * history. Defaults to "now" at construction if omitted.
+   */
+  defaultMark?: string;
+}
+
+/**
+ * Per-channel last-delivered high-water-mark store. One instance per daemon;
+ * constructed at boot with the boot time as the default mark, then read/advanced
+ * on every emit + every (re)connect. Each instance owns its own file + in-memory
+ * map, so tests construct throwaway instances pointed at a temp dir with no
+ * global state to reset.
+ */
+export class DeliveryState {
+  private readonly file: string;
+  private readonly defaultMark: string;
+  private readonly marks: Map<string, string> = new Map();
+
+  constructor(opts: DeliveryStateOptions = {}) {
+    const stateDir = opts.stateDir ?? defaultStateDir();
+    this.file = join(stateDir, "delivery-state.json");
+    this.defaultMark = opts.defaultMark ?? new Date().toISOString();
+    this.load();
+  }
+
+  /** Read the persisted marks once at construction. Missing/corrupt file → empty. */
+  private load(): void {
+    let raw: string;
+    try {
+      raw = readFileSync(this.file, "utf8");
+    } catch {
+      // No file yet (first boot) — start empty; the default mark covers unknowns.
+      return;
+    }
+    try {
+      const parsed = JSON.parse(raw) as unknown;
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        for (const [k, v] of Object.entries(parsed as DeliveryStateFile)) {
+          if (typeof v === "string" && v) this.marks.set(k, v);
+        }
+      }
+    } catch (err) {
+      // Corrupt file — log and start empty rather than crash. The marks rebuild
+      // from boot-time defaults; the cost is a bounded re-replay, not a loss.
+      console.warn(
+        `parachute-agent: delivery-state file ${this.file} is unreadable (${(err as Error).message}); ` +
+          `starting with empty marks.`,
+      );
+    }
+  }
+
+  /** Write the current marks through to disk. Best-effort: a failure is logged, never thrown. */
+  private persist(): void {
+    try {
+      mkdirSync(dirname(this.file), { recursive: true });
+      const obj: DeliveryStateFile = {};
+      for (const [k, v] of this.marks) obj[k] = v;
+      writeFileSync(this.file, JSON.stringify(obj, null, 2));
+    } catch (err) {
+      console.warn(
+        `parachute-agent: failed to persist delivery-state to ${this.file} ` +
+          `(${(err as Error).message}); the mark is held in memory only.`,
+      );
+    }
+  }
+
+  /**
+   * The last-delivered mark for a channel: the persisted value, or the daemon's
+   * boot-time default when this channel has never delivered. Always an ISO string,
+   * so callers can compare note timestamps against it with a plain string `>`.
+   *
+   * NOTE (post-2026-06-19, interactive retirement): the only EXTERNAL reader of the
+   * mark was `replayBacklog`, now retired — so today this is an ADVANCE-ONLY path
+   * (the live caller is `advance`'s own monotonic check below). Kept public + durable:
+   * the channel backend uses note `status` claim-state, not replay, and a future
+   * replay-style feature can read the mark again without re-plumbing the store.
+   */
+  getLastDelivered(channel: string): string {
+    return this.marks.get(channel) ?? this.defaultMark;
+  }
+
+  /**
+   * Move a channel's mark forward to `ts` IF it's newer than the current mark
+   * (monotonic — never rewinds). Returns true if the mark advanced (and was
+   * persisted), false if `ts` was not newer (no write). An empty/missing `ts` is
+   * a no-op (we never advance to a blank mark — that would replay everything).
+   */
+  advance(channel: string, ts: string): boolean {
+    if (!ts) return false;
+    const current = this.getLastDelivered(channel);
+    if (ts > current) {
+      this.marks.set(channel, ts);
+      this.persist();
+      return true;
+    }
+    return false;
+  }
+}

package/src/effective-env.test.ts

@@ -0,0 +1,114 @@
+/**
+ * Unit tests for the PURE effective-env composition (effective-env.ts) — the
+ * precedence/overridden logic + the no-material grant-name derivation, isolated from
+ * the daemon route + any I/O. (The route integration lives in daemon-agent-env-api.test.ts.)
+ */
+import { describe, test, expect } from "bun:test";
+import {
+  approvedGrantEnvNames,
+  composeEffectiveEnv,
+  resolveEffectiveEnv,
+} from "./effective-env.ts";
+
+describe("approvedGrantEnvNames — names only, approved-service grants only, NO material", () => {
+  test("maps an approved service grant to its env-var name via serviceEnvVar", () => {
+    const out = approvedGrantEnvNames([{ kind: "service", target: "github", status: "approved" }]);
+    expect(out).toEqual([{ name: "GITHUB_TOKEN", source: "grant:github" }]);
+  });
+
+  test("a non-default service maps to <TARGET>_TOKEN", () => {
+    const out = approvedGrantEnvNames([{ kind: "service", target: "fireflies", status: "approved" }]);
+    expect(out).toEqual([{ name: "FIREFLIES_TOKEN", source: "grant:fireflies" }]);
+  });
+
+  test("ignores pending grants, vault grants, and mcp grants (none inject an env var)", () => {
+    const out = approvedGrantEnvNames([
+      { kind: "service", target: "github", status: "pending" }, // not approved
+      { kind: "vault", target: "research", status: "approved" }, // vault → MCP, not env
+      { kind: "mcp", target: "https://x/mcp", status: "approved" }, // remote MCP, not env
+      { kind: "service", target: "cloudflare", status: "approved" }, // the only env one
+    ]);
+    expect(out).toEqual([{ name: "CLOUDFLARE_API_TOKEN", source: "grant:cloudflare" }]);
+  });
+
+  test("undefined connections → empty", () => {
+    expect(approvedGrantEnvNames(undefined)).toEqual([]);
+  });
+});
+
+describe("composeEffectiveEnv — precedence channel > default > grant + overridden marking", () => {
+  const channelEnv = {
+    default: ["DEFAULT_VAR", "GITHUB_TOKEN"],
+    channels: { "uni-dev": ["CHANNEL_VAR", "GITHUB_TOKEN"] },
+  };
+  const connections = [{ kind: "service", target: "github", status: "approved" }];
+
+  test("a name set in all three layers → channel wins, default + grant marked overridden", () => {
+    const out = composeEffectiveEnv("uni-dev", channelEnv, connections);
+    const gh = out.filter((e) => e.name === "GITHUB_TOKEN");
+    expect(gh).toHaveLength(3);
+    const winner = gh.find((e) => !e.overridden)!;
+    expect(winner.source).toBe("channel");
+    expect(gh.filter((e) => e.overridden).map((e) => e.source).sort()).toEqual(["default", "grant:github"]);
+  });
+
+  test("single-layer names carry no overridden flag", () => {
+    const out = composeEffectiveEnv("uni-dev", channelEnv, connections);
+    expect(out.find((e) => e.name === "DEFAULT_VAR")).toEqual({ name: "DEFAULT_VAR", source: "default" });
+    expect(out.find((e) => e.name === "CHANNEL_VAR")).toEqual({ name: "CHANNEL_VAR", source: "channel" });
+  });
+
+  test("default beats grant when no channel override exists", () => {
+    const out = composeEffectiveEnv(
+      "uni-dev",
+      { default: ["GITHUB_TOKEN"], channels: {} },
+      connections,
+    );
+    const gh = out.filter((e) => e.name === "GITHUB_TOKEN");
+    expect(gh.find((e) => !e.overridden)!.source).toBe("default");
+    expect(gh.find((e) => e.overridden)!.source).toBe("grant:github");
+  });
+
+  test("an agent with no env-store entries + no connections → empty", () => {
+    expect(composeEffectiveEnv("nobody", { default: [], channels: {} }, undefined)).toEqual([]);
+  });
+
+  test("only the matching agent's channel layer is used (another agent's overrides are ignored)", () => {
+    const out = composeEffectiveEnv(
+      "uni-dev",
+      { default: [], channels: { other: ["OTHER_VAR"], "uni-dev": ["MINE"] } },
+      undefined,
+    );
+    expect(out.map((e) => e.name)).toEqual(["MINE"]);
+  });
+});
+
+describe("resolveEffectiveEnv — degraded note when no def, never returns values", () => {
+  test("hasDef:false → attaches a note + still returns env layers", () => {
+    const res = resolveEffectiveEnv("uni-dev", {
+      describeEnv: () => ({ default: ["DEFAULT_VAR"], channels: { "uni-dev": ["CHANNEL_VAR"] } }),
+      hasDef: false,
+    });
+    expect(res.note).toBeDefined();
+    expect(res.env.map((e) => e.name).sort()).toEqual(["CHANNEL_VAR", "DEFAULT_VAR"]);
+  });
+
+  test("hasDef:true → no note", () => {
+    const res = resolveEffectiveEnv("uni-dev", {
+      describeEnv: () => ({ default: [], channels: {} }),
+      connections: [{ kind: "service", target: "github", status: "approved" }],
+      hasDef: true,
+    });
+    expect(res.note).toBeUndefined();
+    expect(res.env).toEqual([{ name: "GITHUB_TOKEN", source: "grant:github" }]);
+  });
+
+  test("the shape carries NO `value` field on any entry", () => {
+    const res = resolveEffectiveEnv("uni-dev", {
+      describeEnv: () => ({ default: ["A"], channels: { "uni-dev": ["B"] } }),
+      connections: [{ kind: "service", target: "github", status: "approved" }],
+      hasDef: true,
+    });
+    for (const e of res.env) expect(Object.keys(e).sort()).not.toContain("value");
+  });
+});