@synadia-ai/agent-fabric 0.1.0 → 0.2.0

package/dist/index.js

@@ -1,13 +1,14 @@
 import { RequestRejectedError, SenderGate } from '@synadia-ai/agent-service';
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { SILENT_LOGGER, NatsAgentError, SenderSignatureRequiredError, readContextFile } from '@synadia-ai/agents';
+import { SILENT_LOGGER, assertValidSenderName, resolveNatsConnectionBundle, withAgentReconnectDefaults, Agents, NatsAgentError, SenderSignatureRequiredError, readContextFile } from '@synadia-ai/agents';
+import { connect } from '@nats-io/transport-node';
 import { execFile } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
 import { mkdir, realpath } from 'node:fs/promises';
 import { tmpdir, platform, arch, homedir } from 'node:os';
 import { join, resolve } from 'node:path';
+import { mkdirSync, readFileSync, writeFileSync, renameSync, openSync, constants, fstatSync, readSync, closeSync, lstatSync, realpathSync, fsyncSync } from 'node:fs';
 import { headers } from '@nats-io/nats-core';
-import { mkdirSync, readFileSync, writeFileSync, renameSync, lstatSync, realpathSync, openSync, constants, fsyncSync, closeSync } from 'node:fs';
 
 // src/tracing.ts
 var EDGE_RECORD_VERSION = 1;
@@ -211,6 +212,229 @@ function lineageField(extras, wireName) {
   }
   return value;
 }
