@tinycloud/cli 1.3.0-beta.49 → 1.3.0-beta.50

package/dist/courier-entry.js

@@ -4,10 +4,10 @@ var EXT = "https://tinycloud.xyz/ext/courier/v0";
 var DEFAULT_HOST = "https://tee.node.tinycloud.xyz";
 var COURIER_SPACE = "agents";
 var AGENT_GRANT_EXPIRY = "30d";
-var kv = (path20, actions) => ({
+var kv = (path21, actions) => ({
   service: "tinycloud.kv",
   space: COURIER_SPACE,
-  path: `${PREFIX}/${path20}`,
+  path: `${PREFIX}/${path21}`,
   actions: actions.map((action) => `tinycloud.kv/${action}`)
 });
 var AGENT_GRANT = [
@@ -826,7 +826,7 @@ function authorityTuples(entries) {
   return tuples;
 }
 function renderTuples(tuples) {
-  const shown = tuples.slice(0, 3).map(({ service, space, path: path20, action }) => `${service} ${space} ${path20 || '""'} ${action}`);
+  const shown = tuples.slice(0, 3).map(({ service, space, path: path21, action }) => `${service} ${space} ${path21 || '""'} ${action}`);
   if (tuples.length > 3)
     shown.push(`(+${tuples.length - 3} more)`);
   return shown.join("; ");
@@ -6544,24 +6544,9 @@ async function cmdRevoke(args) {
   console.log(`Revoked ${handle} (${peer.courierDid}).
 Note: TC-721 prevents immediate revocation; access ends when the current outbound delegation expires (${peer.outbound.at(-1)?.expiresAt ?? "unknown"}). Rotating the agent key does not invalidate the old grant; it remains valid until its expiry.`);
 }
-async function cmdSend(args) {
-  const { profile, node } = await ctx();
-  const peerHandle = args.positional[0] ?? fail2("usage", sendUsage());
-  const peer = getPeer(profile, peerHandle);
-  const which = oneOf(args, ["new", "thread"]);
-  const threadId = which === "new" ? ulid() : which === "thread" ? requireFlag(args, "thread", sendUsage()) : fail2("usage", sendUsage());
-  const subject = args.get("new");
-  const intentRaw = args.get("intent") ?? "request";
-  if (!INTENTS.includes(intentRaw))
-    fail2("usage", `--intent must be one of: ${INTENTS.join(", ")}`);
-  const text = readTextArg(args, "--text or --file is required (or pipe the body on stdin)");
-  if (text.length > 256 * 1024)
-    fail2("too-large", "Message body exceeds the 256 KB inline limit (\xA74) \u2014 put it under files/ instead.");
+async function sendMessage(node, profile, peerHandle, peer, input) {
+  const { which, threadId, subject, text, intent, asks, constraints, inReplyTo, referenceTaskIds } = input;
   const from = { owner: profile.ownerDid, agent: profile.courierDid, label: profile.label };
-  const asks = args.all("ask").map((title, i) => ({ id: `a${i + 1}`, title }));
-  const constraints = args.all("constraint");
-  const inReplyTo = args.get("reply-to") ?? null;
-  const referenceTaskIds = args.all("task-ref");
   const startedByMe = which === "new" || Boolean(await getJson(node.kv, k.threadMeta(peerHandle, threadId)));
   let refsOwnTask = false;
   let refsAnyTask = false;
@@ -6582,7 +6567,7 @@ async function cmdSend(args) {
     threadId,
     text,
     from,
-    intent: intentRaw,
+    intent,
     asks,
     constraints,
     inReplyTo,
@@ -6599,6 +6584,32 @@ async function cmdSend(args) {
     await putCreate(node.kv, k.threadMeta(peerHandle, threadId), meta);
   }
   await putCreate(node.kv, k.msg(peerHandle, threadId, msg.messageId), msg);
+  return msg;
+}
+async function cmdSend(args) {
+  const { profile, node } = await ctx();
+  const peerHandle = args.positional[0] ?? fail2("usage", sendUsage());
+  const peer = getPeer(profile, peerHandle);
+  const which = oneOf(args, ["new", "thread"]);
+  const threadId = which === "new" ? ulid() : which === "thread" ? requireFlag(args, "thread", sendUsage()) : fail2("usage", sendUsage());
+  const subject = args.get("new");
+  const intentRaw = args.get("intent") ?? "request";
+  if (!INTENTS.includes(intentRaw))
+    fail2("usage", `--intent must be one of: ${INTENTS.join(", ")}`);
+  const text = readTextArg(args, "--text or --file is required (or pipe the body on stdin)");
+  if (text.length > 256 * 1024)
+    fail2("too-large", "Message body exceeds the 256 KB inline limit (\xA74) \u2014 put it under files/ instead.");
+  const msg = await sendMessage(node, profile, peerHandle, peer, {
+    which: which === "new" ? "new" : "thread",
+    threadId,
+    subject,
+    text,
+    intent: intentRaw,
+    asks: args.all("ask").map((title, i) => ({ id: `a${i + 1}`, title })),
+    constraints: args.all("constraint"),
+    inReplyTo: args.get("reply-to") ?? null,
+    referenceTaskIds: args.all("task-ref")
+  });
   printJson({ ok: true, threadId, messageId: msg.messageId, peer: peerHandle, intent: intentRaw, role: msg.role });
 }
 var sendUsage = () => `Usage: ${cmd('send <peer> (--new <subject> | --thread <id>) [--text t | --file f | stdin] [--intent i] [--ask "\u2026"]\u2026 [--reply-to id]')}`;
@@ -7384,8 +7395,8 @@ var Watcher = class {
     const prefix = `${PREFIX}/to/${peer.handle}/threads/`;
     const keys = await listAll(this.deps.selfKv, prefix);
     const known = /* @__PURE__ */ new Set();
-    for (const path20 of keys) {
-      const match = /^([^/]+)\/(?:meta\.json|(?:msg|task)\/[^/]+\.json)$/.exec(path20.slice(prefix.length));
+    for (const path21 of keys) {
+      const match = /^([^/]+)\/(?:meta\.json|(?:msg|task)\/[^/]+\.json)$/.exec(path21.slice(prefix.length));
       if (match && SAFE_ID.test(match[1]))
         known.add(`${peer.handle}/${match[1]}`);
     }
@@ -9043,35 +9054,35 @@ function parseEntry(value2) {
     return void 0;
   return { tier, ratePerHour, outPerHour };
 }
-function loadPeers(path20, ownerUid = process.getuid?.()) {
+function loadPeers(path21, ownerUid2 = process.getuid?.()) {
   let fd;
   try {
-    fd = fs14.openSync(path20, fs14.constants.O_RDONLY | fs14.constants.O_NOFOLLOW);
+    fd = fs14.openSync(path21, fs14.constants.O_RDONLY | fs14.constants.O_NOFOLLOW);
   } catch (error) {
     const code = error.code;
     if (code === "ENOENT")
       return /* @__PURE__ */ Object.create(null);
     if (code === "ELOOP")
-      throw new CourierError("insecure-peers", `${path20} is a symbolic link; point the flag at the file itself.`);
+      throw new CourierError("insecure-peers", `${path21} is a symbolic link; point the flag at the file itself.`);
     throw error;
   }
   try {
     const stat = fs14.fstatSync(fd);
     if (!stat.isFile())
-      throw new CourierError("insecure-peers", `${path20} is not a regular file.`);
-    if (ownerUid !== void 0 && stat.uid !== ownerUid)
-      throw new CourierError("insecure-peers", `${path20} is not owned by the courier user.`);
+      throw new CourierError("insecure-peers", `${path21} is not a regular file.`);
+    if (ownerUid2 !== void 0 && stat.uid !== ownerUid2)
+      throw new CourierError("insecure-peers", `${path21} is not owned by the courier user.`);
     if ((stat.mode & 18) !== 0) {
-      throw new CourierError("insecure-peers", `${path20} is writable by group or others; restrict it to the owner (chmod 600).`);
+      throw new CourierError("insecure-peers", `${path21} is writable by group or others; restrict it to the owner (chmod 600).`);
     }
     const parsed = JSON.parse(fs14.readFileSync(fd, "utf8"));
     if (!isRecord(parsed))
-      throw new CourierError("bad-peers", `${path20} must be a JSON object keyed by peer id.`);
+      throw new CourierError("bad-peers", `${path21} must be a JSON object keyed by peer id.`);
     const peers = /* @__PURE__ */ Object.create(null);
     for (const [peerId, value2] of Object.entries(parsed)) {
       const policy = parseEntry(value2);
       if (!policy)
-        throw new CourierError("bad-peers", `${path20} has an invalid policy for peer "${peerId}"; fix the entry. Nothing was loaded.`);
+        throw new CourierError("bad-peers", `${path21} has an invalid policy for peer "${peerId}"; fix the entry. Nothing was loaded.`);
       peers[peerId] = policy;
     }
     return peers;
@@ -9103,6 +9114,7 @@ function ensureRealDir(dir, mode) {
   }
   if (!existed && stat.uid === process.getuid?.() && (stat.mode & 4095) !== mode)
     fs15.chmodSync(dir, mode);
+  return !existed;
 }
 function fsyncDir(dir) {
   const fd = fs15.openSync(dir, "r");
@@ -9852,6 +9864,643 @@ async function cmdIntake(args) {
   }
 }
 
+// ../courier/dist/outbox.js
+import fs17 from "fs";
+import net from "net";
+import path19 from "path";
+import { randomBytes as randomBytes4 } from "crypto";
+var ULID_RE2 = /^[0-7][0-9A-HJKMNP-TV-Z]{25}$/;
+var PEER_RE = /^[A-Za-z0-9_-]{1,64}$/;
+var REQUEST_RE = /^\{"v":1,"itemId":"([0-7][0-9A-HJKMNP-TV-Z]{25})"\}$/;
+var MAX_REQUEST_BYTES = 64;
+var MAX_ITEM_BYTES = 32 * 1024;
+var RATE_WINDOW_MS2 = 60 * 60 * 1e3;
+var PIPE_TIMEOUT_MS = 5e3;
+var MAX_CONNECTIONS = 64;
+var MAX_PENDING = 32;
+var LOG_WINDOW_MS = 60 * 1e3;
+var LOG_BUDGET = 10;
+var REQUEST_BUDGET = 60;
+var REQUEST_WINDOW_MS = 60 * 1e3;
+var DEFAULT_SOCKET_GROUP = "courier-sender";
+var DENIED_SOCKET_GROUPS = ["tinycloud", "tinycloud-dev", "sudo", "docker"];
+var SERVE_LOCK = "serve.lock";
+var APPROVED_DIR = "approved";
+var ITEM_MODE = 384;
+var ITEM_KEYS = ["v", "itemId", "to", "thread", "subject", "text", "approvedSha256"];
+var Refusal = class extends Error {
+  code;
+  constructor(code) {
+    super(code);
+    this.code = code;
+  }
+};
+var ADD_USAGE = `Usage: ${cmd("outbox add <peer> (--thread <id> | --new <subject>) [--text t | --file f | stdin] [--outbox-dir d]")}`;
+var SERVE_USAGE = `Usage: ${cmd("outbox serve --pipe <socket> [--outbox-dir d] [--socket-group g] [--peers-file f] [--sent-dir d] [--once] [--dry-run]")}`;
+var OUTBOX_USAGE = `Usage: ${cmd("outbox add <peer> ... | outbox serve ...")}`;
+function lstatOrUndefined(file) {
+  try {
+    return fs17.lstatSync(file);
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return void 0;
+    throw error;
+  }
+}
+function ownerUid() {
+  const uid = process.getuid?.();
+  if (uid === void 0)
+    throw new CourierError("unsupported", "the outbox needs POSIX file ownership");
+  return uid;
+}
+var LOGGABLE_CODES = /* @__PURE__ */ new Set([
+  "EACCES",
+  "EEXIST",
+  "EIO",
+  "EISDIR",
+  "EMFILE",
+  "ENOENT",
+  "ENOSPC",
+  "ENOTDIR",
+  "EPERM",
+  "EPIPE",
+  "EROFS",
+  "ECONNRESET",
+  "bad-marker",
+  "bad-peers",
+  "socket-group-denied",
+  "unknown-group",
+  "unsafe-dir",
+  "unsafe-pipe",
+  "unsafe-socket-dir",
+  "unsafe-socket-group",
+  "unsupported"
+]);
+function safeCode(error) {
+  const code = errInfo(error).code;
+  return typeof code === "string" && LOGGABLE_CODES.has(code) ? code : "unknown";
+}
+function itemHash(item) {
+  return requestHash(Object.fromEntries(Object.entries(item).filter(([key]) => key !== "approvedSha256")));
+}
+function textOk(text, subject) {
+  if (!textVerdict(text, "multiline").allowed)
+    return false;
+  return subject === void 0 || textVerdict(subject, "summary").allowed;
+}
+function parseRequest(frame) {
+  if (frame.length > MAX_REQUEST_BYTES)
+    throw new Refusal("bad-request");
+  const match = REQUEST_RE.exec(frame.toString("utf8"));
+  if (match === null)
+    throw new Refusal("bad-request");
+  return match[1];
+}
+function findItem(root, itemId) {
+  const hits = [];
+  for (const entry of fs17.readdirSync(root)) {
+    if (entry === APPROVED_DIR)
+      continue;
+    const dir = path19.join(root, entry);
+    if (lstatOrUndefined(dir)?.isDirectory() !== true)
+      continue;
+    const file = path19.join(dir, `${itemId}.json`);
+    if (lstatOrUndefined(file) !== void 0)
+      hits.push({ peer: entry, file });
+  }
+  if (hits.length === 0)
+    throw new Refusal("not-found");
+  if (hits.length > 1)
+    throw new Refusal("ambiguous-item");
+  return hits[0];
+}
+function readItemFile(file) {
+  let fd;
+  try {
+    fd = fs17.openSync(file, fs17.constants.O_RDONLY | fs17.constants.O_NOFOLLOW);
+  } catch {
+    throw new Refusal("unsafe-item");
+  }
+  try {
+    const st = fs17.fstatSync(fd);
+    if (!st.isFile() || st.uid !== ownerUid() || (st.mode & 63) !== 0)
+      throw new Refusal("unsafe-item");
+    const buf = Buffer.alloc(MAX_ITEM_BYTES + 1);
+    let total = 0;
+    for (; ; ) {
+      const n = fs17.readSync(fd, buf, total, buf.length - total, total);
+      if (n === 0)
+        break;
+      total += n;
+      if (total > MAX_ITEM_BYTES)
+        throw new Refusal("bad-item");
+    }
+    return buf.subarray(0, total);
+  } finally {
+    fs17.closeSync(fd);
+  }
+}
+function readLedger(root, itemId) {
+  const file = path19.join(root, APPROVED_DIR, itemId);
+  let fd;
+  try {
+    fd = fs17.openSync(file, fs17.constants.O_RDONLY | fs17.constants.O_NOFOLLOW);
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return void 0;
+    throw new Refusal("unsafe-item");
+  }
+  try {
+    const st = fs17.fstatSync(fd);
+    if (!st.isFile() || st.uid !== ownerUid() || (st.mode & 63) !== 0 || st.size > 256)
+      throw new Refusal("unsafe-item");
+    return fs17.readFileSync(fd, "utf8").replace(/\n$/, "");
+  } finally {
+    fs17.closeSync(fd);
+  }
+}
+function isOutboxItem(value2, itemId, peer) {
+  if (typeof value2 !== "object" || value2 === null || Array.isArray(value2))
+    return false;
+  const o = value2;
+  if (!Object.keys(o).every((key) => ITEM_KEYS.includes(key)))
+    return false;
+  const threadOk = typeof o.thread === "string" && ULID_RE2.test(o.thread) && o.subject === void 0 || o.thread === null && typeof o.subject === "string";
+  return o.v === 1 && o.itemId === itemId && o.to === peer && PEER_RE.test(peer) && typeof o.text === "string" && typeof o.approvedSha256 === "string" && threadOk;
+}
+function parseItem(raw, itemId, peer) {
+  let value2;
+  try {
+    const text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(raw);
+    value2 = JSON.parse(text);
+    if (text !== `${canonicalJson(value2)}
+`)
+      throw new Refusal("bad-item");
+  } catch {
+    throw new Refusal("bad-item");
+  }
+  if (!isOutboxItem(value2, itemId, peer))
+    throw new Refusal("bad-item");
+  return value2;
+}
+function readMarker(file) {
+  let value2;
+  try {
+    value2 = JSON.parse(fs17.readFileSync(file, "utf8"));
+  } catch {
+    throw new CourierError("bad-marker", "unreadable sent marker");
+  }
+  const m = typeof value2 === "object" && value2 !== null ? value2 : {};
+  const at = typeof m.at === "string" ? Date.parse(m.at) : Number.NaN;
+  if (typeof m.peer !== "string" || Number.isNaN(at))
+    throw new CourierError("bad-marker", "malformed sent marker");
+  return { peer: m.peer, at };
+}
+function checkRate(sentDir, peer, cap2, now) {
+  let recent = 0;
+  for (const name2 of fs17.readdirSync(sentDir)) {
+    if (!ULID_RE2.test(name2))
+      continue;
+    const marker = readMarker(path19.join(sentDir, name2));
+    if (marker.peer === peer && now - marker.at < RATE_WINDOW_MS2)
+      recent++;
+  }
+  if (recent >= cap2)
+    throw new Refusal("rate-limited");
+}
+function recordResult(sentDir, itemId, state, messageId, now, log) {
+  const body = JSON.stringify({ v: 1, state, at: new Date(now).toISOString(), messageId });
+  try {
+    writeReplace(sentDir, `${itemId}.result.json`, `${body}
+`, 384);
+  } catch (error) {
+    log("outbox.result-write-failed", { code: safeCode(error) });
+  }
+}
+function reconcileUncertain(sentDir, now, log) {
+  const pending = fs17.readdirSync(sentDir).filter((name2) => ULID_RE2.test(name2) && lstatOrUndefined(path19.join(sentDir, `${name2}.result.json`)) === void 0);
+  for (const itemId of pending)
+    recordResult(sentDir, itemId, "uncertain", void 0, now, log);
+  return pending.length;
+}
+function recordedState(sentDir, itemId) {
+  const file = path19.join(sentDir, `${itemId}.result.json`);
+  if (lstatOrUndefined(file) === void 0)
+    return void 0;
+  try {
+    const state = JSON.parse(fs17.readFileSync(file, "utf8")).state;
+    return typeof state === "string" ? state : "uncertain";
+  } catch {
+    return "uncertain";
+  }
+}
+function groupGid(name2, file = "/etc/group") {
+  for (const line of fs17.readFileSync(file, "utf8").split("\n")) {
+    const [group, , gid] = line.split(":");
+    if (group === name2 && gid !== void 0 && /^\d+$/.test(gid))
+      return Number(gid);
+  }
+  throw new CourierError("unknown-group", `socket group ${name2} does not exist`);
+}
+function checkSocketDir(dir, group, gidOf) {
+  const st = lstatOrUndefined(dir);
+  if (!st?.isDirectory())
+    throw new CourierError("unsafe-socket-dir", "socket directory must be a real directory");
+  if (st.uid !== ownerUid())
+    throw new CourierError("unsafe-socket-dir", "socket directory must be owned by this user");
+  if ((st.mode & 511 & ~488) !== 0)
+    throw new CourierError("unsafe-socket-dir", "socket directory mode must not exceed 0750");
+  if (DENIED_SOCKET_GROUPS.includes(group))
+    throw new CourierError("unsafe-socket-group", `group ${group} may not own the sender socket`);
+  const gid = gidOf(group);
+  if (st.gid !== gid)
+    throw new CourierError("unsafe-socket-dir", "socket directory group must equal the configured group");
+  return gid;
+}
+function listen(server, pipe) {
+  return new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(pipe, () => {
+      server.off("error", reject);
+      resolve();
+    });
+  });
+}
+function nodeSender() {
+  let node;
+  return async (profile, peerHandle, input) => {
+    node ??= courierNode(profile);
+    return sendMessage(await node, profile, peerHandle, getPeer(profile, peerHandle), input);
+  };
+}
+function budgetedLog(log, now) {
+  const budget = { start: 0, used: 0, suppressed: 0 };
+  return (event, fields = {}) => {
+    const t = now();
+    if (t < budget.start || t - budget.start >= LOG_WINDOW_MS) {
+      if (budget.suppressed > 0)
+        log("outbox.log-suppressed", { count: budget.suppressed });
+      budget.start = t;
+      budget.used = 0;
+      budget.suppressed = 0;
+    }
+    if (budget.used < LOG_BUDGET) {
+      budget.used++;
+      log(event, fields);
+    } else {
+      budget.suppressed++;
+    }
+  };
+}
+async function startOutbox(opts) {
+  const log = opts.log ?? jsonLineLog();
+  const now = opts.now ?? Date.now;
+  const limited = budgetedLog(log, now);
+  const loadNow = opts.loadProfile ?? loadProfile;
+  const send = opts.send ?? nodeSender();
+  const gidOf = opts.groups ?? groupGid;
+  const dryRun = opts.dryRun ?? false;
+  const once = opts.once ?? false;
+  if (ensureRealDir(opts.sentDir, 448))
+    fsyncDir(path19.dirname(opts.sentDir));
+  const releaseLock = acquireLock(path19.join(opts.sentDir, SERVE_LOCK));
+  const uncertain = reconcileUncertain(opts.sentDir, Date.now(), limited);
+  if (uncertain > 0)
+    limited("outbox.uncertain", { count: uncertain });
+  const server = net.createServer({ allowHalfOpen: true }, accept);
+  try {
+    const gid = checkSocketDir(path19.dirname(opts.pipe), opts.socketGroup, gidOf);
+    const stale = lstatOrUndefined(opts.pipe);
+    if (stale !== void 0) {
+      if (!stale.isSocket())
+        throw new CourierError("unsafe-pipe", "pipe path exists and is not a socket");
+      fs17.unlinkSync(opts.pipe);
+    }
+    await listen(server, opts.pipe);
+    try {
+      fs17.chownSync(opts.pipe, -1, gid);
+      fs17.chmodSync(opts.pipe, 432);
+    } catch {
+      throw new CourierError("socket-group-denied", "could not assign the sender socket to the configured group");
+    }
+  } catch (error) {
+    if (server.listening) {
+      server.close();
+      if (lstatOrUndefined(opts.pipe)?.isSocket())
+        fs17.unlinkSync(opts.pipe);
+    }
+    releaseLock();
+    throw error;
+  }
+  limited("outbox.listening", { once, dryRun });
+  let chain = Promise.resolve();
+  let pending = 0;
+  let open = 0;
+  let finish = () => void 0;
+  const done = new Promise((resolve) => {
+    finish = resolve;
+  });
+  let closing;
+  const close = () => {
+    closing ??= (async () => {
+      await new Promise((resolve) => {
+        server.close(() => resolve());
+      });
+      await chain;
+      if (lstatOrUndefined(opts.pipe)?.isSocket())
+        fs17.unlinkSync(opts.pipe);
+      releaseLock();
+      finish();
+    })();
+    return closing;
+  };
+  const requests = { start: 0, count: 0 };
+  function admitRequest() {
+    const t = now();
+    if (t < requests.start || t - requests.start >= REQUEST_WINDOW_MS) {
+      requests.start = t;
+      requests.count = 0;
+    }
+    if (requests.count >= REQUEST_BUDGET)
+      return false;
+    requests.count++;
+    return true;
+  }
+  const UNLOADED_OUT_PER_HOUR = 1;
+  let peersNow;
+  function currentPeers() {
+    try {
+      peersNow = loadPeers(opts.peersFile);
+    } catch (error) {
+      limited("outbox.peers-invalid", { code: safeCode(error) });
+    }
+    return peersNow;
+  }
+  async function processRequest(frame) {
+    const itemId = parseRequest(frame);
+    if (!admitRequest())
+      throw new Refusal("busy");
+    if (lstatOrUndefined(opts.outboxRoot)?.isDirectory() !== true)
+      throw new Refusal("root-unsafe");
+    const found = findItem(opts.outboxRoot, itemId);
+    const raw = readItemFile(found.file);
+    const item = parseItem(raw, itemId, found.peer);
+    const digest = itemHash(item);
+    if (digest !== item.approvedSha256)
+      throw new Refusal("hash-mismatch");
+    const approved = readLedger(opts.outboxRoot, itemId);
+    if (approved === void 0)
+      throw new Refusal("not-approved");
+    if (approved !== digest)
+      throw new Refusal("hash-mismatch");
+    const profile = loadNow();
+    const peers = currentPeers();
+    const peer = Object.hasOwn(profile.peers, item.to) ? profile.peers[item.to] : void 0;
+    if (peer?.status !== "paired")
+      throw new Refusal("unpaired-peer");
+    if (!textOk(item.text, item.subject))
+      throw new Refusal("invalid-text");
+    if (recordedState(opts.sentDir, item.itemId) === "uncertain")
+      throw new Refusal("uncertain");
+    const outPerHour = peers === void 0 ? UNLOADED_OUT_PER_HOUR : policyOf(peers, item.to).outPerHour;
+    checkRate(opts.sentDir, item.to, outPerHour, now());
+    if (dryRun)
+      throw new Refusal("dry-run");
+    const marker = `${JSON.stringify({ v: 1, peer: item.to, at: new Date(now()).toISOString() })}
+`;
+    if (!writeNew(opts.sentDir, item.itemId, marker, 384))
+      throw new Refusal("already-used");
+    const input = {
+      which: item.thread === null ? "new" : "thread",
+      threadId: item.thread ?? ulid(),
+      subject: item.subject,
+      text: item.text,
+      intent: "request",
+      asks: [],
+      constraints: [],
+      inReplyTo: null,
+      referenceTaskIds: []
+    };
+    let sent;
+    try {
+      sent = await send(profile, item.to, input);
+    } catch (error) {
+      recordResult(opts.sentDir, item.itemId, "failed", void 0, now(), limited);
+      limited("outbox.send-failed", { code: safeCode(error) });
+      throw new Refusal("send-failed");
+    }
+    recordResult(opts.sentDir, item.itemId, "sent", sent.messageId, now(), limited);
+  }
+  function refusal(code) {
+    limited("outbox.refused", { code });
+    return `refused:${code}`;
+  }
+  async function serveRequest(frame) {
+    try {
+      await processRequest(frame);
+      return "ok";
+    } catch (error) {
+      if (error instanceof Refusal)
+        return refusal(error.code);
+      limited("outbox.internal", { code: safeCode(error) });
+      return "refused:internal";
+    }
+  }
+  function respond(socket, reply) {
+    if (socket.destroyed)
+      return;
+    socket.end(`${reply}
+`);
+    socket.setTimeout(PIPE_TIMEOUT_MS, () => socket.destroy());
+  }
+  function enqueue(socket, frame, sawExtraBytes) {
+    if (frame === void 0) {
+      respond(socket, refusal("bad-request"));
+      return;
+    }
+    if (pending >= MAX_PENDING) {
+      respond(socket, refusal("busy"));
+      return;
+    }
+    pending++;
+    chain = chain.then(async () => {
+      pending--;
+      respond(socket, sawExtraBytes() ? refusal("bad-request") : await serveRequest(frame));
+    });
+  }
+  function accept(socket) {
+    if (open >= MAX_CONNECTIONS) {
+      socket.destroy();
+      return;
+    }
+    open++;
+    socket.on("error", (error) => limited("outbox.socket-error", { code: safeCode(error) }));
+    socket.on("close", () => {
+      open--;
+      if (once)
+        void close();
+    });
+    let received = Buffer.alloc(0);
+    let decided = false;
+    let extraBytes = false;
+    const decide2 = (frame) => {
+      decided = true;
+      enqueue(socket, frame, () => extraBytes);
+    };
+    socket.setTimeout(PIPE_TIMEOUT_MS, () => {
+      if (!decided && received.length > 0)
+        decide2(void 0);
+      else
+        socket.destroy();
+    });
+    const onData = (chunk) => {
+      if (decided) {
+        extraBytes = true;
+        return;
+      }
+      if (received.length + chunk.length > MAX_REQUEST_BYTES + 1) {
+        decide2(void 0);
+        return;
+      }
+      received = Buffer.concat([received, chunk]);
+      const newline = received.indexOf(10);
+      if (newline === -1)
+        return;
+      decide2(newline === received.length - 1 ? received.subarray(0, newline) : void 0);
+    };
+    const onEnd = () => {
+      if (decided)
+        return;
+      if (received.length === 0)
+        socket.destroy();
+      else
+        decide2(received);
+    };
+    socket.on("data", onData);
+    socket.on("end", onEnd);
+  }
+  return { close, done };
+}
+function configValue(args, flag, env, usage2, fallback) {
+  const value2 = args.get(flag) ?? process.env[env] ?? fallback;
+  if (value2 === void 0 || value2 === "true" || value2 === "") {
+    throw new CourierError("usage", `--${flag} (or ${env}) must be set.
+${usage2}`);
+  }
+  return value2;
+}
+async function cmdOutboxServe(args) {
+  const base = profileDir();
+  const handle = await startOutbox({
+    outboxRoot: configValue(args, "outbox-dir", "COURIER_OUTBOX_DIR", SERVE_USAGE),
+    pipe: configValue(args, "pipe", "COURIER_OUTBOX_PIPE", SERVE_USAGE),
+    socketGroup: configValue(args, "socket-group", "COURIER_OUTBOX_SOCKET_GROUP", SERVE_USAGE, DEFAULT_SOCKET_GROUP),
+    peersFile: args.get("peers-file") ?? path19.join(base, "intake", "peers.json"),
+    sentDir: args.get("sent-dir") ?? path19.join(base, "outbox-sent"),
+    once: args.has("once"),
+    dryRun: args.has("dry-run")
+  });
+  const stop = () => {
+    void handle.close();
+  };
+  process.once("SIGINT", stop);
+  process.once("SIGTERM", stop);
+  await handle.done;
+}
+function ensurePeerDir(root, peerId) {
+  const peerDir = path19.join(root, peerId);
+  const existing = lstatOrUndefined(peerDir);
+  if (existing === void 0) {
+    try {
+      fs17.accessSync(root, fs17.constants.W_OK);
+    } catch {
+      throw new CourierError("outbox-not-writable", "outbox root is not writable by this user");
+    }
+    fs17.mkdirSync(peerDir, 1512);
+    fs17.chmodSync(peerDir, 1512);
+    fsyncDir(root);
+  } else if (!existing.isDirectory()) {
+    throw new CourierError("root-unsafe", "peer outbox path is not a real directory");
+  }
+  return peerDir;
+}
+function publishItem(dir, itemId, body) {
+  const temp = path19.join(dir, `.tmp-${randomBytes4(9).toString("hex")}`);
+  const fd = fs17.openSync(temp, "wx", ITEM_MODE);
+  try {
+    fs17.writeFileSync(fd, body);
+    fs17.fchmodSync(fd, ITEM_MODE);
+    fs17.fsyncSync(fd);
+  } catch (error) {
+    fs17.closeSync(fd);
+    fs17.rmSync(temp, { force: true });
+    throw error;
+  }
+  fs17.closeSync(fd);
+  try {
+    fs17.linkSync(temp, path19.join(dir, `${itemId}.json`));
+    fsyncDir(dir);
+    return true;
+  } catch (error) {
+    if (error.code === "EEXIST")
+      return false;
+    throw error;
+  } finally {
+    fs17.rmSync(temp, { force: true });
+  }
+}
+function ensureLedgerDir(root) {
+  const dir = path19.join(root, APPROVED_DIR);
+  if (ensureRealDir(dir, 448))
+    fsyncDir(root);
+  return dir;
+}
+function cmdOutboxAdd(args) {
+  const peerId = args.positional[0];
+  if (peerId === void 0 || !PEER_RE.test(peerId) || peerId === APPROVED_DIR)
+    throw new CourierError("usage", ADD_USAGE);
+  const which = oneOf(args, ["thread", "new"]);
+  const thread = which === "thread" ? requireFlag(args, "thread", ADD_USAGE) : null;
+  if (thread !== null && !ULID_RE2.test(thread))
+    throw new CourierError("usage", ADD_USAGE);
+  const subject = which === "new" ? requireFlag(args, "new", ADD_USAGE) : void 0;
+  const text = readTextArg(args, ADD_USAGE);
+  if (!textOk(text, subject)) {
+    throw new CourierError("invalid-text", "text must be 1..2000 characters; subject at most 200 characters");
+  }
+  const peer = getPeer(loadProfile(), peerId);
+  if (peer.status !== "paired")
+    throw new CourierError("unpaired-peer", `peer ${peerId} is not paired`);
+  const root = configValue(args, "outbox-dir", "COURIER_OUTBOX_DIR", ADD_USAGE);
+  if (lstatOrUndefined(root)?.isDirectory() !== true) {
+    throw new CourierError("root-unsafe", "outbox root must be an existing real directory");
+  }
+  const itemId = ulid();
+  const body = { v: 1, itemId, to: peerId, thread, ...subject === void 0 ? {} : { subject }, text };
+  const approvedSha256 = itemHash(body);
+  const item = { ...body, approvedSha256 };
+  const peerDir = ensurePeerDir(root, peerId);
+  if (!writeNew(ensureLedgerDir(root), itemId, `${approvedSha256}
+`, ITEM_MODE)) {
+    throw new CourierError("exists", "item id collision; retry");
+  }
+  if (!publishItem(peerDir, itemId, `${canonicalJson(item)}
+`)) {
+    throw new CourierError("exists", "item id collision; retry");
+  }
+  process.stdout.write(`${JSON.stringify({ ok: true, itemId, peer: peerId }, null, 2)}
+`);
+}
+async function cmdOutbox(args) {
+  const action = args.positional[0];
+  const rest = { ...args, positional: args.positional.slice(1) };
+  if (action === "add")
+    return cmdOutboxAdd(rest);
+  if (action === "serve")
+    return cmdOutboxServe(rest);
+  throw new CourierError("usage", OUTBOX_USAGE);
+}
+
 // ../courier/dist/consumed.js
 function isKeyMissing(error) {
   const status = String(error.status ?? error.meta?.status ?? "");
@@ -10039,9 +10688,9 @@ ${targetHelp()}`);
 
 // ../courier/dist/broker.js
 import { execFile } from "child_process";
-import fs17 from "fs";
+import fs18 from "fs";
 import os8 from "os";
-import path19 from "path";
+import path20 from "path";
 var MAX_OUTPUT = 4e3;
 var EXEC_TIMEOUT_MS = 12e4;
 var TOKEN = /^(gh[pousr]_[A-Za-z0-9]{20,255}|github_pat_[A-Za-z0-9_]{20,255})$/;
@@ -10053,7 +10702,7 @@ async function loadBrokerCredential(config, exec = execFileRunner) {
   const result = await exec(config.ghBin, ["auth", "token", "--hostname", "github.com"], {
     cwd: ownerHome,
     timeoutMs: 1e4,
-    env: { PATH: "/usr/bin:/bin", HOME: ownerHome, GH_CONFIG_DIR: path19.join(ownerHome, ".config/gh"), GH_PROMPT_DISABLED: "1", GH_NO_UPDATE_NOTIFIER: "1", LANG: "C" }
+    env: { PATH: "/usr/bin:/bin", HOME: ownerHome, GH_CONFIG_DIR: path20.join(ownerHome, ".config/gh"), GH_PROMPT_DISABLED: "1", GH_NO_UPDATE_NOTIFIER: "1", LANG: "C" }
   });
   const token2 = result.stdout.trim();
   if (result.code !== 0 || !validToken(token2))
@@ -10103,9 +10752,9 @@ var execFileRunner = (bin, args, { cwd, env, timeoutMs }) => {
 };
 function brokerEnv(credential, scratch) {
   return {
-    PATH: `${path19.dirname(credential.ghBin)}:/usr/bin:/bin`,
+    PATH: `${path20.dirname(credential.ghBin)}:/usr/bin:/bin`,
     HOME: scratch,
-    GH_CONFIG_DIR: path19.join(scratch, "gh"),
+    GH_CONFIG_DIR: path20.join(scratch, "gh"),
     GH_TOKEN: credential.token,
     GH_PROMPT_DISABLED: "1",
     GH_NO_UPDATE_NOTIFIER: "1",
@@ -10137,8 +10786,8 @@ async function runApproved(id, deps) {
   if (await isConsumed(deps.kv, id))
     fail4("approval-used", `Approval ${id} was already used; an approval covers one action.`);
   const scratchRoot = deps.scratchRoot ?? brokerRoot();
-  fs17.mkdirSync(scratchRoot, { recursive: true, mode: 448 });
-  const scratch = fs17.mkdtempSync(path19.join(scratchRoot, "run-"));
+  fs18.mkdirSync(scratchRoot, { recursive: true, mode: 448 });
+  const scratch = fs18.mkdtempSync(path20.join(scratchRoot, "run-"));
   const env = brokerEnv(credential, scratch);
   const run2 = (args) => deps.exec(credential.ghBin, args, { cwd: scratch, env, timeoutMs: EXEC_TIMEOUT_MS });
   const clean = (text) => sanitizeOutput(text, [credential.token]);
@@ -10175,7 +10824,7 @@ ${merged.stderr}` : ""}`).trim(),
       ...ok2 ? {} : { note: "The approval is used up. If the merge should still happen, file a new request." }
     };
   } finally {
-    fs17.rmSync(scratch, { recursive: true, force: true });
+    fs18.rmSync(scratch, { recursive: true, force: true });
   }
 }
 var runApprovedUsage = () => `Usage: ${cmd("run-approved <requestId>")}`;
@@ -10187,7 +10836,7 @@ async function cmdRunApproved(args) {
   const config = loadBrokerConfig(currentProfileId(), testOwnerRoot);
   assertPinnedProfile(config, loadProfile());
   const node = await courierNode(loadProfile(config.courierHome), config.courierHome);
-  const result = await runApproved(id, { kv: node.kv, credential: () => loadBrokerCredential(config), scratchRoot: path19.dirname(brokerFile(currentProfileId(), testOwnerRoot)), exec: execFileRunner, now: () => Date.now() });
+  const result = await runApproved(id, { kv: node.kv, credential: () => loadBrokerCredential(config), scratchRoot: path20.dirname(brokerFile(currentProfileId(), testOwnerRoot)), exec: execFileRunner, now: () => Date.now() });
   await writeOut(`${JSON.stringify(result, null, 2)}
 `);
   if (!result.ok)
@@ -10215,7 +10864,7 @@ async function cmdBroker(args) {
     return;
   }
   if (sub2 === "clear") {
-    fs17.rmSync(file, { force: true });
+    fs18.rmSync(file, { force: true });
     await writeOut('{"configured":false}\n');
     return;
   }
@@ -10225,33 +10874,33 @@ async function cmdBroker(args) {
   if (ghBin === "true")
     fail4("usage", "--gh-bin needs a path.");
   if (ghBin === void 0) {
-    for (const dir of (process.env.PATH ?? "").split(path19.delimiter)) {
-      const candidate = path19.join(dir || ".", "gh");
+    for (const dir of (process.env.PATH ?? "").split(path20.delimiter)) {
+      const candidate = path20.join(dir || ".", "gh");
       try {
-        fs17.accessSync(candidate, fs17.constants.X_OK);
-        ghBin = fs17.realpathSync(candidate);
+        fs18.accessSync(candidate, fs18.constants.X_OK);
+        ghBin = fs18.realpathSync(candidate);
         break;
       } catch {
       }
     }
   }
-  if (!ghBin || !path19.isAbsolute(ghBin))
+  if (!ghBin || !path20.isAbsolute(ghBin))
     fail4("usage", "Could not find gh; pass --gh-bin <absolute path>.");
   try {
-    fs17.accessSync(ghBin, fs17.constants.X_OK);
+    fs18.accessSync(ghBin, fs18.constants.X_OK);
   } catch {
     fail4("usage", `${ghBin} is not an executable file.`);
   }
   const profile = loadProfile();
   let testToken;
   if (testOwnerRoot !== void 0) {
-    testToken = fs17.readFileSync(0, "utf8").trim();
+    testToken = fs18.readFileSync(0, "utf8").trim();
     if (testToken !== TEST_TOKEN)
       fail4("usage", "Tests accept only the fixed dummy token fixture on stdin");
   }
-  ghBin = fs17.realpathSync(ghBin);
-  const st = fs17.statSync(ghBin);
-  const config = { v: 2, courierHome: fs17.realpathSync(profileDir()), profile: pinProfile(profile), ghBin, ghIdentity: { dev: st.dev, ino: st.ino }, ...testToken ? { testToken } : {} };
+  ghBin = fs18.realpathSync(ghBin);
+  const st = fs18.statSync(ghBin);
+  const config = { v: 2, courierHome: fs18.realpathSync(profileDir()), profile: pinProfile(profile), ghBin, ghIdentity: { dev: st.dev, ino: st.ino }, ...testToken ? { testToken } : {} };
   if (!testToken)
     await loadBrokerCredential(config);
   saveBrokerConfig(config, testOwnerRoot);
@@ -10349,6 +10998,13 @@ Delivery (one watcher per person per machine; never calls a model):
   intake [--queue-dir d] [--peers-file f] [--state-dir d] [--interval 60] [--once]
                                    Intake reader: copy paired peers' mirrored messages into the local queue
                                    (one <msgId>.json per message) with cheap checks. Never calls a model.
+  outbox add <peer> (--thread <id> | --new <subject>) [--text t | --file f | stdin] [--outbox-dir d]
+                                   Queue one message for a paired peer as a single-use outbox item. Text limit:
+                                   2000 characters (8 KiB UTF-8); subject limit: 200 characters.
+  outbox serve --pipe <socket> [--outbox-dir d] [--socket-group courier-sender] [--peers-file f]
+               [--sent-dir d] [--once] [--dry-run]
+                                   Sender: accept one-line item requests over a Unix socket and send the
+                                   named outbox item. Replies are ok or refused:<code>.
 
   pause <peer> <threadId> [--reason "\u2026"]   Humans: stop waking your agent for a thread; tells the peer
   resume <peer> <threadId>                 Humans: wake it again (the wake budget starts over)
@@ -10399,6 +11055,8 @@ async function run(argv) {
       return cmdWatch(sub2);
     case "intake":
       return cmdIntake(sub2);
+    case "outbox":
+      return cmdOutbox(sub2);
     case "approval":
       return cmdApproval(sub2);
     case "pause":