@ours.network/cli 0.5.0 → 1.0.0

package/dist/server-TDJBEWTU.js

@@ -0,0 +1,2077 @@
+import {
+  API_VISIBILITY,
+  BROKER_URL,
+  CONFIG,
+  FILE_SELECTION_CAP,
+  GC_INTERVAL_MS,
+  PORT,
+  PROTOCOL_VERSION,
+  STATE_DIR,
+  VERSION,
+  appendNotifyLog,
+  bindSession,
+  bootWrapper,
+  buildMessagesPayload,
+  capabilityReconcileSweep,
+  clearNotifyHook,
+  closeTemporaryIdentity,
+  clusterSweep,
+  contactRestoreSweep,
+  decodeWireBin,
+  delegateRole,
+  deleteIdentityCompletely,
+  describeIdentity,
+  e2eRecoverySweep,
+  encodeWireBin,
+  envelopeDispatch,
+  establishRoot,
+  exportAdBlob,
+  findIdentityFile,
+  hashLeaseToken,
+  identities,
+  isSelectableWireId,
+  leaseByToken,
+  leases,
+  log,
+  mimeFromExt,
+  mutatingTx,
+  outboundRemovalInFlight,
+  persistBindings,
+  pidAlive,
+  provisionIdentity,
+  publishToBook,
+  readBook,
+  readE2eWireIds,
+  readonlyTx,
+  refreshUnread,
+  registrar,
+  renderContactRoots,
+  renderContacts,
+  renderDegraded,
+  renderFileMetadata,
+  renderImportRenames,
+  renderInbox,
+  renderPending,
+  requireAuth,
+  reservedNames,
+  resolveBound,
+  rootName,
+  saveState,
+  scheduleCapabilityReconcile,
+  serveNotifications,
+  sessionHeaders,
+  setNotifyHook,
+  startupProgress,
+  sweepStaleTempIdentities,
+  tombstones,
+  unpublishFromBook,
+  unreadSummary,
+  validateName,
+  withScope,
+  withScopeAsync,
+  writeIncomingFiles,
+  writeTempMetaFile
+} from "./chunk-MHVYJY3H.js";
+import {
+  buildIdentityFile,
+  writeIdentityFile
+} from "./chunk-FXKFSNKS.js";
+
+// ../../src/http/server.ts
+import { createServer as createHttpServer } from "node:http";
+import { randomUUID } from "node:crypto";
+import * as fs2 from "node:fs";
+
+// ../../src/protocol.ts
+var OURS_COMPAT_VERSION = 1;
+
+// ../../src/gc.ts
+var gcTimer = null;
+var gcRunning = false;
+function startGcTimer() {
+  if (gcTimer) return;
+  gcTimer = setInterval(() => {
+    if (gcRunning) return;
+    gcRunning = true;
+    void (async () => {
+      try {
+        for (const id of identities.values()) {
+          try {
+            await withScopeAsync(async (lt) => {
+              await mutatingTx(id, "::actor::gc", {}, lt);
+            });
+          } catch (e) {
+            log(`gc(${id.name}) failed:`, String(e));
+          }
+          await contactRestoreSweep(id);
+          await capabilityReconcileSweep(id);
+          await e2eRecoverySweep(id);
+        }
+      } finally {
+        gcRunning = false;
+      }
+    })();
+  }, GC_INTERVAL_MS);
+  gcTimer.unref?.();
+  log(`message GC timer armed (every ${GC_INTERVAL_MS}ms)`);
+}
+function stopGcTimer() {
+  if (gcTimer) {
+    clearInterval(gcTimer);
+    gcTimer = null;
+  }
+}
+
+// ../../src/sse-keepalive.ts
+var DEFAULT_SSE_KEEPALIVE_MS = 25e3;
+var KEEPALIVE_FRAME = ": ka\n\n";
+function sseKeepaliveMs(env = process.env) {
+  const raw = (env.OURS_SSE_KEEPALIVE_MS ?? "").trim();
+  if (raw === "") return DEFAULT_SSE_KEEPALIVE_MS;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= 0 ? n : DEFAULT_SSE_KEEPALIVE_MS;
+}
+function armSseKeepalive(res, intervalMs = sseKeepaliveMs()) {
+  if (!(intervalMs > 0)) return;
+  let isSse = false;
+  const origWriteHead = res.writeHead.bind(res);
+  res.writeHead = (...args) => {
+    const hdrs = typeof args[1] === "object" && args[1] !== null ? args[1] : args[2];
+    if (hdrs && !Array.isArray(hdrs)) {
+      for (const [k, v] of Object.entries(hdrs)) {
+        if (k.toLowerCase() === "content-type" && String(v).includes("text/event-stream")) isSse = true;
+      }
+    }
+    return origWriteHead(...args);
+  };
+  const timer = setInterval(() => {
+    if (!isSse || res.writableEnded || res.destroyed) return;
+    try {
+      res.write(KEEPALIVE_FRAME);
+    } catch {
+    }
+  }, intervalMs);
+  timer.unref?.();
+  const stop = () => clearInterval(timer);
+  res.once("close", stop);
+  res.once("finish", stop);
+}
+
+// ../../src/uploads.ts
+import * as fs from "node:fs";
+import { createHash } from "node:crypto";
+import { basename, join } from "node:path";
+var uploadsDirFor = (id) => join(id.dir, "uploads");
+var UPLOAD_TTL_MS = Number(process.env.OURS_UPLOAD_TTL_MS) > 0 ? Number(process.env.OURS_UPLOAD_TTL_MS) : 60 * 60 * 1e3;
+var UPLOAD_ID_RE = /^[0-9a-f]{32}$/;
+var newUploadId = () => createHash("sha256").update(`${process.pid}:${Date.now()}:${Math.random()}`).digest("hex").slice(0, 32);
+var isUploadId = (s) => UPLOAD_ID_RE.test(s);
+var bytesPath = (id, uploadId) => join(uploadsDirFor(id), uploadId);
+var metaPath = (id, uploadId) => join(uploadsDirFor(id), `${uploadId}.json`);
+function sanitizeUploadFilename(raw) {
+  const flat = raw.replace(/[\u0000-\u001f\u007f]/g, "").replace(/\\/g, "/");
+  const base = basename(flat);
+  const clean = base === "" || base === "." || base === ".." ? "" : base;
+  return clean.slice(0, 255);
+}
+var UploadRefused = class extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "UploadRefused";
+  }
+};
+async function stageUpload(id, body, meta) {
+  const filename = sanitizeUploadFilename(meta.filename);
+  if (filename === "") throw new UploadRefused(400, "x-ours-filename is required and must be a plain file name");
+  if (meta.declaredBytes === null) throw new UploadRefused(411, "Content-Length is required");
+  if (meta.declaredBytes >= meta.cap) {
+    throw new UploadRefused(
+      400,
+      `upload is ${meta.declaredBytes} bytes, at or over the transport's ${meta.cap}-byte envelope budget \u2014 it could not be sent even with no filename or MIME, so it is refused before it is stored`
+    );
+  }
+  const uploadId = newUploadId();
+  fs.mkdirSync(uploadsDirFor(id), { recursive: true, mode: 448 });
+  const dest = bytesPath(id, uploadId);
+  const hash = createHash("sha256");
+  let size = 0;
+  const out = fs.createWriteStream(dest, { mode: 384 });
+  try {
+    await new Promise((resolve2, reject) => {
+      const fail = (err) => {
+        body.unpipe?.(out);
+        out.destroy();
+        reject(err);
+      };
+      body.on("data", (chunk) => {
+        size += chunk.length;
+        if (size > meta.declaredBytes) {
+          fail(new UploadRefused(400, "request body is longer than its Content-Length"));
+          return;
+        }
+        hash.update(chunk);
+      });
+      body.on("error", fail);
+      out.on("error", fail);
+      out.on("finish", () => resolve2());
+      body.pipe(out);
+    });
+  } catch (err) {
+    try {
+      fs.rmSync(dest, { force: true });
+    } catch {
+    }
+    throw err;
+  }
+  const staged = {
+    upload_id: uploadId,
+    filename,
+    mime: meta.mime,
+    size,
+    sha256: hash.digest("hex"),
+    at: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  fs.writeFileSync(metaPath(id, uploadId), JSON.stringify(staged), { mode: 384 });
+  return staged;
+}
+function consumeStagedUpload(id, uploadId) {
+  if (!isUploadId(uploadId)) return null;
+  const bytes = bytesPath(id, uploadId);
+  let buf;
+  let meta;
+  try {
+    buf = fs.readFileSync(bytes);
+    meta = JSON.parse(fs.readFileSync(metaPath(id, uploadId), "utf8"));
+  } catch {
+    return null;
+  } finally {
+    try {
+      fs.rmSync(bytes, { force: true });
+    } catch {
+    }
+    try {
+      fs.rmSync(metaPath(id, uploadId), { force: true });
+    } catch {
+    }
+  }
+  return { meta, buf };
+}
+function sweepStaleUploads() {
+  let dropped = 0;
+  const cutoff = Date.now() - UPLOAD_TTL_MS;
+  for (const id of identities.values()) {
+    const dir = uploadsDirFor(id);
+    let entries;
+    try {
+      entries = fs.readdirSync(dir);
+    } catch {
+      continue;
+    }
+    for (const name of entries) {
+      const p = join(dir, name);
+      try {
+        if (fs.statSync(p).mtimeMs >= cutoff) continue;
+        fs.rmSync(p, { force: true });
+        dropped++;
+      } catch {
+      }
+    }
+    if (dropped > 0) log(`[${id.name}] swept ${dropped} stale staged upload file(s)`);
+  }
+  return dropped;
+}
+
+// ../../src/messaging/file-limit.ts
+import { object_to_adapt_value } from "@adapt-toolkit/sdk/wrapper";
+var WIRE_ID_PLACEHOLDER = "w".repeat(64);
+var WIRE_VERSION = 9;
+var PINNED_FILE_ENVELOPE_CAP = 2097152;
+function resolveFileEnvelopeCap() {
+  return PINNED_FILE_ENVELOPE_CAP;
+}
+var byteLen = (s) => Buffer.byteLength(s, "utf8");
+function envelopeSkipMargin(i) {
+  const replyBytes = i.replyTo ? byteLen(i.replyTo.wire_id) + 32 : 0;
+  return 2048 + 2 * (byteLen(i.filename) + byteLen(i.mime) + replyBytes);
+}
+function needsEnvelopeMeasurement(i) {
+  return i.bytes + envelopeSkipMargin(i) > i.cap;
+}
+function measureFileEnvelope(i) {
+  const data = i.packet.NewBinaryFromBuffer(i.payload).Attach(i.lifetime);
+  const envelope = object_to_adapt_value({
+    filename: i.filename,
+    mime: i.mime,
+    data,
+    wire_id: WIRE_ID_PLACEHOLDER,
+    ...i.replyTo ? { reply_to: i.replyTo } : {},
+    pv: WIRE_VERSION
+  });
+  envelope.Attach(i.lifetime);
+  return envelope.Serialize().length;
+}
+var MAX_SOLVE_ROUNDS = 8;
+function maxFilePayloadBytes(i) {
+  const measure = (n2) => measureFileEnvelope({ ...i, payload: i.payload.subarray(0, n2) });
+  let n = i.payload.length;
+  for (let round = 0; round < MAX_SOLVE_ROUNDS; round++) {
+    const s = measure(n);
+    if (s <= i.cap) break;
+    const next = n - (s - i.cap);
+    if (next <= 0) return 0;
+    n = next;
+  }
+  if (measure(n) > i.cap) return 0;
+  while (n < i.payload.length && measure(n + 1) <= i.cap) n++;
+  return n;
+}
+function checkFileEnvelope(i) {
+  const cap = i.cap ?? resolveFileEnvelopeCap();
+  const bytes = i.payload.length;
+  if (!needsEnvelopeMeasurement({
+    bytes,
+    filename: i.filename,
+    mime: i.mime,
+    replyTo: i.replyTo,
+    cap
+  })) {
+    return { ok: true };
+  }
+  const envelopeBytes = measureFileEnvelope(i);
+  if (envelopeBytes <= cap) return { ok: true };
+  return {
+    ok: false,
+    bytes,
+    cap,
+    envelopeBytes,
+    maxPayloadBytes: maxFilePayloadBytes({ ...i, cap })
+  };
+}
+
+// ../../src/errors.ts
+var OursError = class extends Error {
+  // `details` is PURELY ADDITIVE and optional: every existing construction and
+  // every `e.code` check keeps working untouched. It exists because a refusal a
+  // caller is expected to ACT on (trim N bytes, shorten the filename) cannot be
+  // delivered as prose alone — see errFileTooLarge.
+  constructor(code, message, details) {
+    super(message);
+    this.code = code;
+    this.details = details;
+    this.name = "OursError";
+  }
+};
+var errNameTaken = (tool, name) => new OursError("NAME_TAKEN", `${tool} failed: an identity named "${name}" already exists.`);
+var errNoLeaseHeaders = () => new OursError(
+  "NO_LEASE_HEADERS",
+  "create_temporary_identity failed: this client is not connected through the ours connector (no lease token / client pid headers), so there is no session lease to own the identity. Launch ours via the connector (`ours-mcp proxy`)."
+);
+var errRandomNameExhausted = () => new OursError(
+  "RANDOM_NAME_EXHAUSTED",
+  "create_temporary_identity failed: could not pick a free random name after 5 attempts \u2014 retry."
+);
+var errRootExists = (rootName2) => new OursError(
+  "ROOT_EXISTS",
+  `create_root_identity failed: a root identity already exists ("${rootName2}") \u2014 one root per host. Nothing to do.`
+);
+var errNotBoundNoName = () => new OursError("NOT_BOUND_NO_NAME", "close_temporary_identity failed: no identity is bound to this session and no name was given.");
+var errNotTemporary = (name) => new OursError(
+  "NOT_TEMPORARY",
+  `close_temporary_identity failed: "${name}" is a permanent identity. Use remove_identity if you really mean to delete it.`
+);
+var errTempOwnedElsewhereClose = (name, pid) => new OursError(
+  "TEMP_OWNED_ELSEWHERE",
+  `close_temporary_identity failed: "${name}" is owned by another LIVE session (owner pid ${pid}) \u2014 one session cannot delete another's temporary identity.`
+);
+var errTempClosedWithError = (name, deleteError, remote) => new OursError("DELETE_PARTIAL", `Temporary identity "${name}" closed with an error: ${deleteError}. ${remote}`);
+var errPathNotAbsolute = (path) => new OursError("PATH_NOT_ABSOLUTE", `define_local_identity_file failed: path must be absolute (got "${path}").`);
+var errNoSuchIdentity = (name) => new OursError("NO_SUCH_IDENTITY", `choose_identity failed: no identity named "${name}". Create it with create_identity.`);
+var errNoLeaseToken = () => new OursError(
+  "NO_LEASE_TOKEN",
+  "choose_identity failed: this client is not connected through the ours connector (no lease token header). Launch ours via the connector (`ours-mcp proxy`)."
+);
+var errTempClosingChoose = (name) => new OursError("TEMP_CLOSING", `choose_identity failed: temporary identity "${name}" is closing \u2014 its state is being deleted.`);
+var errTempOwnedLive = (name, pid) => new OursError(
+  "TEMP_OWNED_ELSEWHERE",
+  `choose_identity failed: "${name}" is a TEMPORARY identity owned by another live session (owner pid ${pid}). Ownership is exclusive and cannot be overridden \u2014 not even with force. Create your own with create_temporary_identity.`
+);
+var errTempStale = (name, pid) => new OursError(
+  "TEMP_STALE",
+  `choose_identity failed: temporary identity "${name}" is STALE \u2014 its owning session (pid ${pid}) is gone and it is pending automatic cleanup. It cannot be adopted by another session; use close_temporary_identity to reclaim (clean it up) now.`
+);
+var errBoundElsewhere = (name) => new OursError(
+  "BOUND_ELSEWHERE",
+  `choose_identity declined: "${name}" is currently bound to another live session. Do not retry with force=true on your own \u2014 tell the user it is in use elsewhere and ask whether to forcibly rebind it here; only retry with force=true after they explicitly confirm.`
+);
+var errTempOwnedElsewhereRemove = (name, pid) => new OursError(
+  "TEMP_OWNED_ELSEWHERE",
+  `remove_identity failed: "${name}" is a TEMPORARY identity owned by another LIVE session (owner pid ${pid}) \u2014 one session cannot delete another's temporary identity.`
+);
+var errIdentityClosedWithError = (name, deleteError, remote) => new OursError("DELETE_PARTIAL", `Temporary identity "${name}" closed with an error: ${deleteError}.${remote}`);
+var errRootHasRoles = (name, roles) => new OursError(
+  "ROOT_HAS_ROLES",
+  `remove_identity failed: "${name}" is the root identity and still has ${roles.length} role(s): ${roles.join(", ")}. Remove the roles first.`
+);
+var errIdentityPartiallyRemoved = (name, fail) => new OursError("DELETE_PARTIAL", `Identity "${name}" removed from memory, but ${fail}`);
+var errPublicInviteNamed = () => new OursError(
+  "PUBLIC_INVITE_NAMED",
+  "generate_invite failed: a public invite cannot pre-assign a contact name \u2014 every redeemer would be registered under it. Omit `name` for a public invite."
+);
+var errNoPolicyArgs = () => new OursError("NO_POLICY_ARGS", "set_local_book_policy: pass expose and/or auto_accept.");
+var errSendFileArgs = () => new OursError("SEND_ARGS", "send_file: provide exactly one of `path` or `data_base64`.");
+var errSendFileFilenameRequired = () => new OursError("SEND_ARGS", "send_file: `filename` is required with `data_base64`.");
+var errFileUnreadable = (detail) => new OursError("FILE_UNREADABLE", `send_file: cannot read file: ${detail}`);
+var errSendFileUploadArgs = () => new OursError("SEND_ARGS", "send_file: provide exactly one of `path`, `data_base64` or `upload_id`.");
+var errUploadNotFound = (uploadId) => new OursError(
+  "FILE_UNREADABLE",
+  `send_file: no staged upload "${uploadId}" for the bound identity. Upload the bytes with POST /files/upload first. A staged upload is consumed by the first send that names it \u2014 including a send that failed \u2014 so a retry needs a fresh upload.`
+);
+var errFileTooLarge = (i) => new OursError(
+  "FILE_TOO_LARGE",
+  `send_file: "${i.filename}" is ${i.bytes} bytes. This send's envelope would serialize to ${i.envelopeBytes} bytes, over the transport's ${i.limit}-byte budget \u2014 the largest payload it can carry with this filename, MIME and reply reference is ${i.maxPayloadBytes} bytes. Nothing was sent.`,
+  i
+);
+var errInvalidSelection = (cap) => new OursError("INVALID_SELECTION", `get_files failed: wire_ids must contain 1-${cap} items.`);
+var errMalformedId = () => new OursError("MALFORMED_ID", "get_files failed: every selected wire_id must be exactly 64 hexadecimal characters.");
+var errDuplicateId = () => new OursError("DUPLICATE_ID", "get_files failed: wire_ids must not contain duplicates.");
+var errUnknownOrStaleId = () => new OursError(
+  "UNKNOWN_OR_STALE_ID",
+  "get_files failed: one or more selected wire_ids is unknown, stale, or no longer unread; no files were retrieved."
+);
+var errTool = (tool, detail, code = "TX_FAILED") => new OursError(code, `${tool} failed: ${detail}`);
+
+// ../../src/api/identity.ts
+import { randomBytes } from "node:crypto";
+import { isAbsolute } from "node:path";
+function describeOrNull(id) {
+  try {
+    return describeIdentity(id);
+  } catch {
+    return null;
+  }
+}
+function identityInfo(id) {
+  const d = describeOrNull(id);
+  return {
+    name: id.name,
+    cid: id.cid,
+    bio: d?.bio ?? "",
+    persona: d?.persona ?? "",
+    roleId: d?.roleId ?? "",
+    rootCid: d?.rootCid ?? "",
+    rootName: d?.rootName ?? ""
+  };
+}
+async function setBio(id, bio) {
+  if (!bio) return;
+  await withScopeAsync(async (lt) => {
+    await mutatingTx(id, "::a2a_messaging::set_my_bio", { bio }, lt);
+  });
+}
+function requireBound(ctx) {
+  const b = resolveBound(ctx.sessionId());
+  if (!("error" in b)) return b.id;
+  throw new OursError(b.code, b.error);
+}
+async function createIdentity(ctx, a) {
+  const { name, bio, exposeLocal, localAutoAccept } = a;
+  const bad = validateName(name);
+  if (bad) throw errTool("create_identity", bad, "NAME_INVALID");
+  if (identities.has(name)) throw errNameTaken("create_identity", name);
+  try {
+    const id = await provisionIdentity(name, { exposeLocal, localAutoAccept });
+    await setBio(id, bio);
+    let hierarchy;
+    let underRoot = null;
+    let adopted = [];
+    let failed = [];
+    const root = rootName ? identities.get(rootName) : void 0;
+    if (root) {
+      await delegateRole(root, id);
+      hierarchy = "role";
+      underRoot = root.name;
+      if (envelopeDispatch()) void clusterSweep(root);
+    } else {
+      hierarchy = "root";
+      const res = await establishRoot(id);
+      adopted = res.adopted;
+      failed = res.failed;
+    }
+    bindSession(ctx.sessionId(), name);
+    return { info: identityInfo(id), hierarchy, underRoot, adopted, failed, exposedLocal: exposeLocal, localAutoAccept };
+  } catch (err) {
+    throw errTool("create_identity", String(err), "PROVISION_FAILED");
+  }
+}
+async function createTemporaryIdentity(ctx, a) {
+  const { bio, exposeLocal, localAutoAccept } = a;
+  const token = ctx.leaseToken();
+  const pid = ctx.clientPid();
+  if (!token || !pid) throw errNoLeaseHeaders();
+  let chosen = a.name;
+  if (chosen !== void 0) {
+    const bad = validateName(chosen);
+    if (bad) throw errTool("create_temporary_identity", bad, "NAME_INVALID");
+    if (identities.has(chosen) || reservedNames.has(chosen)) {
+      throw errNameTaken("create_temporary_identity", chosen);
+    }
+  } else {
+    for (let i = 0; i < 5 && chosen === void 0; i++) {
+      const cand = `tmp-${randomBytes(5).toString("hex")}`;
+      if (!identities.has(cand) && !reservedNames.has(cand)) chosen = cand;
+    }
+    if (chosen === void 0) throw errRandomNameExhausted();
+  }
+  const name = chosen;
+  try {
+    const id = await provisionIdentity(name, {
+      exposeLocal,
+      localAutoAccept,
+      temp: { tokenHash: hashLeaseToken(token), pid }
+    });
+    await setBio(id, bio);
+    bindSession(ctx.sessionId(), name);
+    return { info: identityInfo(id), ownerPid: pid, exposedLocal: exposeLocal, localAutoAccept };
+  } catch (err) {
+    throw errTool("create_temporary_identity", String(err), "PROVISION_FAILED");
+  }
+}
+async function closeTemporaryIdentityOp(ctx, a) {
+  const token = ctx.leaseToken();
+  let id;
+  if (a.name !== void 0) {
+    id = identities.get(a.name);
+    if (!id) return { name: a.name, result: null };
+  } else {
+    const lease = token ? leaseByToken(token) : void 0;
+    id = lease ? identities.get(lease.identity) : void 0;
+    if (!id) throw errNotBoundNoName();
+  }
+  if (!id.temp) throw errNotTemporary(id.name);
+  const owner = id.temp.owner;
+  const isOwner = token !== void 0 && owner.tokenHash === hashLeaseToken(token);
+  if (!isOwner && !id.temp.closing && pidAlive(owner.pid)) {
+    throw errTempOwnedElsewhereClose(id.name, owner.pid);
+  }
+  try {
+    const res = await closeTemporaryIdentity(
+      id,
+      isOwner ? "explicit close by owner" : "stale reclaim via close_temporary_identity"
+    );
+    if (res.deleteError) {
+      const remote = res.attempted === 0 ? "It had no contacts, so no remove-me notices were needed." : `Remove-me notices: ${res.notified}/${res.attempted} queued, ${res.failed} not sent (best effort \u2014 delivery and remote contact deletion are not guaranteed).`;
+      throw errTempClosedWithError(id.name, res.deleteError, remote);
+    }
+    return { name: id.name, result: res };
+  } catch (err) {
+    if (err instanceof OursError) throw err;
+    throw errTool("close_temporary_identity", String(err), "CLOSE_FAILED");
+  }
+}
+async function createRootIdentity(ctx, a) {
+  const { name, bio, exposeLocal, localAutoAccept, skipIfRootExists } = a;
+  const bad = validateName(name);
+  if (bad) throw errTool("create_root_identity", bad, "NAME_INVALID");
+  const existingRootName = rootName;
+  if (skipIfRootExists && existingRootName && identities.has(existingRootName)) {
+    throw errRootExists(existingRootName);
+  }
+  if (identities.has(name)) throw errNameTaken("create_root_identity", name);
+  try {
+    const id = await provisionIdentity(name, { exposeLocal, localAutoAccept });
+    await setBio(id, bio);
+    const existingRoot = rootName ? identities.get(rootName) : void 0;
+    if (existingRoot && existingRoot.name !== name) {
+      await delegateRole(existingRoot, id);
+      bindSession(ctx.sessionId(), name);
+      return {
+        // existingRoot.name is the in-memory root name (index.ts:3806).
+        info: identityInfo(id),
+        hierarchy: "role",
+        underRoot: existingRoot.name,
+        adopted: [],
+        failed: [],
+        exposedLocal: exposeLocal,
+        localAutoAccept
+      };
+    }
+    const { adopted, failed } = await establishRoot(id);
+    bindSession(ctx.sessionId(), name);
+    return {
+      info: identityInfo(id),
+      hierarchy: "root",
+      underRoot: null,
+      adopted,
+      failed,
+      exposedLocal: exposeLocal,
+      localAutoAccept
+    };
+  } catch (err) {
+    throw errTool("create_root_identity", String(err), "PROVISION_FAILED");
+  }
+}
+async function defineLocalIdentityFile(a) {
+  if (!isAbsolute(a.path)) throw errPathNotAbsolute(a.path);
+  const opts = { name: a.name, force: a.force, exposeLocal: a.exposeLocal, localAutoAccept: a.localAutoAccept };
+  try {
+    const written = writeIdentityFile(a.path, opts, a.overwrite);
+    return { written, json: buildIdentityFile(opts) };
+  } catch (err) {
+    throw errTool("define_local_identity_file", String(err), "WRITE_FAILED");
+  }
+}
+async function chooseIdentity(ctx, a) {
+  const { name, force } = a;
+  if (!identities.has(name)) throw errNoSuchIdentity(name);
+  const sid = ctx.sessionId();
+  const token = ctx.leaseToken();
+  if (!token) throw errNoLeaseToken();
+  const target = identities.get(name);
+  if (target.temp) {
+    if (target.temp.closing) throw errTempClosingChoose(name);
+    const owner = target.temp.owner;
+    if (owner.tokenHash !== hashLeaseToken(token)) {
+      if (pidAlive(owner.pid)) throw errTempOwnedLive(name, owner.pid);
+      throw errTempStale(name, owner.pid);
+    }
+    const hdrPid = ctx.clientPid();
+    if (hdrPid && hdrPid !== owner.pid) {
+      owner.pid = hdrPid;
+      try {
+        writeTempMetaFile(target.dir, target.temp);
+      } catch (err) {
+        log(`[${name}] temp marker refresh failed:`, String(err));
+      }
+    }
+  }
+  const existing = leases.get(name);
+  if (existing && existing.token !== token) {
+    if (!pidAlive(existing.pid)) {
+      log(`auto-reclaiming "${name}" from dead client pid ${existing.pid}`);
+      leases.delete(name);
+    } else if (!force) {
+      throw errBoundElsewhere(name);
+    } else {
+      tombstones.add(existing.token);
+      leases.delete(name);
+    }
+  }
+  const prev = [...leases.values()].find((l) => l.token === token && l.identity !== name)?.identity;
+  const switchedFrom = prev && identities.has(prev) ? prev : null;
+  bindSession(sid, name);
+  return { name, cid: identities.get(name).cid, switchedFrom };
+}
+async function listIdentities(ctx) {
+  if (identities.size === 0) return [];
+  const myToken = ctx.leaseToken();
+  const sessionOf = (name) => {
+    const lease = leases.get(name);
+    if (!lease) return null;
+    if (lease.token === myToken) return "mine";
+    if (!pidAlive(lease.pid)) return null;
+    return "other-live";
+  };
+  const tempOf = (id) => {
+    if (!id.temp) return null;
+    const ownerPid = id.temp.owner.pid;
+    if (id.temp.closing) return { state: "closing", ownerPid };
+    if (myToken !== void 0 && id.temp.owner.tokenHash === hashLeaseToken(myToken)) {
+      return { state: "mine", ownerPid };
+    }
+    return pidAlive(ownerPid) ? { state: "other-live", ownerPid } : { state: "stale", ownerPid };
+  };
+  const row = (id, kind) => ({
+    name: id.name,
+    cid: id.cid,
+    kind,
+    temp: tempOf(id),
+    session: sessionOf(id.name)
+  });
+  const root = rootName ? identities.get(rootName) : void 0;
+  const rows = [];
+  if (root) {
+    rows.push({ ...row(root, "root"), temp: null });
+    for (const id of identities.values()) {
+      if (id.name === root.name) continue;
+      if (describeIdentity(id).roleId !== "") rows.push(row(id, "role"));
+    }
+    for (const id of identities.values()) {
+      if (id.name === root.name || describeIdentity(id).roleId !== "") continue;
+      rows.push(row(id, "flat"));
+    }
+  } else {
+    for (const id of identities.values()) rows.push(row(id, "flat"));
+  }
+  return rows;
+}
+async function currentIdentity(ctx) {
+  const id = requireBound(ctx);
+  const d = describeOrNull(id);
+  return {
+    name: id.name,
+    cid: id.cid,
+    bio: d?.bio ?? "",
+    persona: d?.persona ?? "",
+    roleId: d?.roleId ?? "",
+    rootCid: d?.rootCid ?? "",
+    rootName: d?.rootName ?? "",
+    temporary: id.temp !== void 0,
+    isRoot: id.name === rootName,
+    described: d !== null
+  };
+}
+async function removeIdentity(ctx, a) {
+  const { name } = a;
+  const id = identities.get(name);
+  if (!id) throw errTool("remove_identity", `no identity named "${name}".`, "NO_SUCH_IDENTITY");
+  if (id.temp) {
+    const token = ctx.leaseToken();
+    const owner = id.temp.owner;
+    if ((token === void 0 || owner.tokenHash !== hashLeaseToken(token)) && !id.temp.closing && pidAlive(owner.pid)) {
+      throw errTempOwnedElsewhereRemove(name, owner.pid);
+    }
+    try {
+      const res = await closeTemporaryIdentity(id, "remove_identity");
+      if (res.deleteError) {
+        const remote = res.attempted === 0 ? "" : ` Remove-me notices: ${res.notified}/${res.attempted} queued, ${res.failed} not sent (best effort).`;
+        throw errIdentityClosedWithError(name, res.deleteError, remote);
+      }
+      return { name, kind: "temporary", close: res };
+    } catch (err) {
+      if (err instanceof OursError) throw err;
+      throw errTool("remove_identity", String(err), "CLOSE_FAILED");
+    }
+  }
+  if (name === rootName) {
+    const roles = [...identities.values()].filter(
+      (i) => i.name !== name && describeIdentity(i).rootCid === id.cid
+    );
+    if (roles.length > 0) throw errRootHasRoles(name, roles.map((r) => r.name));
+  }
+  const fail = deleteIdentityCompletely(id);
+  if (fail) throw errIdentityPartiallyRemoved(name, fail);
+  return { name, kind: "permanent" };
+}
+async function releaseLease(ctx) {
+  const token = ctx.leaseToken();
+  if (!token) throw errNoLeaseToken();
+  const released = [];
+  for (const [n, l] of [...leases]) {
+    if (l.token !== token) continue;
+    leases.delete(n);
+    released.push(n);
+    const rid = identities.get(n);
+    if (rid?.temp && rid.temp.owner.tokenHash === hashLeaseToken(token) && !rid.temp.closing) {
+      void closeTemporaryIdentity(rid, "owning session released its lease").catch(
+        (err) => log(`[${n}] close on lease release failed:`, String(err))
+      );
+    }
+  }
+  tombstones.delete(token);
+  persistBindings();
+  log(`lease released by token \u2026${token.slice(-6)}`);
+  return { released };
+}
+
+// ../../src/api/contacts.ts
+async function generateInvite(ctx, a = {}) {
+  const id = requireBound(ctx);
+  const { name, mode } = a;
+  if (mode === "public" && name) throw errPublicInviteNamed();
+  try {
+    return await withScopeAsync(async (lt) => {
+      const targ = {};
+      if (name) targ.name = name;
+      if (mode) targ.mode = mode;
+      const data = await mutatingTx(id, "::a2a_messaging::generate_invite", targ, lt);
+      return {
+        blob: encodeWireBin(Buffer.from(data.Reduce("invite").GetBinary())),
+        inviteId: data.Reduce("invite_id").Visualize(),
+        // The baseline never types this field — it only asks
+        // `res.mode === 'public'` (index.ts:4147) and treats everything else as
+        // one_time. So make the same judgement rather than ASSERTING the packet's
+        // Visualize() into the union: a cast would be a promise the packet does
+        // not make, and a third mode added packet-side would type as a lie.
+        mode: data.Reduce("mode").Visualize() === "public" ? "public" : "one_time"
+      };
+    });
+  } catch (e) {
+    throw errTool("generate_invite", String(e));
+  }
+}
+async function listInvites(ctx) {
+  const id = requireBound(ctx);
+  try {
+    return withScope((lt) => {
+      const v = readonlyTx(id, "::a2a_messaging::list_invites", lt);
+      const out = [];
+      if (v.IsNil()) return out;
+      for (const key of v.GetKeys()) {
+        const rec = v.Reduce(key);
+        if (rec.IsNil()) continue;
+        const assigned = rec.Reduce("assigned").Visualize();
+        const created = rec.Reduce("created").Visualize();
+        out.push({
+          invite_id: typeof key === "string" ? key : key.Visualize(),
+          mode: rec.Reduce("mode").Visualize(),
+          assigned: assigned === "%%NIL" ? "" : assigned,
+          created: created === "%%NIL" ? "" : created
+        });
+      }
+      return out;
+    });
+  } catch (e) {
+    throw errTool("list_invites", String(e));
+  }
+}
+async function revokeInvite(ctx, a) {
+  const id = requireBound(ctx);
+  const { invite_id } = a;
+  try {
+    return await withScopeAsync(async (lt) => {
+      const data = await mutatingTx(id, "::a2a_messaging::revoke_invite", { invite_id }, lt);
+      const wp = data.Reduce("was_public");
+      return {
+        revoked: data.Reduce("revoked").GetBoolean(),
+        wasPublic: wp.IsNil() ? false : wp.GetBoolean()
+      };
+    });
+  } catch (e) {
+    throw errTool("revoke_invite", String(e));
+  }
+}
+async function addContact(ctx, a) {
+  const id = requireBound(ctx);
+  const { invite, name } = a;
+  let buf;
+  try {
+    buf = decodeWireBin(invite);
+    if (buf.length === 0) throw new Error("the invite blob is empty");
+  } catch (e) {
+    throw errTool(
+      "add_contact",
+      e instanceof Error ? e.message : "the invite blob is not valid.",
+      "INVITE_MALFORMED"
+    );
+  }
+  try {
+    return await withScopeAsync(async (lt) => {
+      const blobValue = id.pw.packet.NewBinaryFromBuffer(buf).Attach(lt);
+      const targ = { invite: blobValue };
+      if (name) targ.name = name;
+      const data = await mutatingTx(id, "::a2a_messaging::add_contact", targ, lt);
+      const cid = data.Reduce("container_id").Visualize();
+      const pending = data.Reduce("pending").Visualize();
+      const inviterName = data.Reduce("inviter_name").Visualize();
+      const nil = (s) => !s || s === "%%NIL";
+      const display = !nil(pending) ? pending : !nil(inviterName) ? inviterName : cid;
+      scheduleCapabilityReconcile(id);
+      return { display, cid };
+    });
+  } catch (e) {
+    throw errTool("add_contact", String(e));
+  }
+}
+async function listContacts(ctx) {
+  const id = requireBound(ctx);
+  try {
+    return withScope((lt) => ({
+      contacts: renderContacts(readonlyTx(id, "::a2a_messaging::list_contacts", lt)),
+      pending: renderPending(readonlyTx(id, "::actor::list_pending_introductions", lt)),
+      roots: renderContactRoots(readonlyTx(id, "::a2a_messaging::list_contact_roots", lt)),
+      degraded: renderDegraded(readonlyTx(id, "::a2a_messaging::list_degraded_contacts", lt)),
+      renames: renderImportRenames(readonlyTx(id, "::a2a_messaging::list_import_renames", lt))
+    }));
+  } catch (e) {
+    throw errTool("list_contacts", String(e));
+  }
+}
+async function listLocalContactBook(ctx) {
+  const entries = Object.values(readBook());
+  const myToken = ctx.leaseToken();
+  const mine = myToken ? leaseByToken(myToken)?.identity : void 0;
+  return entries.map((e) => ({
+    name: e.name,
+    container_id: e.container_id,
+    published_at: e.published_at,
+    isMine: e.name === mine
+  }));
+}
+async function setLocalBookPolicy(ctx, a) {
+  const id = requireBound(ctx);
+  const { expose, auto_accept } = a;
+  if (expose === void 0 && auto_accept === void 0) throw errNoPolicyArgs();
+  const done = [];
+  try {
+    if (auto_accept !== void 0) {
+      await withScopeAsync(async (lt) => {
+        await mutatingTx(id, "::actor::set_local_policy", { auto_accept }, lt);
+      });
+      done.push(`auto_accept=${auto_accept}`);
+    }
+    if (expose === true) {
+      await publishToBook(id);
+      done.push("published in the local contact book");
+    } else if (expose === false) {
+      unpublishFromBook(id);
+      done.push("removed from the local contact book");
+    }
+    return { identity: id.name, changes: done };
+  } catch (e) {
+    throw errTool("set_local_book_policy", String(e));
+  }
+}
+async function removeContact(ctx, a) {
+  const id = requireBound(ctx);
+  const { contact } = a;
+  try {
+    outboundRemovalInFlight.add(id.name);
+    return await withScopeAsync(async (lt) => {
+      const data = await mutatingTx(id, "::a2a_messaging::remove_contact", { contact }, lt);
+      const name = data.Reduce("removed").Visualize();
+      const cid = data.Reduce("container_id").Visualize();
+      const notifiedV = data.Reduce("notified");
+      const notified = notifiedV.IsNil() ? void 0 : notifiedV.GetBoolean();
+      return { name, cid, notified };
+    });
+  } catch (e) {
+    throw errTool("remove_contact", String(e));
+  } finally {
+    outboundRemovalInFlight.delete(id.name);
+  }
+}
+async function renameContact(ctx, a) {
+  const id = requireBound(ctx);
+  const { contact, name } = a;
+  try {
+    return await withScopeAsync(async (lt) => {
+      const data = await mutatingTx(id, "::a2a_messaging::rename_contact", { contact, name }, lt);
+      return {
+        from: data.Reduce("renamed").Visualize(),
+        cid: data.Reduce("container_id").Visualize()
+      };
+    });
+  } catch (e) {
+    throw errTool("rename_contact", String(e));
+  }
+}
+async function respondToIntroduction(ctx, a) {
+  const id = requireBound(ctx);
+  const { contact, action } = a;
+  try {
+    if (action === "approve") {
+      const res = await withScopeAsync(async (lt) => {
+        const data = await mutatingTx(id, "::actor::approve_introduction", { contact }, lt);
+        return {
+          action: "approve",
+          name: data.Reduce("approved").Visualize(),
+          cid: data.Reduce("container_id").Visualize(),
+          flushed: data.Reduce("flushed").Visualize()
+        };
+      });
+      refreshUnread(id);
+      scheduleCapabilityReconcile(id);
+      return res;
+    }
+    return await withScopeAsync(async (lt) => {
+      const data = await mutatingTx(id, "::actor::reject_introduction", { contact }, lt);
+      return {
+        action: "reject",
+        name: data.Reduce("rejected").Visualize(),
+        dropped: data.Reduce("dropped_messages").Visualize()
+      };
+    });
+  } catch (e) {
+    throw errTool("respond_to_introduction", String(e));
+  }
+}
+
+// ../../src/api/messaging.ts
+import { readFile } from "node:fs/promises";
+import { basename as basename2 } from "node:path";
+
+// ../../src/messaging/send.ts
+function findSibling(id, contact) {
+  if (!rootName || !identities.has(rootName)) return null;
+  const target = identities.get(contact) ?? [...identities.values()].find((i) => i.cid === contact);
+  if (!target || target.name === id.name) return null;
+  const member = (i) => i.name === rootName || describeIdentity(i).roleId !== "";
+  return member(id) && member(target) ? target : null;
+}
+async function sendViaSibling(id, target, text) {
+  const targetAd = exportAdBlob(target);
+  await withScopeAsync(async (lt) => {
+    await mutatingTx(id, "::actor::connect_sibling", {
+      name: target.name,
+      target_ad: id.pw.packet.NewBinaryFromBuffer(targetAd).Attach(lt),
+      text
+    }, lt);
+  });
+  scheduleCapabilityReconcile(id);
+  return `"${target.name}" was not a contact yet \u2014 connected as an intra-root sibling (delegation-cert auto-accept) and delivered the message.`;
+}
+async function sendViaLocalBook(id, contact, text) {
+  if (!registrar) {
+    throw new Error(`"${contact}" is not a contact, and the local contact book is unavailable.`);
+  }
+  const entries = readBook();
+  const entry = entries[contact] ?? Object.values(entries).find((e) => e.container_id === contact);
+  if (!entry) {
+    throw new Error(
+      `"${contact}" is not a contact and has no local contact-book entry. Use generate_invite/add_contact for remote peers, or list_local_contact_book to see local ones.`
+    );
+  }
+  if (entry.container_id === id.cid) {
+    throw new Error("that contact-book entry is this identity itself.");
+  }
+  const targetAd = Buffer.from(entry.address_document, "base64url");
+  const entrySig = Buffer.from(entry.registrar_sig, "base64url");
+  const joinerAd = exportAdBlob(id);
+  await withScopeAsync(async (lt) => {
+    const minted = await mutatingTx(registrar, "::actor::mint_introduction", {
+      joiner_ad: registrar.pw.packet.NewBinaryFromBuffer(joinerAd).Attach(lt),
+      target_ad: registrar.pw.packet.NewBinaryFromBuffer(targetAd).Attach(lt)
+    }, lt);
+    const introBlob = Buffer.from(minted.Reduce("intro").GetBinary());
+    await mutatingTx(id, "::actor::connect_local", {
+      name: entry.name,
+      target_ad: id.pw.packet.NewBinaryFromBuffer(targetAd).Attach(lt),
+      intro: id.pw.packet.NewBinaryFromBuffer(introBlob).Attach(lt),
+      entry_sig: id.pw.packet.NewBinaryFromBuffer(entrySig).Attach(lt),
+      text
+    }, lt);
+  });
+  scheduleCapabilityReconcile(id);
+  return `"${entry.name}" was not a contact yet \u2014 connected via the local contact book and sent the message with the introduction. If "${entry.name}" requires approval for local introductions, delivery completes once they approve.`;
+}
+var parseSendVerdict = (sent) => {
+  const has = (f) => !sent.Reduce(f).IsNil();
+  const wireId = sent.Reduce("wire_id").Visualize();
+  const cid = has("sent_to") ? sent.Reduce("sent_to").Visualize() : "";
+  if (has("downgrade_refused")) return { kind: "refused", wireId, cid };
+  if (has("migrating")) return { kind: "migrating", wireId, cid, queued: has("queued") ? Number(sent.Reduce("queued").Visualize()) : 0 };
+  if (has("route")) {
+    const notRetained = has("retained") && !sent.Reduce("retained").GetBoolean();
+    return { kind: "e2e", wireId, cid, notRetained };
+  }
+  if (has("deferred")) return { kind: "deferred", wireId, queued: has("queued") ? Number(sent.Reduce("queued").Visualize()) : 0 };
+  return { kind: "sent", wireId };
+};
+
+// ../../src/api/messaging.ts
+function replyRef(wireId, sentence) {
+  if (!wireId) return void 0;
+  return sentence !== void 0 ? { wire_id: wireId, sentence } : { wire_id: wireId };
+}
+async function sendMessage(ctx, a) {
+  const id = requireBound(ctx);
+  const { contact, text } = a;
+  const reply_to = replyRef(a.reply_to_wire_id, a.reply_to_sentence);
+  try {
+    const v = await withScopeAsync(async (lt) => parseSendVerdict(await mutatingTx(id, "::a2a_messaging::send_message", {
+      contact,
+      text,
+      ...reply_to ? { reply_to } : {}
+    }, lt)));
+    switch (v.kind) {
+      case "refused":
+        log(`[e2e-route] refused cid=${v.cid} wire_id=${v.wireId} (downgrade_refused)`);
+        break;
+      case "migrating":
+        log(`[migration] queued cid=${v.cid} wire_id=${v.wireId} (migrating, ${v.queued} queued)`);
+        break;
+      case "e2e":
+        log(`[e2e-route] cid=${v.cid} wire_id=${v.wireId} verdict=e2e (core delivered over migrated session)${v.notRetained ? " NOT RETAINED (oversized)" : ""}`);
+        if (v.notRetained) {
+          appendNotifyLog(id, { event: "send_not_retained", wire_id: v.wireId, kind: "message" });
+        }
+        break;
+      default:
+        break;
+    }
+    return v;
+  } catch (e) {
+    if (!/Unknown contact/.test(String(e))) {
+      throw errTool("send_message", String(e));
+    }
+    try {
+      const sibling = findSibling(id, contact);
+      const sent = sibling ? await sendViaSibling(id, sibling, text) : await sendViaLocalBook(id, contact, text);
+      return { kind: "introduced", text: sent };
+    } catch (e2) {
+      throw errTool("send_message", String(e2), "FALLBACK_FAILED");
+    }
+  }
+}
+async function sendFile(ctx, a) {
+  const id = requireBound(ctx);
+  const { contact, path, data_base64, upload_id, filename, mime } = a;
+  if ((path ? 1 : 0) + (data_base64 ? 1 : 0) + (upload_id ? 1 : 0) !== 1) {
+    throw upload_id ? errSendFileUploadArgs() : errSendFileArgs();
+  }
+  let buf;
+  let fname;
+  let staged = null;
+  try {
+    if (path) {
+      buf = await readFile(path);
+      fname = filename ?? basename2(path);
+    } else if (upload_id) {
+      const got = consumeStagedUpload(id, upload_id);
+      if (!got) throw errUploadNotFound(upload_id);
+      staged = got.meta;
+      buf = got.buf;
+      fname = filename ?? got.meta.filename;
+    } else {
+      if (!filename) throw errSendFileFilenameRequired();
+      buf = Buffer.from(data_base64, "base64");
+      fname = filename;
+    }
+  } catch (e) {
+    if (e instanceof OursError) throw e;
+    throw errFileUnreadable(String(e));
+  }
+  const mt = mime ?? (path ? mimeFromExt(path) : staged?.mime || "");
+  const reply_to = replyRef(a.reply_to_wire_id, a.reply_to_sentence);
+  const cap = resolveFileEnvelopeCap();
+  let preflight;
+  try {
+    preflight = withScope((lt) => checkFileEnvelope({
+      // ⚠ THE BOUND IDENTITY'S OWN PACKET, for the same reason as the send below.
+      //
+      // Dereferenced LAZILY, and that is load-bearing: checkFileEnvelope's fast
+      // path never builds a binary, so an ordinary small file must not touch
+      // `id.pw` at all. Reading it eagerly here would make every send_file
+      // require a live packet before the size question is even asked, which
+      // breaks Appendix A row 54 (`send_file failed: `) — that row reaches the
+      // outer catch through mutatingTx's fail-closed gate on a packet-less
+      // identity, and would instead die on a TypeError in here.
+      packet: { NewBinaryFromBuffer: (b) => id.pw.packet.NewBinaryFromBuffer(b) },
+      lifetime: lt,
+      filename: fname,
+      mime: mt,
+      payload: buf,
+      replyTo: reply_to,
+      cap
+    }));
+  } catch (e) {
+    if (e instanceof OursError) throw e;
+    throw errTool("send_file", String(e));
+  }
+  if (!preflight.ok) {
+    throw errFileTooLarge({
+      filename: fname,
+      bytes: preflight.bytes,
+      limit: preflight.cap,
+      envelopeBytes: preflight.envelopeBytes,
+      maxPayloadBytes: preflight.maxPayloadBytes
+    });
+  }
+  try {
+    const v = await withScopeAsync(async (lt) => {
+      const binValue = id.pw.packet.NewBinaryFromBuffer(buf).Attach(lt);
+      return parseSendVerdict(await mutatingTx(id, "::a2a_messaging::send_file", {
+        contact,
+        filename: fname,
+        mime: mt,
+        data: binValue,
+        ...reply_to ? { reply_to } : {}
+      }, lt));
+    });
+    switch (v.kind) {
+      case "refused":
+        log(`[e2e-route] refused cid=${v.cid} wire_id=${v.wireId} (downgrade_refused, file)`);
+        break;
+      case "migrating":
+        log(`[migration] file-defer cid=${v.cid} wire_id=${v.wireId} (migrating, not queued)`);
+        break;
+      case "e2e":
+        log(`[e2e-route] cid=${v.cid} wire_id=${v.wireId} verdict=e2e file (core delivered over migrated session)${v.notRetained ? " NOT RETAINED (oversized)" : ""}`);
+        if (v.notRetained) {
+          appendNotifyLog(id, { event: "send_not_retained", wire_id: v.wireId, kind: "file" });
+        }
+        break;
+      default:
+        break;
+    }
+    return { ...v, filename: fname, bytes: buf.length, mime: mt };
+  } catch (e) {
+    throw errTool("send_file", String(e));
+  }
+}
+async function listIncomingMessages(ctx) {
+  const id = requireBound(ctx);
+  try {
+    return withScope((lt) => renderInbox(readonlyTx(id, "::actor::list_incoming_messages", lt)));
+  } catch (e) {
+    throw errTool("list_incoming_messages", String(e));
+  }
+}
+async function getMessages(ctx) {
+  const id = requireBound(ctx);
+  try {
+    const fresh = await withScopeAsync(async (lt) => {
+      const data = await mutatingTx(id, "::actor::get_messages", {}, lt);
+      return renderInbox(data.Reduce("messages"));
+    });
+    refreshUnread(id);
+    const e2eWireIds = readE2eWireIds(id);
+    return buildMessagesPayload(fresh, e2eWireIds);
+  } catch (e) {
+    throw errTool("get_messages", String(e));
+  }
+}
+async function deferMessages(ctx, a) {
+  const id = requireBound(ctx);
+  const { msg_ids } = a;
+  try {
+    const n = await withScopeAsync(async (lt) => {
+      const data = await mutatingTx(id, "::actor::defer_messages", { msg_ids }, lt);
+      return data.Reduce("deferred").Visualize();
+    });
+    refreshUnread(id);
+    return { deferred: n };
+  } catch (e) {
+    throw errTool("defer_messages", String(e));
+  }
+}
+
+// ../../src/api/files.ts
+async function listIncomingFiles(ctx) {
+  const id = requireBound(ctx);
+  try {
+    return withScope((lt) => renderFileMetadata(readonlyTx(id, "::actor::list_incoming_files", lt)));
+  } catch (e) {
+    throw errTool("list_incoming_files", String(e));
+  }
+}
+async function getFiles(ctx, a = {}) {
+  const id = requireBound(ctx);
+  const { wire_ids } = a;
+  if (wire_ids !== void 0) {
+    if (wire_ids.length < 1 || wire_ids.length > FILE_SELECTION_CAP) {
+      throw errInvalidSelection(FILE_SELECTION_CAP);
+    }
+    if (wire_ids.some((wire) => !isSelectableWireId(wire))) throw errMalformedId();
+    if (new Set(wire_ids).size !== wire_ids.length) throw errDuplicateId();
+  }
+  try {
+    const out = await withScopeAsync(async (lt) => {
+      const data = await mutatingTx(id, "::actor::get_files", wire_ids === void 0 ? {} : { wire_ids }, lt);
+      return await writeIncomingFiles(id, data.Reduce("files"));
+    });
+    refreshUnread(id);
+    return {
+      files: out.files,
+      // The finished summary travels; ours-mcp cannot re-derive it. See GetFilesResult.
+      text: out.text,
+      mode: wire_ids === void 0 ? "all_unread" : "selected",
+      // null — NOT [] — for the bulk form. See GetFilesResult.
+      requested: wire_ids ?? null
+    };
+  } catch (e) {
+    const message = String(e);
+    if (wire_ids !== void 0 && /unknown, stale, or no longer unread/i.test(message)) {
+      throw errUnknownOrStaleId();
+    }
+    throw errTool("get_files", message);
+  }
+}
+function saveFileFallbackNotice(ctx, a) {
+  const id = requireBound(ctx);
+  return { existsOnDisk: findIdentityFile(id, a.wire_id) !== null };
+}
+async function deferFiles(ctx, a) {
+  const id = requireBound(ctx);
+  const { file_ids } = a;
+  try {
+    const n = await withScopeAsync(async (lt) => {
+      const data = await mutatingTx(id, "::actor::defer_files", { file_ids }, lt);
+      return data.Reduce("deferred").Visualize();
+    });
+    refreshUnread(id);
+    return { deferred: n };
+  } catch (e) {
+    throw errTool("defer_files", String(e));
+  }
+}
+
+// ../../src/api/profile.ts
+async function setBio2(ctx, a) {
+  const id = requireBound(ctx);
+  const { bio } = a;
+  try {
+    await withScopeAsync(async (lt) => {
+      await mutatingTx(id, "::a2a_messaging::set_my_bio", { bio }, lt);
+    });
+    let refreshed = 0;
+    if (id.name === rootName) {
+      for (const other of identities.values()) {
+        if (other.name === id.name) continue;
+        if (describeIdentity(other).rootCid !== id.cid) continue;
+        try {
+          await delegateRole(id, other);
+          refreshed += 1;
+        } catch (e) {
+          log(`failed to refresh root profile in role "${other.name}":`, String(e));
+        }
+      }
+    }
+    return { identity: id.name, rolesRefreshed: refreshed };
+  } catch (e) {
+    throw errTool("set_bio", String(e));
+  }
+}
+async function advertiseMigrate(ctx) {
+  const id = requireBound(ctx);
+  try {
+    return await withScopeAsync(async (lt) => {
+      const r = await mutatingTx(id, "::a2a_messaging::advertise_migrate", {}, lt);
+      return {
+        wasAdvertising: r.Reduce("was_advertising").Visualize() === "true",
+        advertising: r.Reduce("advertising").Visualize() === "true",
+        offers: parseInt(r.Reduce("offers_initiated").Visualize(), 10) || 0
+      };
+    });
+  } catch (e) {
+    throw errTool("advertise_migrate", String(e));
+  }
+}
+async function setPersona(ctx, a) {
+  const id = requireBound(ctx);
+  const { persona } = a;
+  try {
+    await withScopeAsync(async (lt) => {
+      await mutatingTx(id, "::a2a_messaging::set_my_persona", { persona }, lt);
+    });
+    return { identity: id.name };
+  } catch (e) {
+    throw errTool("set_persona", String(e));
+  }
+}
+async function readvertiseOnUpgrade(ctx) {
+  const id = requireBound(ctx);
+  try {
+    const n = await withScopeAsync(async (lt) => {
+      const data = await mutatingTx(id, "::a2a_messaging::readvertise_on_upgrade", {}, lt);
+      return data.Reduce("readvertised").Visualize();
+    });
+    return { readvertised: n };
+  } catch (e) {
+    throw errTool("readvertise_on_upgrade", String(e));
+  }
+}
+
+// ../../src/api/conversations.ts
+function renderConversation(av) {
+  const out = [];
+  const msgs = av.Reduce("messages");
+  if (msgs.IsNil()) return out;
+  for (let i = 0; ; i++) {
+    const m = msgs.Reduce(i);
+    if (m.IsNil()) break;
+    const wire = m.Reduce("wire_id");
+    const receipt = m.Reduce("receipt");
+    out.push({
+      dir: m.Reduce("dir").Visualize() === "out" ? "out" : "in",
+      text: m.Reduce("text").Visualize(),
+      date: m.Reduce("date").Visualize(),
+      // GetBoolean, never Visualize: a MUFL boolean visualizes as '%%TRUE',
+      // never 'TRUE' — the G4 trap from wire-handlers, one layer up.
+      read: m.Reduce("read").GetBoolean(),
+      wire_id: wire.IsNil() ? "" : wire.Visualize(),
+      receipt: receipt.IsNil() ? null : receipt.Visualize()
+    });
+  }
+  return out;
+}
+async function getConversation(ctx, a) {
+  const id = requireBound(ctx);
+  try {
+    const messages = withScope(
+      (lt) => renderConversation(readonlyTx(id, "::actor::get_conversation", lt, { contact: a.contact }))
+    );
+    return { contact: a.contact, messages };
+  } catch (e) {
+    throw errTool("get_conversation", String(e));
+  }
+}
+async function getReceipts(ctx, a) {
+  const id = requireBound(ctx);
+  try {
+    const receipts = withScope((lt) => {
+      const av = readonlyTx(id, "::actor::get_receipts", lt, { contact: a.contact }).Reduce("receipts");
+      const out = {};
+      if (av.IsNil()) return out;
+      for (const key of av.GetKeys()) {
+        const wid = key.Visualize();
+        out[wid] = av.Reduce(wid).Visualize();
+      }
+      return out;
+    });
+    return { contact: a.contact, receipts };
+  } catch (e) {
+    throw errTool("get_receipts", String(e));
+  }
+}
+async function markRead(ctx, a) {
+  const id = requireBound(ctx);
+  try {
+    const marked = await withScopeAsync(async (lt) => {
+      const data = await mutatingTx(id, "::actor::mark_read", { contact: a.contact }, lt);
+      return Number(data.Reduce("marked").Visualize());
+    });
+    return { contact: a.contact, marked };
+  } catch (e) {
+    throw errTool("mark_read", String(e));
+  }
+}
+async function setConversationPolicy(ctx, a) {
+  const id = requireBound(ctx);
+  try {
+    return await withScopeAsync(async (lt) => {
+      const data = await mutatingTx(id, "::actor::set_local_policy", { keep_history: a.keep_history }, lt);
+      return {
+        keepHistory: data.Reduce("keep_history").GetBoolean(),
+        autoAccept: data.Reduce("auto_accept").GetBoolean()
+      };
+    });
+  } catch (e) {
+    throw errTool("set_local_policy", String(e));
+  }
+}
+
+// ../../src/http/api-routes.ts
+var API_PREFIX = "/api/v1/";
+var op = (fn) => (ctx, body) => fn(ctx, body);
+var op0 = (fn) => (ctx) => fn(ctx);
+var opNoCtx = (fn) => (_ctx, body) => fn(body);
+var API_OPERATIONS = {
+  // ----- identity (Task 10) --------------------------------------------------
+  createIdentity: op(createIdentity),
+  createTemporaryIdentity: op(createTemporaryIdentity),
+  closeTemporaryIdentityOp: op(closeTemporaryIdentityOp),
+  createRootIdentity: op(createRootIdentity),
+  defineLocalIdentityFile: opNoCtx(defineLocalIdentityFile),
+  chooseIdentity: op(chooseIdentity),
+  listIdentities: op0(listIdentities),
+  currentIdentity: op0(currentIdentity),
+  removeIdentity: op(removeIdentity),
+  releaseLease: op0(releaseLease),
+  // ----- contacts, invites, introductions, local book (Task 11) --------------
+  generateInvite: op(generateInvite),
+  listInvites: op0(listInvites),
+  revokeInvite: op(revokeInvite),
+  addContact: op(addContact),
+  listContacts: op0(listContacts),
+  listLocalContactBook: op0(listLocalContactBook),
+  setLocalBookPolicy: op(setLocalBookPolicy),
+  removeContact: op(removeContact),
+  renameContact: op(renameContact),
+  respondToIntroduction: op(respondToIntroduction),
+  // ----- profile (Task 12) ---------------------------------------------------
+  setBio: op(setBio2),
+  advertiseMigrate: op0(advertiseMigrate),
+  readvertiseOnUpgrade: op0(readvertiseOnUpgrade),
+  setPersona: op(setPersona),
+  // ----- messaging (Task 12) -------------------------------------------------
+  sendMessage: op(sendMessage),
+  sendFile: op(sendFile),
+  listIncomingMessages: op0(listIncomingMessages),
+  getMessages: op0(getMessages),
+  deferMessages: op(deferMessages),
+  deferFiles: op(deferFiles),
+  // The messenger conversation surface. getConversation and getReceipts read
+  // without consuming or emitting; markRead is the human read event.
+  getConversation: op(getConversation),
+  getReceipts: op(getReceipts),
+  markRead: op(markRead),
+  setConversationPolicy: op(setConversationPolicy),
+  // ----- files (Task 12) -----------------------------------------------------
+  listIncomingFiles: op0(listIncomingFiles),
+  getFiles: op(getFiles),
+  saveFileFallbackNotice: op(saveFileFallbackNotice)
+};
+var apiSessionRefs = /* @__PURE__ */ new Map();
+var headerValue = (req, name) => {
+  const v = req.headers[name];
+  return typeof v === "string" && v !== "" ? v : void 0;
+};
+function enterApiSession(req) {
+  const token = headerValue(req, "x-ours-lease-token");
+  const pidRaw = headerValue(req, "x-ours-client-pid");
+  const parsed = pidRaw ? parseInt(pidRaw, 10) : NaN;
+  const pid = Number.isInteger(parsed) ? parsed : void 0;
+  const sid = token ? `api:${hashLeaseToken(token)}` : "api:anonymous";
+  sessionHeaders.set(sid, { token, pid });
+  apiSessionRefs.set(sid, (apiSessionRefs.get(sid) ?? 0) + 1);
+  return {
+    // Lazy, like the `/mcp` context: an operation that rebinds mid-call must see
+    // the map as it is now, not a copy taken at request entry.
+    ctx: {
+      sessionId: () => sid,
+      leaseToken: () => sessionHeaders.get(sid)?.token,
+      clientPid: () => sessionHeaders.get(sid)?.pid
+    },
+    release: () => {
+      const n = (apiSessionRefs.get(sid) ?? 1) - 1;
+      if (n > 0) {
+        apiSessionRefs.set(sid, n);
+        return;
+      }
+      apiSessionRefs.delete(sid);
+      sessionHeaders.delete(sid);
+    }
+  };
+}
+var sendJson = (res, status, value) => {
+  if (res.writableEnded) return;
+  res.writeHead(status, { "Content-Type": "application/json" });
+  res.end(JSON.stringify(value ?? null));
+};
+async function serveApiOperation(req, res, pathname, readBody2) {
+  const name = pathname.slice(API_PREFIX.length);
+  if (!requireAuth(req, res)) return;
+  if (req.method !== "POST") {
+    sendJson(res, 405, { error: "method not allowed: the typed API is POST-only" });
+    return;
+  }
+  const handler = Object.prototype.hasOwnProperty.call(API_OPERATIONS, name) ? API_OPERATIONS[name] : void 0;
+  if (!handler) {
+    sendJson(res, 404, { error: `unknown operation "${name}"` });
+    return;
+  }
+  let body;
+  try {
+    body = await readBody2(req);
+  } catch {
+    sendJson(res, 400, { error: "the request body must be JSON" });
+    return;
+  }
+  if (body === null || typeof body !== "object" || Array.isArray(body)) {
+    sendJson(res, 400, { error: "the request body must be a JSON object" });
+    return;
+  }
+  const session = enterApiSession(req);
+  try {
+    sendJson(res, 200, await handler(session.ctx, body));
+  } catch (err) {
+    if (err instanceof OursError) {
+      sendJson(res, 400, { error: { code: err.code, message: err.message } });
+      return;
+    }
+    log("api handler error:", name, String(err));
+    sendJson(res, 500, { error: `internal error in ${name}: ${String(err)}` });
+  } finally {
+    session.release();
+  }
+}
+
+// ../../src/runtime/sdk-signal-ownership.ts
+import { readFileSync as readFileSync2 } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+var SIGNALS = ["SIGINT", "SIGTERM"];
+var PINNED_SDK_VERSION = "0.10.12";
+var PINNED_HANDLER_NAME = "bound onSignal";
+var BOUND_FUNCTION_SOURCE = "function () { [native code] }";
+var neutralized = false;
+var lastAudit = null;
+var installedSdkVersion = () => {
+  const wrapperEntry = fileURLToPath(import.meta.resolve("@adapt-toolkit/sdk/wrapper"));
+  const packagePath = resolve(dirname(wrapperEntry), "..", "..", "package.json");
+  const parsed = JSON.parse(readFileSync2(packagePath, "utf8"));
+  return typeof parsed.version === "string" ? parsed.version : "unknown";
+};
+var sameReferences = (left, right) => left.length === right.length && left.every((listener, index) => listener === right[index]);
+var isPinnedSdkExitHandler = (listener) => listener.name === PINNED_HANDLER_NAME && listener.length === 0 && !Object.prototype.hasOwnProperty.call(listener, "prototype") && Function.prototype.toString.call(listener) === BOUND_FUNCTION_SOURCE;
+function neutralizePinnedSdkSignalHandlers() {
+  if (neutralized) return;
+  const sdkVersion = installedSdkVersion();
+  const exitBefore = process.listeners("exit");
+  const owned = /* @__PURE__ */ new Map();
+  const invalid = (detail) => {
+    lastAudit = {
+      sdkVersion,
+      outcome: "ambiguous",
+      exitListenerCount: exitBefore.length,
+      exitListenerReferencesPreserved: sameReferences(exitBefore, process.listeners("exit"))
+    };
+    throw new Error(
+      `Cannot safely neutralize @adapt-toolkit/sdk ${sdkVersion} signal ownership: ${detail}. No process signal listeners were changed.`
+    );
+  };
+  if (sdkVersion !== PINNED_SDK_VERSION) {
+    invalid(`this compatibility bridge is pinned to ${PINNED_SDK_VERSION}`);
+  }
+  for (const signal of SIGNALS) {
+    const matches = process.listeners(signal).filter(isPinnedSdkExitHandler);
+    if (matches.length !== 1) {
+      invalid(`${signal} expected exactly one ${PINNED_HANDLER_NAME} listener, found ${matches.length}`);
+    }
+    owned.set(signal, matches[0]);
+  }
+  if (owned.get("SIGINT") === owned.get("SIGTERM")) {
+    invalid("the SIGINT/SIGTERM pair unexpectedly shares one function reference");
+  }
+  for (const [signal, listener] of owned) process.off(signal, listener);
+  const exitAfter = process.listeners("exit");
+  const exitListenerReferencesPreserved = sameReferences(exitBefore, exitAfter);
+  if (!exitListenerReferencesPreserved) {
+    throw new Error("ADAPT signal neutralization unexpectedly changed process exit listeners");
+  }
+  lastAudit = {
+    sdkVersion,
+    outcome: "neutralized",
+    exitListenerCount: exitAfter.length,
+    exitListenerReferencesPreserved
+  };
+  neutralized = true;
+}
+
+// ../../src/http/server.ts
+neutralizePinnedSdkSignalHandlers();
+function looksLikeInitializeRequest(body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return false;
+  const m = body;
+  return m.jsonrpc === "2.0" && m.method === "initialize";
+}
+var LOAD_TIME_CONFIG_FIELDS = ["brokerUrl", "port", "stateDir", "gcIntervalMs", "apiVisibility"];
+function readBody(req) {
+  return new Promise((resolve2, reject) => {
+    let data = "";
+    req.on("data", (chunk) => data += chunk);
+    req.on("end", () => {
+      try {
+        resolve2(JSON.parse(data));
+      } catch (e) {
+        reject(e);
+      }
+    });
+    req.on("error", reject);
+  });
+}
+async function startDaemon(opts = {}) {
+  try {
+    return await startHttpDaemon(opts);
+  } catch (err) {
+    startupProgress?.failed();
+    log(`fatal startup error: ${err?.stack ?? err}`);
+    throw err;
+  }
+}
+async function startHttpDaemon(opts) {
+  const handleSignals = opts.handleSignals !== false;
+  if (process.env.OURS_TEST_STARTUP_FAIL === "1") {
+    throw new Error("forced startup failure (OURS_TEST_STARTUP_FAIL)");
+  }
+  if (opts.config) {
+    const drift = LOAD_TIME_CONFIG_FIELDS.filter((k) => opts.config[k] !== CONFIG[k]);
+    if (drift.length > 0) {
+      throw new Error(
+        `startDaemon(config) disagrees with the config resolved at module load (${drift.join(", ")}). The engine reads its config when src/runtime/env.ts is imported, so a later override cannot move the state dir, port or broker \u2014 set OURS_* env or config.json before importing the SDK.`
+      );
+    }
+  }
+  const mcp = opts.mcp;
+  const isInitialize = mcp?.isInitializeRequest ?? looksLikeInitializeRequest;
+  let installedHook = null;
+  if (typeof opts.onIdentityNotify === "function") {
+    const sink = opts.onIdentityNotify;
+    installedHook = (identityName, summary) => {
+      sink(identityName, summary, leases.get(identityName)?.sid ?? null);
+    };
+    setNotifyHook(installedHook);
+  }
+  log("booting wrapper\u2026");
+  try {
+    await bootWrapper();
+    startGcTimer();
+  } catch (err) {
+    if (installedHook) clearNotifyHook(installedHook);
+    stopGcTimer();
+    throw err;
+  }
+  log(`wrapper ready (identities=${identities.size}), starting HTTP server\u2026`);
+  startupProgress?.update("server");
+  const transports = {};
+  const serversBySession = /* @__PURE__ */ new Map();
+  const inflight = /* @__PURE__ */ new Map();
+  const STUCK_MS = 3e4;
+  const enterInflight = (sid) => {
+    const e = inflight.get(sid);
+    if (e) e.n++;
+    else inflight.set(sid, { n: 1, since: Date.now() });
+  };
+  const leaveInflight = (sid) => {
+    const e = inflight.get(sid);
+    if (e && --e.n <= 0) inflight.delete(sid);
+  };
+  const reapDeadSessions = () => {
+    let reaped = 0;
+    for (const sid of [...serversBySession.keys()]) {
+      if (sid === "stdio") continue;
+      const pid = sessionHeaders.get(sid)?.pid;
+      if (pid === void 0 || pid <= 1 || pidAlive(pid)) continue;
+      const inf = inflight.get(sid);
+      if (inf && inf.n > 0 && Date.now() - inf.since < STUCK_MS) continue;
+      const srv = serversBySession.get(sid);
+      serversBySession.delete(sid);
+      delete transports[sid];
+      sessionHeaders.delete(sid);
+      inflight.delete(sid);
+      void srv?.close().catch(() => {
+      });
+      mcp?.onSessionClosed?.(sid);
+      reaped++;
+      log(`session ${sid.slice(0, 8)}\u2026 reaped (client pid ${pid} dead)`);
+    }
+    return reaped;
+  };
+  const sessionReaper = setInterval(() => {
+    reapDeadSessions();
+    sweepStaleTempIdentities();
+    sweepStaleUploads();
+  }, 6e4);
+  sessionReaper.unref?.();
+  const REQ_META_MAX = 1e3;
+  const REQ_META_TTL_MS = 10 * 6e4;
+  const requestMeta = /* @__PURE__ */ new Map();
+  const noteRequestMeta = (sid, body) => {
+    const list = Array.isArray(body) ? body : [body];
+    for (const m of list) {
+      const msg = m;
+      if (!msg || typeof msg !== "object") continue;
+      if (msg.id === void 0 || msg.id === null || typeof msg.method !== "string") continue;
+      requestMeta.set(`${sid}:${String(msg.id)}`, { method: msg.method, at: Date.now() });
+    }
+    if (requestMeta.size > REQ_META_MAX) {
+      const cutoff = Date.now() - REQ_META_TTL_MS;
+      for (const [k, v] of requestMeta) {
+        if (v.at < cutoff) requestMeta.delete(k);
+        if (requestMeta.size <= REQ_META_MAX) break;
+      }
+      while (requestMeta.size > REQ_META_MAX) {
+        const oldest = requestMeta.keys().next();
+        if (oldest.done) break;
+        requestMeta.delete(oldest.value);
+      }
+    }
+  };
+  const reportUndeliverable = (sid, err) => {
+    try {
+      const text = err instanceof Error ? err.message : String(err);
+      const m = /No connection established for request ID:\s*(\S+)/.exec(text);
+      if (!m) return;
+      const rid = m[1];
+      const meta = requestMeta.get(`${sid}:${rid}`);
+      requestMeta.delete(`${sid}:${rid}`);
+      log(
+        `UNDELIVERABLE RESPONSE session=${sid.slice(0, 8)}\u2026 request_id=${rid} method=${meta?.method ?? "unknown"} age_ms=${meta ? Date.now() - meta.at : "unknown"} at=${(/* @__PURE__ */ new Date()).toISOString()} \u2014 the answer was produced but its stream was already gone`
+      );
+    } catch {
+    }
+  };
+  const httpServer = createHttpServer(async (req, res) => {
+    const url = new URL(req.url, `http://localhost:${PORT}`);
+    if (req.method === "GET" && url.pathname === "/state-dir") {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ stateDir: STATE_DIR, version: VERSION, compat: OURS_COMPAT_VERSION }));
+      return;
+    }
+    if (req.method === "GET" && (url.pathname === "/version" || url.pathname === "/info")) {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(
+        JSON.stringify({
+          name: "ours",
+          version: VERSION,
+          compat: OURS_COMPAT_VERSION,
+          protocol: PROTOCOL_VERSION,
+          pid: process.pid,
+          stateDir: STATE_DIR
+        })
+      );
+      return;
+    }
+    if (req.method === "GET" && url.pathname === "/identities") {
+      if (!requireAuth(req, res)) return;
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({
+        identities: [...identities.values()].map((i) => ({
+          name: i.name,
+          ...i.temp ? { temporary: true, stale: !pidAlive(i.temp.owner.pid) } : {}
+        }))
+      }));
+      return;
+    }
+    if (req.method === "GET" && url.pathname === "/unread") {
+      if (!requireAuth(req, res)) return;
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify(unreadSummary()));
+      return;
+    }
+    {
+      const m = /^\/identities\/([^/]+)\/notifications$/.exec(url.pathname);
+      if (req.method === "GET" && m) {
+        if (!requireAuth(req, res)) return;
+        const name = decodeURIComponent(m[1]);
+        if (validateName(name) !== null) {
+          res.writeHead(400, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ error: "invalid identity name" }));
+          return;
+        }
+        await serveNotifications(req, res, name, url.searchParams.get("since"), url.searchParams.get("kinds"));
+        return;
+      }
+    }
+    if (req.method === "POST" && url.pathname === "/files/upload") {
+      if (!requireAuth(req, res)) return;
+      const leaseTok = req.headers["x-ours-lease-token"];
+      const lease = typeof leaseTok === "string" && leaseTok ? leaseByToken(leaseTok) : void 0;
+      const id = lease ? identities.get(lease.identity) : void 0;
+      if (!id) {
+        res.writeHead(401, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "no identity bound to this session" }));
+        return;
+      }
+      const lenRaw = req.headers["content-length"];
+      const len = typeof lenRaw === "string" ? Number(lenRaw) : NaN;
+      const hdrName = req.headers["x-ours-filename"];
+      try {
+        const staged = await stageUpload(id, req, {
+          filename: typeof hdrName === "string" ? decodeURIComponent(hdrName) : "",
+          mime: typeof req.headers["content-type"] === "string" ? req.headers["content-type"] : "",
+          declaredBytes: Number.isInteger(len) && len >= 0 ? len : null,
+          cap: resolveFileEnvelopeCap()
+        });
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(staged));
+      } catch (e) {
+        const status = e instanceof UploadRefused ? e.status : 500;
+        if (!res.headersSent) {
+          res.writeHead(status, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ error: e instanceof Error ? e.message : String(e) }));
+        }
+      }
+      return;
+    }
+    {
+      const m = /^\/files\/([^/]+)$/.exec(url.pathname);
+      if (req.method === "GET" && m) {
+        if (!requireAuth(req, res)) return;
+        const wireId = decodeURIComponent(m[1]);
+        const leaseTok = req.headers["x-ours-lease-token"];
+        const lease = typeof leaseTok === "string" && leaseTok ? leaseByToken(leaseTok) : void 0;
+        const id = lease ? identities.get(lease.identity) : void 0;
+        if (!id) {
+          res.writeHead(401, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ error: "no identity bound to this session" }));
+          return;
+        }
+        const filePath = findIdentityFile(id, wireId);
+        if (!filePath) {
+          res.writeHead(404, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ error: "no such file for the bound identity (run get_files first, or it belongs to another identity)" }));
+          return;
+        }
+        try {
+          const stat = fs2.statSync(filePath);
+          res.writeHead(200, { "Content-Type": "application/octet-stream", "Content-Length": String(stat.size) });
+          const stream = fs2.createReadStream(filePath);
+          stream.on("error", () => {
+            try {
+              res.destroy();
+            } catch {
+            }
+          });
+          stream.pipe(res);
+        } catch (e) {
+          res.writeHead(500, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ error: `failed to read file: ${String(e)}` }));
+        }
+        return;
+      }
+    }
+    if (url.pathname.startsWith(API_PREFIX)) {
+      await serveApiOperation(req, res, url.pathname, readBody);
+      return;
+    }
+    if (url.pathname !== "/mcp" || !mcp) {
+      res.writeHead(404, { "Content-Type": "text/plain" });
+      res.end("Not found");
+      return;
+    }
+    if (!requireAuth(req, res)) return;
+    try {
+      if (req.method === "POST") {
+        const body = await readBody(req);
+        const sessionId = req.headers["mcp-session-id"];
+        const hdrToken = req.headers["x-ours-lease-token"];
+        const hdrPidRaw = req.headers["x-ours-client-pid"];
+        const hdrPid = hdrPidRaw ? parseInt(hdrPidRaw, 10) : void 0;
+        const headers = { token: hdrToken, pid: Number.isInteger(hdrPid) ? hdrPid : void 0 };
+        if (sessionId && transports[sessionId]) {
+          sessionHeaders.set(sessionId, headers);
+          noteRequestMeta(sessionId, body);
+          enterInflight(sessionId);
+          armSseKeepalive(res);
+          try {
+            await transports[sessionId].handleRequest(req, res, body);
+          } finally {
+            leaveInflight(sessionId);
+          }
+        } else if (!sessionId && isInitialize(body)) {
+          reapDeadSessions();
+          const transport = mcp.createTransport({
+            sessionIdGenerator: () => randomUUID(),
+            onsessioninitialized: (sid) => {
+              transports[sid] = transport;
+              sessionHeaders.set(sid, headers);
+              serversBySession.set(sid, server);
+              mcp.onSessionInitialized?.(sid, server);
+              log(`session ${sid.slice(0, 8)}\u2026 initialized`);
+            }
+          });
+          const ctx = {
+            sessionId: () => transport.sessionId ?? "pending",
+            leaseToken: () => sessionHeaders.get(transport.sessionId ?? "pending")?.token,
+            clientPid: () => sessionHeaders.get(transport.sessionId ?? "pending")?.pid
+          };
+          const server = mcp.createServer(ctx);
+          server.server.onerror = (err) => reportUndeliverable(transport.sessionId ?? "pending", err);
+          transport.onclose = () => {
+            const sid = transport.sessionId;
+            if (sid) {
+              delete transports[sid];
+              serversBySession.delete(sid);
+              sessionHeaders.delete(sid);
+              mcp.onSessionClosed?.(sid);
+              log(`session ${sid.slice(0, 8)}\u2026 closed (lease kept)`);
+            }
+          };
+          await server.connect(transport);
+          armSseKeepalive(res);
+          await transport.handleRequest(req, res, body);
+        } else {
+          res.writeHead(400, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32e3, message: "Bad Request: No valid session ID" }, id: null }));
+        }
+      } else if (req.method === "GET") {
+        const sessionId = req.headers["mcp-session-id"];
+        if (!sessionId || !transports[sessionId]) {
+          res.writeHead(400, { "Content-Type": "text/plain" });
+          res.end("Invalid or missing session ID");
+          return;
+        }
+        enterInflight(sessionId);
+        armSseKeepalive(res);
+        try {
+          await transports[sessionId].handleRequest(req, res);
+        } finally {
+          leaveInflight(sessionId);
+        }
+      } else if (req.method === "DELETE") {
+        const sessionId = req.headers["mcp-session-id"];
+        if (!sessionId || !transports[sessionId]) {
+          res.writeHead(400, { "Content-Type": "text/plain" });
+          res.end("Invalid or missing session ID");
+          return;
+        }
+        const token = sessionHeaders.get(sessionId)?.token ?? req.headers["x-ours-lease-token"];
+        if (token) {
+          for (const [n, l] of [...leases]) {
+            if (l.token !== token) continue;
+            leases.delete(n);
+            const rid = identities.get(n);
+            if (rid?.temp && rid.temp.owner.tokenHash === hashLeaseToken(token) && !rid.temp.closing) {
+              void closeTemporaryIdentity(rid, "owning session released its lease").catch(
+                (err) => log(`[${n}] close on lease release failed:`, String(err))
+              );
+            }
+          }
+          tombstones.delete(token);
+          persistBindings();
+          log(`lease released by token \u2026${token.slice(-6)}`);
+        }
+        await transports[sessionId].handleRequest(req, res);
+      } else {
+        res.writeHead(405, { "Content-Type": "text/plain" });
+        res.end("Method not allowed");
+      }
+    } catch (err) {
+      log("HTTP handler error:", String(err));
+      if (!res.headersSent) {
+        res.writeHead(500, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32603, message: "Internal server error" }, id: null }));
+      }
+    }
+  });
+  httpServer.requestTimeout = 0;
+  let torn = false;
+  const teardown = async () => {
+    if (torn) return;
+    torn = true;
+    clearInterval(sessionReaper);
+    stopGcTimer();
+    if (installedHook) clearNotifyHook(installedHook);
+    for (const sid of Object.keys(transports)) {
+      try {
+        await transports[sid].close();
+      } catch {
+      }
+      delete transports[sid];
+    }
+    serversBySession.clear();
+    for (const id of identities.values()) {
+      try {
+        saveState(id);
+      } catch (err) {
+        log(`[${id.name}] shutdown save failed:`, String(err));
+      }
+    }
+    httpServer.closeAllConnections?.();
+  };
+  try {
+    await new Promise((resolve2, reject) => {
+      const onError = (err) => reject(err);
+      httpServer.once("error", onError);
+      httpServer.listen(PORT, "127.0.0.1", () => {
+        httpServer.off("error", onError);
+        startupProgress?.ready();
+        log(`MCP server v${opts.version ?? VERSION} ready (transport=http, port=${PORT}, visibility=${API_VISIBILITY}, identities=${identities.size}, state=${STATE_DIR}, broker=${BROKER_URL})`);
+        resolve2();
+      });
+    });
+  } catch (err) {
+    await teardown();
+    throw err;
+  }
+  const shutdown = async () => {
+    log("shutting down\u2026");
+    await teardown();
+    httpServer.close();
+    await opts.onShutdown?.();
+    process.exit(0);
+  };
+  if (handleSignals) {
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+  }
+  const address = httpServer.address();
+  const port = typeof address === "object" && address !== null ? address.port : PORT;
+  return {
+    port,
+    close: async () => {
+      if (handleSignals) {
+        process.off("SIGINT", shutdown);
+        process.off("SIGTERM", shutdown);
+      }
+      await teardown();
+      await new Promise((resolve2) => httpServer.close(() => resolve2()));
+    }
+  };
+}
+export {
+  startDaemon
+};