signafaide 0.0.0-stage → 0.3.0

package/dist/chunk-P3GJDXSQ.js

@@ -0,0 +1,3025 @@
+import {
+  AGENT_KEYS_FORMAT,
+  AGENT_RE,
+  API_KEY_RE,
+  DEFAULT_TIMESTAMP_URL,
+  DRAND_NOT_CHECKED,
+  INSTANCE_START,
+  INSTANCE_STOP,
+  KeysRequired,
+  MAX_CLOCK_SKEW_MS,
+  SigningKey,
+  TOOLS,
+  agentName,
+  b64url,
+  b64urlDecode,
+  byCodePoint,
+  canonicalize,
+  checkContent,
+  clampTime,
+  contentFromText,
+  declaredName,
+  hashJson,
+  instanceStartContent,
+  instanceStopContent,
+  isLoopbackUrl,
+  isStopNote,
+  isUnsafeInteger,
+  loadDrandVerifier,
+  lookupTimestamps,
+  makeDraft,
+  makeRecord,
+  manifestEntry,
+  now,
+  parseAgentKeys,
+  parseHeadFile,
+  parseJson,
+  parseServiceKeys,
+  plural,
+  recordHash,
+  registration,
+  signDraft,
+  timestampHeights,
+  toolNoteName,
+  useNativeCrypto,
+  validProjectId,
+  validTime,
+  verifyLocalState,
+  verifyPack,
+  verifySig,
+  wireRecord,
+  withWallTime
+} from "./chunk-6UDL5LZL.js";
+import {
+  ADAPTERS,
+  Client,
+  DEFAULT_URL,
+  SignafaideError,
+  VERSION,
+  adapterField,
+  clientHeader,
+  detectAgent,
+  fetchJson,
+  telemetryEnabled
+} from "./chunk-DRRRZNIH.js";
+
+// src/nodecrypto.ts
+import { createHash, createPublicKey, verify } from "crypto";
+var SPKI_ED25519 = Buffer.from("302a300506032b6570032100", "hex");
+var keys = /* @__PURE__ */ new Map();
+function publicKey(raw) {
+  const id = Buffer.from(raw).toString("hex");
+  let k = keys.get(id);
+  if (k === void 0) {
+    try {
+      k = createPublicKey({ key: Buffer.concat([SPKI_ED25519, raw]), format: "der", type: "spki" });
+    } catch {
+      k = null;
+    }
+    if (keys.size > 1e4) keys.clear();
+    keys.set(id, k);
+  }
+  return k;
+}
+function installNodeCrypto() {
+  useNativeCrypto({
+    sha256: (data) => new Uint8Array(createHash("sha256").update(data).digest()),
+    verify: (pk, message, sig) => {
+      const k = publicKey(pk);
+      if (!k) return false;
+      try {
+        return verify(null, message, k, sig);
+      } catch {
+        return false;
+      }
+    }
+  });
+}
+
+// src/index.ts
+import * as fs4 from "fs";
+import * as path3 from "path";
+
+// src/runtime.ts
+import { AsyncLocalStorage } from "async_hooks";
+import * as fs2 from "fs";
+import * as os2 from "os";
+import * as path2 from "path";
+
+// src/nodehttp.ts
+import * as http from "http";
+import * as https from "https";
+function nodeTransport(hold) {
+  return (req) => new Promise((resolve2, reject) => {
+    const u = new URL(req.url);
+    const mod = u.protocol === "https:" ? https : http;
+    const keep = hold();
+    let settled = false;
+    const done = (f) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      req.signal?.removeEventListener("abort", onAbort);
+      f();
+    };
+    const r = mod.request(u, { method: req.method, headers: { ...req.headers, ...req.body !== void 0 ? { "Content-Length": Buffer.byteLength(req.body) } : {} }, agent: false }, (res) => {
+      const chunks = [];
+      res.on("data", (c) => chunks.push(c));
+      res.on("end", () => done(() => resolve2({ status: res.statusCode ?? 0, contentType: String(res.headers["content-type"] ?? ""), text: Buffer.concat(chunks).toString("utf8") })));
+      res.on("error", (e) => done(() => reject(e)));
+    });
+    const timer = setTimeout(() => {
+      r.destroy(new Error("timeout"));
+    }, req.timeoutMs);
+    const onAbort = () => {
+      r.destroy(new Error("aborted"));
+    };
+    if (!keep) {
+      timer.unref();
+      r.on("socket", (s) => s.unref());
+    }
+    if (req.signal?.aborted) onAbort();
+    else req.signal?.addEventListener("abort", onAbort, { once: true });
+    r.on("error", (e) => done(() => reject(e)));
+    if (req.body !== void 0) r.write(req.body);
+    r.end();
+  });
+}
+
+// src/state.ts
+import { createHash as createHash2, randomBytes } from "crypto";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+var MARKERS = [".git", "pyproject.toml", "package.json"];
+var SEGMENT_BYTES = () => Number(process.env.SIGNAFAIDE_SEGMENT_BYTES) || 64 * 1024 * 1024;
+var scopeOf = (bucket) => bucket.endsWith("/live") ? "live" : "";
+var agentKeyEnvName = (agent, scope = "") => `SIGNAFAIDE_AGENT_KEY_${scope ? "LIVE_" : ""}${agent.toUpperCase().replace(/[^A-Z0-9]/g, "_")}`;
+function fsError(e, home) {
+  const code = e?.code;
+  if (code === "EACCES" || code === "EROFS" || code === "EPERM") {
+    return new StateError(
+      `cannot write signafAIde's local state in ${home} (${code === "EROFS" ? "read-only file system" : "permission denied"}). Set SIGNAFAIDE_HOME to a writable folder (for example a mounted volume, or /tmp/signafaide on serverless) or SIGNAFAIDE_DISABLED=1 to turn recording off; see https://signafaide.co.uk/docs/production`
+    );
+  }
+  return e;
+}
+var TOOL_SOURCE_REFRESH_MS = 36e5;
+var TOOL_SOURCE_MAX_AGE_MS = 864e5;
+var LOCK_STALE_MS = 1e4;
+var LOCK_WAIT_MS = 15e3;
+var PENDING = "_pending";
+var monotonicMs = () => Number(process.hrtime.bigint() / 1000000n);
+function bootId() {
+  try {
+    return fs.readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim();
+  } catch {
+    return "";
+  }
+}
+function lockStamp() {
+  return `${process.pid} ${bootId() || "-"} ${(monotonicMs() / 1e3).toFixed(3)}`;
+}
+function lockAgeMs(p) {
+  let parts = [];
+  try {
+    parts = fs.readFileSync(p, "utf8").split(/\s+/).filter(Boolean);
+  } catch {
+    parts = [];
+  }
+  const boot = bootId();
+  if (parts.length === 3 && boot && parts[1] === boot && Number.isFinite(Number(parts[2]))) return monotonicMs() - Number(parts[2]) * 1e3;
+  return Date.now() - fs.statSync(p).mtimeMs;
+}
+var keyFingerprint = (apiKey) => createHash2("sha256").update(apiKey).digest("hex").slice(0, 16);
+var StateError = class extends Error {
+  name = "StateError";
+};
+function findRoot(start = process.cwd()) {
+  start = path.resolve(start);
+  const home = path.resolve(os.homedir());
+  const chain = [];
+  for (let d = start; ; d = path.dirname(d)) {
+    chain.push(d);
+    if (path.dirname(d) === d) break;
+  }
+  for (const d of chain) if (isDir(path.join(d, ".signafaide"))) return d;
+  for (const d of chain) {
+    if (d === home || path.dirname(d) === d) break;
+    if (MARKERS.some((m) => fs.existsSync(path.join(d, m)))) return d;
+  }
+  return start;
+}
+var isDir = (p) => {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+};
+var sleepSync = (ms) => {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+};
+var pad = (seq) => String(seq).padStart(12, "0");
+var State = class _State {
+  constructor(home, root) {
+    this.home = home;
+    this.root = root;
+  }
+  home;
+  root;
+  /** Agent keys from a secret store, before the key files (`RecorderOptions.keyProvider`). */
+  keyProvider;
+  /** `root`: the project folder (default: found from the cwd). */
+  static discover(home, root) {
+    root = root ? path.resolve(root) : findRoot();
+    home = home || process.env.SIGNAFAIDE_HOME;
+    return new _State(home ? path.resolve(home) : path.join(root, ".signafaide"), root);
+  }
+  // --- layout -----------------------------------------------------------------
+  /** Create the folders. `.gitignore` is never edited here: only `signafaide init` and
+   * `agent setup` do that, so a CI checkout stays clean (§8). */
+  ensure() {
+    try {
+      for (const sub of ["agents", "chain", "outbox"]) fs.mkdirSync(path.join(this.home, sub), { recursive: true });
+      const gi = path.join(this.home, ".gitignore");
+      if (!fs.existsSync(gi)) fs.writeFileSync(gi, "*\n");
+    } catch (e) {
+      throw fsError(e, this.home);
+    }
+  }
+  /** Add `.signafaide/` (and `.env` when asked) to the project's .gitignore (init and agent setup only). */
+  ignoreInGit(...extra) {
+    const gi = path.join(this.root, ".gitignore");
+    if (this.home === path.join(this.root, ".signafaide")) ensureGitignore(gi, ".signafaide/");
+    for (const e of extra) ensureGitignore(gi, e);
+  }
+  keyDir(scope = "") {
+    return scope ? path.join(this.home, "agents", scope) : path.join(this.home, "agents");
+  }
+  keyPath(agent, scope = "") {
+    return path.join(this.keyDir(scope), `${agent}.key`);
+  }
+  /** The key handed in for this agent (provider, then SIGNAFAIDE_AGENT_KEY_<NAME>), or null. */
+  providedKey(agent, scope = "") {
+    let v = this.keyProvider?.(agent, scope);
+    if (v === void 0) v = process.env[agentKeyEnvName(agent, scope)] || (scope ? process.env[agentKeyEnvName(agent)] : void 0);
+    if (v === void 0 || v === "") return null;
+    let doc = v;
+    if (typeof v === "string") {
+      try {
+        doc = JSON.parse(v);
+      } catch {
+        throw new StateError(`${agentKeyEnvName(agent, scope)} must hold the agent's key file (JSON with private_key and created), as \`cat .signafaide/agents/${agent}.key\` shows it`);
+      }
+    }
+    if (!doc || typeof doc.private_key !== "string" || !validTime(doc.created) || doc.agent !== void 0 && doc.agent !== agent) {
+      throw new StateError(`the key given for agent ${agent} must be the agent's key file: {"agent", "private_key", "created", ...}`);
+    }
+    return { private_key: doc.private_key, created: doc.created };
+  }
+  chainPath(chain) {
+    return path.join(this.home, "chain", `${chain}.jsonl`);
+  }
+  outboxDir(chain) {
+    return path.join(this.home, "outbox", chain);
+  }
+  /** Every local chain id (`<project>/<env>/<agent>` or `_pending/<fp>/<agent>`). */
+  chains() {
+    return depth3(path.join(this.home, "chain")).filter((c) => c.endsWith(".jsonl")).map((c) => c.slice(0, -6)).sort();
+  }
+  agents() {
+    const names = new Set(this.chains().map((c) => c.split("/")[2]));
+    for (const scope of ["", "live"]) {
+      for (const f of readdir(this.keyDir(scope))) if (f.endsWith(".key")) names.add(f.slice(0, -4));
+      for (const f of readdir(this.retiredDir(scope))) if (f.endsWith(".key")) names.add(f.split(".")[0]);
+    }
+    for (const k of Object.keys(process.env)) {
+      const m = k.match(/^SIGNAFAIDE_AGENT_KEY_(?:LIVE_)?([A-Z0-9_]+)$/);
+      if (m && process.env[k]) {
+        try {
+          const a = JSON.parse(process.env[k]).agent;
+          if (typeof a === "string") names.add(a);
+        } catch {
+        }
+      }
+    }
+    return [...names].filter((n) => AGENT_RE.test(n)).sort();
+  }
+  // --- projects -----------------------------------------------------------------
+  /** `<project>/<env>` for this API key, or `_pending/<fp>` while its project is unknown. */
+  bucket(apiKey) {
+    if (!apiKey) return `${PENDING}/nokey`;
+    const fp = keyFingerprint(apiKey);
+    const p = this.config().projects?.[fp];
+    return p && validProjectId(p.project) && (p.env === "test" || p.env === "live") ? `${p.project}/${p.env}` : `${PENDING}/${fp}`;
+  }
+  /** Remember an API key's project. The values come from the service, so they are checked
+   * before they can name a folder (§8). */
+  learnProject(apiKey, project, env) {
+    if (!validProjectId(project) || env !== "test" && env !== "live") {
+      throw new StateError(`the service named project ${JSON.stringify(project)} env ${JSON.stringify(env)}, which is not a valid project id and env; check SIGNAFAIDE_URL`);
+    }
+    this.saveConfig({ projects: { ...this.config().projects ?? {}, [keyFingerprint(apiKey)]: { project, env } } });
+  }
+  /** Sign every draft chain of bucket `src` into `dst` (`<project>/<env>`) with its outbox
+   * (§8), keeping each record's time. Returns the chains left pending, with why: `exists` (that
+   * agent already has a chain under `dst`) or the first draft's time when it is before
+   * `notBefore` (the service would refuse it, §2.4). */
+  adopt(src, dst, key, wire, notBefore, bases = {}) {
+    const [project, env] = dst.split("/");
+    const conflicts = [];
+    for (const f of readdir(path.join(this.home, "chain", src)).filter((f2) => f2.endsWith(".jsonl")).sort()) {
+      const agent = f.slice(0, -6);
+      this.lock(
+        `${src}/${agent}`,
+        () => this.lock(`${dst}/${agent}`, () => {
+          const lines = this.lines(`${src}/${agent}`);
+          const target = this.chainPath(`${dst}/${agent}`);
+          const mapping = this.draftMap(`${dst}/${agent}`);
+          const first = lines[0]?.envelope.time;
+          const tooOld = !!notBefore && !!first && Date.parse(first) < Date.parse(notBefore);
+          if (fs.existsSync(target)) {
+            if (lines.length && lines.every((d) => recordHash(d) in mapping)) fs.unlinkSync(this.chainPath(`${src}/${agent}`));
+            else conflicts.push([`${src}/${agent}`, tooOld ? first : "exists"]);
+            return;
+          }
+          if (tooOld) {
+            conflicts.push([`${src}/${agent}`, first]);
+            return;
+          }
+          const base = bases[agent];
+          let prev = base ? base.record_hash : null;
+          let offset = base ? base.seq : 0;
+          const out = [];
+          if (base && lines.length) {
+            const note2 = makeRecord(key(agent, first), {
+              kind: "note",
+              project,
+              env,
+              agent,
+              seq: base.seq + 1,
+              prev,
+              name: INSTANCE_START,
+              content: instanceStartContent(base.seq, base.record_hash, !!base.stop),
+              ref: null,
+              time: first
+            });
+            prev = recordHash(note2);
+            offset += 1;
+            out.push([note2, lines[0].store_content]);
+          }
+          for (const d of lines) {
+            if (!d.draft) throw new StateError(`${this.chainPath(`${src}/${agent}`)} holds a signed record; pending chains hold drafts only. Move it aside and run \`signafaide verify\``);
+            const ref = d.envelope.ref;
+            const rec = signDraft(key(agent, first), d, project, env, prev, ref ? mapping[ref] ?? ref : null, d.envelope.seq + offset);
+            mapping[recordHash(d)] = prev = recordHash(rec);
+            out.push([rec, d.store_content]);
+          }
+          fs.mkdirSync(path.dirname(target), { recursive: true });
+          writeJson(this.mapPath(`${dst}/${agent}`), mapping);
+          if (base?.signed) writeJson(this.basePath(`${dst}/${agent}`), base.stop ? { ...base.signed, stop: base.stop } : base.signed);
+          const fd = fs.openSync(target + ".tmp", "w");
+          fs.writeSync(fd, out.map(([r]) => canonicalize(r) + "\n").join(""));
+          fs.fsyncSync(fd);
+          fs.closeSync(fd);
+          for (const [rec, store] of out) this.writeOutbox(`${dst}/${agent}`, store === void 0 ? wire(rec) : wireOf(rec, store));
+          fs.renameSync(target + ".tmp", target);
+          fs.unlinkSync(this.chainPath(`${src}/${agent}`));
+        })
+      );
+    }
+    return conflicts;
+  }
+  basePath(chain) {
+    return path.join(this.home, "chain", `${chain}.base.json`);
+  }
+  /** The witness's signed head `chain` continues after, when this machine started it on an
+   * empty disk (§8). */
+  chainBase(chain) {
+    return readJson(this.basePath(chain)) ?? void 0;
+  }
+  /** The last record of a local chain, or undefined when it is empty. */
+  lastRecord(chain) {
+    const all = this.readChain(chain);
+    return all[all.length - 1];
+  }
+  mapPath(chain) {
+    return path.join(this.home, "chain", `${chain}.drafts.json`);
+  }
+  draftMap(chain) {
+    return readJson(this.mapPath(chain)) ?? {};
+  }
+  /** A ref to a draft that has since been signed points at the signed record. */
+  translateRef(chain, ref) {
+    if (!ref) return ref ?? null;
+    return this.draftMap(chain)[ref] ?? ref;
+  }
+  // --- blocked chains, held segments ---------------------------------------------
+  /** Chains the witness refused, with why: `{chain: {code, message, at, seq}}` (blocked.json). */
+  blocked() {
+    return readJson(path.join(this.home, "blocked.json")) ?? {};
+  }
+  /** Record (or, with null, clear) why the witness refuses a chain. Never throws (read-only disks). */
+  setBlocked(chain, info) {
+    try {
+      const all = this.blocked();
+      if (info === null) {
+        if (!(chain in all)) return;
+        delete all[chain];
+      } else {
+        const old = all[chain];
+        if (old && old.code === info.code && old.message === info.message && old.seq === info.seq) return;
+        all[chain] = { ...info, at: now() };
+      }
+      writeJson(path.join(this.home, "blocked.json"), all);
+    } catch {
+    }
+  }
+  heldDir(chain) {
+    return path.join(this.home, "held", chain);
+  }
+  /** Every held segment: [chain, file, records]. */
+  heldSegments() {
+    const out = [];
+    for (const chain of depth3(path.join(this.home, "held"))) {
+      for (const f of readdir(this.heldDir(chain)).filter((x) => x.endsWith(".jsonl")).sort()) {
+        const p = path.join(this.heldDir(chain), f);
+        out.push([chain, p, fs.readFileSync(p, "utf8").split("\n").filter((l) => l.trim()).map((l) => parseLine(p, l))]);
+      }
+    }
+    return out;
+  }
+  /** `signafaide repair`: move the chain's records from `fromSeq` to the end (none of them
+   * co-signed) into `held/<chain>/<from>-<to>.jsonl`, and drop them from the outbox. The held
+   * file is written and flushed before the chain file is cut, so a crash never loses a line. */
+  holdTail(chain, fromSeq) {
+    return this.lock(chain, () => {
+      const p = this.chainPath(chain);
+      const cut = [];
+      for (const item of this.reverse(chain)) {
+        if (item[1].envelope.seq < fromSeq) break;
+        if (item[1].receipt) throw new StateError(`${chain} seq ${item[1].envelope.seq} has a receipt: co-signed records are never set aside`);
+        cut.push(item);
+      }
+      cut.reverse();
+      if (!cut.length) throw new StateError(`${chain} has no records from seq ${fromSeq}`);
+      const recs = cut.map((c) => c[1]);
+      const dir = this.heldDir(chain);
+      fs.mkdirSync(dir, { recursive: true });
+      const file = path.join(dir, `${pad(recs[0].envelope.seq)}-${pad(recs[recs.length - 1].envelope.seq)}.jsonl`);
+      const fd = fs.openSync(file + ".tmp", "w", 384);
+      fs.writeSync(fd, recs.map((r) => canonicalize(r) + "\n").join(""));
+      fs.fsyncSync(fd);
+      fs.closeSync(fd);
+      fs.renameSync(file + ".tmp", file);
+      const cfd = fs.openSync(p, "r+");
+      try {
+        fs.ftruncateSync(cfd, cut[0][0]);
+        fs.fsyncSync(cfd);
+      } finally {
+        fs.closeSync(cfd);
+      }
+      this.dropOutbox(chain, recs.map((r) => r.envelope.seq));
+      return { file, records: recs };
+    });
+  }
+  hasDrafts() {
+    return this.chains().some((c) => c.startsWith(PENDING + "/"));
+  }
+  draftCount(chain) {
+    return this.lines(chain).filter((r) => r.draft).length;
+  }
+  // --- keys -------------------------------------------------------------------
+  /** When the key was generated: the `valid_from` sent at registration, so records
+   * signed offline before registering still verify (§2.4). */
+  keyCreated(agent, scope = "") {
+    const given = this.providedKey(agent, scope);
+    if (given) return given.created;
+    try {
+      return JSON.parse(fs.readFileSync(this.keyPath(agent, scope), "utf8")).created;
+    } catch {
+      return void 0;
+    }
+  }
+  retiredDir(scope = "") {
+    return path.join(this.keyDir(scope), "retired");
+  }
+  /** [key, created] of the agent's retired keys, newest first. */
+  retiredKeys(agent, scope = "") {
+    const out = [];
+    for (const f of readdir(this.retiredDir(scope))) {
+      if (!f.startsWith(agent + ".") || !f.endsWith(".key") || f.split(".").length !== 3) continue;
+      try {
+        const doc = JSON.parse(fs.readFileSync(path.join(this.retiredDir(scope), f), "utf8"));
+        if (doc.agent === agent) out.push([new SigningKey(b64urlDecode(doc.private_key)), doc.created]);
+      } catch {
+        throw new StateError(`${path.join(this.retiredDir(scope), f)} is not a valid signafaide key file; restore it from backup`);
+      }
+    }
+    return out.sort((a, b) => a[1] < b[1] ? 1 : a[1] > b[1] ? -1 : 0);
+  }
+  /** When the service retired this key (§2.4 rotation), once it said so; null before. */
+  retiredAt(agent, keyId, scope = "") {
+    try {
+      const v = JSON.parse(fs.readFileSync(path.join(this.retiredDir(scope), `${agent}.${keyId}.key`), "utf8")).retired;
+      return typeof v === "string" && validTime(v) ? v : null;
+    } catch {
+      return null;
+    }
+  }
+  /** Record the service's retirement time in a retired key's file (kept for keys export). */
+  markRetired(agent, keyId, validTo, scope = "") {
+    const p = path.join(this.retiredDir(scope), `${agent}.${keyId}.key`);
+    if (!AGENT_RE.test(agent) || !validTime(validTo) || !/^[0-9a-f]{16}$/.test(keyId) || !fs.existsSync(p)) return false;
+    const doc = JSON.parse(fs.readFileSync(p, "utf8"));
+    if (doc.retired === validTo) return false;
+    doc.retired = validTo;
+    const tmp = p + ".tmp";
+    fs.writeFileSync(tmp, canonicalize(doc) + "\n", { mode: 384 });
+    fs.renameSync(tmp, p);
+    return true;
+  }
+  /** Retire the agent's key and make a new one: [old, new]. The next registration is
+   * signed by the old key (§2.4 rotation). */
+  rotateKey(agent, scope = "") {
+    if (!AGENT_RE.test(agent)) throw new StateError(`agent "${agent}" is invalid`);
+    if (this.providedKey(agent, scope)) {
+      throw new StateError(`agent ${agent}'s key comes from ${agentKeyEnvName(agent, scope)} (or a key provider): make a new key with \`signafaide keys rotate\` on a machine with the key file, store the new file in your secret store, and keep the old one as ${agent}.<key id>.key in .signafaide/agents/${scope ? scope + "/" : ""}retired/`);
+    }
+    const old = this.loadKey(agent, false, scope);
+    if (!old) throw new StateError(`agent ${agent} has no key to rotate; it gets one with its first record, or make one for a secret store with \`signafaide keys create --agent ${agent} --env ${scope === "live" ? "live" : "test"} --print\``);
+    fs.mkdirSync(this.retiredDir(scope), { recursive: true });
+    fs.renameSync(this.keyPath(agent, scope), path.join(this.retiredDir(scope), `${agent}.${old.keyId}.key`));
+    return [old, this.loadKey(agent, true, scope)];
+  }
+  /** A new agent key file `{agent, key_id, public_key, private_key, created}` (§8), not
+   * written anywhere: `keys create` registers it and prints it for a secret store, or saves it
+   * as the agent's key file with `saveKeyFile`. */
+  newKeyFile(agent) {
+    if (!AGENT_RE.test(agent)) throw new StateError(`agent "${agent}" is invalid`);
+    const key = SigningKey.generate((n) => new Uint8Array(randomBytes(n)));
+    return { key, doc: { agent, key_id: key.keyId, public_key: b64url(key.publicKey), private_key: b64url(key.seed()), created: now() } };
+  }
+  /** Write a key file made by `newKeyFile` as the agent's key (mode 0600); never replaces one. */
+  saveKeyFile(doc, scope = "") {
+    this.ensure();
+    const p = this.keyPath(doc.agent, scope);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    let fd;
+    try {
+      fd = fs.openSync(p, "wx", 384);
+    } catch (e) {
+      if (e.code === "EEXIST") throw new StateError(`agent ${doc.agent} already has a key file (${p}); use \`signafaide keys rotate\` to replace it`);
+      throw fsError(e, this.home);
+    }
+    fs.writeSync(fd, canonicalize(doc) + "\n");
+    fs.closeSync(fd);
+    return p;
+  }
+  /** Every current and retired agent key: `{agent, key_id, public_key, created, retired}`
+   * (`retired`: when the service retired it, or null). */
+  agentPublicKeys() {
+    const out = [];
+    const seen = /* @__PURE__ */ new Set();
+    for (const agent of this.agents()) {
+      for (const scope of ["", "live"]) {
+        const k = this.loadKey(agent, false, scope);
+        if (k && !seen.has(k.keyId)) {
+          seen.add(k.keyId);
+          out.push({ agent, key_id: k.keyId, public_key: b64url(k.publicKey), created: this.keyCreated(agent, scope) ?? now(), retired: null });
+        }
+        for (const [rk, created] of this.retiredKeys(agent, scope)) {
+          if (seen.has(rk.keyId)) continue;
+          seen.add(rk.keyId);
+          out.push({ agent, key_id: rk.keyId, public_key: b64url(rk.publicKey), created, retired: this.retiredAt(agent, rk.keyId, scope) });
+        }
+      }
+    }
+    return out;
+  }
+  /** The §2.5 manifest of every current and retired key, each entry self-signed. */
+  exportAgentKeys() {
+    const keys2 = [];
+    const seen = /* @__PURE__ */ new Set();
+    for (const agent of this.agents()) {
+      for (const scope of ["", "live"]) {
+        const k = this.loadKey(agent, false, scope);
+        if (k && !seen.has(k.keyId)) {
+          seen.add(k.keyId);
+          keys2.push(manifestEntry(agent, k, this.keyCreated(agent, scope) ?? now()));
+        }
+        for (const [rk, created] of this.retiredKeys(agent, scope)) {
+          if (seen.has(rk.keyId)) continue;
+          seen.add(rk.keyId);
+          keys2.push(manifestEntry(agent, rk, created, this.retiredAt(agent, rk.keyId, scope)));
+        }
+      }
+    }
+    return { format: AGENT_KEYS_FORMAT, keys: keys2 };
+  }
+  /** `createdAt`: for a key made now to sign records written earlier (drafts signed into a live
+   * chain), its creation time, so it is valid from the first of them (§2.4). */
+  loadKey(agent, create = true, scope = "", createdAt) {
+    const given = this.providedKey(agent, scope);
+    if (given) {
+      try {
+        return new SigningKey(b64urlDecode(given.private_key));
+      } catch (e) {
+        throw new StateError(`the key given for agent ${agent} (${agentKeyEnvName(agent, scope)}) is not a valid key (${e.message})`);
+      }
+    }
+    const p = this.keyPath(agent, scope);
+    if (!fs.existsSync(p)) {
+      if (!create) return null;
+      this.ensure();
+      const key = SigningKey.generate((n) => new Uint8Array(randomBytes(n)));
+      const t = now();
+      const doc = { agent, key_id: key.keyId, public_key: b64url(key.publicKey), private_key: b64url(key.seed()), created: createdAt && validTime(createdAt) && createdAt < t ? createdAt : t };
+      let fd;
+      try {
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fd = fs.openSync(p, "wx", 384);
+      } catch (e) {
+        if (e.code === "EEXIST") return this.loadKey(agent, false, scope);
+        throw fsError(e, this.home);
+      }
+      fs.writeSync(fd, canonicalize(doc) + "\n");
+      fs.closeSync(fd);
+      return key;
+    }
+    try {
+      return new SigningKey(b64urlDecode(JSON.parse(fs.readFileSync(p, "utf8")).private_key));
+    } catch (e) {
+      throw new StateError(`${p} is not a valid signafaide key file (${e.message}); restore it from backup`);
+    }
+  }
+  // --- locking ----------------------------------------------------------------
+  lock(chain, fn) {
+    return this.lockAt(path.join(this.home, "chain", `${chain}.lock`), () => {
+      this.recover(chain);
+      return fn();
+    });
+  }
+  /** Hold the lock file `p` (§8 chain locks) while `fn` runs. */
+  lockAt(p, fn) {
+    try {
+      fs.mkdirSync(path.dirname(p), { recursive: true });
+    } catch (e) {
+      throw fsError(e, this.home);
+    }
+    const deadline = monotonicMs() + LOCK_WAIT_MS;
+    for (; ; ) {
+      try {
+        const fd = fs.openSync(p, "wx", 384);
+        fs.writeSync(fd, lockStamp());
+        fs.closeSync(fd);
+        break;
+      } catch (e) {
+        if (e.code !== "EEXIST") throw fsError(e, this.home);
+        try {
+          if (lockAgeMs(p) > LOCK_STALE_MS) {
+            fs.unlinkSync(p);
+            continue;
+          }
+        } catch {
+          continue;
+        }
+        if (monotonicMs() > deadline) throw new StateError(`${p} is held by another process; delete it if no signafaide process is running`);
+        sleepSync(2);
+      }
+    }
+    try {
+      return fn();
+    } finally {
+      try {
+        fs.unlinkSync(p);
+      } catch {
+      }
+    }
+  }
+  /** Finish an interrupted receipt rewrite (journal `.tail`). */
+  recover(chain) {
+    const file = this.chainPath(chain);
+    const journal = file + ".tail";
+    if (!fs.existsSync(journal)) return;
+    const buf = fs.readFileSync(journal);
+    const nl = buf.indexOf(10);
+    const offset = Number(buf.subarray(0, nl).toString());
+    const fd = fs.openSync(file, "r+");
+    try {
+      fs.ftruncateSync(fd, offset);
+      fs.writeSync(fd, buf.subarray(nl + 1), 0, buf.length - nl - 1, offset);
+      fs.fsyncSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+    fs.unlinkSync(journal);
+  }
+  // --- chain ------------------------------------------------------------------
+  /** [seq, record_hash, time] of the last record in the local chain (the last sealed segment's
+   * when the chain file was just rolled), [0, null, null] if empty. */
+  tail(chain) {
+    for (const [, rec] of this.reverse(chain)) return [rec.envelope.seq, recordHash(rec), rec.envelope.time];
+    const segs = this.segments(chain);
+    if (segs.length) {
+      const lines = fs.readFileSync(segs[segs.length - 1], "utf8").split("\n").filter((l) => l.trim());
+      if (lines.length) {
+        const rec = parseLine(segs[segs.length - 1], lines[lines.length - 1]);
+        return [rec.envelope.seq, recordHash(rec), rec.envelope.time];
+      }
+    }
+    return [0, null, null];
+  }
+  segmentDir(chain) {
+    return path.join(this.home, "chain", `${chain}.segments`);
+  }
+  /** Sealed segments of a chain, oldest first. */
+  segments(chain) {
+    const d = this.segmentDir(chain);
+    return readdir(d).filter((f) => f.endsWith(".jsonl")).sort().map((f) => path.join(d, f));
+  }
+  /** Roll a large chain file into a sealed segment, under the chain lock. Only a fully shipped
+   * file rolls (its last line has a receipt), so receipts are never written into a segment. */
+  maybeRoll(chain) {
+    const p = this.chainPath(chain);
+    let size = 0;
+    try {
+      size = fs.statSync(p).size;
+    } catch {
+      return;
+    }
+    if (size < SEGMENT_BYTES()) return;
+    let last;
+    for (const [, rec] of this.reverse(chain)) {
+      last = rec;
+      break;
+    }
+    if (!last?.receipt) return;
+    const firstLine = fs.readFileSync(p, "utf8").split("\n", 1)[0];
+    const first = parseLine(p, firstLine);
+    fs.mkdirSync(this.segmentDir(chain), { recursive: true });
+    fs.renameSync(p, path.join(this.segmentDir(chain), `${pad(first.envelope.seq)}-${pad(last.envelope.seq)}.jsonl`));
+    fs.writeFileSync(p, "");
+  }
+  /** Under the chain lock: build the next record from (seq, prev), append it to the chain
+   * and put `wire(record)` in the outbox. Returns null when `stillValid()` is false once
+   * the lock is held (the chain was just moved under its project; resolve it again). */
+  append(chain, build, wire, stillValid = () => true) {
+    return this.appendRun(chain, [build], wire, stillValid)?.[0] ?? null;
+  }
+  /** `append` for several records that must follow each other with nothing between them (a tool
+   * declaration, §2.6): all of them are built and written under one hold of the chain lock, in
+   * one write, so no other writer's record lands inside the run. */
+  appendRun(chain, builds, wire, stillValid = () => true) {
+    this.ensure();
+    return this.lock(chain, () => {
+      if (!stillValid()) return null;
+      let [seq, prev, prevTime] = this.tail(chain);
+      const recs = [];
+      for (const build of builds) {
+        const rec = build(seq + 1, prev, prevTime);
+        recs.push(rec);
+        [seq, prev, prevTime] = [rec.envelope.seq, recordHash(rec), rec.envelope.time];
+      }
+      try {
+        fs.appendFileSync(this.chainPath(chain), recs.map((r) => canonicalize(r) + "\n").join(""));
+      } catch (e) {
+        throw fsError(e, this.home);
+      }
+      for (const rec of recs) if (!rec.draft) this.writeOutbox(chain, wire(rec));
+      return recs;
+    });
+  }
+  // --- tool declarations --------------------------------------------------------
+  /** `tools/<agent>.json` (§8): the tools each source (the SDK in an application, each gateway)
+   * last declared for the agent. */
+  toolsPath(agent) {
+    return path.join(this.home, "tools", `${agent}.json`);
+  }
+  /** The tools every source last declared for `agent`: source -> {tool name: recorded}. */
+  toolSources(agent) {
+    return Object.fromEntries(Object.entries(this.toolEntries(agent)).map(([src, e]) => [src, e.tools]));
+  }
+  /** The entries of `tools/<agent>.json`: source -> when it last declared or refreshed, and its tools. */
+  toolEntries(agent) {
+    const doc = readJson(this.toolsPath(agent));
+    const out = {};
+    const sources = doc?.sources;
+    if (!sources || typeof sources !== "object" || Array.isArray(sources)) return out;
+    for (const [src, entry] of Object.entries(sources)) {
+      const tools = entry?.tools;
+      if (!tools || typeof tools !== "object" || Array.isArray(tools)) continue;
+      out[src] = { at: typeof entry.at === "string" ? entry.at : "", tools: Object.fromEntries(Object.entries(tools).filter(([, v]) => typeof v === "boolean")) };
+    }
+    return out;
+  }
+  /** A source that ends cleanly takes its own entry out of `tools/<agent>.json`, so the next
+   * declaration by any source no longer counts its tools (§8). Nothing is written to the chain. */
+  releaseToolSource(agent, source) {
+    const file = this.toolsPath(agent);
+    if (!fs.existsSync(file)) return;
+    this.lockAt(path.join(this.home, "tools", `${agent}.lock`), () => {
+      const entries = this.toolEntries(agent);
+      if (!(source in entries)) return;
+      delete entries[source];
+      writeJson(file, { sources: entries });
+    });
+  }
+  /** Set the tools `source` declares for `agent` and call `write` with the agent's whole tool
+   * list: the union over every source, a tool recorded when any source records it (§8). Held
+   * under `tools/<agent>.lock`, so two sources never write declarations that miss each other's
+   * tools. The source's own entry gets the time `nowMs`; another source's entry not refreshed for
+   * `TOOL_SOURCE_MAX_AGE_MS` is dropped (that source has stopped), and `expired` tells `write`
+   * whether dropping changed the agent's tool list. The file is updated only when `write` returns. */
+  declareTools(agent, source, tools, write, nowMs = Date.now()) {
+    this.ensure();
+    const file = this.toolsPath(agent);
+    return this.lockAt(path.join(this.home, "tools", `${agent}.lock`), () => {
+      const union = (entries) => {
+        const all2 = {};
+        for (const src of Object.keys(entries).sort()) for (const [name, recorded] of Object.entries(entries[src].tools)) all2[name] = all2[name] === true || recorded;
+        return all2;
+      };
+      const sorted = (all2) => JSON.stringify(Object.keys(all2).sort().map((n) => [n, all2[n]]));
+      const held = { ...this.toolEntries(agent), [source]: { at: new Date(nowMs).toISOString(), tools } };
+      const live = Object.fromEntries(
+        Object.entries(held).filter(([src, e]) => {
+          const at = Date.parse(e.at);
+          return src === source || Number.isFinite(at) && nowMs - at <= TOOL_SOURCE_MAX_AGE_MS;
+        })
+      );
+      const all = union(live);
+      const out = write(all, sorted(all) !== sorted(union(held)));
+      try {
+        writeJson(file, { sources: live });
+      } catch (e) {
+        throw fsError(e, this.home);
+      }
+      return out;
+    });
+  }
+  writeOutbox(chain, rec) {
+    const d = this.outboxDir(chain);
+    fs.mkdirSync(d, { recursive: true });
+    const tmp = path.join(d, `.${pad(rec.envelope.seq)}.tmp`);
+    fs.writeFileSync(tmp, canonicalize(rec));
+    fs.renameSync(tmp, path.join(d, `${pad(rec.envelope.seq)}.json`));
+  }
+  lines(chain) {
+    const out = [];
+    for (const p of [...this.segments(chain), this.chainPath(chain)]) {
+      if (!fs.existsSync(p)) continue;
+      for (const l of fs.readFileSync(p, "utf8").split("\n")) if (l.trim()) out.push(parseLine(p, l));
+    }
+    return out;
+  }
+  /** Every line of a chain, drafts included (§8). */
+  readAll(chain) {
+    return this.lines(chain);
+  }
+  /** The signed records of a chain (drafts are skipped: they are not signed yet). */
+  readChain(chain) {
+    return this.lines(chain).filter((r) => !r.draft);
+  }
+  /** Lines from the end of the chain file: [offset, record]. */
+  *reverse(chain) {
+    const p = this.chainPath(chain);
+    let fd;
+    try {
+      fd = fs.openSync(p, "r");
+    } catch {
+      return;
+    }
+    try {
+      let pos = fs.fstatSync(fd).size;
+      let buf = Buffer.alloc(0);
+      while (pos > 0) {
+        const n = Math.min(65536, pos);
+        pos -= n;
+        const chunk = Buffer.alloc(n);
+        fs.readSync(fd, chunk, 0, n, pos);
+        buf = Buffer.concat([chunk, buf]);
+        const parts = [];
+        let start = 0;
+        for (let i = buf.indexOf(10); i !== -1; i = buf.indexOf(10, start)) {
+          parts.push(buf.subarray(start, i));
+          start = i + 1;
+        }
+        parts.push(buf.subarray(start));
+        const head = parts.shift();
+        let off = pos + head.length + 1;
+        const complete = parts.map((ln) => {
+          const item = [off, ln];
+          off += ln.length + 1;
+          return item;
+        });
+        buf = Buffer.from(head);
+        for (const [o, ln] of complete.reverse()) if (ln.toString().trim()) yield [o, parseLine(p, ln.toString())];
+      }
+      if (buf.toString().trim()) yield [0, parseLine(p, buf.toString())];
+    } finally {
+      fs.closeSync(fd);
+    }
+  }
+  /** Fill receipts into the trailing chain lines that lack one. Returns how many were filled. */
+  applyReceipts(chain, receipts) {
+    const p = this.chainPath(chain);
+    if (!fs.existsSync(p)) return 0;
+    return this.lock(chain, () => {
+      const suffix = [];
+      for (const item of this.reverse(chain)) {
+        if (item[1].receipt) break;
+        suffix.push(item);
+      }
+      suffix.reverse();
+      let filled = 0;
+      const out = suffix.map(([, rec]) => {
+        const r = receipts.get(recordHash(rec));
+        if (r) {
+          rec.receipt = r;
+          filled++;
+        }
+        return canonicalize(rec) + "\n";
+      });
+      if (filled) {
+        const journal = p + ".tail";
+        const tmp = p + ".tail.tmp";
+        const fd = fs.openSync(tmp, "w");
+        fs.writeSync(fd, `${suffix[0][0]}
+` + out.join(""));
+        fs.fsyncSync(fd);
+        fs.closeSync(fd);
+        fs.renameSync(tmp, journal);
+        this.recover(chain);
+        this.maybeRoll(chain);
+      }
+      return filled;
+    });
+  }
+  /** Re-queue chain records that have neither a receipt nor an outbox file
+   * (a crash between the chain write and the outbox write). */
+  reconcileOutbox(chain, wire) {
+    if (!fs.existsSync(this.chainPath(chain))) return 0;
+    return this.lock(chain, () => {
+      let n = 0;
+      for (const [, rec] of this.reverse(chain)) {
+        if (rec.receipt || rec.draft) break;
+        if (!fs.existsSync(path.join(this.outboxDir(chain), `${pad(rec.envelope.seq)}.json`))) {
+          this.writeOutbox(chain, wire(rec));
+          n++;
+        }
+      }
+      return n;
+    });
+  }
+  // --- outbox -----------------------------------------------------------------
+  outbox(chain, limit = 1e3) {
+    const d = this.outboxDir(chain);
+    const out = [];
+    for (const f of readdir(d).filter((f2) => f2.endsWith(".json")).sort().slice(0, limit)) {
+      try {
+        out.push(JSON.parse(fs.readFileSync(path.join(d, f), "utf8")));
+      } catch (e) {
+        if (e.code !== "ENOENT") throw e;
+      }
+    }
+    return out;
+  }
+  dropOutbox(chain, seqs) {
+    for (const s of seqs) fs.rmSync(path.join(this.outboxDir(chain), `${pad(s)}.json`), { force: true });
+  }
+  /** Chains with records waiting, optionally only those under `prefix` (a bucket). */
+  outboxChains(prefix) {
+    const d = path.join(this.home, "outbox");
+    return depth3(d).filter((c) => readdir(path.join(d, c)).some((f) => f.endsWith(".json")) && (!prefix || c.startsWith(prefix + "/"))).sort();
+  }
+  /** Records waiting: everything, a bucket (`<project>/<env>`) or one chain. */
+  outboxSize(prefix) {
+    const d = path.join(this.home, "outbox");
+    return depth3(d).filter((c) => !prefix || `${c}/`.startsWith(prefix + "/")).reduce((n, c) => n + readdir(path.join(d, c)).filter((f) => f.endsWith(".json")).length, 0);
+  }
+  // --- heads, sandbox ---------------------------------------------------------
+  /** `{project: {env: {agent: {head, head_sig}}}}`. */
+  heads() {
+    return readJson(path.join(this.home, "head.json")) ?? {};
+  }
+  /** The newest signed head per chain id `<project>/<env>/<agent>`. */
+  chainHeads() {
+    const out = {};
+    for (const [p, envs] of Object.entries(this.heads())) for (const [e, agents] of Object.entries(envs)) for (const [a, sh] of Object.entries(agents)) out[`${p}/${e}/${a}`] = sh;
+    return out;
+  }
+  /** Keep the newest head per (project, env, agent). Returns warnings for heads that go
+   * backwards (the service showing a shorter chain = truncation). */
+  updateHeads(signed) {
+    const warnings = [];
+    const heads = this.heads();
+    for (const sh of signed) {
+      const { project = "", env = "", agent } = sh.head ?? {};
+      const slot = (heads[project] ??= {})[env] ??= {};
+      const old = slot[agent]?.head;
+      if (old && (sh.head.seq ?? 0) < (old.seq ?? 0)) {
+        warnings.push(`service head for ${agent} went back from seq ${old.seq} to ${sh.head.seq}: keep .signafaide/head.json, it proves truncation`);
+        continue;
+      }
+      slot[agent] = sh;
+    }
+    writeJson(path.join(this.home, "head.json"), heads);
+    if (this.headFile) warnings.push(...this.persistHeads(signed));
+    return warnings;
+  }
+  /** `SIGNAFAIDE_HEAD_FILE` (or `RecorderOptions.headFile`): a copy of the newest signed heads
+   * kept outside this folder (a persistent volume, a mounted bucket), in the `head.json` format,
+   * so an ephemeral container's heads outlive it. Several processes may share one file: each
+   * merges its heads in under `<file>.lock`, keeping the higher seq per chain. */
+  headFile;
+  persistHeads(signed) {
+    const file = this.headFile;
+    try {
+      fs.mkdirSync(path.dirname(path.resolve(file)), { recursive: true });
+      return this.lockAt(file + ".lock", () => {
+        const doc = readJson(file) ?? {};
+        for (const sh of signed) {
+          const { project = "", env = "", agent } = sh.head ?? {};
+          const slot = (doc[project] ??= {})[env] ??= {};
+          if ((slot[agent]?.head?.seq ?? 0) <= (sh.head.seq ?? 0)) slot[agent] = sh;
+        }
+        writeJson(file, doc);
+        return [];
+      });
+    } catch (e) {
+      return [`could not write the head file ${file} (SIGNAFAIDE_HEAD_FILE): ${e.message}`];
+    }
+  }
+  /** `config.json`: settings kept with the project (the coding agent that set it up). */
+  config() {
+    return readJson(path.join(this.home, "config.json")) ?? {};
+  }
+  saveConfig(values) {
+    this.ensure();
+    try {
+      writeJson(path.join(this.home, "config.json"), { ...this.config(), ...values });
+    } catch (e) {
+      throw fsError(e, this.home);
+    }
+  }
+  sandbox() {
+    return readJson(path.join(this.home, "sandbox.json"));
+  }
+  saveSandbox(info) {
+    this.ensure();
+    writeJson(path.join(this.home, "sandbox.json"), info);
+  }
+};
+function parseLine(p, line) {
+  try {
+    const rec = JSON.parse(line);
+    if (typeof rec.envelope.seq !== "number") throw new Error();
+    return rec;
+  } catch {
+    throw new StateError(`${p} has a damaged line; move that line aside and run \`signafaide verify\``);
+  }
+}
+function depth3(d) {
+  return readdir(d).flatMap((a) => readdir(path.join(d, a)).flatMap((b) => readdir(path.join(d, a, b)).filter((c) => !c.endsWith(".segments")).map((c) => `${a}/${b}/${c}`)));
+}
+function readdir(d) {
+  try {
+    return fs.readdirSync(d);
+  } catch {
+    return [];
+  }
+}
+function readJson(p) {
+  let text;
+  try {
+    text = fs.readFileSync(p, "utf8");
+  } catch {
+    return null;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new StateError(`${p} is not valid JSON; fix or delete it`);
+  }
+}
+function writeJson(p, value) {
+  const sorted = (v) => Array.isArray(v) ? v.map(sorted) : v && typeof v === "object" ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, sorted(v[k])])) : v;
+  fs.writeFileSync(p + ".tmp", JSON.stringify(sorted(value), null, 2) + "\n");
+  fs.renameSync(p + ".tmp", p);
+}
+function ensureGitignore(p, entry) {
+  const text = fs.existsSync(p) ? fs.readFileSync(p, "utf8") : "";
+  const bare = entry.replace(/^\/+|\/+$/g, "");
+  if (text.split(/\r?\n/).some((l) => l.trim().replace(/^\/+|\/+$/g, "") === bare)) return;
+  fs.writeFileSync(p, text + (text && !text.endsWith("\n") ? "\n" : "") + entry + "\n");
+}
+function readEnvFile(p) {
+  const out = {};
+  let text;
+  try {
+    text = fs.readFileSync(p, "utf8");
+  } catch {
+    return out;
+  }
+  for (let line of text.split(/\r?\n/)) {
+    line = line.trim();
+    if (!line || line.startsWith("#") || !line.includes("=")) continue;
+    let k = line.slice(0, line.indexOf("=")).trim();
+    let v = line.slice(line.indexOf("=") + 1).trim();
+    if (k.startsWith("export ")) k = k.slice(7).trim();
+    if (v.length >= 2 && v[0] === v[v.length - 1] && (v[0] === '"' || v[0] === "'")) v = v.slice(1, -1);
+    out[k] = v;
+  }
+  return out;
+}
+function appendEnvFile(p, key, value) {
+  if (/[\r\n\0]/.test(value) || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) throw new StateError(`refusing to write ${key} to ${p}: the value is not a single line`);
+  let link = false;
+  try {
+    link = fs.lstatSync(p).isSymbolicLink();
+  } catch {
+  }
+  if (link) throw new StateError(`refusing to write ${p}: it is a symbolic link`);
+  const text = fs.existsSync(p) ? fs.readFileSync(p, "utf8") : "";
+  fs.appendFileSync(p, (text && !text.endsWith("\n") ? "\n" : "") + `${key}=${value}
+`, { mode: 384 });
+  try {
+    fs.chmodSync(p, 384);
+  } catch {
+  }
+}
+function wireOf(rec, store) {
+  const out = { envelope: rec.envelope, key_id: rec.key_id, sig: rec.sig };
+  if (store && rec.content !== void 0) {
+    out.content = rec.content;
+    if (rec.salt !== void 0) out.salt = rec.salt;
+  }
+  return out;
+}
+
+// src/runtime.ts
+var BATCH_MAX = 1e3;
+var KEY_MAX_AGE_MS = 7 * 864e5 - 36e5;
+var LOCAL_CODES = /* @__PURE__ */ new Set(["too_old", "chain_exists"]);
+var noWrites = new AsyncLocalStorage();
+function recordingDisabled(env = process.env) {
+  return /^(1|true|yes)$/i.test((env.SIGNAFAIDE_DISABLED ?? "").trim());
+}
+function testMode(env = process.env) {
+  const v = (env.SIGNAFAIDE_TEST ?? "").trim();
+  if (v) return /^(1|true|yes)$/i.test(v);
+  return !!(env.VITEST || env.JEST_WORKER_ID || env.NODE_TEST_CONTEXT);
+}
+var testHomes = /* @__PURE__ */ new Set();
+function removeAtExit(dir) {
+  if (!testHomes.size) process.once("exit", () => testHomes.forEach((d) => fs2.rmSync(d, { recursive: true, force: true })));
+  testHomes.add(dir);
+}
+var Recorder = class {
+  state;
+  storeContent;
+  flushIntervalMs;
+  flushSize;
+  quiet;
+  via;
+  exitFlushMs;
+  /** Test mode (see `testMode()`): local only, in a temporary folder. */
+  test;
+  /** A strict-mode tool ran in this process (client header). */
+  strictUsed = false;
+  /** Write a stop note at a clean exit (see `RecorderOptions.instanceStop`). */
+  instanceStop;
+  /** Agents this process wrote records for since its last stop note. */
+  wrote = /* @__PURE__ */ new Set();
+  toldStrict = false;
+  /** `<agent>\n<source>` -> the tool set this recorder last declared for it (§2.6), and the header's hash. */
+  declared = /* @__PURE__ */ new Map();
+  toolTimer;
+  /** @internal */
+  _url;
+  /** @internal */
+  _apiKey;
+  /** `<agent>\n<scope>` -> [key, the key file's identity when loaded] */
+  keys = /* @__PURE__ */ new Map();
+  /** `<api key>\n<agent>\n<key id>` of each key registered by this process: a key rotated
+   * while the process runs (`signafaide keys rotate`) is a new entry, so it gets registered. */
+  registered = /* @__PURE__ */ new Set();
+  reconciled = /* @__PURE__ */ new Set();
+  /** Chains the witness refused, with the configuration they were refused under. */
+  blocked = /* @__PURE__ */ new Map();
+  /** A refusal that applies to every chain (quota, API key): nothing is sent until the configuration changes. */
+  halted;
+  shipping = Promise.resolve();
+  timer;
+  /** Monotonic ms (`monotonicMs`) before which the background shipper waits: a wall-clock step never shortens or stretches the backoff. */
+  nextAttempt = 0;
+  failures = 0;
+  failing;
+  pending = 0;
+  inFlight = false;
+  ioMode = "fg";
+  bgAbort = new AbortController();
+  exitAbort;
+  exitHooked = false;
+  toldLocal = false;
+  toldBadKey = false;
+  exitFlushed = false;
+  closed = false;
+  onHead;
+  constructor(opts = {}) {
+    this.test = testMode();
+    const temp = opts.home === void 0 && this.test && !process.env.SIGNAFAIDE_HOME ? fs2.mkdtempSync(path2.join(os2.tmpdir(), "signafaide-test-")) : void 0;
+    if (temp) removeAtExit(temp);
+    const home = opts.home ?? temp;
+    this.state = State.discover(home, opts.root);
+    this.state.keyProvider = opts.keyProvider;
+    this.state.headFile = opts.headFile || process.env.SIGNAFAIDE_HEAD_FILE || void 0;
+    this.onHead = opts.onHead;
+    const envStop = process.env.SIGNAFAIDE_INSTANCE_STOP;
+    this.instanceStop = envStop === "0" ? false : opts.instanceStop ?? (envStop === "1" || !!this.state.headFile);
+    this._url = opts.url;
+    this._apiKey = opts.apiKey;
+    this.storeContent = opts.storeContent ?? false;
+    this.flushIntervalMs = opts.flushIntervalMs ?? 2e3;
+    this.flushSize = opts.flushSize ?? 100;
+    this.quiet = opts.quiet ?? false;
+    this.via = opts.via ?? "sdk";
+    const envMs = Number(process.env.SIGNAFAIDE_EXIT_FLUSH_MS);
+    this.exitFlushMs = Math.max(0, opts.exitFlushMs ?? (process.env.SIGNAFAIDE_EXIT_FLUSH_MS !== void 0 && Number.isFinite(envMs) ? envMs : 3e3));
+  }
+  // --- configuration ------------------------------------------------------------
+  setting(name) {
+    return process.env[name] || readEnvFile(path2.join(this.state.root, ".env"))[name] || void 0;
+  }
+  get url() {
+    return (this._url || this.setting("SIGNAFAIDE_URL") || DEFAULT_URL).replace(/\/+$/, "");
+  }
+  /** SIGNAFAIDE_API_KEY as set, even when it is not a valid key. */
+  get rawApiKey() {
+    return this._apiKey || this.setting("SIGNAFAIDE_API_KEY");
+  }
+  /** The API key, or undefined: none set, test mode, or not a signafAIde key (checked here, so a
+   * wrong value is never sent anywhere). */
+  get apiKey() {
+    if (this.test) return void 0;
+    const k = this.rawApiKey;
+    if (!k) return void 0;
+    if (!API_KEY_RE.test(k)) {
+      if (!this.toldBadKey && !this.quiet) {
+        this.toldBadKey = true;
+        console.warn(
+          `signafaide: SIGNAFAIDE_API_KEY (${k.slice(0, 8)}...) is not a signafAIde key (sfa_test_ or sfa_live_ and 32 letters or digits); nothing is sent and records stay on this machine. Fix it or remove it.`
+        );
+      }
+      return void 0;
+    }
+    return k;
+  }
+  /** What shipping depends on: when it changes, refused chains are tried again. */
+  configFp() {
+    const stamp = (d) => {
+      try {
+        return String(fs2.statSync(d).mtimeMs);
+      } catch {
+        return "0";
+      }
+    };
+    const dirs = [this.state.keyDir(""), this.state.retiredDir(""), this.state.keyDir("live"), this.state.retiredDir("live")];
+    return [this.url, this.apiKey ?? "", ...dirs.map(stamp)].join("\n");
+  }
+  client(timeoutMs = 1e4, apiKey = this.apiKey) {
+    const mode = this.ioMode;
+    const transport = typeof process !== "undefined" && process.versions?.node ? nodeTransport(() => mode !== "bg") : void 0;
+    const signal = mode === "bg" ? this.bgAbort.signal : mode === "exit" ? this.exitAbort?.signal : void 0;
+    const timeoutLabel = mode === "exit" ? `no answer within the ${this.exitFlushMs / 1e3} s allowed at exit (SIGNAFAIDE_EXIT_FLUSH_MS)` : void 0;
+    return new Client(this.url, apiKey, timeoutMs, this.clientId(), { transport, signal, timeoutLabel });
+  }
+  /** The coding agent stored when the project was set up (`init`, `agent setup`). It is never
+   * guessed per process: a program started from a terminal inside a coding agent is not that agent. */
+  agent() {
+    return this.state.config().agent ?? "unknown";
+  }
+  clientId() {
+    return clientHeader({ via: this.via, adapter: adapterField(), agent: this.agent(), strict: this.strictUsed });
+  }
+  /** Store the detected coding agent in config.json (not when telemetry is off). Only `init`
+   * and `agent setup` call it. */
+  rememberAgent() {
+    const agent = detectAgent();
+    if (telemetryEnabled() && agent !== "unknown" && this.state.config().agent !== agent) this.state.saveConfig({ agent });
+  }
+  /** Fire-and-forget usage event; never throws, skipped when telemetry is off and when there
+   * is no API key (nothing is sent before a human opts in). */
+  async event(name) {
+    if (!telemetryEnabled() || !this.apiKey) return;
+    try {
+      await this.client(2e3).event(name);
+    } catch {
+    }
+  }
+  /** The Terms and Privacy notice links of this project's sandbox (from the service's answer). */
+  legal() {
+    const s = this.state.sandbox();
+    return legalLinks(s ?? {}, s?.url ?? this.url);
+  }
+  /** The one agent with records here, when there is exactly one (replay and compare without
+   * `--agent`). */
+  onlyAgent() {
+    const names = new Set(this.state.chains().map((c) => c.split("/")[2]));
+    return names.size === 1 ? [...names][0] : void 0;
+  }
+  /** The agent name used when none is given: the project folder's name. Give agents explicit
+   * names in production (one per running instance); see the production guide. */
+  get defaultAgent() {
+    return agentName(path2.basename(this.state.root));
+  }
+  /** Return the API key; create a sandbox project if there is none. Only an explicit human
+   * opt-in calls this (`signafaide init`, the MCP `signafaide_init` tool): records never
+   * create a sandbox by themselves. */
+  async createSandbox() {
+    const raw = this.rawApiKey;
+    if (raw && !API_KEY_RE.test(raw)) {
+      throw new SignafaideError(`SIGNAFAIDE_API_KEY (${raw.slice(0, 8)}...) is not a signafAIde key (sfa_test_ or sfa_live_ and 32 letters or digits): fix it, or remove it to create a sandbox.`, { code: "invalid_key" });
+    }
+    const existing = this.apiKey;
+    if (existing) {
+      try {
+        await this.resolveProject(existing);
+      } catch (e) {
+        if (e.code !== "network") throw e;
+      }
+      return existing;
+    }
+    this.rememberAgent();
+    const resp = await this.client().sandbox();
+    if (typeof resp?.api_key !== "string" || !API_KEY_RE.test(resp.api_key) || !resp.api_key.startsWith("sfa_test_") || !validProjectId(resp.project)) {
+      throw new SignafaideError(`The service at ${this.url} answered POST /v1/sandbox with an invalid api_key or project; check SIGNAFAIDE_URL.`, { code: "bad_response" });
+    }
+    this.state.ensure();
+    return this.state.lock("~init", () => {
+      const raced = this.apiKey;
+      if (raced) return raced;
+      const envFile = path2.join(this.state.root, ".env");
+      appendEnvFile(envFile, "SIGNAFAIDE_API_KEY", resp.api_key);
+      if (this.url !== DEFAULT_URL && !readEnvFile(envFile).SIGNAFAIDE_URL) appendEnvFile(envFile, "SIGNAFAIDE_URL", this.url);
+      this.state.ignoreInGit(".env");
+      this.state.learnProject(resp.api_key, resp.project, "test");
+      const legal = legalLinks(resp, this.url);
+      this.state.saveSandbox({ project: resp.project, claim_url: resp.claim_url, free_quota: resp.free_quota, url: this.url, created: now(), ...legal });
+      this._apiKey = resp.api_key;
+      if (!this.quiet) console.error(`signafaide: sandbox ready, key saved to .env; claim it at ${resp.claim_url}. ${termsNotice(legal)}`);
+      return resp.api_key;
+    });
+  }
+  /** Learn the API key's project (`GET /v1/project`) if it is not known yet, so envelopes
+   * can name it (§2.2). Throws SignafaideError when the service cannot say. */
+  async resolveProject(apiKey) {
+    if (!this.state.bucket(apiKey).startsWith(PENDING + "/")) return;
+    const resp = await this.client(1e4, apiKey).project();
+    if (resp?.env !== envOf(apiKey) || !validProjectId(resp?.project)) {
+      throw new SignafaideError(`The service at ${this.url} answered GET /v1/project with an invalid project or env; check SIGNAFAIDE_URL.`, { code: "bad_response" });
+    }
+    this.state.learnProject(apiKey, resp.project, resp.env);
+  }
+  /** Records waiting to ship, drafts included. */
+  waiting() {
+    return this.state.outboxSize() + this.state.chains().filter((c) => c.startsWith(PENDING + "/")).reduce((n, c) => n + this.state.draftCount(c), 0);
+  }
+  // --- writing --------------------------------------------------------------------
+  /** `firstTime`: when a new key must sign records written earlier (drafts), its creation time. */
+  key(agent, scope = "", firstTime) {
+    const stamp = () => {
+      if (this.state.providedKey(agent, scope)) return "provided";
+      try {
+        const s = fs2.statSync(this.state.keyPath(agent, scope), { bigint: true });
+        return `${s.ino}:${s.mtimeNs}:${s.size}`;
+      } catch {
+        return "";
+      }
+    };
+    const id = `${agent}
+${scope}`;
+    const held = this.keys.get(id);
+    const now2 = stamp();
+    if (held && held[1] === now2 && now2) return held[0];
+    const k = this.state.loadKey(agent, true, scope, firstTime);
+    this.keys.set(id, [k, stamp()]);
+    return k;
+  }
+  /** The record's time (§2.2): never earlier than the previous record's or the key's valid_from.
+   * When the clock read earlier, its reading is kept in `meta.wall_time`. */
+  timed(content, prevTime, agent, scope) {
+    const wall = now();
+    const [time, raised] = clampTime(wall, prevTime, this.state.keyCreated(agent, scope) ?? null);
+    return raised ? [time, withWallTime(content, wall)] : [time, content];
+  }
+  /** Sign and chain one record locally (synchronous) and queue it for shipping.
+   * The chain is this API key's `<project>/<env>/<agent>` (§8). */
+  write(kind, name, content, opts = {}) {
+    return this.writeRun([{ kind, name, content, ref: opts.ref }], opts)[0];
+  }
+  /** `write` for records that must follow each other with nothing between them (a tool
+   * declaration, §2.6): they are signed and appended under one hold of the chain lock. */
+  writeRun(items, opts = {}) {
+    const why = noWrites.getStore();
+    if (why) throw new SignafaideError(`${why} must not write records: candidate functions must be side-effect free (it tried to record "${items[0]?.name}")`, { code: "no_writes" });
+    const agent = opts.agent || this.defaultAgent;
+    if (!AGENT_RE.test(agent)) throw new Error(`agent "${agent}" is invalid: use lowercase letters, digits, '.', '_' or '-' (max 64)`);
+    const sc = opts.storeContent ?? this.storeContent;
+    const apiKey = this.apiKey;
+    let recs = null;
+    while (!recs) {
+      const bucket = this.writeBucket(apiKey, agent);
+      const scope = scopeOf(bucket);
+      const key = this.key(agent, scope);
+      const chain = `${bucket}/${agent}`;
+      if (!fs2.existsSync(this.state.chainPath(chain))) for (const e of Object.values(this.adoptInto(bucket, apiKey))) this.report(`signafaide: ${e.message}`);
+      const [project, env] = bucket.split("/");
+      const builds = items.map(
+        ({ kind, name, content, ref }) => bucket.startsWith(PENDING + "/") ? (seq, prev, prevTime) => {
+          const [time, c] = this.timed(content, prevTime, agent, scope);
+          return makeDraft(key, { kind, agent, seq, prev, name, content: c, ref: ref ?? null, time }, sc);
+        } : (seq, prev, prevTime) => {
+          const [time, c] = this.timed(content, prevTime, agent, scope);
+          return makeRecord(key, { kind, project, env, agent, seq, prev, name, content: c, ref: this.state.translateRef(chain, ref), time });
+        }
+      );
+      recs = this.state.appendRun(chain, builds, (r) => wireRecord(r, sc), () => this.writeBucket(apiKey, agent) === bucket);
+    }
+    this.pending += recs.length;
+    this.exitFlushed = false;
+    if (items.some((i) => i.name !== INSTANCE_STOP)) this.wrote.add(agent);
+    if (!apiKey && !this.toldLocal && !this.quiet && !this.test) {
+      this.toldLocal = true;
+      console.error(
+        `signafaide: recording locally in ${this.state.home} (signed and chained; no API key, so nothing is sent). Run \`npx signafaide init\` to send hashes for co-signature and public timestamps, or set SIGNAFAIDE_API_KEY.`
+      );
+    }
+    this.start();
+    if (this.pending >= this.flushSize) void this.tick();
+    return recs;
+  }
+  /** Declare the tools one source knows for an agent (§2.6): a `signafaide.tools` note followed
+   * by one note per tool, written as one run. `source` names who declares (the SDK in this
+   * program, or one gateway); the notes list the agent's whole tool list, the union over every
+   * source that declared on this machine (§8 `tools/<agent>.json`), a tool recorded when any
+   * source records it. Written at most once per recorder for the same set: the first time, and
+   * again when the set changes. Returns the header's record hash. */
+  declareTools(tools, opts) {
+    const agent = opts.agent || this.defaultAgent;
+    if (!AGENT_RE.test(agent)) throw new Error(`agent "${agent}" is invalid: use lowercase letters, digits, '.', '_' or '-' (max 64)`);
+    const names = Object.keys(tools).sort(byCodePoint);
+    const bad = names.find((n) => !n || /[\u0000-\u001f\u007f]/.test(n));
+    if (bad !== void 0) throw new TypeError(`a tool name must be a non-empty string without control characters (got ${JSON.stringify(bad)})`);
+    const id = `${agent}
+${opts.source}`;
+    const sig = JSON.stringify(names.map((n) => [n, tools[n]]));
+    const held = this.declared.get(id);
+    const hash = this.state.declareTools(agent, opts.source, tools, (all, expired) => {
+      if (held?.sig === sig && !expired) return held.hash;
+      const byName = /* @__PURE__ */ new Map();
+      for (const [tool, recorded2] of Object.entries(all)) {
+        const d = declaredName(tool);
+        const prev = byName.get(d);
+        if (!prev || recorded2 && !prev.recorded) byName.set(d, { tool, recorded: recorded2 });
+      }
+      const list = [...byName.keys()].sort(byCodePoint).map((d) => byName.get(d));
+      const recorded = list.filter((t) => t.recorded).length;
+      const items = [
+        { kind: "note", name: TOOLS, content: { source: opts.origin, tools: list.length, recorded, unrecorded: list.length - recorded } },
+        ...list.map((t) => ({ kind: "note", name: toolNoteName(t.tool, t.recorded), content: { tool: t.tool, recorded: t.recorded } }))
+      ];
+      return recordHash(this.writeRun(items, { agent, storeContent: opts.storeContent })[0]);
+    });
+    this.declared.set(id, { sig, hash, agent, source: opts.source, origin: opts.origin, tools, storeContent: opts.storeContent });
+    if (!this.toolTimer && !this.closed) {
+      this.toolTimer = setInterval(() => this.refreshToolSources(), TOOL_SOURCE_REFRESH_MS);
+      this.toolTimer.unref?.();
+    }
+    return hash;
+  }
+  /** Refresh this recorder's entries in `tools/<agent>.json` (§8): each gets the current time,
+   * so other sources keep counting its tools, and entries of sources that stopped more than 24
+   * hours ago drop out. Nothing is written to the chain unless that changed the agent's tool
+   * list. Runs by itself once an hour while the process lives. Never throws. */
+  refreshToolSources() {
+    for (const d of [...this.declared.values()]) {
+      try {
+        this.declareTools(d.tools, { agent: d.agent, source: d.source, origin: d.origin, storeContent: d.storeContent });
+      } catch (e) {
+        this.report(`signafaide: could not refresh the tool list of ${d.agent}: ${e.message}`);
+      }
+    }
+  }
+  /** A clean end of this source (§8): its entries leave `tools/<agent>.json`, so the next
+   * declaration by any source no longer counts its tools. Nothing is written to the chain. With
+   * `source`, only that source ends (a gateway run inside another program). Never throws. */
+  releaseToolSources(source) {
+    for (const [id, d] of [...this.declared]) {
+      if (source !== void 0 && d.source !== source) continue;
+      try {
+        this.state.releaseToolSource(d.agent, d.source);
+      } catch {
+      }
+      this.declared.delete(id);
+    }
+    if (!this.declared.size && this.toolTimer) {
+      clearInterval(this.toolTimer);
+      this.toolTimer = void 0;
+    }
+  }
+  /** Where `agent`'s next record goes. A known project whose chain for `agent` is not on this
+   * disk (an empty `SIGNAFAIDE_HOME` on Lambda or Cloud Run) may already have that chain on the
+   * witness, so the record is a draft until the shipper has asked for the witness's head and
+   * continues after it (§8). Writing never waits for the network. */
+  writeBucket(apiKey, agent) {
+    const bucket = this.state.bucket(apiKey);
+    if (!apiKey || bucket.startsWith(PENDING + "/") || fs2.existsSync(this.state.chainPath(`${bucket}/${agent}`))) return bucket;
+    const nokey = `${PENDING}/nokey`;
+    return fs2.existsSync(this.state.chainPath(`${nokey}/${agent}`)) ? nokey : `${PENDING}/${keyFingerprint(apiKey)}`;
+  }
+  /** Move pending chains (written before the project was known) under `bucket`. Returns the
+   * chains that stay pending, with why (chain id -> error). `bases`: agent -> the service's head,
+   * for a chain whose local file is gone (an ephemeral disk): its drafts continue after it. */
+  adoptInto(bucket, apiKey, bases = {}) {
+    const out = {};
+    if (bucket.startsWith(PENDING + "/")) return out;
+    const sources = [`${PENDING}/nokey`];
+    if (apiKey) sources.push(`${PENDING}/${keyFingerprint(apiKey)}`);
+    const notBefore = new Date(Date.now() - KEY_MAX_AGE_MS).toISOString();
+    const scope = scopeOf(bucket);
+    for (const src of sources) {
+      for (const [chain, why] of this.state.adopt(src, bucket, (a, first) => this.key(a, scope, first), (r) => wireRecord(r, this.storeContent), notBefore, bases)) {
+        const msg = why === "exists" ? `${chain} cannot join ${bucket}, which already has that agent's chain; it stays pending (local only) and still verifies with \`signafaide verify\`` : `${chain} starts at ${why}, more than 7 days ago: the service accepts records up to 7 days old (\xA72.4), so this chain stays local; it still verifies with \`signafaide verify\`. New records of that agent start a new chain under ${bucket}`;
+        out[chain] = new SignafaideError(msg, { code: why === "exists" ? "chain_exists" : "too_old" });
+      }
+    }
+    return out;
+  }
+  /** The service's heads for pending agents that have no local chain under `bucket` yet (an
+   * ephemeral disk lost it): their drafts continue the service's chain instead of conflicting. */
+  async remoteBases(bucket, apiKey) {
+    const out = {};
+    const agents = /* @__PURE__ */ new Set();
+    for (const c of this.state.chains()) {
+      if (!c.startsWith(`${PENDING}/nokey/`) && !c.startsWith(`${PENDING}/${keyFingerprint(apiKey)}/`)) continue;
+      const a = c.split("/")[2];
+      if (!fs2.existsSync(this.state.chainPath(`${bucket}/${a}`))) agents.add(a);
+    }
+    const client = this.client(1e4, apiKey);
+    for (const a of agents) {
+      try {
+        const sh = await client.head(a);
+        const h = sh?.head;
+        if (h && Number.isInteger(h.seq) && h.seq > 0 && /^[0-9a-f]{64}$/.test(h.record_hash) && `${h.project}/${h.env}` === bucket && h.agent === a) {
+          out[a] = { seq: h.seq, record_hash: h.record_hash, signed: { head: h, head_sig: sh.head_sig } };
+          try {
+            const got = (await client.record(h.record_hash))?.record;
+            if (isStopNote(got, a, h.record_hash)) out[a].stop = { envelope: got.envelope, key_id: got.key_id, sig: got.sig };
+          } catch (e) {
+            if (!(e instanceof SignafaideError)) throw e;
+          }
+        }
+      } catch (e) {
+        const code = e.code;
+        if (code !== "not_found" && code !== "unknown_agent") throw e;
+      }
+    }
+    return out;
+  }
+  // --- shipping -------------------------------------------------------------------
+  /** Run shipping work one at a time in this process. */
+  serial(mode, fn) {
+    const run = this.shipping.then(async () => {
+      this.ioMode = mode;
+      try {
+        return await fn();
+      } finally {
+        this.ioMode = "fg";
+      }
+    });
+    this.shipping = run.catch(() => void 0);
+    return run;
+  }
+  /** A label for errors that are about the API key, not a chain. */
+  keyLabel(apiKey) {
+    return `API key ${apiKey.slice(0, 13)}...`;
+  }
+  /** Ship the outbox of this API key's project now. `errors` maps chain id (or the API key, for
+   * errors about the key) to the one-sentence fix. Records of other projects (an earlier key)
+   * wait for that key. An explicit flush always tries, even after a refusal. */
+  flush(timeoutMs = 1e4, mode = "fg") {
+    if (mode === "fg") {
+      this.halted = void 0;
+      this.blocked.clear();
+    }
+    return this.serial(mode, async () => {
+      let shipped = 0;
+      const errors = {};
+      if (!this.state.outboxSize() && !this.state.hasDrafts()) return { shipped, left: 0, errors };
+      const key = this.apiKey;
+      if (!key) return { shipped, left: this.waiting(), errors };
+      const apiKey = key;
+      let bases = {};
+      try {
+        await this.resolveProject(apiKey);
+        const bucket = this.state.bucket(apiKey);
+        if (this.state.hasDrafts()) bases = await this.remoteBases(bucket, apiKey);
+      } catch (e) {
+        if (!(e instanceof SignafaideError) && !(e instanceof StateError)) throw e;
+        const err = e instanceof SignafaideError ? e : new SignafaideError(e.message, { code: "state" });
+        return { shipped, left: this.waiting(), errors: { [this.keyLabel(apiKey)]: err } };
+      }
+      const done = /* @__PURE__ */ new Set();
+      for (; ; ) {
+        const bucket = this.state.bucket(apiKey);
+        Object.assign(errors, this.adoptInto(bucket, apiKey, bases));
+        bases = {};
+        const next = this.state.outboxChains(bucket).find((c) => !done.has(c));
+        if (!next) break;
+        done.add(next);
+        try {
+          shipped += (await this.shipChain(next, apiKey, timeoutMs)).size;
+        } catch (e) {
+          if (!(e instanceof SignafaideError)) throw e;
+          const projectWide = e.retryable || e.code === "invalid_key" || e.code === "quota_exceeded" || e.code === "plan_required";
+          errors[e.code === "invalid_key" ? this.keyLabel(apiKey) : next] = e;
+          if (projectWide) break;
+        }
+      }
+      return { shipped, left: this.waiting(), errors };
+    });
+  }
+  /** A clean stop (§8): ship everything, then write and ship a signed stop note for each agent
+   * this process wrote records for. The next instance's start right after it is a clean restart,
+   * with no "earlier unsent records are not known" warning. Nothing is written while any record
+   * is still unsent (the next start then carries the warning, as it should). Call it in the
+   * shutdown handler of an ephemeral container (SIGTERM); a program that ends by itself with a
+   * head file set does it at exit. */
+  async stop(timeoutMs = 1e4, mode = "fg") {
+    const first = await this.flush(timeoutMs, mode);
+    const apiKey = this.apiKey;
+    const stopped = [];
+    if (this.test || !apiKey || first.left || Object.keys(first.errors).length) return { ...first, stopped };
+    const bucket = this.state.bucket(apiKey);
+    if (bucket.startsWith(PENDING + "/")) return { ...first, stopped };
+    for (const agent of [...this.wrote].sort()) {
+      const chain = `${bucket}/${agent}`;
+      const last = this.state.lastRecord(chain);
+      if (!last || !("receipt" in last) || last.envelope.kind === "note" && last.envelope.name === INSTANCE_STOP) continue;
+      this.write("note", INSTANCE_STOP, instanceStopContent(last.envelope.seq, recordHash(last)), { agent });
+      stopped.push(chain);
+    }
+    this.wrote.clear();
+    if (!stopped.length) return { ...first, stopped };
+    const second = await this.flush(timeoutMs, mode);
+    return { shipped: first.shipped + second.shipped, left: second.left, errors: second.errors, stopped: second.left ? [] : stopped };
+  }
+  /** One stderr line, the first time a strict tool is refused in this process (frameworks often
+   * swallow the tool's error): the tool, why, and the fix. */
+  warnStrictRefused(tool, err) {
+    if (this.toldStrict) return;
+    this.toldStrict = true;
+    const fix = err.code === "no_key" ? "there is no API key, and strict mode needs the witness's receipt. Fix: run `npx signafaide init` (a free sandbox) or set SIGNAFAIDE_API_KEY, or drop strict for this tool" : err.message;
+    console.warn(`signafaide: WARNING strict tool "${tool}" was refused and did not run (${err.code}): ${fix}. Later strict refusals in this process are not printed again.`);
+  }
+  /** Strict mode: ship `rec`'s chain now and return its receipt, or throw. */
+  ensureReceipt(rec, timeoutMs = 1e4) {
+    this.strictUsed = true;
+    return this.serial("fg", async () => {
+      const apiKey = this.apiKey;
+      if (!apiKey) {
+        throw new SignafaideError(
+          "Strict mode needs the service's receipt, and there is no API key: run `npx signafaide init` (a free sandbox) or set SIGNAFAIDE_API_KEY.",
+          { code: "no_key" }
+        );
+      }
+      await this.resolveProject(apiKey);
+      const bucket = this.state.bucket(apiKey);
+      this.adoptInto(bucket, apiKey, this.state.hasDrafts() ? await this.remoteBases(bucket, apiKey) : {});
+      const h = this.state.translateRef(`${bucket}/${rec.envelope.agent}`, recordHash(rec));
+      const got = (await this.shipChain(`${bucket}/${rec.envelope.agent}`, apiKey, timeoutMs)).get(h);
+      if (!got) throw new SignafaideError(`The service did not return a receipt for record ${h.slice(0, 12)}; check \`signafaide status\`.`, { code: "not_recorded" });
+      this.adoptInto(this.state.bucket(apiKey), apiKey);
+      return got;
+    });
+  }
+  /** The witness's refusal, in words that say what happened and what to do. */
+  explain(e, chain, keyId, current2) {
+    const agent = chain.split("/")[2];
+    let msg = `${e.message} (chain ${chain})`;
+    if (e.code === "bad_signature" && /revoked|retired/.test(e.message)) {
+      const scope = scopeOf(chain.split("/").slice(0, 2).join("/"));
+      msg = keyId === current2 ? this.state.providedKey(agent, scope) ? `${chain}: agent key ${keyId} was revoked, so the witness refuses every record it signs. Put a new key for ${agent} in ${agentKeyEnvName(agent, scope)} (or your key provider), then run \`signafaide repair --agent ${agent}\`: it sets aside the records the revoked key signed after it ended, kept on this machine and still verifiable.` : `${chain}: agent key ${keyId} was revoked, so the witness refuses every record it signs. Run \`signafaide repair --agent ${agent}\`: it sets aside the records the revoked key signed after it ended, kept on this machine and still verifiable, and gives the agent a new key.` : `${chain}: records signed by agent key ${keyId} after it was revoked or retired cannot be co-signed, and new records wait behind them. Run \`signafaide repair --agent ${agent}\`: it sets them aside (kept on this machine, still verifiable) so the new key's records ship.`;
+    } else if (/signafaide repair/.test(e.message)) {
+      msg = `${e.message} (chain ${chain})`;
+    } else if (/ahead of the service clock|must not be in the future/.test(e.message)) {
+      msg = `${e.message} (chain ${chain}). This machine's clock is ahead of the witness's. Fix the clock (NTP); records already written with future times ship once the witness's clock reaches them, or run \`signafaide repair --agent ${agent}\` to set them aside with a fresh key now.`;
+    } else if (/not active at|earlier than the time of/.test(e.message)) {
+      msg = `${e.message} (chain ${chain}). Run \`signafaide repair --agent ${agent}\`: it sets the records the witness cannot take aside (kept, still verifiable) and starts a new segment with a fresh key.`;
+    }
+    return new SignafaideError(msg, { code: e.code, status: e.status, docs: e.docs, body: e.body });
+  }
+  /** Ship one chain's outbox in order. */
+  async shipChain(chain, apiKey, timeoutMs) {
+    const agent = chain.split("/")[2];
+    const scope = scopeOf(chain.split("/").slice(0, 2).join("/"));
+    const received = /* @__PURE__ */ new Map();
+    const fp = this.configFp();
+    const blocked = this.blocked.get(chain);
+    if (blocked && blocked.fp === fp) throw blocked.err;
+    this.blocked.delete(chain);
+    const wire = (r) => wireRecord(r, this.storeContent);
+    if (!this.reconciled.has(chain)) {
+      this.state.reconcileOutbox(chain, wire);
+      this.reconciled.add(chain);
+    }
+    const client = this.client(timeoutMs, apiKey);
+    for (; ; ) {
+      let batch = this.state.outbox(chain, BATCH_MAX);
+      if (!batch.length) return received;
+      const current2 = this.key(agent, scope).keyId;
+      if (batch[0].key_id !== current2) {
+        const cut = batch.findIndex((r) => r.key_id === current2);
+        batch = cut < 0 ? batch : batch.slice(0, cut);
+      } else await this.register(client, agent, scope);
+      let resp;
+      try {
+        try {
+          resp = await client.submit(batch);
+        } catch (e) {
+          if (!(e instanceof SignafaideError) || e.code !== "unknown_agent") throw e;
+          this.registered.delete(`${client.apiKey}
+${agent}
+${this.key(agent, scope).keyId}`);
+          await this.register(client, agent, scope);
+          resp = await client.submit(batch);
+        }
+      } catch (e) {
+        if (!(e instanceof SignafaideError)) throw e;
+        let err;
+        if (e.code === "chain_conflict") {
+          const head = e.body.error?.head ?? {};
+          err = new SignafaideError(
+            `${e.message} (chain ${chain}: service head is seq ${head.seq} ${head.record_hash}; local outbox starts at seq ${batch[0].envelope.seq}; nothing was rewritten, run \`signafaide verify\` and \`signafaide status\`)`,
+            { code: e.code, status: e.status, docs: e.docs, body: e.body }
+          );
+        } else err = e.permanent ? this.explain(e, chain, batch[0].key_id, current2) : e;
+        if (err.permanent && !["invalid_key", "quota_exceeded", "plan_required"].includes(err.code)) {
+          this.blocked.set(chain, { fp, err });
+          this.state.setBlocked(chain, { code: err.code, message: err.message, seq: batch[0].envelope.seq });
+        }
+        throw err;
+      }
+      const got = new Map((resp.receipts ?? []).map((r) => [r.record_hash, r]));
+      const bucket = chain.split("/").slice(0, 2).join("/");
+      if ([...got.values()].some((r) => `${r.batch.project}/${r.batch.env}` !== bucket)) {
+        throw new SignafaideError(`The service returned receipts for another project than ${bucket}; nothing was written. Check SIGNAFAIDE_URL and the API key.`, { code: "bad_response" });
+      }
+      this.state.applyReceipts(chain, got);
+      this.state.dropOutbox(
+        chain,
+        batch.filter((r) => got.has(recordHash(r))).map((r) => r.envelope.seq)
+      );
+      for (const w of this.state.updateHeads(resp.heads ?? [])) console.warn(`signafaide: ${w}`);
+      if (this.onHead && resp.heads?.length) {
+        try {
+          await this.onHead(resp.heads);
+        } catch (e) {
+          console.warn(`signafaide: onHead failed (the heads are still in head.json): ${e.message}`);
+        }
+      }
+      for (const [h, r] of got) received.set(h, r);
+      this.pending = 0;
+      if (!got.size) throw new SignafaideError("The service accepted the batch but returned no matching receipts.", { code: "no_receipts" });
+      this.state.setBlocked(chain, null);
+    }
+  }
+  /** `signafaide keys create`: a new key for `agent` in `env`, registered with the witness under
+   * the API key (which must be of that env), writing no record. With `print`, nothing is written
+   * here: the key file is returned for a secret store (`SIGNAFAIDE_AGENT_KEY_LIVE_<NAME>` for
+   * live). Otherwise it becomes the agent's key file. Refused when the agent already has a key
+   * here or from the environment; the witness refuses it when the agent already has an active
+   * key there (`keys rotate` on the machine that holds it, or revoke it in the console first). */
+  async createKey(agent, env, print) {
+    const apiKey = this.apiKey;
+    if (!apiKey) throw new SignafaideError("keys create registers the new key with the witness: set SIGNAFAIDE_API_KEY to a key of that env first (a live key from the console for --env live).", { code: "no_key" });
+    if (envOf(apiKey) !== env) throw new SignafaideError(`SIGNAFAIDE_API_KEY is a ${envOf(apiKey)} key; --env ${env} needs a ${env} key.`, { code: "invalid_key" });
+    const scope = env === "live" ? "live" : "";
+    if (this.state.providedKey(agent, scope)) throw new StateError(`agent ${agent} already has a key from ${agentKeyEnvName(agent, scope)} (or a key provider); unset it to make a new one, or use \`signafaide keys rotate\``);
+    if (!print && fs2.existsSync(this.state.keyPath(agent, scope))) throw new StateError(`agent ${agent} already has a key file (${this.state.keyPath(agent, scope)}); use \`signafaide keys rotate\` to replace it`);
+    const known = this.state.bucket(apiKey);
+    let project, keyEnv;
+    if (!known.startsWith(PENDING + "/")) [project, keyEnv] = known.split("/");
+    else {
+      const resp2 = await this.client(1e4, apiKey).project();
+      if (resp2?.env !== env || !validProjectId(resp2?.project)) {
+        throw new SignafaideError(`The service at ${this.url} answered GET /v1/project with an invalid project or env; check SIGNAFAIDE_URL.`, { code: "bad_response" });
+      }
+      [project, keyEnv] = [resp2.project, resp2.env];
+      if (!print) this.state.learnProject(apiKey, project, keyEnv);
+    }
+    const { key, doc } = this.state.newKeyFile(agent);
+    const reg = registration(project, keyEnv, agent, doc.public_key, doc.created);
+    const h = hashJson(reg);
+    let resp;
+    try {
+      resp = await this.client(1e4, apiKey).registerAgent(agent, doc.public_key, doc.created, key.sign("register", h));
+    } catch (e) {
+      if (e instanceof SignafaideError && e.code === "bad_signature") {
+        throw new SignafaideError(
+          `agent ${agent} already has an active key on the witness, so a new one needs the old key's rotation signature: run \`signafaide keys rotate --agent ${agent} --env ${env}\` where that key is, or have an admin revoke it in the console, then run keys create again.`,
+          { code: "bad_signature" }
+        );
+      }
+      throw e;
+    }
+    if (resp?.key_id && resp.key_id !== key.keyId) throw new SignafaideError(`The service registered key ${resp.key_id} for ${agent}, expected ${key.keyId}.`, { code: "key_mismatch" });
+    this.registered.add(`${apiKey}
+${agent}
+${key.keyId}`);
+    const out = { doc, envName: agentKeyEnvName(agent, scope), project };
+    return print ? out : { ...out, file: this.state.saveKeyFile(doc, scope) };
+  }
+  async register(client, agent, scope) {
+    const k = this.key(agent, scope);
+    const id = `${client.apiKey}
+${agent}
+${k.keyId}`;
+    if (this.registered.has(id)) return;
+    const [project, env] = this.state.bucket(client.apiKey).split("/");
+    const nowIso = now();
+    const floor = new Date(Date.now() - KEY_MAX_AGE_MS).toISOString().slice(0, 19) + ".000Z";
+    const created = this.state.keyCreated(agent, scope) ?? nowIso;
+    let validFrom = created > floor ? created : floor;
+    if (validFrom > nowIso) validFrom = nowIso;
+    const reg = registration(project, env, agent, b64url(k.publicKey), validFrom);
+    const h = hashJson(reg);
+    const retired = this.state.retiredKeys(agent, scope)[0]?.[0];
+    const rotation = retired ? { key_id: retired.keyId, sig: retired.sign("rotate", h) } : void 0;
+    let resp;
+    try {
+      resp = await client.registerAgent(agent, reg.public_key, validFrom, k.sign("register", h), rotation);
+    } catch (e) {
+      if (e instanceof SignafaideError && e.permanent) throw this.explain(e, `${project}/${env}/${agent}`, k.keyId, k.keyId);
+      throw e;
+    }
+    if (resp?.key_id && resp.key_id !== k.keyId) {
+      throw new SignafaideError(`The service registered key ${resp.key_id} for ${agent}, expected ${k.keyId}.`, { code: "key_mismatch" });
+    }
+    for (const r of Array.isArray(resp?.retired) ? resp.retired : []) {
+      if (r && typeof r.key_id === "string" && typeof r.valid_to === "string") this.state.markRetired(agent, r.key_id, r.valid_to, scope);
+    }
+    this.registered.add(id);
+  }
+  // --- background -----------------------------------------------------------------
+  start() {
+    if (this.closed) return;
+    if (!this.timer) {
+      this.timer = setInterval(() => void this.tick(), this.flushIntervalMs);
+      this.timer.unref?.();
+    }
+    if (!this.exitHooked && typeof process !== "undefined") {
+      this.exitHooked = true;
+      process.on("beforeExit", this.onBeforeExit);
+      process.on("exit", this.onExit);
+    }
+  }
+  /** One background attempt: never two at once, never inside the backoff, and never after a
+   * refusal retrying cannot fix until the configuration (API key, URL, agent keys) changes. */
+  async tick() {
+    if (this.closed || this.inFlight || monotonicMs() < this.nextAttempt) return;
+    if (!this.apiKey || !this.waiting()) return;
+    const fp = this.configFp();
+    if (this.halted) {
+      if (this.halted.fp === fp) return;
+      this.halted = void 0;
+    }
+    this.inFlight = true;
+    let r;
+    try {
+      r = await this.flushLogged(1e4, "bg");
+    } finally {
+      this.inFlight = false;
+    }
+    const errs = r ? Object.values(r.errors).filter((e) => !LOCAL_CODES.has(e.code)) : [];
+    if (r && !errs.length) {
+      this.failures = 0;
+      this.nextAttempt = 0;
+      return;
+    }
+    const wide = errs.find((e) => e.permanent && ["invalid_key", "quota_exceeded", "plan_required"].includes(e.code));
+    if (wide) {
+      this.halted = { fp, err: wide };
+      this.report(`signafaide: sending stopped until the API key or SIGNAFAIDE_URL changes (\`signafaide flush\` tries again now): ${wide.message}`);
+      return;
+    }
+    this.failures++;
+    const base = Math.min(6e4, this.flushIntervalMs * 2 ** this.failures);
+    this.nextAttempt = monotonicMs() + base * (0.8 + Math.random() * 0.4);
+  }
+  async flushLogged(timeoutMs = 1e4, mode = "fg") {
+    const cut = mode === "bg" ? this.bgAbort.signal : void 0;
+    let r;
+    try {
+      r = await this.flush(timeoutMs, mode);
+    } catch (e) {
+      if (cut?.aborted) return null;
+      this.report(`signafaide: ${e.message}`);
+      return null;
+    }
+    if (cut?.aborted) return r;
+    const errs = Object.entries(r.errors);
+    if (errs.length) this.report("signafaide: " + errs.map(([a, e]) => e.message.includes(a) ? e.message : `${a}: ${e.message}`).join("; "));
+    else if (this.failing && r.shipped) {
+      console.warn(`signafaide: service reachable again, shipped ${plural(r.shipped, "record")}`);
+      this.failing = void 0;
+    }
+    return r;
+  }
+  report(msg) {
+    if (msg !== this.failing) {
+      console.warn(msg);
+      this.failing = msg;
+    }
+  }
+  /** The program has nothing left to do: one last attempt, held open at most `exitFlushMs`.
+   * Background requests never keep the process alive, so they are cut off here. */
+  onBeforeExit = () => {
+    void this.exitAttempt();
+  };
+  /** The last attempt of a program that ends on its own schedule (the gateway, once its server
+   * has exited): what happens by itself when a program runs out of work. Ships what is left and,
+   * when stop notes are on, writes the signed stop note, all within `exitFlushMs`; then stops the
+   * background timer. Never throws. */
+  async shutdown() {
+    await this.exitAttempt();
+    this.releaseToolSources();
+    this.close();
+  }
+  exitAttempt() {
+    const stop2 = this.instanceStop && this.wrote.size > 0 && !this.test;
+    if (this.exitFlushed || !this.exitFlushMs || !this.apiKey || !this.waiting() && !stop2) return void 0;
+    this.exitFlushed = true;
+    if (this.halted && this.halted.fp === this.configFp()) return void 0;
+    this.bgAbort.abort();
+    this.bgAbort = new AbortController();
+    const ctrl = new AbortController();
+    this.exitAbort = ctrl;
+    const timer = setTimeout(() => ctrl.abort(), this.exitFlushMs);
+    const done = () => {
+      clearTimeout(timer);
+      this.exitFlushed = true;
+    };
+    if (!stop2) return this.flushLogged(this.exitFlushMs, "exit").then(done, done);
+    return this.stop(this.exitFlushMs, "exit").then((r) => {
+      const errs = Object.entries(r.errors);
+      if (errs.length && !ctrl.signal.aborted) this.report("signafaide: " + errs.map(([a, e]) => e.message.includes(a) ? e.message : `${a}: ${e.message}`).join("; "));
+    }, (e) => {
+      if (!ctrl.signal.aborted) this.report(`signafaide: ${e.message}`);
+    }).then(done, done);
+  }
+  onExit = () => {
+    this.releaseToolSources();
+    const left = this.waiting();
+    if (left && !this.quiet && this.apiKey) {
+      console.error(`signafaide: ${plural(left, "record")} kept in ${path2.join(this.state.home, "outbox")}; they ship on the next run or with \`signafaide flush\``);
+    }
+  };
+  /** Stop the background timer and exit hooks (records stay in the outbox). */
+  close() {
+    this.closed = true;
+    if (this.toolTimer) clearInterval(this.toolTimer);
+    this.toolTimer = void 0;
+    if (this.timer) clearInterval(this.timer);
+    this.timer = void 0;
+    this.bgAbort.abort();
+    if (this.exitHooked) {
+      process.off("beforeExit", this.onBeforeExit);
+      process.off("exit", this.onExit);
+      this.exitHooked = false;
+    }
+  }
+  // --- blocked chains and repair -----------------------------------------------------
+  /** Why each chain cannot ship, found on this machine (time going back, a clock ahead, a key
+   * used after it ended) or said by the witness (blocked.json). Reads only the records without
+   * a receipt. */
+  diagnose() {
+    const out = [];
+    const saved = this.state.blocked();
+    const nowMs = Date.now();
+    for (const chain of this.state.chains()) {
+      if (chain.startsWith(PENDING + "/")) continue;
+      const agent = chain.split("/")[2];
+      const scope = scopeOf(chain.split("/").slice(0, 2).join("/"));
+      const tail = [];
+      let prevTime = null;
+      for (const [, r] of this.state.reverse(chain)) {
+        if (r.receipt) {
+          prevTime = r.envelope.time;
+          break;
+        }
+        tail.push(r);
+      }
+      tail.reverse();
+      if (!tail.length) continue;
+      const ended = /* @__PURE__ */ new Map();
+      for (const [rk] of this.state.retiredKeys(agent, scope)) {
+        const t = this.state.retiredAt(agent, rk.keyId, scope);
+        if (t) ended.set(rk.keyId, t);
+      }
+      const created = /* @__PURE__ */ new Map();
+      const cur = this.state.loadKey(agent, false, scope);
+      const c0 = this.state.keyCreated(agent, scope);
+      if (cur && c0) created.set(cur.keyId, c0);
+      for (const [rk, c] of this.state.retiredKeys(agent, scope)) created.set(rk.keyId, c);
+      const next = `run \`signafaide repair --agent ${agent}\` (sets these records aside, kept and verifiable, and starts a new segment with a fresh key)`;
+      const wait = `fix the clock (NTP) and wait until it catches up with these records, which then ship, or run \`signafaide repair --agent ${agent}\` (sets them aside, kept and verifiable, and starts a new segment with a fresh key)`;
+      let found = null;
+      for (const r of tail) {
+        const t = r.envelope.time;
+        const at = (code, reason) => ({ chain, seq: r.envelope.seq, code, reason, records: tail.length - tail.indexOf(r), next });
+        if (prevTime && t < prevTime) found = at("time_back", `seq ${r.envelope.seq} has time ${t}, earlier than the record before it (${prevTime}): the clock went back while an older SDK was writing`);
+        else if (created.has(r.key_id) && t < created.get(r.key_id)) found = at("before_key", `seq ${r.envelope.seq} has time ${t}, before its key ${r.key_id} was made (${created.get(r.key_id)})`);
+        else if (ended.has(r.key_id) && t >= ended.get(r.key_id)) found = at("key_ended", `seq ${r.envelope.seq} is signed by key ${r.key_id} after it ended at ${ended.get(r.key_id)}`);
+        else if (Date.parse(t) > nowMs + MAX_CLOCK_SKEW_MS)
+          found = { ...at("clock_ahead", `seq ${r.envelope.seq} has time ${t}, ahead of this machine's clock now: the clock was ahead when it was written`), next: wait };
+        if (found) break;
+        prevTime = t;
+      }
+      const w = saved[chain];
+      if (!found && w) {
+        const first = tail.find((r) => w.seq === null || r.envelope.seq >= w.seq) ?? tail[0];
+        const msg = (w.message.startsWith(`${chain}: `) ? w.message.slice(chain.length + 2) : w.message).replace(/[\s.]+$/, "");
+        const ahead = /ahead of the service clock|must not be in the future/.test(msg);
+        found = { chain, seq: first.envelope.seq, code: w.code, reason: `refused by the witness: ${msg}`, records: tail.length - tail.indexOf(first), next: ahead ? wait : next };
+      }
+      if (found) out.push(found);
+    }
+    return out;
+  }
+  /** `signafaide repair`: for each blocked chain (of `agent`, or every agent), set the records
+   * from the first one that cannot ship aside into `held/` (kept, still verifiable locally), give
+   * the agent a new key (rotation, §2.4), and write a `note` named `signafaide.repair` that
+   * commits to the held records' hashes, so the new segment's first co-signed record fixes them
+   * in time. Co-signed records are never touched. */
+  repair(opts = {}) {
+    const out = [];
+    for (const b of this.diagnose()) {
+      const agent = b.chain.split("/")[2];
+      if (opts.agent && agent !== opts.agent) continue;
+      if (opts.dryRun) {
+        out.push({ chain: b.chain, blocked: b });
+        continue;
+      }
+      const bucket = b.chain.split("/").slice(0, 2).join("/");
+      const scope = scopeOf(bucket);
+      const { file, records } = this.state.holdTail(b.chain, b.seq);
+      let newKey;
+      if (!this.state.providedKey(agent, scope)) newKey = this.state.rotateKey(agent, scope)[1].keyId;
+      this.keys.delete(`${agent}
+${scope}`);
+      const content = {
+        held: path2.relative(this.state.home, file),
+        from_seq: records[0].envelope.seq,
+        to_seq: records[records.length - 1].envelope.seq,
+        records: records.length,
+        records_hash: hashJson(records.map((r) => recordHash(r))),
+        code: b.code,
+        reason: b.reason
+      };
+      const [project, env] = bucket.split("/");
+      const key = this.key(agent, scope);
+      const note2 = this.state.append(
+        b.chain,
+        (seq, prev, prevTime) => {
+          const [time, c] = this.timed(content, prevTime, agent, scope);
+          return makeRecord(key, { kind: "note", project, env, agent, seq, prev, name: "signafaide.repair", content: c, ref: null, time });
+        },
+        (r) => wireRecord(r, this.storeContent)
+      );
+      this.state.setBlocked(b.chain, null);
+      this.blocked.delete(b.chain);
+      this.halted = void 0;
+      out.push({ chain: b.chain, blocked: b, held: file, records: records.length, newKey, note: recordHash(note2) });
+    }
+    return out;
+  }
+  // --- status ---------------------------------------------------------------------
+  status() {
+    const heads = this.state.chainHeads();
+    const bucket = this.state.bucket(this.apiKey);
+    const blocked = new Map(this.diagnose().map((b) => [b.chain, b]));
+    const chains = this.state.chains().map((chain) => {
+      const agent = chain.split("/")[2];
+      const h = heads[chain]?.head;
+      const scope = scopeOf(chain.split("/").slice(0, 2).join("/"));
+      return {
+        chain,
+        agent,
+        current: chain.startsWith(bucket + "/"),
+        key_id: this.state.loadKey(agent, false, scope)?.keyId ?? null,
+        records: this.state.tail(chain)[0],
+        waiting: this.state.outboxSize(chain),
+        receipt_seq: h?.seq ?? null,
+        receipt_time: h?.server_time ?? null,
+        blocked: blocked.get(chain) ?? null
+      };
+    });
+    const held = this.state.heldSegments().map(([chain, file, recs]) => ({ chain, file, records: recs.length }));
+    const key = this.apiKey;
+    return {
+      url: this.url,
+      home: this.state.home,
+      api_key: key ?? null,
+      api_key_invalid: !key && !!this.rawApiKey && !this.test,
+      test_mode: this.test,
+      env: envOf(key),
+      bucket,
+      sandbox: this.state.sandbox(),
+      chains,
+      held,
+      // Drafts wait too: for the project, or for the witness's head of a chain new to this disk.
+      outbox: this.waiting()
+    };
+  }
+};
+function envOf(key) {
+  if (!key) return null;
+  return key.startsWith("sfa_test_") ? "test" : key.startsWith("sfa_live_") ? "live" : "unknown";
+}
+var current;
+function getRecorder() {
+  return current ??= new Recorder();
+}
+function configure(opts = {}) {
+  current?.close();
+  current = new Recorder(opts);
+  return current;
+}
+function legalLinks(resp, url) {
+  const ok = (v) => typeof v === "string" && v.length <= 300 && /^https?:\/\/[^\s]+$/.test(v);
+  const base = url.replace(/\/+$/, "");
+  return { terms_url: ok(resp.terms_url) ? resp.terms_url : `${base}/legal/terms`, privacy_url: ok(resp.privacy_url) ? resp.privacy_url : `${base}/legal/privacy` };
+}
+function termsNotice(l) {
+  return `By creating a sandbox you agree to the signafAIde Terms (${l.terms_url}) and Privacy notice (${l.privacy_url}).`;
+}
+
+// src/record.ts
+var NotRecorded = class extends SignafaideError {
+  name = "NotRecorded";
+};
+var WRAPPED = /* @__PURE__ */ new Map();
+var LISTED = /* @__PURE__ */ new Map();
+var EXPLICIT = /* @__PURE__ */ new Map();
+var toolsVersion = 0;
+var checked = /* @__PURE__ */ new WeakMap();
+var toldDeclare = false;
+function autoDeclareTools(env = process.env) {
+  return !/^(0|false|no|off)$/i.test((env.SIGNAFAIDE_DECLARE_TOOLS ?? "").trim());
+}
+function remember(map, agent, name) {
+  const set = map.get(agent ?? "") ?? /* @__PURE__ */ new Set();
+  map.set(agent ?? "", set);
+  if (!set.has(name)) {
+    set.add(name);
+    toolsVersion++;
+  }
+}
+function namesFor(map, agent, isDefault) {
+  return /* @__PURE__ */ new Set([...map.get(agent) ?? [], ...isDefault ? map.get("") ?? [] : []]);
+}
+function ownTools(rec, agent) {
+  const isDefault = agent === rec.defaultAgent;
+  const explicit = EXPLICIT.get(agent) ?? (isDefault ? EXPLICIT.get("") : void 0);
+  if (explicit) {
+    const wrapped = namesFor(WRAPPED, agent, isDefault);
+    const tools = {};
+    for (const n of explicit.names) tools[n] = wrapped.has(n) && !explicit.unrecorded.has(n);
+    for (const n of explicit.unrecorded) tools[n] = false;
+    return [tools, "declared"];
+  }
+  const listed = namesFor(LISTED, agent, isDefault);
+  if (!listed.size || !autoDeclareTools()) return null;
+  return [Object.fromEntries([...listed].map((n) => [n, true])), "wrap_tools"];
+}
+function declareOwn(rec, agentOpt, storeContent) {
+  const agent = agentOpt || rec.defaultAgent;
+  const own = ownTools(rec, agent);
+  if (!own) return "";
+  return rec.declareTools(own[0], { agent, source: "sdk", origin: own[1], storeContent });
+}
+function declareBeforeCall(rec, agentOpt) {
+  const agent = agentOpt || rec.defaultAgent;
+  const seen = checked.get(rec) ?? /* @__PURE__ */ new Map();
+  checked.set(rec, seen);
+  if (seen.get(agent) === toolsVersion || noWrites.getStore()) return;
+  try {
+    declareOwn(rec, agentOpt);
+    seen.set(agent, toolsVersion);
+  } catch (e) {
+    seen.set(agent, toolsVersion);
+    if (!toldDeclare) {
+      toldDeclare = true;
+      console.error(`signafaide: could not write the tool declaration for ${agent}: ${e.message}`);
+    }
+  }
+}
+function declareTools(names, opts = {}) {
+  const list = [...names];
+  const unrecorded = [...opts.unrecorded ?? []];
+  for (const n of [...list, ...unrecorded]) if (typeof n !== "string" || !n) throw new TypeError("declareTools needs tool names: non-empty strings");
+  EXPLICIT.set(opts.agent ?? "", { names: list, unrecorded: new Set(unrecorded) });
+  toolsVersion++;
+  if (recordingDisabled()) return "";
+  const rec = getRecorder();
+  const hash = declareOwn(rec, opts.agent);
+  const seen = checked.get(rec) ?? /* @__PURE__ */ new Map();
+  checked.set(rec, seen);
+  seen.set(opts.agent || rec.defaultAgent, toolsVersion);
+  return hash;
+}
+var Spec = class {
+  constructor(name, opts, listed = false) {
+    this.name = name;
+    this.opts = opts;
+    if (!name) throw new TypeError('record(fn) needs a name: record(fn, { name: "approve_payout" })');
+    remember(WRAPPED, opts.agent, name);
+    if (listed) remember(LISTED, opts.agent, name);
+  }
+  name;
+  opts;
+  decide(input) {
+    const rec = getRecorder();
+    declareBeforeCall(rec, this.opts.agent);
+    const meta = { sdk: `signafaide-js/${VERSION}`, ...this.opts.meta ?? {} };
+    const content = { input: toJsonable(input) ?? null, meta: toJsonable(meta) };
+    return [rec, rec.write("decision", this.name, content, { agent: this.opts.agent, storeContent: this.opts.storeContent })];
+  }
+  outcome(rec, d, content) {
+    try {
+      rec.write("outcome", this.name, content, { agent: d.envelope.agent, ref: recordHash(d), storeContent: this.opts.storeContent });
+    } catch (e) {
+      console.error(`signafaide: could not write the outcome of ${this.name}: ${e.message}`);
+    }
+  }
+  async strictCheck(rec, d) {
+    if (rec.test) return;
+    try {
+      await rec.ensureReceipt(d);
+    } catch (e) {
+      const err = e instanceof SignafaideError ? e : new SignafaideError(e.message);
+      rec.warnStrictRefused(this.name, err);
+      throw new NotRecorded(`${err.message} (strict mode: ${this.name} did not run)`, { code: err.code, status: err.status, docs: err.docs, body: err.body });
+    }
+  }
+  /** Run `fn` between a decision and an outcome. Sync stays sync unless strict. */
+  call(input, fn) {
+    if (recordingDisabled()) return this.opts.strict ? Promise.resolve().then(fn) : fn();
+    const [rec, d] = this.decide(input);
+    if (this.opts.strict) return this.strictCheck(rec, d).then(() => this.run(rec, d, fn));
+    return this.run(rec, d, fn);
+  }
+  run(rec, d, fn) {
+    let out;
+    try {
+      out = fn();
+    } catch (e) {
+      this.outcome(rec, d, errorContent(e));
+      throw e;
+    }
+    if (out && typeof out.then === "function") {
+      return out.then(
+        (v) => {
+          this.outcome(rec, d, { output: toJsonable(v) ?? null });
+          return v;
+        },
+        (e) => {
+          this.outcome(rec, d, errorContent(e));
+          throw e;
+        }
+      );
+    }
+    this.outcome(rec, d, { output: toJsonable(out) ?? null });
+    return out;
+  }
+};
+function record(fn, opts = {}) {
+  return recordWith(new Spec(opts.name ?? fn.name, opts), fn);
+}
+function recordWith(spec, fn) {
+  const wrapped = function(...args) {
+    return spec.call(args.length === 1 ? args[0] : args, () => fn.apply(this, args));
+  };
+  Object.defineProperty(wrapped, "name", { value: fn.name });
+  return wrapped;
+}
+function note(name, content, opts = {}) {
+  if (recordingDisabled()) return "";
+  return recordHash(getRecorder().write("note", name, toJsonable(content), opts));
+}
+function wrapTools(tools, opts = {}) {
+  if (Array.isArray(tools)) return tools.map((t) => wrapTool(t, opts));
+  if (tools && typeof tools === "object" && !isTool(tools)) {
+    return Object.fromEntries(Object.entries(tools).map(([k, t]) => [k, wrapTool(t, { ...opts, name: k })]));
+  }
+  return wrapTool(tools, opts);
+}
+var isTool = (t) => typeof t === "function" || isOpenAIAgentsTool(t) || isLangChainTool(t) || typeof t?.execute === "function";
+var isOpenAIAgentsTool = (t) => t?.type === "function" && typeof t.invoke === "function" && typeof t.name === "string";
+var isLangChainTool = (t) => Array.isArray(t?.lc_namespace) && typeof t._call === "function" && typeof t.invoke === "function";
+function wrapTool(tool, opts = {}) {
+  const t = tool;
+  const { declareTools: declare = true, ...ropts } = opts;
+  const spec = (name) => new Spec(ropts.name ?? name, ropts, declare);
+  if (isOpenAIAgentsTool(t)) {
+    const s = spec(t.name);
+    ADAPTERS.add("openai-agents");
+    return {
+      ...t,
+      invoke: (runContext, input, details) => Promise.resolve(s.call(parseJson2(input), () => t.invoke(runContext, input, details)))
+    };
+  }
+  if (isLangChainTool(t)) {
+    const s = spec(t.name);
+    ADAPTERS.add("langchain");
+    const proxy = Object.create(t);
+    proxy._call = function(arg, runManager, config) {
+      return s.call(arg, () => t._call.call(proxy, arg, runManager, config));
+    };
+    return proxy;
+  }
+  if (typeof t === "function") return recordWith(spec(t.name), t);
+  if (typeof t?.execute === "function") {
+    const s = spec(t.name ?? "");
+    ADAPTERS.add("vercel-ai");
+    return { ...t, execute: (input, options) => s.call(input, () => t.execute(input, options)) };
+  }
+  throw new TypeError(`wrapTools cannot record ${t === null ? "null" : typeof t}: pass a function, a tool with execute(), an OpenAI Agents tool or a LangChain tool`);
+}
+function parseJson2(s) {
+  try {
+    return s ? JSON.parse(s) : {};
+  } catch {
+    return s;
+  }
+}
+function errorContent(e) {
+  const err = e;
+  return { error: { type: err?.name ?? typeof e, message: err?.message ?? String(e) } };
+}
+function base64(b) {
+  let s = "";
+  for (const x of b) s += String.fromCharCode(x);
+  return btoa(s);
+}
+function toJsonable(v, seen = /* @__PURE__ */ new Set()) {
+  if (v === null || v === void 0) return null;
+  switch (typeof v) {
+    case "boolean":
+    case "string":
+      return v;
+    case "number":
+      if (!Number.isFinite(v) || isUnsafeInteger(v)) return String(v);
+      return v;
+    case "bigint":
+      return v >= -BigInt(Number.MAX_SAFE_INTEGER) && v <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(v) : v.toString();
+    case "function":
+    case "symbol":
+      return null;
+  }
+  if (seen.has(v)) return "[Circular]";
+  const inner = new Set(seen).add(v);
+  if (v instanceof Date) return Number.isNaN(v.getTime()) ? null : v.toISOString();
+  if (v instanceof Uint8Array) return base64(v);
+  if (v instanceof ArrayBuffer) return base64(new Uint8Array(v));
+  if (v instanceof Error) return { name: v.name, message: v.message };
+  if (Array.isArray(v)) return v.map((x) => toJsonable(x, inner));
+  if (v instanceof Set) return [...v].map((x) => toJsonable(x, inner)).sort((a, b) => canonicalize(a) < canonicalize(b) ? -1 : 1);
+  if (v instanceof Map) return Object.fromEntries([...v].map(([k, x]) => [String(k), toJsonable(x, inner)]));
+  if (typeof v.toJSON === "function") return toJsonable(v.toJSON(), inner);
+  const out = {};
+  for (const [k, x] of Object.entries(v)) {
+    if (x === void 0 || typeof x === "function" || typeof x === "symbol") continue;
+    out[k] = toJsonable(x, inner);
+  }
+  return out;
+}
+
+// src/replay.ts
+import * as fs3 from "fs";
+var TIME_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+var DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+async function loadServiceKeys(src) {
+  if (typeof src !== "string") return parseServiceKeys(src);
+  return parseServiceKeys(/^https?:\/\//.test(src) ? await fetchJson(src) : JSON.parse(fs3.readFileSync(src, "utf8")));
+}
+function timeArg(value, name, end = false) {
+  if (!value) return void 0;
+  if (DATE_RE.test(value)) {
+    const d = /* @__PURE__ */ new Date(`${value}T00:00:00.000Z`);
+    if (Number.isNaN(d.getTime())) throw new SyntaxError(`${name} must be YYYY-MM-DD or a time like 2026-11-13T10:00:00.000Z`);
+    if (end) d.setUTCDate(d.getUTCDate() + 1);
+    return d.toISOString();
+  }
+  if (!TIME_RE.test(value)) throw new SyntaxError(`${name} must be YYYY-MM-DD or a time like 2026-11-13T10:00:00.000Z`);
+  return value;
+}
+function agentChain(rec, agent) {
+  const current2 = `${rec.state.bucket(rec.apiKey)}/${agent}`;
+  if (fs3.existsSync(rec.state.chainPath(current2))) return current2;
+  const found = rec.state.chains().filter((c) => c.split("/").pop() === agent);
+  if (found.length === 1) return found[0];
+  if (!found.length) throw new StateError(`no local chain for agent "${agent}" in ${rec.state.home}; agents here: ${rec.state.agents().join(", ") || "none"}`);
+  throw new StateError(`agent "${agent}" has several chains (${found.join(", ")}); pass chain (--chain) to pick one`);
+}
+async function verifyChain(rec, chain, keys2) {
+  const st = rec.state;
+  const records = st.readAll(chain);
+  let serviceKeys;
+  let note2;
+  if (keys2 !== void 0) {
+    serviceKeys = await loadServiceKeys(keys2);
+    note2 = `service keys: ${typeof keys2 === "string" ? keys2 : "given"}`;
+  } else if (!records.some((r) => r.receipt)) {
+    serviceKeys = [];
+    note2 = "service keys: none needed (nothing co-signed yet)";
+  } else {
+    try {
+      serviceKeys = parseServiceKeys(await rec.client().request("GET", "/.well-known/signafaide-keys.json", { auth: false }));
+      note2 = `service keys: ${rec.url}/.well-known/signafaide-keys.json`;
+    } catch (e) {
+      if (records.some((r) => r.receipt)) throw new KeysRequired(`could not load service keys from ${rec.url} (${e.message}); pass keys (--keys <file|url>)`);
+      serviceKeys = [];
+      note2 = "service keys: none needed (nothing co-signed yet)";
+    }
+  }
+  const agentKeys = st.agentPublicKeys().map((k) => ({ agent: k.agent, key_id: k.key_id, public_key: k.public_key, valid_from: null, valid_to: k.retired }));
+  const heads = Object.fromEntries(Object.entries(st.chainHeads()).filter(([c]) => c === chain));
+  const base = rec.state.chainBase(chain);
+  const report = verifyLocalState({ records, chainIds: records.map(() => chain), agentKeys, heads, bases: base ? { [chain]: base } : {} }, serviceKeys, await loadDrandVerifier());
+  report.notes.unshift(`chain: ${chain}`, note2);
+  return report;
+}
+var Entry = class {
+  constructor(record2, hash) {
+    this.record = record2;
+    this.hash = hash;
+  }
+  record;
+  hash;
+  problems = [];
+  /** The outcome of a decision, or the decision of an outcome. */
+  pair = null;
+  get envelope() {
+    return this.record.envelope;
+  }
+  get content() {
+    const c = this.record.content;
+    return c && typeof c === "object" && !Array.isArray(c) ? c : null;
+  }
+  get receipt() {
+    return this.record.receipt ?? null;
+  }
+  /** Why the witness can never take this record (the chain is BLOCKED from here), or null. */
+  blocked = null;
+  /** `verified`, `signed` (not co-signed by the service yet), `BLOCKED` (can never be co-signed as it is) or `FAIL`. */
+  get status() {
+    return this.problems.length ? "FAIL" : this.receipt ? "verified" : this.blocked ? "BLOCKED" : "signed";
+  }
+  toJSON() {
+    const e = this.envelope;
+    const b = this.receipt?.batch ?? {};
+    return {
+      seq: e.seq,
+      kind: e.kind,
+      name: e.name,
+      time: e.time,
+      record_hash: this.hash,
+      ref: e.ref,
+      content_hash: e.content_hash,
+      content: this.content,
+      status: this.status,
+      problems: this.problems,
+      ...this.blocked ? { blocked: this.blocked } : {},
+      batch_seq: b.seq ?? null,
+      server_time: b.server_time ?? null,
+      drand_round: b.drand?.round ?? null,
+      pair: this.pair?.hash ?? null
+    };
+  }
+};
+var esc = (s) => String(s).replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+var Replay = class {
+  constructor(agent, chain, entries, report, since, until, total) {
+    this.agent = agent;
+    this.chain = chain;
+    this.entries = entries;
+    this.report = report;
+    this.since = since;
+    this.until = until;
+    this.total = total;
+  }
+  agent;
+  chain;
+  entries;
+  report;
+  since;
+  until;
+  total;
+  /** Why the chain cannot ship from some record on (`signafaide repair` fixes it), or null. */
+  blocked = null;
+  get ok() {
+    return this.report.ok && !this.blocked;
+  }
+  /** PASS, FAIL or BLOCKED (a chain the witness refuses never passes). */
+  get result() {
+    return this.report.result === "PASS" && this.blocked ? "BLOCKED" : this.report.result;
+  }
+  toJSON() {
+    return {
+      agent: this.agent,
+      chain: this.chain,
+      since: this.since,
+      until: this.until,
+      total: this.total,
+      shown: this.entries.length,
+      result: this.result,
+      ...this.blocked ? { blocked: this.blocked } : {},
+      verification: this.report.toJSON(),
+      entries: this.entries.map((e) => e.toJSON())
+    };
+  }
+  lines() {
+    const out = [`signafAIde replay: ${this.agent}  (${this.chain})`, `window: ${this.since ?? "start"} to ${this.until ?? "now"}; ${this.entries.length} of ${plural(this.total, "record")} shown`];
+    out.push(`verification: ${this.report.resultLine}` + (this.report.ok ? "" : ` (first failed check: ${this.report.firstFailed()})`));
+    if (this.blocked) out.push(`BLOCKED from seq ${this.blocked.seq}: ${this.blocked.reason}. Next: ${this.blocked.next}`);
+    out.push(...this.report.notes.map((n) => `  ${n}`), "");
+    for (const e of this.entries) {
+      const env = e.envelope;
+      const link = e.pair ? env.kind === "decision" ? `  -> outcome #${e.pair.envelope.seq}` : `  <- decision #${e.pair.envelope.seq}` : "";
+      const rc = e.receipt;
+      const where = rc ? `batch ${rc.batch.seq}` + (rc.batch.drand ? `, drand ${rc.batch.drand.round}` : "") : e.blocked ? "the witness cannot take it" : "not co-signed yet";
+      out.push(`#${String(env.seq).padEnd(5)} ${env.time}  ${env.kind.padEnd(8)} ${env.name}${link}`);
+      out.push(`       ${e.hash.slice(0, 16)}  ${e.status.toUpperCase()} (${where})`);
+      for (const p of e.problems) out.push(`       ! ${p}`);
+      for (const [k, v] of Object.entries(e.content ?? {})) {
+        let text = JSON.stringify(v);
+        if (text.length > 100) text = JSON.stringify(v, null, 2).split("\n").map((l, i) => i ? "         " + l : l).join("\n");
+        out.push(`       ${k.padEnd(7)} ${text}`);
+      }
+      if (!e.content) out.push("       (no local content for this record)");
+      out.push("");
+    }
+    const failed = this.entries.filter((e) => e.problems.length).length;
+    const signed = this.entries.filter((e) => !e.receipt && !e.problems.length).length;
+    const blockedN = this.entries.filter((e) => e.status === "BLOCKED").length;
+    const what = failed ? `${failed} failed` : signed ? `each checked against its content_hash and signature; ${signed} not co-signed yet${blockedN ? ` (${blockedN} BLOCKED)` : ""}, so their receipts could not be checked` : "each checked against its content_hash, its signature and its receipt";
+    out.push(`${this.result}: ${plural(this.entries.length, "record")} shown, ${what}`);
+    return out;
+  }
+  toString() {
+    return this.lines().join("\n");
+  }
+  /** One self-contained page: inline CSS, no scripts, no external assets. */
+  toHtml() {
+    const rows = this.entries.map((e) => {
+      const env = e.envelope;
+      const rc = e.receipt;
+      const link = e.pair ? `<span class="muted">${env.kind === "decision" ? "outcome" : "decision"} <a href="#r${e.pair.envelope.seq}">#${e.pair.envelope.seq}</a></span>` : "";
+      const cls = { verified: "ok", signed: "warn", BLOCKED: "bad", FAIL: "bad" }[e.status];
+      const body = Object.entries(e.content ?? {}).map(([k, v]) => `<div class="kv"><span>${esc(k)}</span><pre>${esc(JSON.stringify(v, null, 2))}</pre></div>`).join("") || '<p class="muted">No local content for this record.</p>';
+      const probs = e.problems.map((p) => `<li>${esc(p)}</li>`).join("");
+      const receipt = rc ? `batch ${rc.batch.seq} \xB7 ${esc(rc.batch.server_time)}` + (rc.batch.drand ? ` \xB7 drand ${rc.batch.drand.round}` : "") : e.blocked ? `BLOCKED: ${esc(e.blocked)}` : "not co-signed by the service yet";
+      return `<article id="r${env.seq}" class="${esc(env.kind)}"><header><span class="seq">#${env.seq}</span><span class="kind">${esc(env.kind)}</span><b>${esc(env.name)}</b>${link}<span class="st ${cls}">${e.status}</span></header><div class="meta"><code title="record_hash">${e.hash}</code> \xB7 ${esc(env.time)} \xB7 ${receipt}</div>` + (probs ? `<ul class="probs">${probs}</ul>` : "") + body + "</article>";
+    });
+    const label = (c) => c.status === "fail" ? "FAIL" : c.status === "not_checked" ? "NOT CHECKED" : c.status === "pending" ? "PENDING" : (c.value ?? "pass").toUpperCase();
+    const checks = this.report.checks.map((c) => `<tr><td>${c.n}</td><td>${esc(c.title)}</td><td><span class="st ${c.status === "pass" ? "ok" : c.status === "fail" ? "bad" : ""}">${label(c)}</span></td><td>${esc(c.detail)}</td></tr>`).join("");
+    const notes = this.report.notes.map((n) => `<li>${esc(n)}</li>`).join("");
+    return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Replay: ${esc(this.agent)}</title><style>${CSS}</style></head><body><main>
+<p class="muted small">signafAIde replay</p><h1>${esc(this.agent)}</h1>
+<p class="muted">${esc(this.chain)} \xB7 ${esc(this.since ?? "start")} to ${esc(this.until ?? "now")} \xB7 ${this.entries.length} of ${plural(this.total, "record")}</p>
+<p class="result">Verification: <span class="st ${this.ok ? "ok" : "bad"}">${this.result}</span> <span class="muted small">${esc(this.report.resultLine)}</span></p>
+${this.blocked ? `<p class="probs">BLOCKED from seq ${this.blocked.seq}: ${esc(this.blocked.reason)}. Next: ${esc(this.blocked.next)}</p>` : ""}
+<details><summary>Checks</summary><ul class="small muted">${notes}</ul><table>${checks}</table></details>
+${rows.join("")}
+<footer>Each record was checked against its content_hash, its signature and the service's receipt. Generated by signafAIde from the local chain.</footer>
+</main></body></html>`;
+  }
+};
+var CSS = `
+*{box-sizing:border-box}body{margin:0;background:#f6f7f9;color:#1a1d23;font:14px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif}
+main{max-width:960px;margin:0 auto;padding:32px 24px 64px}h1{margin:0;font-size:22px}a{color:#2456c4}
+.muted{color:#5d6472}.small{font-size:12px}.result{font-weight:600}
+table{border-collapse:collapse;width:100%;font-size:12.5px;margin:8px 0}td{padding:4px 8px;border-bottom:1px solid #e3e6ec;vertical-align:top}
+article{background:#fff;border:1px solid #e3e6ec;border-radius:8px;padding:12px 14px;margin:10px 0}
+article.outcome{margin-left:28px}article header{display:flex;gap:10px;align-items:baseline;flex-wrap:wrap}
+.seq{color:#5d6472;font-variant-numeric:tabular-nums}.kind{font-size:11px;text-transform:uppercase;letter-spacing:.05em;color:#5d6472}
+.meta{font-size:12px;color:#5d6472;margin:4px 0 8px;word-break:break-all}code,pre{font:12px ui-monospace,SFMono-Regular,Menlo,Consolas,monospace}
+pre{margin:2px 0 6px;padding:8px 10px;background:#f6f7f9;border-radius:6px;white-space:pre-wrap;word-break:break-word}
+.kv>span{font-size:11.5px;font-weight:600;color:#4a5160}
+.st{margin-left:auto;padding:1px 8px;border-radius:4px;font-size:11.5px;font-weight:700;background:#eceef2;color:#4a5160}
+.st.ok{background:#e3f4ea;color:#1d6b3f}.st.warn{background:#fdf2dc;color:#7a5200}.st.bad{background:#fbe5e5;color:#9b1c1c}
+.probs{color:#9b1c1c;font-size:12.5px;margin:4px 0}footer{margin-top:24px;font-size:12px;color:#5d6472}
+@media print{body{background:#fff}article{break-inside:avoid}}
+`;
+async function replay(opts = {}) {
+  const rec = getRecorder();
+  const agent = opts.agent ?? rec.onlyAgent() ?? rec.defaultAgent;
+  const chain = opts.chain ?? agentChain(rec, agent);
+  const lo = timeArg(opts.since, "since");
+  const hi = timeArg(opts.until, "until", true);
+  const report = await verifyChain(rec, chain, opts.keys);
+  let entries = rec.state.readAll(chain).map((r2) => new Entry(r2, hashJson(r2.envelope)));
+  const byLabel = /* @__PURE__ */ new Map();
+  for (const c of report.checks) for (const f of c.failures) byLabel.set(f.item, [...byLabel.get(f.item) ?? [], `${c.title}: ${f.message}`]);
+  const byHash = new Map(entries.map((e) => [e.hash, e]));
+  for (const e of entries) {
+    const env = e.envelope;
+    const rc = e.receipt;
+    e.problems = [...byLabel.get(`${chain}#${env.seq}`) ?? []];
+    if (rc) e.problems.push(...byLabel.get(`batch ${rc.batch.seq}`) ?? [], ...byLabel.get(`head ${rc.head.agent}#${rc.head.seq}`) ?? []);
+    const d = env.kind === "outcome" && env.ref ? byHash.get(env.ref) : void 0;
+    if (d) [e.pair, d.pair] = [d, e];
+  }
+  const total = entries.length;
+  if (opts.record) {
+    const r2 = opts.record.toLowerCase();
+    if (r2.length < 8) throw new SyntaxError("record must be a record hash or a prefix of at least 8 characters");
+    const hit = entries.filter((e) => e.hash.startsWith(r2));
+    if (hit.length !== 1) throw new StateError(`${hit.length ? hit.length : "no"} records match ${opts.record} in ${chain}`);
+    entries = [hit[0], hit[0].pair].filter((x) => !!x).sort((a, b2) => a.envelope.seq - b2.envelope.seq);
+  }
+  const b = rec.diagnose().find((x) => x.chain === chain);
+  if (b) {
+    for (const e of entries) if (!e.receipt && e.envelope.seq >= b.seq) e.blocked = b.reason;
+  }
+  entries = entries.filter((e) => (!lo || e.envelope.time >= lo) && (!hi || e.envelope.time < hi));
+  const r = new Replay(agent, chain, entries, report, lo ?? null, hi ?? null, total);
+  if (b) r.blocked = { seq: b.seq, reason: b.reason, next: b.next };
+  return r;
+}
+
+// src/experiments.ts
+var VerificationFailed = class extends Error {
+  name = "VerificationFailed";
+};
+function recordedValue(outcomeContent) {
+  return "output" in outcomeContent ? outcomeContent.output : outcomeContent;
+}
+var ExperimentReport = class {
+  constructor(agent, chain, name, candidateName, rows, skipped, verification, since = null, until = null, label = null) {
+    this.agent = agent;
+    this.chain = chain;
+    this.name = name;
+    this.candidateName = candidateName;
+    this.rows = rows;
+    this.skipped = skipped;
+    this.verification = verification;
+    this.since = since;
+    this.until = until;
+    this.label = label;
+  }
+  agent;
+  chain;
+  name;
+  candidateName;
+  rows;
+  skipped;
+  verification;
+  since;
+  until;
+  label;
+  uploaded = null;
+  get n() {
+    return this.rows.length;
+  }
+  get agreed() {
+    return this.rows.filter((r) => r.result === "agreed").length;
+  }
+  get changed() {
+    return this.rows.filter((r) => r.result === "changed").length;
+  }
+  get errors() {
+    return this.rows.filter((r) => r.result === "error").length;
+  }
+  get agreement() {
+    return this.n ? this.agreed / this.n : null;
+  }
+  toJSON() {
+    return { agent: this.agent, chain: this.chain, name: this.name, candidate: this.candidateName, since: this.since, until: this.until, n: this.n, agreed: this.agreed, changed: this.changed, errors: this.errors, skipped: this.skipped, rows: this.rows };
+  }
+  toString() {
+    const pct = this.n ? ` (${(this.agreed / this.n * 100).toFixed(1)}% agreement)` : "";
+    const out = [`compare ${this.candidateName} on ${this.agent}${this.name ? ` / ${this.name}` : ""} (${this.chain})`, `n ${this.n}: agreed ${this.agreed}, changed ${this.changed}, errors ${this.errors}${pct}`];
+    if (this.skipped) out.push(`skipped ${plural(this.skipped, "decision")} without a co-signed outcome yet`);
+    const off = this.rows.filter((r) => r.result !== "agreed");
+    for (const r of off.slice(0, 20)) {
+      const what = r.result === "error" ? `error ${r.error}` : `recorded ${canonicalize(r.recorded).slice(0, 80)}  candidate ${canonicalize(r.candidate).slice(0, 80)}`;
+      out.push(`  ${r.result.padEnd(7)} ${r.record_hash.slice(0, 16)}  ${r.time}  ${what}`);
+    }
+    if (off.length > 20) out.push(`  ... and ${off.length - 20} more`);
+    if (this.uploaded) out.push(`uploaded: ${this.uploaded.url}`);
+    return out.join("\n");
+  }
+  /**
+   * The `POST /v1/experiments` body. Hash-only unless `values`: record hashes, the result and
+   * the hash of each candidate output; with `values`, the recorded and candidate values too
+   * (accepted only for decisions whose content is stored with the service).
+   */
+  payload(values = false) {
+    const rows = this.rows.map((r) => ({
+      record_hash: r.record_hash,
+      outcome_hash: r.outcome_hash,
+      result: r.result,
+      candidate_hash: hashJson(r.candidate),
+      ...values ? { recorded: r.recorded, candidate: r.candidate } : {}
+    }));
+    const body = { agent: this.agent, name: this.name, label: this.label, candidate: this.candidateName, since: this.since, until: this.until, rows };
+    return Object.fromEntries(Object.entries(body).filter(([, v]) => v !== null && v !== void 0));
+  }
+  /** Send the report to the service. `values` defaults to the recorder's `storeContent`. */
+  async upload(values) {
+    const rec = getRecorder();
+    this.uploaded = await rec.client(6e4).request("POST", "/v1/experiments", { body: this.payload(values ?? rec.storeContent) });
+    return this.uploaded;
+  }
+};
+async function compare(candidate, opts = {}) {
+  const rec = getRecorder();
+  const agent = opts.agent ?? rec.onlyAgent() ?? rec.defaultAgent;
+  const chain = opts.chain ?? agentChain(rec, agent);
+  const lo = timeArg(opts.since, "since");
+  const hi = timeArg(opts.until, "until", true);
+  const report = await verifyChain(rec, chain, opts.keys);
+  if (!report.ok) throw new VerificationFailed(`the local chain ${chain} does not verify, so it is not compared:
+${report}`);
+  const records = rec.state.readChain(chain);
+  const outcomes = new Map(records.filter((r) => r.envelope.kind === "outcome" && r.receipt).map((r) => [r.envelope.ref, r]));
+  let picked = [];
+  let skipped = 0;
+  for (const r of records) {
+    const e = r.envelope;
+    if (e.kind !== "decision" || opts.name && e.name !== opts.name || lo && e.time < lo || hi && e.time >= hi) continue;
+    const h = hashJson(e);
+    const o = outcomes.get(h);
+    const isObj = (c) => !!c && typeof c === "object" && !Array.isArray(c);
+    if (!r.receipt || !o || !isObj(r.content) || !isObj(o.content)) {
+      skipped++;
+      continue;
+    }
+    picked.push([h, r, o]);
+  }
+  if (opts.limit !== void 0) picked = opts.limit > 0 ? picked.slice(-opts.limit) : [];
+  const equal = opts.same ?? ((a, b) => canonicalize(a) === canonicalize(b));
+  const fname = candidate.name || "candidate";
+  const rows = await noWrites.run(`compare candidate ${fname}`, async () => {
+    const out = [];
+    for (const [h, d, o] of picked) {
+      const recorded = recordedValue(o.content);
+      const row = { record_hash: h, outcome_hash: hashJson(o.envelope), time: d.envelope.time, name: d.envelope.name, input: d.content.input, recorded, candidate: null, same: null, error: null, result: "error" };
+      try {
+        row.candidate = toJsonable(await candidate(d.content.input)) ?? null;
+        row.same = !!equal(recorded, row.candidate);
+        row.result = row.same ? "agreed" : "changed";
+      } catch (e) {
+        const err = e;
+        row.candidate = { error: { type: err?.name ?? typeof e, message: err?.message ?? String(e) } };
+        row.error = `${err?.name ?? "Error"}: ${err?.message ?? String(e)}`;
+      }
+      out.push(row);
+    }
+    return out;
+  });
+  const result = new ExperimentReport(agent, chain, opts.name ?? null, fname, rows, skipped, report, lo ?? null, hi ?? null, opts.label ?? null);
+  if (opts.upload) await result.upload();
+  return result;
+}
+
+// src/index.ts
+installNodeCrypto();
+async function init(opts = {}) {
+  const rec = configure(opts);
+  const key = rec.apiKey;
+  if (!key) return rec;
+  try {
+    await rec.resolveProject(key);
+  } catch (e) {
+    if (!(e instanceof Error)) throw e;
+    if (!opts.quiet) console.error(`signafaide: ${e.message} Records are kept locally until then.`);
+  }
+  return rec;
+}
+function flush(timeoutMs) {
+  return getRecorder().flush(timeoutMs);
+}
+function stop(timeoutMs) {
+  return getRecorder().stop(timeoutMs);
+}
+function status() {
+  return getRecorder().status();
+}
+function chainBases(st, chainIds) {
+  const out = {};
+  for (const c of new Set(chainIds)) {
+    const b = st.chainBase(c);
+    if (b) out[c] = b;
+  }
+  return out;
+}
+function checkHeld(rec) {
+  const keys2 = new Map(rec.state.agentPublicKeys().map((k) => [k.key_id, k]));
+  const failures = [];
+  let records = 0;
+  const segs = rec.state.heldSegments();
+  for (const [chain, file, recs] of segs) {
+    let prev = null;
+    for (const r of recs) {
+      records++;
+      const item = `${chain}#${r.envelope.seq} (held, ${path3.basename(file)})`;
+      const k = keys2.get(r.key_id);
+      if (!k) failures.push({ check: "record_sig", item, message: `no key ${r.key_id} for agent ${r.envelope.agent} on this machine` });
+      else if (!verifySig(k.public_key, r.draft ? "draft" : "record", recordHash(r), r.sig)) failures.push({ check: "record_sig", item, message: "signature does not verify" });
+      if (prev && (r.envelope.seq !== prev.envelope.seq + 1 || r.envelope.prev !== recordHash(prev))) failures.push({ check: "chain", item, message: "does not follow the held record before it" });
+      try {
+        const h = checkContent(r.content, r.salt, r.envelope.content_hash);
+        if (h) failures.push({ check: "content", item, message: `content hashes to ${h}, envelope says ${r.envelope.content_hash}` });
+      } catch (e) {
+        failures.push({ check: "content", item, message: e.message });
+      }
+      prev = r;
+    }
+  }
+  return { records, segments: segs.length, failures };
+}
+async function readInput(src, flag) {
+  if (typeof src !== "string") return src;
+  if (/^https?:\/\//.test(src)) {
+    if (src.startsWith("http://")) {
+      if (!isLoopbackUrl(src)) {
+        throw new Error(`${flag} ${src} uses plain http://, which anyone on the network path can alter; use https:// (plain http is accepted only from this machine, e.g. http://127.0.0.1)`);
+      }
+      console.error(`WARNING: ${flag} ${src} uses plain http:// on this machine; the keys do not count as independent`);
+    }
+    return parseJson(JSON.stringify(await (await import("./http-BZI6VZM3.js")).fetchJson(src)));
+  }
+  return parseJson(fs4.readFileSync(src, "utf8"));
+}
+var plainHttp = (src) => typeof src === "string" && src.startsWith("http://");
+function notYet(unsent, total, hasKey) {
+  if (!unsent) return [];
+  const what = unsent === total ? `all ${total}` : `${unsent} of ${total}`;
+  return [
+    `checked here: signatures, chain links and content hashes of ${what} record${total === 1 ? "" : "s"}, using this machine's keys`,
+    hasKey ? `co-signature, public timestamp: not yet for ${what} (\`signafaide flush\` sends them now, or says why it cannot)` : "co-signature, public timestamp: not yet. Run `signafaide init` to send hashes, or self-host (SIGNAFAIDE_URL)"
+  ];
+}
+function loadContent(src) {
+  const out = /* @__PURE__ */ new Map();
+  const walk = (p) => {
+    if (fs4.statSync(p).isDirectory()) for (const f of fs4.readdirSync(p).sort()) walk(path3.join(p, f));
+    else if (p === src || p.endsWith(".jsonl")) contentFromText(fs4.readFileSync(p, "utf8"), out);
+  };
+  walk(src);
+  return out;
+}
+async function verify2(pack, opts = {}) {
+  const rec = getRecorder();
+  const notes = [];
+  let keys2 = null;
+  let keysPlain = false;
+  if (opts.keys !== void 0) {
+    keys2 = parseServiceKeys(await readInput(opts.keys, "--keys"));
+    keysPlain = plainHttp(opts.keys);
+    notes.push(`service keys: ${typeof opts.keys === "string" ? opts.keys : "given"}`);
+  } else if (pack == null && !Object.keys(rec.state.chainHeads()).length) {
+    keys2 = [];
+  } else if (pack == null || !opts.trustEmbeddedKeys) {
+    const url = `${rec.url}/.well-known/signafaide-keys.json`;
+    if (url.startsWith("http://") && !isLoopbackUrl(url)) {
+      throw new KeysRequired(`will not fetch service keys over plain http from ${url}: anyone on the network path can alter them; pass --keys <file|https url>`);
+    }
+    keysPlain = url.startsWith("http://");
+    try {
+      keys2 = parseServiceKeys(await rec.client().request("GET", "/.well-known/signafaide-keys.json", { auth: false }));
+      notes.push(`service keys: ${url}${keysPlain ? " (plain http on this machine: not independent)" : ""}`);
+    } catch (e) {
+      if (pack != null || Object.keys(rec.state.chainHeads()).length) {
+        throw new KeysRequired(`could not load service keys from ${url} (${e.message}); pass --keys <file|url>`);
+      }
+      keys2 = [];
+    }
+  }
+  const drand = await loadDrandVerifier();
+  let report;
+  if (pack == null) {
+    const st = rec.state;
+    const agentKeys = st.agentPublicKeys().map((k) => ({ agent: k.agent, key_id: k.key_id, public_key: k.public_key, valid_from: null, valid_to: k.retired }));
+    const records = [];
+    const chainIds = [];
+    for (const chain of st.chains()) {
+      for (const r of st.readAll(chain)) {
+        records.push(r);
+        chainIds.push(chain);
+      }
+    }
+    report = verifyLocalState({ records, chainIds, agentKeys, heads: st.chainHeads(), bases: chainBases(st, chainIds) }, keys2 ?? [], drand, keysPlain);
+    notes.unshift(`local state: ${st.home}`);
+    const unsent = records.filter((r) => !r.receipt).length;
+    report.after.push(...notYet(unsent, records.length, !!rec.apiKey));
+    const held = checkHeld(rec);
+    if (held.segments) {
+      for (const f of held.failures) {
+        const c = report.check(f.check);
+        c.failures.push({ item: f.item, message: f.message });
+        c.status = "fail";
+      }
+      report.after.push(`held aside by \`signafaide repair\`: ${plural(held.records, "record")} in ${plural(held.segments, "segment")} (signatures, links and content hashes checked here; not co-signed)`);
+    }
+    for (const b of rec.diagnose()) report.blocked.push(`${b.chain}: ${b.reason}; ${plural(b.records, "record")} cannot ship. Next: ${b.next}`);
+    if (opts.failOnPendingSend) report.notSent = unsent;
+  } else {
+    const p = typeof pack === "string" ? parseJson(fs4.readFileSync(pack, "utf8")) : pack;
+    const chainDir = path3.join(rec.state.home, "chain");
+    const content = opts.content ?? (fs4.existsSync(chainDir) ? chainDir : void 0);
+    let agentKeys = null;
+    if (opts.agentKeys !== void 0) {
+      agentKeys = parseAgentKeys(await readInput(opts.agentKeys, "--agent-keys"));
+      notes.push(`agent keys: ${typeof opts.agentKeys === "string" ? opts.agentKeys : "given"}`);
+    } else if (!opts.trustEmbeddedAgentKeys) {
+      const own = rec.state.agentPublicKeys().map((k) => ({ agent: k.agent, key_id: k.key_id, public_key: k.public_key, valid_from: k.created, valid_to: k.retired }));
+      if (own.length) {
+        agentKeys = own;
+        notes.push(`agent keys: this project's own (${path3.join(rec.state.home, "agents")})`);
+      }
+    }
+    let heads = opts.head !== void 0 ? parseHeadFile(await readInput(opts.head, "--head")) : null;
+    if (opts.head === void 0) {
+      const own = parseHeadFile(rec.state.heads());
+      if (own.length) {
+        heads = own;
+        notes.push(`head: this project's own (${path3.join(rec.state.home, "head.json")})`);
+      }
+    }
+    const heights = timestampHeights(p);
+    const timestamps = opts.offline || !heights.length ? null : await lookupTimestamps(opts.timestampCheck ?? DEFAULT_TIMESTAMP_URL, heights);
+    report = verifyPack(p, keys2, {
+      trustEmbeddedKeys: opts.trustEmbeddedKeys,
+      agentKeys,
+      trustEmbeddedAgentKeys: opts.trustEmbeddedAgentKeys,
+      heads,
+      timestamps,
+      contents: content ? loadContent(content) : void 0,
+      drand,
+      serviceKeysPlainHttp: keysPlain,
+      agentKeysPlainHttp: plainHttp(opts.agentKeys)
+    });
+    if (!agentKeys && !opts.trustEmbeddedAgentKeys) notes.push("no agent keys: ask the customer for `signafaide keys export -o agent-keys.json` and pass --agent-keys agent-keys.json");
+  }
+  if (!drand && report.check("drand").checked) notes.push(DRAND_NOT_CHECKED);
+  report.notes.unshift(...notes);
+  return report;
+}
+
+export {
+  TOOL_SOURCE_REFRESH_MS,
+  TOOL_SOURCE_MAX_AGE_MS,
+  StateError,
+  findRoot,
+  State,
+  recordingDisabled,
+  testMode,
+  Recorder,
+  envOf,
+  getRecorder,
+  configure,
+  termsNotice,
+  NotRecorded,
+  autoDeclareTools,
+  declareTools,
+  record,
+  note,
+  wrapTools,
+  wrapTool,
+  toJsonable,
+  loadServiceKeys,
+  Entry,
+  Replay,
+  replay,
+  VerificationFailed,
+  recordedValue,
+  ExperimentReport,
+  compare,
+  init,
+  flush,
+  stop,
+  status,
+  checkHeld,
+  notYet,
+  loadContent,
+  verify2 as verify
+};