+var CALLER_INBOX_PREFIX = "_INBOX.agents";
+var CANNOT_ANSWER = "The caller is a command line and cannot answer; continue with your best judgement.";
+var DEFAULT_DISCOVER_TIMEOUT_MS = 1e3;
+var NATS_URL_VAR = "NATS_URL";
+var NATS_CREDS_VAR = "NATS_CREDS";
+var FabricCallerError = class extends Error {
+  constructor(reason, message) {
+    super(message);
+    this.reason = reason;
+    this.name = "FabricCallerError";
+  }
+  reason;
+};
+var CallerStream = class {
+  #inner;
+  #sink;
+  constructor(inner, sink) {
+    this.#inner = inner;
+    this.#sink = sink;
+  }
+  /** The subject the prompt is published to. */
+  get subject() {
+    return this.#inner.subject;
+  }
+  /** Stop the stream, as `PromptStream.cancel()`. */
+  cancel() {
+    this.#sink.reject(notSent("it was cancelled"));
+    this.#inner.cancel();
+  }
+  async *[Symbol.asyncIterator]() {
+    try {
+      for await (const msg of this.#inner) yield msg;
+    } catch (err) {
+      this.#sink.reject(err);
+      throw err;
+    } finally {
+      this.#sink.reject(notSent("its stream ended first"));
+    }
+  }
+};
+function notSent(why) {
+  return new FabricCallerError("not-sent", `the prompt never went out, so it has no root: ${why}`);
+}
+var ROOT_SINK_KEY = "agentFabricCallerRootSink";
+function rootDeferred() {
+  let settled = false;
+  let resolve3;
+  let reject2;
+  const rootId = new Promise((res, rej) => {
+    resolve3 = res;
+    reject2 = rej;
+  });
+  rootId.catch(() => {
+  });
+  const once = (fn) => (v) => {
+    if (settled) return;
+    settled = true;
+    fn(v);
+  };
+  return { rootId, sink: { resolve: once(resolve3), reject: once(reject2) } };
+}
+async function fabricCaller(options) {
+  const creds = options.creds;
+  if (typeof creds !== "string" || creds.length === 0) {
+    throw new FabricCallerError(
+      "config",
+      `no creds file: pass creds, or set ${NATS_CREDS_VAR} to the creds file the console gave you`
+    );
+  }
+  const url = options.url ?? process.env[NATS_URL_VAR];
+  if (url === void 0 || url.length === 0) {
+    throw new FabricCallerError(
+      "config",
+      `no server URL: pass url, or set ${NATS_URL_VAR} to the URL the console showed next to your creds file`
+    );
+  }
+  const tracing = fabricTracing(
+    options.edgeSubject !== void 0 ? { edgeSubject: options.edgeSubject } : {}
+  );
+  if (options.name !== void 0) {
+    try {
+      assertValidSenderName(options.name);
+    } catch (err) {
+      throw new FabricCallerError("config", `name: ${errorMessage(err)}`);
+    }
+  }
+  let bundle;
+  try {
+    bundle = await resolveNatsConnectionBundle({ url, creds }, { identity: "signed" });
+  } catch (err) {
+    throw new FabricCallerError("config", `creds file ${creds}: ${errorMessage(err)}`);
+  }
+  let nc;
+  try {
+    nc = await connect(
+      withAgentReconnectDefaults({
+        ...bundle.connectionOptions,
+        inboxPrefix: CALLER_INBOX_PREFIX,
+        ...options.name !== void 0 ? { name: options.name } : {},
+        // A caller is short-lived: a wrong URL fails now, naming the URL,
+        // instead of retrying forever before the first connection.
+        waitOnFirstConnect: false
+      })
+    );
+  } catch (err) {
+    bundle.wipe();
+    throw new FabricCallerError("connect", `could not connect to ${url}: ${errorMessage(err)}`);
+  }
+  let agents;
+  try {
+    agents = new Agents({
+      nc,
+      identity: {
+        signer: bundle.signer,
+        ...options.name !== void 0 ? { name: options.name } : {}
+      },
+      interceptors: [rootCapturing(tracing.promptInterceptor)]
+    });
+  } catch (err) {
+    await nc.close();
+    bundle.wipe();
+    throw err;
+  }
+  try {
+    await agents.selfId();
+  } catch (err) {
+    await agents.close();
+    await nc.close();
+    bundle.wipe();
+    throw new FabricCallerError(
+      "identity",
+      `the server at ${url} would not tell this creds file's identity, which signing needs: ${errorMessage(err)}`
+    );
+  }
+  const list = (opts = {}) => agents.discover({ timeoutMs: opts.timeoutMs ?? DEFAULT_DISCOVER_TIMEOUT_MS });
+  const find = async (who, opts = {}) => pickAgent(await list(opts), who);
+  const prompt = async (who, text2, promptOptions = {}) => {
+    const target = typeof who === "string" ? await find(who) : who;
+    const { sink, rootId } = rootDeferred();
+    let inner;
+    try {
+      inner = await target.prompt(text2, {
+        ...promptOptions,
+        context: { ...promptOptions.context ?? {}, [ROOT_SINK_KEY]: sink }
+      });
+    } catch (err) {
+      sink.reject(err);
+      throw err;
+    }
+    return { stream: new CallerStream(inner, sink), rootId };
+  };
+  const ask = async (who, text2, askOptions = {}) => {
+    const { onQuery, ...promptOptions } = askOptions;
+    const { stream, rootId } = await prompt(who, text2, promptOptions);
+    let reply = "";
+    for await (const msg of stream) {
+      if (msg.type === "response") reply += msg.text;
+      else if (msg.type === "query") {
+        const answer = onQuery !== void 0 ? await onQuery(msg) : "";
+        await msg.reply(answer.trim() === "" ? CANNOT_ANSWER : answer);
+      }
+    }
+    return { text: reply, rootId: await rootId };
+  };
+  let closed = false;
+  const close = async () => {
+    if (closed) return;
+    closed = true;
+    try {
+      await agents.close();
+      await nc.close();
+    } finally {
+      bundle.wipe();
+    }
+  };
+  return { agents, url, list, find, prompt, ask, close };
+}
+function fabricCallerFromEnv(options = {}) {
+  return fabricCaller({ ...options, creds: process.env[NATS_CREDS_VAR] ?? "" });
+}
+function pickAgent(found, who) {
+  const byAddress = found.find((a) => a.promptSubject === who);
+  if (byAddress !== void 0) return byAddress;
+  const ofKind = distinctAddresses(found.filter((a) => a.agent === who));
+  if (ofKind.length === 1) return ofKind[0];
+  if (ofKind.length > 1) {
+    throw new FabricCallerError(
+      "ambiguous",
+      `${ofKind.length} agents of kind "${who}": ${ofKind.map((a) => a.promptSubject).join(", ")}; name one by its address`
+    );
+  }
+  const there = distinctAddresses(found).map((a) => a.promptSubject).join(", ");
+  throw new FabricCallerError("not-found", `no agent "${who}"; there: ${there || "nobody"}`);
+}
+function distinctAddresses(agents) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const a of agents) if (!seen.has(a.promptSubject)) seen.set(a.promptSubject, a);
+  return [...seen.values()];
+}
+function rootCapturing(inner) {
+  return {
+    async beforePrompt(ctx) {
+      const sink = ctx.context[ROOT_SINK_KEY];
+      let extras;
+      try {
+        extras = await inner.beforePrompt(ctx);
+      } catch (err) {
+        sink?.reject(err);
+        throw err;
+      }
+      const root = extras?.fields?.[ROOT_ID_FIELD];
+      if (typeof root === "string") sink?.resolve(root);
+      else sink?.reject(notSent("tracing minted no root"));
+      return extras;
+    },
+    async beforePublish(ctx, extras) {
+      await inner.beforePublish?.(ctx, extras);
+    }
+  };
+}
+function errorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
 var OUTSIDE_RUN_ID = /[^A-Za-z0-9_-]/gu;
 function durableRunId(toolCallId) {
   if (!validToolCallId(toolCallId)) {
@@ -894,6 +1118,7 @@ var MAX_READ_BYTES = CHUNK_SIZE;
 var MAX_PREPARE_OBJECTS = 64;
 var MAX_VOLUME_OBJECTS = 65536;
 var MAX_VOLUME_BYTES = 8 * 2 ** 30;
+var MAX_ADMISSION_SLOT = 4294967295;
 var WRITER_SLOTS = 8;
 var RETENTION_SLOTS = 8;
 var GRANT_SLOTS = 16;
@@ -908,6 +1133,7 @@ var CODES = [
   "exists",
   "conflict",
   "fenced",
+  "generation_retired",
   "intent_changed",
   "capacity",
   "summary_limit",
@@ -1080,16 +1306,11 @@ function validateGrantHandle(value) {
   uint(v.generation, void 0, 1);
 }
 function validateCommand(value) {
-  const v = record(value, [
-    "creation_id",
-    "writer",
-    "number",
-    "operation_id",
-    "base",
-    "root",
-    "trace",
-    "retention"
-  ]);
+  const v = record(
+    value,
+    ["creation_id", "writer", "number", "operation_id", "base", "root", "trace", "retention"],
+    ["remove_path"]
+  );
   validateTarget({ volume: "v", creation_id: v.creation_id });
   validateWriter(v.writer);
   uint(v.number, void 0, 1);
@@ -1105,6 +1326,10 @@ function validateCommand(value) {
     r.enabled || r.slot === 0 && r.generation === 0 && r.until === 0,
     "disabled retention must be zero"
   );
+  if (v.remove_path !== void 0) {
+    validatePath(v.remove_path);
+    check(v.remove_path !== "/" && !r.enabled, "removal cannot retain or remove the root");
+  }
 }
 function validateReceipt(value) {
   const v = record(value, ["volume", "principal", "command", "head", "retention"]);
@@ -1134,19 +1359,24 @@ function sameValue(a, b) {
   return Object.keys(left).length === Object.keys(right).length && Object.keys(left).every((key) => Object.hasOwn(right, key) && sameValue(left[key], right[key]));
 }
 function validateVolumeView(value) {
-  const v = record(value, [
-    "target",
-    "owner",
-    "head",
-    "revision",
-    "closed",
-    "epoch",
-    "objects",
-    "bytes",
-    "writers",
-    "retentions",
-    "grants"
-  ]);
+  const v = record(
+    value,
+    [
+      "target",
+      "owner",
+      "head",
+      "revision",
+      "closed",
+      "epoch",
+      "objects",
+      "bytes",
+      "writers",
+      "retentions",
+      "grants"
+    ],
+    ["lifetime"]
+  );
+  if (v.lifetime !== void 0) validateLifetimeView(v.lifetime);
   validateTarget(v.target);
   validatePrincipal(v.owner);
   validateHead(v.head);
@@ -1168,12 +1398,12 @@ function validateVolumeView(value) {
     if (slot.principal !== void 0) {
       validatePrincipal(slot.principal);
       check(slot.principal.account === v.owner.account, "writer belongs to another account");
-    } else check(!slot.write && slot.number === 0, "writer identity absent");
+    } else check(!slot.write, "writer identity absent");
     if (slot.number === 0) check(slot.receipt === void 0, "unused writer has a receipt");
     else {
       validateReceipt(slot.receipt);
       check(
-        slot.write && sameValue(slot.receipt.principal, slot.principal) && slot.receipt.volume === v.target.volume && slot.receipt.command.creation_id === v.target.creation_id && slot.receipt.command.writer.slot === index && slot.receipt.command.writer.generation === slot.generation && slot.receipt.command.number === slot.number && slot.receipt.head.generation <= v.head.generation,
+        (slot.principal === void 0 && !slot.write || slot.write && sameValue(slot.receipt.principal, slot.principal)) && slot.receipt.principal.account === v.owner.account && slot.receipt.volume === v.target.volume && slot.receipt.command.creation_id === v.target.creation_id && slot.receipt.command.writer.slot === index && slot.receipt.command.writer.generation === slot.generation && slot.receipt.command.number === slot.number && slot.receipt.head.generation <= v.head.generation,
         "writer receipt differs from slot"
       );
     }
@@ -1235,7 +1465,8 @@ function validateInfo(value) {
   check(Array.isArray(v.scopes) && v.scopes.length <= 16, "scope count exceeds bound");
   const seen = /* @__PURE__ */ new Set();
   for (const raw of v.scopes) {
-    const scope = record(raw, ["volume", "objects", "bytes"]);
+    const scope = record(raw, ["volume", "objects", "bytes"], ["admission"]);
+    if (scope.admission !== void 0) validateAdmissionBinding(scope.admission);
     validateVolume(scope.volume);
     uint(scope.objects, MAX_VOLUME_OBJECTS, 1);
     uint(scope.bytes, MAX_VOLUME_BYTES, 4);
@@ -1248,6 +1479,130 @@ function validateContentObject(value) {
   validateContentID(v.id);
   check(v.kind === "chnk" || v.kind === "fobj" || v.kind === "tree", "unsupported object kind");
 }
+function validateAdmissionBinding(value) {
+  const v = record(value, ["slot", "generation", "operation_id"]);
+  uint(v.slot, MAX_ADMISSION_SLOT);
+  uint(v.generation, void 0, 1);
+  validateAction({ operation_id: v.operation_id, trace: {} });
+}
+function validateLifetimeView(value) {
+  const v = record(value, [
+    "admission",
+    "phase",
+    "expires_at",
+    "grace_until",
+    "max_lease_seconds",
+    "grace_seconds",
+    "recovery_reads",
+    "reserve_objects",
+    "reserve_bytes"
+  ]);
+  validateAdmissionBinding(v.admission);
+  for (const key of ["expires_at", "grace_until", "max_lease_seconds", "grace_seconds"])
+    uint(v[key]);
+  bool(v.recovery_reads);
+  uint(v.reserve_objects, 128);
+  uint(v.reserve_bytes, 8 * 2 ** 20);
+  check(v.reserve_objects === 0 === (v.reserve_bytes === 0), "incomplete metadata reserve");
+  check(
+    v.phase === "active" || v.phase === "shrinking" || v.phase === "expiring",
+    "invalid lifetime phase"
+  );
+  check(
+    v.phase === "expiring" ? v.expires_at > 0 && (v.grace_until === 0 || v.grace_until >= v.expires_at) : v.grace_until === 0,
+    "invalid lifetime grace"
+  );
+  check(
+    v.expires_at === 0 ? v.grace_seconds === 0 : v.max_lease_seconds > 0 && v.grace_seconds > 0,
+    "invalid lease policy"
+  );
+}
+function validateRenewRequest(value) {
+  const v = record(value, ["target", "until"]);
+  validateTarget(v.target);
+  uint(v.until, void 0, 1);
+}
+function validateRemovalRequest(value) {
+  const v = record(value, ["target", "command"]);
+  validateTarget(v.target);
+  validateCommand(v.command);
+  check(
+    v.command.remove_path && v.command.creation_id === v.target.creation_id,
+    "invalid removal command"
+  );
+}
+function validateRemovalPlan(value) {
+  const v = record(value, [
+    "target",
+    "slot",
+    "generation",
+    "sequence",
+    "command",
+    "added_objects",
+    "added_bytes"
+  ]);
+  validateRemovalRequest({ target: v.target, command: v.command });
+  uint(v.slot, MAX_ADMISSION_SLOT);
+  uint(v.generation, void 0, 1);
+  uint(v.sequence, void 0, 1);
+  uint(v.added_objects, 128);
+  uint(v.added_bytes, 8 * 2 ** 20);
+}
+function validateVolumeReleaseRequest(value) {
+  const v = record(value, ["target", "operation_id", "end_promises"]);
+  validateTarget(v.target);
+  validateAction({ operation_id: v.operation_id, trace: {} });
+  bool(v.end_promises);
+}
+function validateVolumeReleasePlan(value) {
+  const v = record(value, [
+    "request",
+    "incarnation",
+    "slot",
+    "generation",
+    "sequence",
+    "head",
+    "effects"
+  ]);
+  validateVolumeReleaseRequest(v.request);
+  text(v.incarnation, 64, 64);
+  check(/^[0-9a-f]{64}$/.test(v.incarnation), "invalid release incarnation");
+  uint(v.slot, MAX_ADMISSION_SLOT);
+  uint(v.generation, void 0, 1);
+  uint(v.sequence, void 0, 1);
+  validateHead(v.head);
+  const effects = record(v.effects, [
+    "objects",
+    "bytes",
+    "retentions",
+    "read_grants",
+    "access_slots",
+    "references"
+  ]);
+  uint(effects.objects, MAX_VOLUME_OBJECTS);
+  uint(effects.bytes, MAX_VOLUME_BYTES);
+  uint(effects.retentions, RETENTION_SLOTS);
+  uint(effects.read_grants, GRANT_SLOTS);
+  uint(effects.access_slots, WRITER_SLOTS);
+  uint(effects.references, RETENTION_SLOTS);
+}
+function validateVolumeReleaseResult(value) {
+  const v = record(value, [
+    "target",
+    "slot",
+    "generation",
+    "operation_id",
+    "disposed",
+    "capacity_returned"
+  ]);
+  validateTarget(v.target);
+  uint(v.slot, MAX_ADMISSION_SLOT);
+  uint(v.generation, void 0, 1);
+  validateAction({ operation_id: v.operation_id, trace: {} });
+  bool(v.disposed);
+  bool(v.capacity_returned);
+  check(!v.capacity_returned || v.disposed, "capacity returned before disposal");
+}
 function validateObjectSpec(value) {
   const v = record(value, ["object", "length"]);
   validateContentObject(v.object);
@@ -2002,6 +2357,45 @@ function validateReferenceRetainResult(value) {
     previous = ref.path;
   }
 }
+var MAX_BOOTSTRAP_BYTES = 4096;
+function decodeScratchPadBootstrap(data) {
+  const value = record(parseStrictJSON(data, MAX_BOOTSTRAP_BYTES), [
+    "version",
+    "principal",
+    "volume",
+    "admission",
+    "creation"
+  ]);
+  check(value.version === 1, "unsupported ScratchPad bootstrap version");
+  validatePrincipal(value.principal);
+  validateVolume(value.volume);
+  validateAdmissionBinding(value.admission);
+  validateAction(value.creation);
+  return value;
+}
+function readScratchPadBootstrapFile(path) {
+  check(typeof path === "string" && path.length > 0, "bootstrap file path is required");
+  let fd;
+  try {
+    fd = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK | (constants.O_NOFOLLOW ?? 0));
+    const stat = fstatSync(fd);
+    check(stat.isFile(), "bootstrap must be a regular file");
+    check(stat.size <= MAX_BOOTSTRAP_BYTES, "bootstrap exceeds its byte bound");
+    const bytes = Buffer.alloc(MAX_BOOTSTRAP_BYTES + 1);
+    let count2 = 0;
+    while (count2 < bytes.length) {
+      const read = readSync(fd, bytes, count2, bytes.length - count2, count2);
+      if (read === 0) break;
+      count2 += read;
+    }
+    return decodeScratchPadBootstrap(bytes.subarray(0, count2));
+  } catch (cause) {
+    if (cause instanceof NativeScratchPadError) throw cause;
+    throw invalid("cannot read ScratchPad bootstrap file", cause);
+  } finally {
+    if (fd !== void 0) closeSync(fd);
+  }
+}
 
 // src/scratchpad-cli.ts
 var DEFAULT_SP_BIN = "sp";
@@ -2160,6 +2554,15 @@ function cleanupCannotHelp(view, at = now()) {
   return room ? void 0 : "every retention slot holds a live pin";
 }
 function spCliScratchPad(options) {
+  const bootstrap = options.bootstrapFile === void 0 ? void 0 : readScratchPadBootstrapFile(options.bootstrapFile);
+  const selectedVolume = options.volume ?? bootstrap?.volume;
+  if (!selectedVolume || !VOLUME_RE.test(selectedVolume))
+    throw new Error("ScratchPad: a valid volume or bootstrap file is required");
+  const volumeName = selectedVolume;
+  if (bootstrap && bootstrap.volume !== volumeName)
+    throw new Error("ScratchPad: bootstrap differs from the configured volume");
+  if (bootstrap && !options.dir)
+    throw new Error("ScratchPad: bootstrap import requires a persistent dir");
   if (!("creds" in options.nats) || options.nats.creds === void 0) {
     throw new Error(
       "ScratchPad: the sp CLI needs NATS_URL and NATS_CREDS; a NATS context or an nkey seed alone is not supported"
@@ -2167,7 +2570,7 @@ function spCliScratchPad(options) {
   }
   const connection = ["--url", options.nats.url, "--creds", options.nats.creds];
   const bin = options.bin ?? DEFAULT_SP_BIN;
-  const configuredDir = options.dir ?? join(tmpdir(), `scratchpad-${options.volume}`);
+  const configuredDir = options.dir ?? join(tmpdir(), `scratchpad-${volumeName}`);
   const grantTtlS = Math.min(options.grantTtlS ?? DEFAULT_GRANT_TTL_S, DEFAULT_GRANT_TTL_S);
   let dir;
   let binding;
@@ -2216,8 +2619,18 @@ function spCliScratchPad(options) {
   async function sp(command, args, opts = {}) {
     const trace = opts.trace ? ["--thread-id", opts.trace.threadId, "--root-id", opts.trace.rootId] : [];
     if (opts.trace && opts.toolCallId !== void 0) trace.push("--tool-call-id", opts.toolCallId);
-    const volume = ["read", "resolve"].includes(command) ? [] : ["--volume", options.volume];
-    const argv = [command, ...connection, "--dir", await workspace(), ...volume, ...args, ...trace];
+    const volume = ["read", "resolve"].includes(command) ? [] : ["--volume", volumeName];
+    const bootstrapArgs = command === "init" && options.bootstrapFile ? ["--bootstrap-file", options.bootstrapFile] : [];
+    const argv = [
+      command,
+      ...connection,
+      "--dir",
+      await workspace(),
+      ...volume,
+      ...bootstrapArgs,
+      ...args,
+      ...trace
+    ];
     const maxStdout = opts.maxStdout ?? MAX_STDOUT;
     const { code, stdout, stderr } = await new Promise((resolve3) => {
       const child = execFile(
@@ -2278,7 +2691,7 @@ function spCliScratchPad(options) {
         false
       );
     }
-    if (r.target.volume !== options.volume) {
+    if (r.target.volume !== volumeName) {
       throw new ScratchPadError(
         `sp ${command}: the workspace is bound to another volume`,
         "invalid",
@@ -2573,6 +2986,7 @@ function spCliScratchPad(options) {
   return pad;
 }
 var SCRATCHPAD_VOLUME_VAR = "SCRATCHPAD_VOLUME";
+var SCRATCHPAD_BOOTSTRAP_FILE_VAR = "SCRATCHPAD_BOOTSTRAP_FILE";
 var SCRATCHPAD_BIN_VAR = "SCRATCHPAD_BIN";
 var SCRATCHPAD_DIR_VAR = "SCRATCHPAD_DIR";
 var SCRATCHPAD_GRANT_TTL_S_VAR = "SCRATCHPAD_GRANT_TTL_S";
@@ -2582,7 +2996,8 @@ function scratchPadFromEnv(env = process.env, options = {}) {
     return value === void 0 || value === "" ? void 0 : value;
   };
   const volume = optional(SCRATCHPAD_VOLUME_VAR);
-  if (volume === void 0) return void 0;
+  const bootstrapFile = optional(SCRATCHPAD_BOOTSTRAP_FILE_VAR);
+  if (volume === void 0 && bootstrapFile === void 0) return void 0;
   const ttl = optional(SCRATCHPAD_GRANT_TTL_S_VAR);
   let grantTtlS;
   if (ttl !== void 0) {
@@ -2598,7 +3013,8 @@ function scratchPadFromEnv(env = process.env, options = {}) {
   const bin = optional(SCRATCHPAD_BIN_VAR);
   const dir = optional(SCRATCHPAD_DIR_VAR);
   return spCliScratchPad({
-    volume,
+    ...volume === void 0 ? {} : { volume },
+    ...bootstrapFile === void 0 ? {} : { bootstrapFile },
     nats,
     ...bin !== void 0 ? { bin } : {},
     ...dir !== void 0 ? { dir } : {},
@@ -2693,6 +3109,12 @@ function loopGuard() {
     waiting
   };
 }
+function normalizeCommand(command) {
+  return {
+    ...command,
+    trace: Object.fromEntries(Object.entries(command.trace).filter(([, value]) => value !== ""))
+  };
+}
 function pathRequest(v) {
   validateTarget(v.target);
   validateContentID(v.root);
@@ -2706,11 +3128,27 @@ function validateRequest(verb, value) {
       validateEmpty(value);
       return;
     case "volume.create": {
-      const v = record(value, ["volume", "action"]);
+      const v = record(value, ["volume", "action"], ["admission"]);
       validateVolume(v.volume);
       validateAction(v.action);
+      if (v.admission !== void 0) validateAdmissionBinding(v.admission);
       return;
     }
+    case "volume.renew":
+      validateRenewRequest(value);
+      return;
+    case "volume.remove.plan":
+      validateRemovalRequest(value);
+      return;
+    case "volume.remove.apply":
+      validateRemovalPlan(value);
+      return;
+    case "volume.release.plan":
+      validateVolumeReleaseRequest(value);
+      return;
+    case "volume.release.apply":
+      validateVolumeReleasePlan(value);
+      return;
     case "volume.get": {
       const v = record(value, ["target"]);
       validateTarget(v.target);
@@ -2775,6 +3213,7 @@ function validateRequest(verb, value) {
       const v = record(value, ["target", "command"]);
       validateTarget(v.target);
       validateCommand(v.command);
+      check(v.command.remove_path === void 0, "removal requires volume.remove.apply");
       check(
         v.target.creation_id === v.command.creation_id,
         "command names another creation identity"
@@ -3029,6 +3468,88 @@ var ScratchPadTransport = class {
       options
     );
     this.matching(result.target.volume === expected.volume, true, "reply names another volume");
+    this.matching(
+      sameValue(result.lifetime?.admission, expected.admission),
+      true,
+      "creation reply names another admission"
+    );
+    return result;
+  }
+  async renewLease(request, options = {}) {
+    const expected = structuredClone(request);
+    const result = await this.view("volume.renew", expected.target, expected, true, options);
+    this.matching(
+      result.lifetime !== void 0 && result.lifetime.expires_at >= expected.until,
+      true,
+      "renewal reply differs from saved deadline"
+    );
+    return result;
+  }
+  async planRemoval(request, options = {}) {
+    const expected = structuredClone(request);
+    const result = await this.control(
+      "volume.remove.plan",
+      expected,
+      validateRemovalPlan,
+      false,
+      options
+    );
+    this.matching(
+      sameValue(result.target, expected.target) && sameValue(
+        normalizeCommand(result.command),
+        normalizeCommand({ ...expected.command, root: result.command.root })
+      ),
+      false,
+      "removal plan changed requested intent"
+    );
+    return result;
+  }
+  async applyRemoval(plan, options = {}) {
+    const expected = structuredClone(plan);
+    const result = await this.control(
+      "volume.remove.apply",
+      expected,
+      validateReceipt,
+      true,
+      options
+    );
+    this.matching(
+      result.volume === expected.target.volume && sameValue(normalizeCommand(result.command), normalizeCommand(expected.command)),
+      true,
+      "removal receipt changed saved command"
+    );
+    return result;
+  }
+  async planVolumeRelease(request, options = {}) {
+    const expected = structuredClone(request);
+    const result = await this.control(
+      "volume.release.plan",
+      expected,
+      validateVolumeReleasePlan,
+      false,
+      options
+    );
+    this.matching(
+      sameValue(result.request, expected),
+      false,
+      "release plan changed requested disposition"
+    );
+    return result;
+  }
+  async applyVolumeRelease(plan, options = {}) {
+    const expected = structuredClone(plan);
+    const result = await this.control(
+      "volume.release.apply",
+      expected,
+      validateVolumeReleaseResult,
+      true,
+      options
+    );
+    this.matching(
+      sameValue(result.target, expected.request.target) && result.slot === expected.slot && result.generation === expected.generation && result.operation_id === expected.request.operation_id,
+      true,
+      "release reply changed saved lifetime or operation"
+    );
     return result;
   }
   getVolume(target, options = {}) {
@@ -3103,12 +3624,8 @@ var ScratchPadTransport = class {
       true,
       options
     );
-    const normalize = (command) => ({
-      ...command,
-      trace: Object.fromEntries(Object.entries(command.trace).filter(([, value]) => value !== ""))
-    });
     this.matching(
-      result.volume === expected.target.volume && sameValue(normalize(result.command), normalize(expected.command)),
+      result.volume === expected.target.volume && sameValue(normalizeCommand(result.command), normalizeCommand(expected.command)),
       true,
       "receipt names another command"
     );
@@ -3620,13 +4137,48 @@ function validateState(value) {
   const s = record(
     value,
     ["version", "principal", "volume", "creator", "creation", "next", "grants"],
-    ["target", "writer", "pending", "last"]
+    [
+      "target",
+      "writer",
+      "pending",
+      "last",
+      "admission",
+      "removal",
+      "disposal",
+      "renewal",
+      "disposal_plan",
+      "release_acceptance_unknown"
+    ]
   );
   check(s.version === 1, "unsupported workspace version");
   validatePrincipal(s.principal);
   validateVolume(s.volume);
   text(s.creator, 512, 1);
   validateAction(s.creation);
+  if (s.admission !== void 0) validateAdmissionBinding(s.admission);
+  if (s.removal !== void 0) {
+    validateReceipt(s.removal);
+    check(
+      s.removal.command.remove_path && s.removal.volume === s.volume && sameValue(s.removal.principal, s.principal) && s.removal.command.creation_id === s.target?.creation_id,
+      "saved removal differs from workspace"
+    );
+  }
+  if (s.disposal !== void 0) {
+    validateVolumeReleaseResult(s.disposal);
+    check(
+      s.disposal.capacity_returned && !s.pending && sameValue(s.disposal.target, s.target) && s.disposal.slot === s.admission?.slot && s.disposal.generation === s.admission?.generation,
+      "unfinished or foreign disposal"
+    );
+  }
+  if (s.disposal_plan !== void 0) {
+    validateVolumeReleasePlan(s.disposal_plan);
+    check(
+      s.disposal && sameValue(s.disposal_plan.request.target, s.disposal.target) && s.disposal_plan.slot === s.disposal.slot && s.disposal_plan.generation === s.disposal.generation && s.disposal_plan.request.operation_id === s.disposal.operation_id,
+      "completed release plan differs from disposal"
+    );
+  }
+  if (s.release_acceptance_unknown !== void 0)
+    check(s.release_acceptance_unknown === true && s.disposal, "invalid release acceptance marker");
   uint(s.next, void 0, 1);
   if (s.target !== void 0) {
     validateTarget(s.target);
@@ -3636,6 +4188,13 @@ function validateState(value) {
     validateWriter(s.writer);
     check(s.writer.slot === 0 && s.target, "workspace writer binding is invalid");
   }
+  if (s.renewal !== void 0) {
+    validateRenewRequest(s.renewal);
+    check(
+      s.admission && sameValue(s.renewal.target, s.target) && !s.disposal && !["renew", "volume_release"].includes(s.pending?.kind ?? ""),
+      "saved renewal conflicts with the workspace lifetime"
+    );
+  }
   check(Array.isArray(s.grants) && s.grants.length <= 16, "workspace grant ledger exceeds bound");
   for (const raw of s.grants) {
     const g = record(raw, ["request", "handle", "kind"]);
@@ -3670,6 +4229,25 @@ function validateState(value) {
     check(s.target, "pending operation has no target");
     const p = s.pending;
     switch (p.kind) {
+      case "renew":
+        record(p, ["kind", "request"]);
+        validateRenewRequest(p.request);
+        break;
+      case "remove":
+        record(p, ["kind", "plan"]);
+        validateRemovalPlan(p.plan);
+        check(
+          sameValue(p.plan.target, s.target) && sameValue(p.plan.command.writer, s.writer) && p.plan.command.number === s.next,
+          "saved removal writer differs"
+        );
+        break;
+      case "volume_release":
+        record(p, ["kind", "plan"], ["fence_accepted"]);
+        if (p.fence_accepted !== void 0)
+          check(p.fence_accepted === true, "invalid release fence marker");
+        validateVolumeReleasePlan(p.plan);
+        check(sameValue(p.plan.request.target, s.target), "saved disposal names another target");
+        break;
       case "publish":
         record(p, ["kind", "command", "path", "ttl"], ["expiry_revision", "reference"]);
         if (p.reference !== void 0) {
@@ -3718,6 +4296,11 @@ function validateState(value) {
     }
     if ("request" in p)
       check(sameValue(p.request.target, s.target), "pending operation names another target");
+    if (p.kind === "remove" || p.kind === "volume_release")
+      check(
+        s.admission && p.plan.slot === s.admission.slot && p.plan.generation === s.admission.generation,
+        "saved plan names another lifetime"
+      );
   }
 }
 function validateGrant(value) {
@@ -3757,12 +4340,18 @@ var NativeScratchPad = class extends ScratchPadReader {
   tail = Promise.resolve();
   closing = false;
   closePromise;
-  run(work) {
+  run(work, allowRenewal = false, allowDisposed = false) {
     if (this.closing)
       return Promise.reject(
         new NativeScratchPadError("closed", "native client is closed", { local: true })
       );
-    const result = this.tail.then(work);
+    const result = this.tail.then(() => {
+      if (this.state.renewal && !allowRenewal)
+        refuse("busy", "recover the saved renewal before another mutation");
+      if (this.state.disposal && !allowDisposed)
+        refuse("fenced", "this workspace lifetime has been released");
+      return work();
+    });
     this.tail = result.then(
       () => {
       },
@@ -3796,7 +4385,8 @@ var NativeScratchPad = class extends ScratchPadReader {
     if (!this.state.target) {
       const view2 = await this.transport.createVolume({
         volume: this.state.volume,
-        action: this.state.creation
+        action: this.state.creation,
+        ...this.state.admission ? { admission: this.state.admission } : {}
       });
       if (!sameValue(view2.owner, this.principal))
         throw unknown(void 0, "volume creation names another owner");
@@ -3808,6 +4398,10 @@ var NativeScratchPad = class extends ScratchPadReader {
       sameValue(view.owner, this.principal),
       "workspace principal is no longer the volume owner"
     );
+    check(
+      sameValue(view.lifetime?.admission, this.state.admission),
+      "workspace lifetime differs from volume"
+    );
     return view;
   }
   async initialize() {
@@ -3836,6 +4430,7 @@ var NativeScratchPad = class extends ScratchPadReader {
     const state = { ...this.state, writer: result, next: 1 };
     delete state.pending;
     delete state.last;
+    delete state.removal;
     this.save(state, true, true);
     return result;
   }
@@ -3867,15 +4462,228 @@ var NativeScratchPad = class extends ScratchPadReader {
     });
   }
   describe() {
+    return this.run(
+      async () => {
+        const volume = await this.ensureTarget();
+        const pending = this.state.pending?.kind ?? (this.state.renewal ? "renew" : void 0);
+        return pending ? { volume, pending } : { volume };
+      },
+      true,
+      true
+    );
+  }
+  /** Save an absolute deadline before sending it. Retries never extend it implicitly. */
+  renewLease(until) {
     return this.run(async () => {
-      const volume = await this.ensureTarget();
-      return this.state.pending ? { volume, pending: this.state.pending.kind } : { volume };
+      const request = { target: this.target(), until };
+      validateRenewRequest(request);
+      if (this.state.disposal) refuse("fenced", "this workspace lifetime has been released");
+      if (this.state.pending?.kind === "volume_release")
+        refuse("busy", "the saved volume release must settle before renewal");
+      if (this.state.pending?.kind === "renew") {
+        if (!sameValue(this.state.pending.request, request))
+          refuse("busy", "recover the saved renewal before changing its deadline");
+        return (await this.lifecycle(this.state.pending, false)).volume;
+      }
+      const saved = this.state.renewal;
+      if (saved && !sameValue(saved, request))
+        refuse("busy", "recover the saved renewal before changing its deadline");
+      if (!saved) this.save({ ...this.state, renewal: request });
+      return this.resumeRenewal(request, !saved);
+    }, true);
+  }
+  async resumeRenewal(request, fresh) {
+    let volume;
+    try {
+      volume = await this.transport.renewLease(request);
+      if (!sameValue(volume.lifetime?.admission, this.state.admission))
+        throw unknown(void 0, "renewal names another lifetime");
+    } catch (error) {
+      if (error instanceof NativeScratchPadError && !error.unknown && (fresh || error.code === "expired")) {
+        const state2 = { ...this.state };
+        delete state2.renewal;
+        this.save(state2, true);
+        throw error;
+      }
+      throw unknown(error, "the saved renewal stays pending; call recover()");
+    }
+    const state = { ...this.state };
+    delete state.renewal;
+    this.save(state, true);
+    return structuredClone(volume);
+  }
+  /** Read-only plan for an initialized writer. The caller chooses the path to remove. */
+  planRemoval(path, options) {
+    return this.run(async () => {
+      if (this.state.pending)
+        refuse("busy", "recover the pending operation before planning removal");
+      check(
+        this.state.writer && this.state.admission,
+        "removal requires an initialized reusable writer"
+      );
+      const view = await this.ensureTarget();
+      return this.transport.planRemoval({
+        target: this.target(),
+        command: {
+          creation_id: this.target().creation_id,
+          writer: this.state.writer,
+          number: this.state.next,
+          operation_id: options.operationId,
+          base: view.head,
+          root: view.head.root,
+          trace: wireTrace(options.trace),
+          remove_path: path,
+          retention: { enabled: false, slot: 0, generation: 0, until: 0 }
+        }
+      });
+    });
+  }
+  applyRemoval(plan) {
+    const saved = structuredClone(plan);
+    return this.run(async () => {
+      validateRemovalPlan(saved);
+      check(
+        sameValue(saved.target, this.target()) && saved.slot === this.state.admission?.slot && saved.generation === this.state.admission.generation,
+        "removal plan names another lifetime"
+      );
+      if (!this.state.pending && this.state.removal && sameValue(this.state.removal.command, saved.command))
+        return structuredClone(this.state.removal);
+      return (await this.beginLifecycle({ kind: "remove", plan: saved })).receipt;
     });
   }
+  /** Lists every promise affected. EndPromises must be explicitly true to authorize release. */
+  planVolumeRelease(options) {
+    return this.run(async () => {
+      if (this.state.pending)
+        refuse("busy", "recover the pending operation before planning release");
+      check(this.state.admission, "volume release requires a reusable lifetime");
+      return this.transport.planVolumeRelease({
+        target: this.target(),
+        operation_id: options.operationId,
+        end_promises: options.endPromises ?? false
+      });
+    });
+  }
+  applyVolumeRelease(plan) {
+    const saved = structuredClone(plan);
+    return this.run(
+      async () => {
+        validateVolumeReleasePlan(saved);
+        if (!this.state.pending && this.state.disposal) {
+          check(sameValue(this.state.disposal_plan, saved), "completed release differs from plan");
+          return this.releaseOutcome();
+        }
+        return (await this.beginLifecycle({ kind: "volume_release", plan: saved })).release;
+      },
+      false,
+      true
+    );
+  }
+  async beginLifecycle(pending) {
+    if (this.state.disposal) refuse("fenced", "this workspace lifetime has been released");
+    if (this.state.pending) {
+      const saved = this.state.pending;
+      const intent = saved.kind === "volume_release" ? { kind: saved.kind, plan: saved.plan } : saved;
+      if (!sameValue(intent, pending))
+        refuse("busy", "recover the saved operation before changing intent");
+      return this.lifecycle(saved, false);
+    }
+    this.change(pending);
+    return this.lifecycle(pending, true);
+  }
+  async lifecycle(pending, fresh) {
+    let result;
+    try {
+      if (pending.kind === "renew") {
+        const volume = await this.transport.renewLease(pending.request);
+        if (!sameValue(volume.lifetime?.admission, this.state.admission))
+          throw unknown(void 0, "renewal names another lifetime");
+        result = { kind: pending.kind, volume };
+      } else if (pending.kind === "remove") {
+        const receipt = await this.transport.applyRemoval(pending.plan);
+        if (!sameValue(receipt.principal, this.principal))
+          throw unknown(void 0, "removal names another principal");
+        result = { kind: pending.kind, receipt };
+      } else {
+        result = {
+          kind: pending.kind,
+          release: await this.transport.applyVolumeRelease(pending.plan)
+        };
+      }
+    } catch (error) {
+      if (pending.kind === "volume_release" && error instanceof NativeScratchPadError && error.code === "generation_retired" && !error.unknown) {
+        const release = {
+          target: pending.plan.request.target,
+          slot: pending.plan.slot,
+          generation: pending.plan.generation,
+          operation_id: pending.plan.request.operation_id,
+          disposed: true,
+          capacity_returned: true
+        };
+        return this.finishRelease(pending.plan, release, !pending.fence_accepted);
+      }
+      if (pending.kind === "volume_release" && !fresh && !pending.fence_accepted && error instanceof NativeScratchPadError && !error.unknown && error.code === "conflict" && await this.releaseFenced(pending.plan)) {
+        const state2 = { ...this.state };
+        delete state2.pending;
+        this.save(state2, true);
+        refuse("fenced", "the saved release cannot take effect; review a new release plan");
+      }
+      if (error instanceof NativeScratchPadError && !error.unknown && (fresh || pending.kind === "renew" && error.code === "expired")) {
+        const state2 = { ...this.state };
+        delete state2.pending;
+        this.save(state2, true);
+        throw error;
+      }
+      throw unknown(error, `the saved ${pending.kind} request stays pending; call recover()`);
+    }
+    if (pending.kind === "volume_release" && result.release) {
+      if (result.release.capacity_returned)
+        return this.finishRelease(pending.plan, result.release, false);
+      this.save({ ...this.state, pending: { ...pending, fence_accepted: true } }, true);
+      return structuredClone(result);
+    }
+    const state = { ...this.state };
+    delete state.pending;
+    if (result.receipt) {
+      state.removal = result.receipt;
+      state.next = result.receipt.command.number + 1;
+    }
+    this.save(state, true);
+    return structuredClone(result);
+  }
+  async releaseFenced(plan) {
+    let current;
+    try {
+      current = await this.transport.planVolumeRelease(plan.request);
+    } catch {
+      return false;
+    }
+    return sameValue(current.request, plan.request) && current.incarnation === plan.incarnation && current.slot === plan.slot && current.generation === plan.generation && current.sequence > plan.sequence;
+  }
+  releaseOutcome() {
+    check(this.state.disposal, "workspace has no completed release");
+    return structuredClone({
+      ...this.state.disposal,
+      ...this.state.release_acceptance_unknown ? { acceptance_unknown: true } : {}
+    });
+  }
+  finishRelease(plan, disposal, acceptanceUnknown) {
+    const state = { ...this.state, disposal, disposal_plan: plan };
+    delete state.pending;
+    if (acceptanceUnknown) state.release_acceptance_unknown = true;
+    this.save(state, true);
+    return { kind: "volume_release", release: this.releaseOutcome() };
+  }
   recover() {
-    return this.run(() => this.recoverPending());
+    return this.run(() => this.recoverPending(), true, true);
   }
   async recoverPending() {
+    if (this.state.renewal)
+      return { kind: "renew", volume: await this.resumeRenewal(this.state.renewal, false) };
+    const lifecycle = this.state.pending;
+    if (lifecycle?.kind === "renew" || lifecycle?.kind === "remove" || lifecycle?.kind === "volume_release")
+      return this.lifecycle(lifecycle, false);
+    if (this.state.disposal) return { kind: "volume_release", release: this.releaseOutcome() };
     if (this.state.pending?.kind === "reset")
       refuse("fenced", "reset outcome needs an explicit resetWriter with the observed generation");
     await this.initialize();
@@ -3890,6 +4698,8 @@ var NativeScratchPad = class extends ScratchPadReader {
       }
     }
     if (pending) {
+      if (pending.kind === "renew" || pending.kind === "remove" || pending.kind === "volume_release")
+        return this.lifecycle(pending, false);
       await this.control(pending, false);
       return { kind: pending.kind };
     }
@@ -3913,6 +4723,9 @@ var NativeScratchPad = class extends ScratchPadReader {
       validateAction({ operation_id: options.operationId, trace });
       if (recover) await this.recoverPending();
       await this.initialize();
+      const scope = this.scope;
+      if (!scope || !sameValue(scope.admission, this.state.admission) || this.state.disposal)
+        refuse("fenced", "workspace has no matching current reservation");
       const pending = this.state.pending;
       if (pending) {
         if (pending.kind !== "publish" || pending.command.operation_id !== options.operationId)
@@ -3937,7 +4750,7 @@ var NativeScratchPad = class extends ScratchPadReader {
       let ordinal = 0, totalBytes = 0;
       const put = (object, data) => {
         totalBytes += data.length;
-        if (totalBytes > this.scope.bytes || ordinal + 1 > this.scope.objects)
+        if (totalBytes > scope.bytes || ordinal + 1 > scope.objects)
           refuse("capacity", "artifact exceeds this volume's configured capacity");
         this.store.putObject(ordinal++, object, data);
       };
@@ -3967,7 +4780,7 @@ var NativeScratchPad = class extends ScratchPadReader {
             "capacity",
             "all retention slots hold live or protected handoffs; cleanup cannot free a slot"
           );
-        const needsCleanup = fullRetention || view.objects + objects.length > this.scope.objects || view.bytes + objects.reduce((n, object) => n + object.length, 0) > this.scope.bytes;
+        const needsCleanup = fullRetention || view.objects + objects.length > scope.objects || view.bytes + objects.reduce((n, object) => n + object.length, 0) > scope.bytes;
         if (needsCleanup) view = await this.maintainInternal();
         const slot = view.retentions.findIndex((entry) => !entry.pin);
         if (slot < 0)
@@ -3975,13 +4788,20 @@ var NativeScratchPad = class extends ScratchPadReader {
             "capacity",
             "all retention slots are occupied; release finished handoffs or wait for their expiry"
           );
-        if (view.objects + objects.length > this.scope.objects || view.bytes + objects.reduce((n, object) => n + object.length, 0) > this.scope.bytes)
+        if (view.objects + objects.length > scope.objects || view.bytes + objects.reduce((n, object) => n + object.length, 0) > scope.bytes)
           refuse("capacity", "live roots and this artifact exceed the volume's capacity");
         const writer = this.state.writer;
         const actual = view.writers[writer.slot];
         if (actual.generation !== writer.generation || actual.number + 1 !== this.state.next)
           refuse("fenced", "remote writer position differs from the durable workspace");
         if (view.closed) refuse("closed", "volume is closed by another maintenance interval");
+        const deadlineClock = now2();
+        const until = Math.min(
+          deadlineClock + ttl,
+          view.lifetime?.expires_at || Number.MAX_SAFE_INTEGER
+        );
+        if (until <= deadlineClock)
+          refuse("expired", "the observed lifetime has no remaining retention window");
         const command = {
           creation_id: this.target().creation_id,
           writer,
@@ -3994,7 +4814,7 @@ var NativeScratchPad = class extends ScratchPadReader {
             enabled: true,
             slot,
             generation: view.retentions[slot].generation,
-            until: now2() + ttl
+            until
           }
         };
         const publication = {
@@ -4325,6 +5145,27 @@ var NativeScratchPad = class extends ScratchPadReader {
     return this.transport.getVolume(this.target());
   }
   async control(control, fresh) {
+    if (control.kind === "apply" && this.state.admission) {
+      let view2;
+      try {
+        view2 = await this.transport.getVolume(control.request.target);
+      } catch (error) {
+        throw unknown(error, "private collection completion has not been observed");
+      }
+      if (view2.epoch > control.request.revision) {
+        const state3 = { ...this.state };
+        delete state3.pending;
+        this.save(state3, true);
+        refuse("fenced", "a later collection epoch superseded the saved interval");
+      }
+      if (view2.epoch < control.request.revision)
+        throw unknown(void 0, "saved collection epoch has not been observed");
+      if (view2.closed) refuse("closed", "the private worker has not reopened the saved interval");
+      const state2 = { ...this.state };
+      delete state2.pending;
+      this.save(state2, true);
+      return;
+    }
     let failure, view, handle;
     let settled = false;
     try {
@@ -4356,13 +5197,13 @@ var NativeScratchPad = class extends ScratchPadReader {
               settled = true;
             }
           } else if (control.kind === "close") {
-            if (view.closed && view.revision === control.request.revision + 1) {
+            if (this.state.admission ? view.epoch === control.request.revision + 1 : view.closed && view.revision === control.request.revision + 1) {
               failure = void 0;
               settled = true;
             } else if (view.revision !== control.request.revision) {
               settled = true;
               failure = new NativeScratchPadError(
-                "conflict",
+                this.state.admission ? "fenced" : "conflict",
                 "saved close is fenced by another revision"
               );
             }
@@ -4376,9 +5217,15 @@ var NativeScratchPad = class extends ScratchPadReader {
       if (error instanceof NativeScratchPadError && !error.unknown && (fresh || control.kind === "release" || control.kind === "grant" && error.code === "expired"))
         settled = true;
     }
+    if (control.kind === "close" && this.state.admission && view && view.epoch > control.request.revision + 1) {
+      const state2 = { ...this.state };
+      delete state2.pending;
+      this.save(state2, true);
+      refuse("fenced", "a later collection epoch superseded the saved close");
+    }
     if (!settled)
       throw unknown(failure, `the saved ${control.kind} request stays pending; call recover()`);
-    if (!failure && control.kind === "close" && (!view?.closed || view.revision !== control.request.revision + 1))
+    if (!failure && control.kind === "close" && (this.state.admission ? view?.epoch !== control.request.revision + 1 : !view?.closed || view.revision !== control.request.revision + 1))
       throw unknown(void 0, "close returned another maintenance interval");
     const state = { ...this.state };
     delete state.pending;
@@ -4389,10 +5236,13 @@ var NativeScratchPad = class extends ScratchPadReader {
       );
       state.grants.push({ request: control.request, handle, kind: control.provenance });
     }
-    if (!failure && control.kind === "close")
+    if (!failure && control.kind === "close" && (!this.state.admission || view.closed))
       state.pending = {
         kind: "apply",
-        request: { target: this.target(), revision: view.revision }
+        request: {
+          target: this.target(),
+          revision: this.state.admission ? control.request.revision + 1 : view.revision
+        }
       };
     this.save(state, true);
     if (failure)
@@ -4406,32 +5256,59 @@ var NativeScratchPad = class extends ScratchPadReader {
   }
 };
 async function nativeScratchPad(options) {
-  validateVolume(options.volume);
+  if (options.volume !== void 0) validateVolume(options.volume);
   text(options.creator, 512, 1);
   const ttl = options.ttlSeconds ?? 600;
   uint(ttl, MAX_GRANT_SECONDS, 1);
   const transport = new ScratchPadTransport(options.nc, options);
   const info = await transport.info();
-  const scope = info.scopes.find((scope2) => scope2.volume === options.volume);
-  if (!scope) refuse("denied", "authenticated principal owns no provisioned scope for this volume");
+  const bootstrap = options.bootstrapFile === void 0 ? void 0 : readScratchPadBootstrapFile(options.bootstrapFile);
+  const volume = options.volume ?? bootstrap?.volume;
+  validateVolume(volume);
+  if (bootstrap) {
+    check(
+      sameValue(bootstrap.principal, info.principal),
+      "bootstrap names another authenticated principal"
+    );
+    check(bootstrap.volume === volume, "bootstrap differs from the configured volume");
+  }
+  const scope = info.scopes.find((scope2) => scope2.volume === volume);
   const store = await WorkspaceStore.open(options.dir);
   try {
     let state = store.load();
     if (state === void 0) {
+      if (!scope)
+        refuse("denied", "authenticated principal owns no provisioned scope for this volume");
+      if (bootstrap && !sameValue(scope.admission, bootstrap.admission))
+        refuse("fenced", "bootstrap does not match the current admission");
       state = {
         version: 1,
         principal: info.principal,
-        volume: options.volume,
+        volume,
         creator: options.creator,
-        creation: { operation_id: randomUUID(), trace: {} },
+        creation: bootstrap ? structuredClone(bootstrap.creation) : { operation_id: randomUUID(), trace: {} },
+        ...scope.admission ? { admission: structuredClone(scope.admission) } : {},
         next: 1,
         grants: []
       };
       store.save(state);
     }
     validateState(state);
+    if (bootstrap) {
+      check(
+        sameValue(state.principal, bootstrap.principal) && state.volume === bootstrap.volume && sameValue(state.admission, bootstrap.admission) && sameValue(state.creation, bootstrap.creation),
+        "workspace differs from the bootstrap creation request"
+      );
+      if (state.disposal || state.disposal_plan || state.pending?.kind === "volume_release")
+        refuse("fenced", "bootstrap cannot reopen a workspace with a saved disposal");
+    }
+    if (!bootstrap && !state.target && (!scope || !sameValue(state.admission, scope.admission)))
+      refuse(
+        "fenced",
+        "saved creation does not match the current admission; it cannot adopt a new lifetime"
+      );
     check(
-      sameValue(state.principal, info.principal) && state.volume === options.volume && state.creator === options.creator,
+      sameValue(state.principal, info.principal) && state.volume === volume && state.creator === options.creator,
       "workspace is bound to another principal, volume, or creator"
     );
     return new NativeScratchPad(transport, store, state, scope, ttl);
@@ -4442,14 +5319,16 @@ async function nativeScratchPad(options) {
 }
 async function nativeScratchPadFromEnv(env, options) {
   const volume = env["SCRATCHPAD_VOLUME"];
-  if (!volume) return void 0;
+  const bootstrapFile = env["SCRATCHPAD_BOOTSTRAP_FILE"] || void 0;
+  if (!volume && !bootstrapFile) return void 0;
   const dir = env["SCRATCHPAD_DIR"];
   check(dir, "SCRATCHPAD_DIR must name a persistent private directory for the native client");
   const value = env["SCRATCHPAD_GRANT_TTL_S"];
   check(value === void 0 || /^[0-9]+$/.test(value), "SCRATCHPAD_GRANT_TTL_S must be an integer");
   return nativeScratchPad({
     ...options,
-    volume,
+    ...volume ? { volume } : {},
+    ...bootstrapFile ? { bootstrapFile } : {},
     dir,
     ...value === void 0 ? {} : { ttlSeconds: Number(value) }
   });
@@ -4472,6 +5351,7 @@ var SP_VARS = {
   creds: "SP_NATS_CREDS",
   dir: SCRATCHPAD_DIR_VAR,
   volume: SCRATCHPAD_VOLUME_VAR,
+  bootstrapFile: SCRATCHPAD_BOOTSTRAP_FILE_VAR,
   creator: "SP_CREATOR",
   threadId: "SP_THREAD_ID",
   rootId: "SP_ROOT_ID",
@@ -4489,8 +5369,13 @@ async function resolveScratchPad(ctx, env) {
     const fromEnv = env[variable];
     return fromEnv === void 0 || fromEnv === "" ? void 0 : fromEnv;
   };
-  const volume = pick("volume", SP_VARS.volume);
+  const configuredBootstrap = pick("bootstrapFile", SP_VARS.bootstrapFile);
+  const bootstrapFile = configuredBootstrap === void 0 ? void 0 : resolve(expandHome(configuredBootstrap));
+  const bootstrap = bootstrapFile === void 0 ? void 0 : readScratchPadBootstrapFile(bootstrapFile);
+  const volume = pick("volume", SP_VARS.volume) ?? bootstrap?.volume;
   if (volume === void 0) return void 0;
+  if (bootstrap && bootstrap.volume !== volume)
+    throw new Error("ScratchPad bootstrap differs from the configured volume");
   let url = pick("url", "NATS_URL");
   let creds = pick("creds", "NATS_CREDS");
   if (url === void 0 || creds === void 0) {
@@ -4520,6 +5405,8 @@ async function resolveScratchPad(ctx, env) {
   if (dir === void 0 && ctx.settings.stateDir !== void 0) {
     dir = join(ctx.settings.stateDir, "scratchpad");
   }
+  if (bootstrap && dir === void 0)
+    throw new Error("ScratchPad bootstrap requires a persistent workspace directory");
   if (dir !== void 0) {
     dir = resolve(expandHome(dir));
     try {
@@ -4534,6 +5421,7 @@ async function resolveScratchPad(ctx, env) {
     url,
     creds: expandHome(creds),
     volume,
+    ...bootstrapFile === void 0 ? {} : { bootstrapFile },
     ...dir !== void 0 ? { dir } : {},
     ...grants !== void 0 ? { grants } : {}
   };
@@ -4541,7 +5429,13 @@ async function resolveScratchPad(ctx, env) {
 function exportScratchPad(settings, env) {
   env[SP_VARS.url] = settings.url;
   env[SP_VARS.creds] = settings.creds;
-  env[SP_VARS.volume] = settings.volume;
+  if (settings.bootstrapFile !== void 0) {
+    env[SP_VARS.bootstrapFile] = settings.bootstrapFile;
+    delete env[SP_VARS.volume];
+  } else {
+    env[SP_VARS.volume] = settings.volume;
+    delete env[SP_VARS.bootstrapFile];
+  }
   if (settings.dir !== void 0) env[SP_VARS.dir] = settings.dir;
   if (settings.grants !== void 0) env[SP_VARS.grants] = settings.grants;
 }
@@ -4658,6 +5552,7 @@ function spPort(settings, creator, env, skillDir) {
   if (bin === void 0) return void 0;
   const port = spCliScratchPad({
     volume: settings.volume,
+    ...settings.bootstrapFile === void 0 ? {} : { bootstrapFile: settings.bootstrapFile },
     nats: { url: settings.url, creds: settings.creds },
     bin,
     creator,
@@ -4728,6 +5623,6 @@ function expandHome(path) {
   return path;
 }
 
-export { DEFAULT_EDGE_SUBJECT, DEFAULT_GRANT_REQUEST_TIMEOUT_MS, DEFAULT_GRANT_TTL_S, DEFAULT_READ_LIMIT_BYTES, DEFAULT_SP_BIN, EDGE_RECORD_VERSION, EDGE_SUBJECT_OPTION, EDGE_SUBJECT_VAR, GRANT_REQUEST_ENDPOINT, HARNESS_THREAD_ID_MAX, LOOP_GUARD_CODE, NativeScratchPad, NativeScratchPadError, READS_REFERENCES_KEY, READS_SCRATCHPAD_REFERENCES_FIELD, REFERENCE_PREFIX, ROOT_ID_FIELD, ROOT_ID_HEADER, SCRATCHPAD_BIN_VAR, SCRATCHPAD_DIR_VAR, SCRATCHPAD_GRANT_TTL_S_VAR, SCRATCHPAD_OPTION, SCRATCHPAD_VOLUME_VAR, SERVED_RECORD_REASON_VERSION, SERVED_RECORD_VERSION, SHORT_REFERENCE_PREFIX, SP_VARS, ScratchPadError, ScratchPadExtension, ScratchPadHandOn, ScratchPadReader, ServedPromptEnv, ServedPublisher, THREAD_ID_FIELD, THREAD_ID_HEADER, THREAD_ID_HEX_LEN, TOOL_CALL_ID_CONTEXT_KEY, TOOL_CALL_ID_MAX, activeTrace, answerGrantRequest, assertValidTraceOptions, bindActiveTrace, buildEdgeRecord, buildServedRecord, countTraceRecordDropped, countTraceRecordPublished, decodeReference, decodeShortReference, durableHeaders, durableRunId, durableTrace, encodeGrantReply, encodeGrantRequest, encodeReference, exportScratchPad, fabricTracing, findReferences, grantRequestEndpoint, grantSubject, granteeFromIdentity, isThreadId, loopGuard, loopGuardDescription, nativeScratchPad, nativeScratchPadFromEnv, randomThreadId, readRecordedGrants, readsReferences, referenceCreator, removeReferences, requestGrant, resolveEdgeSubject, resolveScratchPad, scratchPadExtension, scratchPadFromEnv, scratchPadReader, servedPublisher, spBinary, spCliScratchPad, spPort, traceHeaders, traceRecordCounts, unixSeconds, validHarnessThreadId, validToolCallId, withDurableTrace, withRecordedGrants };
+export { CALLER_INBOX_PREFIX, CANNOT_ANSWER, CallerStream, DEFAULT_DISCOVER_TIMEOUT_MS, DEFAULT_EDGE_SUBJECT, DEFAULT_GRANT_REQUEST_TIMEOUT_MS, DEFAULT_GRANT_TTL_S, DEFAULT_READ_LIMIT_BYTES, DEFAULT_SP_BIN, EDGE_RECORD_VERSION, EDGE_SUBJECT_OPTION, EDGE_SUBJECT_VAR, FabricCallerError, GRANT_REQUEST_ENDPOINT, HARNESS_THREAD_ID_MAX, LOOP_GUARD_CODE, MAX_BOOTSTRAP_BYTES, NATS_CREDS_VAR, NATS_URL_VAR, NativeScratchPad, NativeScratchPadError, READS_REFERENCES_KEY, READS_SCRATCHPAD_REFERENCES_FIELD, REFERENCE_PREFIX, ROOT_ID_FIELD, ROOT_ID_HEADER, SCRATCHPAD_BIN_VAR, SCRATCHPAD_BOOTSTRAP_FILE_VAR, SCRATCHPAD_DIR_VAR, SCRATCHPAD_GRANT_TTL_S_VAR, SCRATCHPAD_OPTION, SCRATCHPAD_VOLUME_VAR, SERVED_RECORD_REASON_VERSION, SERVED_RECORD_VERSION, SHORT_REFERENCE_PREFIX, SP_VARS, ScratchPadError, ScratchPadExtension, ScratchPadHandOn, ScratchPadReader, ServedPromptEnv, ServedPublisher, THREAD_ID_FIELD, THREAD_ID_HEADER, THREAD_ID_HEX_LEN, TOOL_CALL_ID_CONTEXT_KEY, TOOL_CALL_ID_MAX, activeTrace, answerGrantRequest, assertValidTraceOptions, bindActiveTrace, buildEdgeRecord, buildServedRecord, countTraceRecordDropped, countTraceRecordPublished, decodeReference, decodeScratchPadBootstrap, decodeShortReference, durableHeaders, durableRunId, durableTrace, encodeGrantReply, encodeGrantRequest, encodeReference, exportScratchPad, fabricCaller, fabricCallerFromEnv, fabricTracing, findReferences, grantRequestEndpoint, grantSubject, granteeFromIdentity, isThreadId, loopGuard, loopGuardDescription, nativeScratchPad, nativeScratchPadFromEnv, pickAgent, randomThreadId, readRecordedGrants, readsReferences, referenceCreator, removeReferences, requestGrant, resolveEdgeSubject, resolveScratchPad, scratchPadExtension, scratchPadFromEnv, scratchPadReader, servedPublisher, spBinary, spCliScratchPad, spPort, traceHeaders, traceRecordCounts, unixSeconds, validHarnessThreadId, validToolCallId, withDurableTrace, withRecordedGrants };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map