@volter/supercode-teams 0.3.85 → 0.3.87

package/mail/send.mjs

@@ -0,0 +1,723 @@
+// One send for every sender (docs/architecture/overview.md, "The mail operations", 3b-1): `supercode message send` and
+// `reply`, a session's `send_message`, harness serve's `sessions.message`, the daemon's own notices, and a request that
+// came through another machine's link to this machine's mail door. It resolves the receiver on the live-session map,
+// routes to another machine through Teams or to the receiver's door here, guards against loops and repeats, and words
+// the outcome for the sending agent, as crates/harness/src/mail_send.rs and mail_route.rs `deliver` did (their texts
+// kept word for word: an agent reads them). The mail it files is mailbox.rs's, through the store (store.mjs).
+import { appendFileSync, chmodSync, closeSync, fsyncSync, linkSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync, writeSync } from 'node:fs';
+import { join } from 'node:path';
+import { blake3Hex, render, shortId } from './envelope.mjs';
+import { AGENT_HARNESS, RESUME_WAIT_MS } from './agents.mjs';
+import { MAX_RELAYED_BYTES, RELAY_NAME_PREFIX } from './relay.mjs';
+import { FULL_ID_LEN, cameThroughLink, envelope as makeEnvelope, makeAddress, messageIdFor, normalMachineName, parseAddress, senderIdentity, subjectLine, threadOf } from './compose.mjs';
+
+export const EXIT_REFUSED = 2;
+export const EXIT_UNKNOWN = 3;
+export const EXIT_STORED = 4;
+export const EXIT_FAILED = 5;
+/** Exit code of a send whose answer was lost: neither refused nor failed, its outcome unknown. */
+export const EXIT_UNANSWERED = 1;
+
+/** What a sender reads of a send whose answer was lost (docs/architecture/overview.md, 3b-1: unanswered). */
+export function unansweredText(where, detail, id) {
+  return `Unanswered: ${where} took the message, but its answer was lost (${detail}), so whether it was delivered is unknown. Message id ${shortId(id)}. Don't send it again as a new message; supercode message show ${shortId(id)} says where it stands.`;
+}
+
+/** Replies in one unbroken chain between two sessions beyond which another is refused. */
+const REPLY_CHAIN_LIMIT = 32;
+/** How long a name no running session carries still reaches the session that last carried it. */
+const NAME_KEPT_MS = 7 * 24 * 60 * 60 * 1000;
+/** How often a name's last listing is written again while its session runs. */
+const NAME_SEEN_EVERY_MS = 60 * 60 * 1000;
+
+const outcome = (code, text, receipt = null) => ({ code, text, receipt });
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const readJson = (path) => { try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return null; } };
+
+/** A delivery a door refused before anything was sent. */
+class Refused extends Error { constructor(kind, bytes = 0) { super(kind); this.kind = kind; this.bytes = bytes; } }
+
+export class MailSend {
+  /**
+   * `live` the live-session map; `store` the mail store; `agents` an agent's records and plan; `relays` the Claude relay
+   * sender; `askMachine(machine, request)` one request to another machine's mail door; `deliverRuntime(receipt, text,
+   * wake)` one hosted runtime's input ('steered', 'started' or 'not_woken'); `codexAnswer(request)` a native Codex
+   * question's answer through its app-server.
+   */
+  constructor({ machine, mailRoot, live, store, agents, relays, askMachine, deliverRuntime, codexAnswer, log = () => {} }) {
+    Object.assign(this, { machine, mailRoot, live, store, agents, relays, askMachine, deliverRuntime, codexAnswer, log });
+  }
+
+  // ---- one send ----------------------------------------------------------------------------------------------------
+
+  /**
+   * Send `body` from `caller` (`{ address, name }`) to `to` (an address, `name@machine`, `operator:<name>`, or a name
+   * unique here): through Teams when `to` is on another machine, else through its door here. `link` is the link a request
+   * came through (`{ principal, name }`), or null for this machine's own callers. Answers `{ code, text, receipt }`.
+   */
+  async send(caller, to, body, options = {}, context = {}) {
+    // A send under an --id is held while it runs: the sent marker is written only once it is done, so a second send
+    // under the same key meanwhile waits for the first and takes its outcome (sent once), never delivering it again; one
+    // after a first that was not sent sends.
+    const key = typeof options.id === 'string' ? `${caller.address}\0${options.id}` : null;
+    if (key) {
+      const running = (this.inFlight ??= new Map()).get(key);
+      if (running) {
+        const first = await running.catch(() => null);
+        if (first?.code === 0) return outcome(0, `Already sent with --id ${options.id}: ${first.text} Nothing was sent again.`, first.receipt ?? null);
+        return this.send(caller, to, body, options, context);
+      }
+    }
+    const sending = this.#send(caller, to, body, options, context);
+    if (!key) return sending;
+    this.inFlight.set(key, sending);
+    try { return await sending; } finally { if (this.inFlight.get(key) === sending) this.inFlight.delete(key); }
+  }
+
+  async #send(caller, to, body, { subject = null, in_reply_to = null, notify_when_idle = false, queue = false, id = null, notice = false, thread = null, message_id = null } = {}, { link = null } = {}) {
+    // an id its client chose (so a lost answer can name it), never an idempotency key: it marks nothing sent
+    const chosen = typeof message_id === 'string' && /^m-[0-9a-f]{24}$/.test(message_id) ? message_id : null;
+    const machine = this.#remoteMachine(to);
+    if (machine) {
+      if (link) return outcome(EXIT_UNKNOWN, `${to} is not on this machine; a send through its mail door is for its own sessions.`);
+      const answered = this.#answeredId(caller.address, in_reply_to);
+      if (answered.refused) return answered.refused;
+      // the sender names the message's id itself (the other door files it under exactly this id), so its own send log
+      // holds every message it sent, wherever it went
+      const messageId = id == null && chosen ? chosen : messageIdFor(caller.address, id);
+      const carried = answered.id ? (this.#filedThread(answered.id) ?? this.#sentThread(caller.address, answered.id)) : null;
+      const request = { op: 'send', from: caller.address, from_name: caller.name, to, body, subject, in_reply_to: answered.id, thread: carried, notify_when_idle, queue, id: messageId, notice };
+      const sent = await this.#remoteSend(machine, request);
+      // unanswered, it may have been delivered: kept in the send log, so a later reply to it resolves here
+      if (sent.code === 0 || sent.code === EXIT_STORED || sent.receipt?.unanswered === true) this.#recordSend(caller.address, to, messageId, carried ?? answered.id ?? messageId);
+      return sent;
+    }
+    return this.#deliver(caller, to, body, { subject, in_reply_to, notify_when_idle, queue, id, notice, thread, chosen }, link);
+  }
+
+  /** The machine `to` names when it is not this one, in its normal form. */
+  #remoteMachine(to) {
+    const parsed = parseAddress(to);
+    let machine = parsed?.machine ?? null;
+    if (!parsed) { const at = String(to).lastIndexOf('@'); if (at < 0) return null; machine = normalMachineName(String(to).slice(at + 1)); }
+    return machine !== this.machine ? machine : null;
+  }
+
+  /** Hand a request to another machine's mail door through Teams (mail_send.rs `remote_send`). */
+  async #remoteSend(machine, request) {
+    try {
+      const answer = await this.askMachine(machine, request);
+      const code = Number.isInteger(answer?.code) ? answer.code : EXIT_FAILED;
+      const text = typeof answer?.text === 'string' ? answer.text : typeof answer?.detail === 'string' ? answer.detail : 'the other machine answered nothing readable';
+      return outcome(code, text, answer?.receipt ?? null);
+    } catch (error) {
+      const detail = String(error?.message ?? error);
+      // the door took it and its answer was lost: unanswered, never refused or failed (what it did there is unknown)
+      if (error?.unanswered === true) return outcome(EXIT_UNANSWERED, unansweredText(`machine ${machine}`, detail, request.id), { unanswered: true, message_ids: [request.id] });
+      if (detail.includes('no mail grant')) return outcome(EXIT_REFUSED, `Not sent: machine ${machine} does not accept mail from you (no mail grant). Only an operator can grant it; tell your user. Don't retry.`);
+      return outcome(EXIT_FAILED, `Not sent to machine ${machine}: ${detail}`);
+    }
+  }
+
+  /**
+   * The message a reply answers, named as the agent was shown it (mail_send.rs `answered_id`): a prefix names the one
+   * message it matches among those the caller received and those it sent, or nothing is sent; a whole id is kept.
+   */
+  #answeredId(callerAddress, answered) {
+    if (typeof answered !== 'string' || answered.length >= FULL_ID_LEN) return { id: answered ?? null };
+    const found = this.store.findPrefixIn(callerAddress, answered).map((item) => item.envelope.id);
+    for (const id of this.#sentIds(callerAddress)) if (id.startsWith(answered) && !found.includes(id)) found.push(id);
+    if (found.length === 1) return { id: found[0] };
+    if (!found.length) return { refused: outcome(EXIT_REFUSED, `Not sent: no message you received or sent has an id starting ${answered}. Name the message you answer as its envelope or your send showed it.`) };
+    return { refused: outcome(EXIT_REFUSED, `Not sent: ${answered} names ${found.length} messages you received or sent (${found.join(', ')}). Give more of its id.`) };
+  }
+
+  /** The receiver `to` names here: `{ address, name, session (its live row, when it runs) }`, or an outcome. */
+  #receiver(to, sessions) {
+    const operator = String(to).startsWith('operator:') ? makeAddress(this.machine, 'operator', String(to).slice('operator:'.length)) : null;
+    const parsed = parseAddress(operator ?? to);
+    // an operator (a board, a script) is not a listed session: its address is taken as given
+    if (parsed && (parsed.harness === 'operator' || parsed.harness === 'board')) return { address: parsed.address, name: `${parsed.session}@${parsed.machine}` };
+    // an agent's one mailbox: its plan decides which of its sessions receives it
+    if (parsed?.harness === AGENT_HARNESS) {
+      if (!this.agents.load(parsed.session)) return { outcome: outcome(EXIT_UNKNOWN, `No agent named ${parsed.session} is declared on this machine. Nothing was sent. Run supercode agent show for the declared agents.`) };
+      return { address: parsed.address, name: `agent ${parsed.session}@${parsed.machine}` };
+    }
+    if (parsed) {
+      const session = sessions.find((row) => row.address === parsed.address);
+      if (!session) return { outcome: outcome(EXIT_UNKNOWN, `${to} is no longer running. Nothing was sent. Run supercode message list for the live sessions.`) };
+      return { address: session.address, name: session.name, session };
+    }
+    // a name: unique among the sessions here, else the session it last named (the names ledger)
+    const [wantedRaw, at] = [String(to).split('@')[0], String(to).includes('@') ? String(to).slice(String(to).indexOf('@') + 1) : null];
+    if (at !== null && at !== this.machine) return { outcome: outcome(EXIT_UNKNOWN, `Not sent: ${to} is on machine ${at}, not this one. Nothing was sent.`) };
+    const wanted = wantedRaw;
+    const short = (row) => row.name.split('@')[0];
+    const matching = sessions.filter((row) => short(row) === wanted);
+    if (matching.length === 1) return { address: matching[0].address, name: matching[0].name, session: matching[0] };
+    if (!matching.length) {
+      const remembered = this.#rememberedAddress(wanted);
+      if (remembered) {
+        const session = sessions.find((row) => row.address === remembered);
+        if (!session) return { outcome: outcome(EXIT_UNKNOWN, `${wanted} was ${remembered}, which is not running. Nothing was sent. Run supercode message list for the live sessions.`) };
+        return { address: session.address, name: session.name, session, alias: ` "${wanted}" is a name it ran under before; it runs as ${session.name} now.` };
+      }
+    }
+    let hint = '';
+    if (matching.length > 1) hint = ` ${matching.length} sessions are named ${wanted}; use its address.`;
+    else {
+      const near = sessions.filter((row) => {
+        const name = short(row);
+        let common = 0; while (common < name.length && common < wanted.length && name[common] === wanted[common]) common++;
+        return name.includes(wanted) || wanted.includes(name) || common >= 4;
+      }).slice(0, 3).map((row) => `${row.name} (${row.address.split(':')[2]}, ${row.status})`);
+      if (near.length) hint = ` Did you mean: ${near.join(', ')}?`;
+    }
+    return { outcome: outcome(EXIT_UNKNOWN, `No session named "${wanted}" is reachable.${hint} Run supercode message list. Nothing was sent.`) };
+  }
+
+  /** The door that reaches `address` here, from one read of the live sessions (mail_route.rs `door_in`): null when no
+   *  running session has it. */
+  #door(address, sessions) {
+    const parsed = parseAddress(address);
+    if (!parsed || parsed.machine !== this.machine) return { kind: 'other_machine', machine: parsed?.machine ?? null };
+    if (parsed.harness === 'operator' || parsed.harness === 'board') return { kind: 'operator' };
+    const session = sessions.find((row) => row.address === address);
+    if (!session) return null;
+    if (session.door === 'runtime') return { kind: 'runtime', session };
+    if (session.door === 'native') return { kind: 'native', session };
+    if (session.door === 'hook') return { kind: 'hook', session, pane: session.pane ?? null, idle: session.status === 'idle' };
+    return { kind: 'stored', session };
+  }
+
+  /** Deliver from `caller` to `to` on this machine (mail_send.rs `deliver`). */
+  async #deliver(caller, to, body, { subject, in_reply_to, notify_when_idle, queue, id, notice, thread: carried, chosen }, link) {
+    const sessions = this.live.sessions();
+    const receiver = this.#receiver(to, sessions);
+    if (receiver.outcome) return receiver.outcome;
+    const { address, name } = receiver;
+    if (address === caller.address) return outcome(EXIT_REFUSED, 'Not sent: that address is your own session.');
+    const door = parseAddress(address).harness === AGENT_HARNESS ? null : this.#door(address, sessions);
+    const messageId = id == null && chosen ? chosen : messageIdFor(caller.address, id);
+    const marker = this.#sentMarker(caller.address, messageId);
+    const terminal = door?.kind === 'hook' && door.pane != null;
+    let previous = null; try { previous = readFileSync(marker, 'utf8'); } catch { /* not sent before */ }
+    if (previous !== null) {
+      if (terminal && !queue) this.store.requestWake(address, messageId);
+      return outcome(0, `Already sent with --id ${id ?? ''}: ${previous} Nothing was sent again.`, this.#deliveryReceipt(address, messageId, terminal));
+    }
+    const answered = this.#answeredId(caller.address, in_reply_to);
+    if (answered.refused) return answered.refused;
+    if (answered.id?.startsWith('q-')) return this.#questionReply(caller, address, answered.id, body, link);
+    if (answered.id && this.#replyChainDepth(caller.address, address, answered.id) >= REPLY_CHAIN_LIMIT) {
+      return outcome(EXIT_REFUSED, `Not sent: you and ${name} have answered each other ${REPLY_CHAIN_LIMIT} times in a row. If you are trading acknowledgements or status, stop; to go on, send a new message (without --re), or tell your user.`);
+    }
+    const sent = makeEnvelope({
+      id: messageId, from: caller.address, from_name: caller.name, sender_identity: senderIdentity(caller.address, link, this.machine),
+      kind: notice ? 'notice' : 'peer', reply_via: { mode: notice ? 'none' : 'command' },
+      in_reply_to: answered.id, thread: answered.id ? this.#replyThread(caller.address, address, answered.id, carried) : null,
+      subject: subjectLine(subject), body,
+    });
+    const plan = await this.#plan(sent, address, {});
+    if (plan.outcome) return plan.outcome;
+    if (plan.plan) return this.#deliverPlanned(caller, sent, plan.plan, { queue, notify_when_idle });
+    // the thread this message is in, kept in the send log: a later reply to it continues that thread
+    const sentIn = threadOf(sent);
+    if (!door || door.kind === 'other_machine') return outcome(EXIT_UNKNOWN, `${name} is no longer running. Nothing was sent. Run supercode message list for the live sessions.`);
+    const idleNote = notify_when_idle && cameThroughLink(sent)
+      ? ' No idle notice: this message came through a link, so its return address is as claimed, and nothing is sent to it on its own (D200); a reply is the receiver\'s own send.'
+      : notify_when_idle ? ' Subscribed: one idle notice reaches you when its next turn ends.' : '';
+    let delivered;
+    try { delivered = await this.route(sent, address, door, !queue, notify_when_idle); }
+    catch (error) {
+      if (error instanceof Refused && error.kind === 'queue') return outcome(EXIT_REFUSED, `Not sent: ${name} is idle, and a Claude session always starts a turn when a message arrives, so --queue cannot hold it. Send without --queue to wake it.`);
+      if (error instanceof Refused) return outcome(EXIT_REFUSED, `Not sent: the message is ${error.bytes} bytes; the limit is ${MAX_RELAYED_BYTES}. Write it to a file and send its path instead.`);
+      return outcome(EXIT_FAILED, `Not sent to ${name}: ${error.message}`);
+    }
+    const [code, what] = {
+      steered: [0, 'steered into its running turn'],
+      started: [0, 'it was idle, so the message started a turn'],
+      native_busy: [0, 'it will read it at its next tool call'],
+      native_idle: [0, 'it was idle, so the message starts its next turn'],
+      hooked: [0, 'queued in its mailbox; terminal delivery waits for native transcript confirmation'],
+      hook_woken: [0, 'it was idle, so its pane was told to read its mailbox; its hook shows it the message in that turn'],
+      queued: [0, 'it is idle and --queue leaves it so; the message waits in its mailbox'],
+      operator: [0, 'filed in its mailbox'],
+      already: [0, 'it already had this message; nothing was sent again'],
+      stored: [EXIT_STORED, 'Stored (not failed): it has no delivery door, so it sees this only if it runs supercode message inbox (a Codex session gets one with: supercode message setup codex). Don\'t resend, and don\'t wait for a reply'],
+    }[delivered];
+    this.#recordSend(caller.address, address, messageId, sentIn);
+    const harness = parseAddress(address).harness;
+    const text = code === 0
+      ? `sent to ${name} (${harness}, ${door.kind}): ${what}. Message id ${shortId(messageId)}.${receiver.alias ?? ''}${idleNote} Don't poll; carry on.`
+      : `${name} (${harness}): ${what}. Message id ${shortId(messageId)}.${idleNote}`;
+    if (code === 0 && id != null) { try { mkdirSync(join(marker, '..'), { recursive: true }); writeFileSync(marker, text); } catch { /* the marker is best kept */ } }
+    return outcome(code, text, code === 0 ? this.#deliveryReceipt(address, messageId, terminal) : null);
+  }
+
+  /** An agent's plan for `sent` (its thread store decides), or an outcome when the plan refused it. */
+  async #plan(sent, address, channel) {
+    try { return { plan: await this.agents.plan(sent, address, channel) }; }
+    catch (error) { return { outcome: outcome(EXIT_FAILED, `Not sent: ${error.message}`) }; }
+  }
+
+  // ---- the doors ---------------------------------------------------------------------------------------------------
+
+  /**
+   * Deliver `sent` to `to` through `door` (mail_route.rs `deliver`); with `wake` false an idle receiver is not started,
+   * with `notifyWhenIdle` its sender gets one idle notice after its next turn. Answers how it went ('steered', 'started',
+   * 'native_busy', 'native_idle', 'hooked', 'queued', 'stored', 'operator' or 'already'); throws Refused for a delivery
+   * refused before anything was sent, and an Error with what failed.
+   */
+  async route(sent, to, door, wake, notifyWhenIdle) {
+    this.store.open(to);
+    let finalReply = false;
+    let delivered;
+    // a message its receiver already has (its own claim, or an earlier hand-over to its door) is never handed over again
+    if ((door.kind === 'native' || door.kind === 'runtime') && this.store.findIn(to, sent.id)?.state === 'read' && this.store.claimOf(to, sent.id)?.recipient === true) return 'already';
+    if (door.kind === 'runtime') {
+      // its final message goes back as the reply only to a sender this machine knows (D200)
+      const answers = sent.reply_via?.mode === 'command' && !cameThroughLink(sent);
+      const handed = answers ? { ...sent, reply_via: { mode: 'final_message', destination: sent.from_name } } : sent;
+      const receipt = this.live.runtimeReceipt(door.session.address.split(':')[2], door.session.address.split(':').slice(3).join(':'));
+      if (!receipt) throw new Error('the live runtime\'s receipt is gone');
+      const how = await this.deliverRuntime(receipt, render(handed), wake);
+      if (how === 'not_woken') { this.store.deliver(to, sent); delivered = 'queued'; }
+      else { this.store.deliverRead(to, handed); finalReply = answers; delivered = how === 'steered' ? 'steered' : 'started'; }
+    } else if (door.kind === 'native') {
+      const busy = door.session.status !== 'idle';
+      if (!wake && !busy) throw new Refused('queue');
+      // its reply line names the door this session really has: its tools when it runs supercode's MCP server
+      const handed = sent.reply_via?.mode === 'command' && door.session.tools ? { ...sent, reply_via: { mode: 'tool' } } : sent;
+      const text = render(handed);
+      if (Buffer.byteLength(text) > MAX_RELAYED_BYTES) throw new Refused('too_long', Buffer.byteLength(text));
+      // filed before it is handed over: a session that reads its mailbox at its first tool call finds it; a relay that
+      // fails takes back the copy this delivery filed
+      const filedHere = this.store.findIn(to, handed.id) == null;
+      const filed = this.store.deliverRead(to, handed);
+      const relayed = await this.relays.send(handed.from, handed.from_name, { sessionId: door.session.address.split(':').slice(3).join(':'), name: door.session.name.split('@')[0], socket: door.session.socket }, text, handed.id);
+      if (!relayed.delivered) { if (filedHere) { try { unlinkSync(filed); } catch { /* gone */ } } throw new Error(relayed.detail); }
+      delivered = busy ? 'native_busy' : 'native_idle';
+    } else if (door.kind === 'hook') {
+      this.store.deliver(to, sent);
+      if (wake) this.store.requestWake(to, sent.id);
+      delivered = 'hooked';
+    } else if (door.kind === 'stored') { this.store.deliver(to, sent); delivered = 'stored'; }
+    else { this.store.deliver(to, sent); delivered = 'operator'; }
+    // a hand-over to the recipient's own door is its delivery, recorded as such
+    if (['steered', 'started', 'native_busy', 'native_idle'].includes(delivered)) {
+      try { this.store.claimFor(to, sent.id, { pid: process.pid, via: 'door', caller: null, recipient: true, at_ms: Date.now() }); } catch { /* best kept */ }
+    }
+    // nor is an idle notice routed to a claimed address (D200)
+    const noticeWanted = notifyWhenIdle && door.kind !== 'operator' && !cameThroughLink(sent);
+    if (noticeWanted || finalReply) this.store.subscribeIdle(to, { message_id: sent.id, subscriber: sent.from, notice: noticeWanted, final_reply: finalReply });
+    return delivered;
+  }
+
+  /**
+   * Deliver `sent` to every receiver `plan` names: a `to` receiver through its door (a stopped holder the mailbox
+   * launched is resumed first), a `cc` receiver filed unread and not woken (mail_send.rs `deliver_planned`).
+   */
+  async deliverPlanned(caller, sent, plan, { queue = false, notify_when_idle = false } = {}) { return this.#deliverPlanned(caller, sent, plan, { queue, notify_when_idle }); }
+
+  async #deliverPlanned(caller, sent, plan, { queue, notify_when_idle }) {
+    const reached = [], copied = [], failed = [];
+    if (plan.agent) {
+      // the agent's own mailbox keeps the record of what was addressed to it
+      try { this.store.deliverRead(plan.agent, sent); } catch (error) { failed.push(`the agent's mailbox (${error.message})`); }
+    }
+    const sessions = this.live.sessions();
+    for (const recipient of plan.recipients.filter((item) => item.address !== caller.address)) {
+      const label = this.#label(sessions, recipient.address);
+      this.#recordSend(caller.address, recipient.address, sent.id, threadOf(sent));
+      if (!recipient.wake) {
+        try { this.#fileUnread(recipient.address, sent); copied.push(label); } catch (error) { failed.push(`${label} (${error.message})`); }
+        continue;
+      }
+      try { reached.push(`${label} (${await this.#deliverWoken(sent, recipient.address, sessions, queue, notify_when_idle)})`); }
+      catch (error) { failed.push(`${label} (${error.message})`); }
+    }
+    const thread = plan.thread ? ` Thread ${shortId(plan.thread.id)}.` : '';
+    let text;
+    if (!reached.length && !copied.length) text = `Not sent: nobody in its thread could be reached.${thread}`;
+    else text = `sent to ${reached.length ? reached.join(', ') : 'no one woken'}.${copied.length ? ` CC (filed, not woken): ${copied.join(', ')}.` : ''} Message id ${shortId(sent.id)}.${thread} Don't poll; carry on.`;
+    if (failed.length) text += ` Not delivered to: ${failed.join('; ')}.`;
+    const code = reached.length || copied.length ? 0 : EXIT_FAILED;
+    return outcome(code, text, code === 0 ? { delivered: true, message_ids: [sent.id], receipt: 'agent-mailbox' } : null);
+  }
+
+  /** `sent` filed unread in `address`'s mailbox on this machine's mail, without waking it (mail_agent.rs `file_unread`):
+   *  mail for another machine's address waits here until the watch carries it; one that came through a link is never
+   *  filed for another machine (the store refuses it). */
+  #fileUnread(address, sent) { this.store.deliver(address, sent); }
+
+  /** What a receiver is called in an outcome: its session name when it runs here, else its address. */
+  #label(sessions, address) {
+    const parsed = parseAddress(address);
+    if (parsed && (parsed.harness === 'operator' || parsed.harness === 'board')) return `${parsed.session}@${parsed.machine}`;
+    return sessions.find((row) => row.address === address)?.name ?? address;
+  }
+
+  /** Deliver `sent` to `to` through its door, waking it: on another machine filed there, a stopped one here resumed
+   *  first (mail_send.rs `deliver_woken`). Says how it went. */
+  async #deliverWoken(sent, to, sessions, queue, notifyWhenIdle) {
+    let door = this.#door(to, sessions);
+    if (door?.kind === 'other_machine') {
+      // the one way out: mail that came to this machine through a link never leaves it again (mailbox.rs `ask_machine`)
+      if (cameThroughLink(sent)) throw new Error(`not carried on to ${door.machine}: a message that came to this machine through a link is for its own sessions only`);
+      const answer = await this.askMachine(door.machine, { op: 'file', to, envelope: sent });
+      if (answer?.code !== 0) throw new Error(typeof answer?.text === 'string' ? answer.text : 'the other machine refused the message');
+      return 'filed on its machine';
+    }
+    if (!door) {
+      // a reply to a closed session resumes it; only one the mailbox launched, the way it was launched
+      this.store.deliver(to, sent);
+      if (!(await this.agents.resumable(to))) return 'stopped; not resumed, since the mailbox did not launch it: the message waits in its mailbox';
+      try { await this.agents.resume(to); } catch (error) { throw new Error(`not resumed: ${error.message}`); }
+      const started = Date.now();
+      for (;;) {
+        door = this.#door(to, this.live.sessions());
+        if (door) break;
+        if (Date.now() - started > RESUME_WAIT_MS) return 'resumed; the message waits in its mailbox';
+        await sleep(1000);
+      }
+    }
+    let how;
+    try { how = await this.route(sent, to, door, !queue, notifyWhenIdle); }
+    catch (error) {
+      if (error instanceof Refused && error.kind === 'queue') throw new Error('idle, and --queue cannot hold a Claude session\'s mail');
+      if (error instanceof Refused) throw new Error(`${error.bytes} bytes; the limit is ${MAX_RELAYED_BYTES}`);
+      throw error;
+    }
+    return { steered: 'steered into its running turn', started: 'started a turn', native_busy: 'read at its next tool call', native_idle: 'starts its next turn', hooked: 'in its mailbox, its hook shows it', queued: 'waits in its mailbox', operator: 'filed', already: 'it already had it', stored: 'stored; it has no delivery door' }[how];
+  }
+
+  // ---- a filing --------------------------------------------------------------------------------------------------
+
+  /**
+   * File `body` from `from` (`{ address, name }`) in the mailbox of `to`, on this machine's mail whatever machine `to`
+   * names (mail for another machine waits here until the watch carries it there), as mail_file.rs `file` did: a key
+   * names the same message every time, so a repeat files nothing new; a wake is asked only by the filing that wrote it.
+   * A typed line's record (`typed`, D195) is filed read, under its own `i-` id, from the principal that typed it.
+   * `sender_identity` is the filer's observation (this daemon's), never the request's own. Answers `{ code, message_id,
+   * new, to }`, or `{ code, text }`.
+   */
+  file(from, to, body, { subject = null, key = null, wake = true, sender_identity = null, typed = false } = {}) {
+    const sender = parseAddress(from.address), receiver = parseAddress(to);
+    if (!sender) return { code: EXIT_REFUSED, text: `\`${from.address}\` is not a session address; addresses look like sc:<machine>:<harness>:<session-id>` };
+    if (!receiver) return { code: EXIT_REFUSED, text: `\`${to}\` is not a session address; addresses look like sc:<machine>:<harness>:<session-id>` };
+    let id = messageIdFor(sender.address, key);
+    if (typed) id = `i-${id.replace(/^m-/, '')}`;
+    const filed = makeEnvelope({ id, from: sender.address, from_name: from.name ?? '', sender_identity, kind: typed ? 'user' : 'peer', reply_via: { mode: typed ? 'none' : 'command' }, subject: subjectLine(subject), body });
+    try {
+      if (this.store.findIn(receiver.address, id)) return { code: 0, message_id: id, new: false, to: receiver.address };
+      // a typed line's record is read already: it reached the session as its composer turn, never as mail
+      if (typed) this.store.deliverRead(receiver.address, filed);
+      else {
+        this.store.deliver(receiver.address, filed);
+        if (wake) this.store.requestWake(receiver.address, id);
+      }
+      return { code: 0, message_id: id, new: true, to: receiver.address };
+    } catch (error) { return { code: EXIT_FAILED, text: error.message }; }
+  }
+
+  // ---- harness serve's sessions.message ----------------------------------------------------------------------------
+
+  /**
+   * `harness.v1.sessions.message` without `as_user` (harness_service.rs `message_live_session`): `text` from an operator
+   * mailbox (`from_name`, `supercode` by default) into the session or agent `locator` names. A refusal is a result, not
+   * an error: `{ delivered_to_bus: false, refusal: { reason, message } }`. harness serve adds its own inbound controls.
+   */
+  async message(params) {
+    const refused = (reason, message) => ({ delivered_to_bus: false, refusal: { reason, message } });
+    const text = typeof params?.text === 'string' ? params.text : '';
+    if (!text.trim()) return refused('delivery_failed', 'refusing to deliver an empty message');
+    const fromName = String(params.from_name ?? 'supercode').trim().replace(/[\s@]/g, '-');
+    if (!fromName) return refused('invalid_sender', 'from_name must not be empty');
+    const sender = makeAddress(this.machine, 'operator', fromName);
+    if (!sender) return refused('invalid_sender', `\`sc:${this.machine}:operator:${fromName}\` is not a session address; addresses look like sc:<machine>:<harness>:<session-id>`);
+    const harness = params.locator?.harness, sessionId = params.locator?.session_id;
+    const receiver = typeof harness === 'string' && typeof sessionId === 'string' ? makeAddress(this.machine, harness, sessionId) : null;
+    if (!receiver) return refused('delivery_failed', `\`sc:${this.machine}:${harness}:${sessionId}\` is not a session address; addresses look like sc:<machine>:<harness>:<session-id>`);
+    if (params.voice_for != null && params.voice_for !== receiver) return refused('invalid_sender', 'a voice front must represent the receiving session');
+    const sessions = this.live.sessions();
+    // a Claude session's registry name must still name only that session; a holder the mailbox launched may have stopped
+    if (harness === 'claude-code' && !(await this.agents.resumable(receiver)) && !this.live.runtimeReceipt('claude-code', sessionId)) {
+      const target = sessions.find((row) => row.address === receiver && row.door === 'native');
+      if (!target) return refused('not_live', `no live Claude Code process is running session \`${sessionId}\`; its transcript is persisted only`);
+      const short = target.name.split('@')[0];
+      if (sessions.filter((row) => row.door === 'native' && row.name.split('@')[0] === short).length !== 1) return refused('identity_mismatch', `the registry name \`${short}\` no longer resolves to session \`${sessionId}\` alone; refusing rather than delivering into another session`);
+    }
+    const door = harness === AGENT_HARNESS ? null : this.#door(receiver, sessions);
+    const subject = subjectLine(params.subject ?? null);
+    let id = null;
+    if (params.idempotency_key != null) {
+      const key = params.idempotency_key;
+      if (typeof key !== 'string' || !key || Buffer.byteLength(key) > 256) return refused('invalid_key', 'idempotency_key needs 1–256 bytes');
+      id = `m-${blake3Hex(JSON.stringify([sender, receiver, key]))}`.slice(0, 26);
+      const previous = this.store.findIn(receiver, id);
+      const saved = previous ? readJson(previous.path) : null;
+      if (saved && (saved.body !== text || (saved.subject ?? null) !== subject || saved.kind !== (params.channel ? 'channel' : 'peer') || saved.from_name !== (params.sender_name ?? `${fromName}@${this.machine}`) || (saved.in_reply_to ?? null) !== (params.in_reply_to ?? null) || (saved.voice_for ?? null) !== (params.voice_for ?? null))) {
+        return refused('idempotency_conflict', 'this key already names different mail');
+      }
+    }
+    const inReplyTo = typeof params.in_reply_to === 'string' ? params.in_reply_to : null;
+    const sent = makeEnvelope({
+      id: id ?? messageIdFor(sender, null), from: sender, from_name: params.sender_name ?? `${fromName}@${this.machine}`, sender_identity: senderIdentity(sender, null, this.machine),
+      kind: params.channel ? 'channel' : 'peer', reply_via: { mode: 'command' }, in_reply_to: inReplyTo,
+      thread: inReplyTo ? (this.#filedThread(inReplyTo) ?? inReplyTo) : null, voice_for: params.voice_for ?? null, subject, body: text,
+    });
+    const channel = { marker: params.marker ?? null, reply_marker: params.reply_marker ?? null, surface: params.surface ?? null };
+    let plan;
+    try { plan = await this.agents.plan(sent, receiver, channel); } catch (error) { return refused('delivery_failed', error.message); }
+    if (plan) {
+      const done = await this.#deliverPlanned({ address: sender, name: sent.from_name }, sent, plan, { queue: false, notify_when_idle: params.notify_when_idle === true });
+      return { delivered_to_bus: done.code === 0, message_id: sent.id, reply_to: sender, thread: plan.thread?.id ?? null, target: { harness, session_id: sessionId }, delivery: { door: 'agent', how: done.text } };
+    }
+    if (!door || door.kind === 'other_machine') return refused('not_live', `no running \`${harness}\` session \`${sessionId}\` is reachable; its transcript is persisted only`);
+    let how;
+    try { how = await this.route(sent, receiver, door, true, params.notify_when_idle === true); }
+    catch (error) {
+      if (error instanceof Refused && error.kind === 'too_long') return refused('too_long', `the message is ${error.bytes} bytes; the limit is ${MAX_RELAYED_BYTES}`);
+      return refused('delivery_failed', error.message);
+    }
+    return {
+      delivered_to_bus: door.kind !== 'stored', message_id: sent.id, reply_to: sender,
+      target: { harness, session_id: sessionId, name: door.kind === 'native' ? door.session.name.split('@')[0] : null },
+      delivery: { door: door.kind, how: { steered: 'steered', started: 'started', native_busy: 'next_tool_call', native_idle: 'started', hooked: 'hook', queued: 'queued', stored: 'stored', operator: 'filed', already: 'already' }[how] },
+    };
+  }
+
+  // ---- a filed message handed to its door --------------------------------------------------------------------------
+
+  /**
+   * A message filed unread in `address`'s mailbox handed to its session's door, once (mail_watch.rs `carry` and message.rs
+   * `push`, and the native watch's notices): only a door that hands it to the session (a relay, a runtime) takes it, a
+   * hook's is woken when `wake`, and an agent's mail is planned; `markRead` moves it to `cur/` once handed over. The
+   * hand-over is recorded on its wake before it starts, so one interrupted mid-way is never handed over again. Answers
+   * `{ outcome: 'delivered' | 'filed' | 'later', detail }`.
+   */
+  async handOver(address, id, { markRead = false, wake = false } = {}) {
+    const found = this.store.findIn(address, id);
+    if (!found) return { outcome: 'filed', detail: 'not in its mailbox' };
+    const sent = readJson(found.path);
+    if (!sent) return { outcome: 'later', detail: 'its envelope could not be read' };
+    if (found.state !== 'unread') return { outcome: 'filed', detail: 'already read' };
+    const parsed = parseAddress(address);
+    if (parsed?.harness === AGENT_HARNESS) {
+      const plan = await this.#plan(sent, address, {});
+      if (!plan.plan) return { outcome: 'filed', detail: plan.outcome?.text ?? 'no plan' };
+      const done = await this.#deliverPlanned({ address: sent.from, name: sent.from_name }, sent, plan.plan, { queue: false, notify_when_idle: false });
+      return done.code === 0 ? { outcome: 'delivered', detail: done.text } : { outcome: 'later', detail: done.text };
+    }
+    const door = this.#door(address, this.live.sessions());
+    if (!door) return { outcome: 'later', detail: 'its session is not running' };
+    if (door.kind === 'other_machine') return { outcome: 'later', detail: `it is on ${door.machine}` };
+    if (door.kind !== 'native' && door.kind !== 'runtime') {
+      // a hook's session is pointed at its mailbox by a wake (a native notice filed for it asks one)
+      if (door.kind === 'hook' && wake) this.store.requestWake(address, id);
+      return { outcome: 'filed', detail: `its door is ${door.kind}` };
+    }
+    const state = this.store.wakeState(address, id);
+    if (state.handover_at_ms != null) return { outcome: 'filed', detail: 'an earlier hand-over never settled' };
+    this.store.setWakeState(address, id, { ...state, handover_at_ms: Date.now() });
+    try {
+      await this.route(sent, address, door, true, false);
+      if (markRead) { const now = this.store.findIn(address, id); if (now?.state === 'unread') this.store.markRead(address, now.path); }
+      return { outcome: 'delivered', detail: null };
+    } catch (error) {
+      // a message its door can never take (too long for a relay) stays filed for the session to read
+      return error instanceof Refused ? { outcome: 'filed', detail: error.kind } : { outcome: 'later', detail: error.message };
+    } finally {
+      const after = this.store.wakeState(address, id);
+      this.store.setWakeState(address, id, { ...after, handover_at_ms: null });
+    }
+  }
+
+  // ---- a native question's answer ----------------------------------------------------------------------------------
+
+  /** Answer the native question `id` asked in `to` (mail_question.rs `reply`): only its recorded creator answers, once. */
+  async #questionReply(caller, to, id, body, link) {
+    const dir = join(this.mailRoot, 'native-questions');
+    const path = (suffix) => join(dir, `${id}.${suffix}`);
+    const question = readJson(path('json'));
+    if (!question) return outcome(EXIT_FAILED, `Not answered: question ${id} could not be read.`);
+    if (question.binding?.session !== to || question.binding?.creator !== caller.address) return outcome(EXIT_REFUSED, 'Not answered: this question belongs to a different session or recipient.');
+    if (parseAddress(to).harness === 'claude-code') {
+      const waiting = readJson(path('waiting'));
+      if (!waiting) return outcome(EXIT_REFUSED, 'Not answered: the native question hook is no longer waiting.');
+      let alive = false; try { process.kill(waiting.pid, 0); alive = true; } catch (error) { alive = error.code === 'EPERM'; }
+      if (!Number.isInteger(waiting.pid) || !alive) return outcome(EXIT_REFUSED, 'Not answered: the native question hook has ended.');
+    }
+    let answers;
+    try { answers = questionAnswers(question, body); } catch (error) { return outcome(EXIT_FAILED, `Not answered: ${error.message}`); }
+    const reply = {
+      envelope: makeEnvelope({ id: `u-${blake3Hex(`${id}\n${caller.address}`).slice(0, 24)}`, from: caller.address, from_name: caller.name, sender_identity: senderIdentity(caller.address, link, this.machine), kind: 'user', reply_via: { mode: 'none' }, in_reply_to: id, thread: id, body }),
+      answers,
+    };
+    try { createPrivate(dir, path('claim'), reply); }
+    catch (error) {
+      if (error.code === 'EEXIST') return outcome(EXIT_REFUSED, 'An answer is already recorded for this question. Nothing was submitted again; inspect its thread for delivery.');
+      throw error;
+    }
+    this.store.deliver(to, reply.envelope);
+    // published to the hook only once the whole reply is in mail
+    linkSync(path('claim'), path('reply'));
+    if (parseAddress(to).harness === 'claude-code') return outcome(0, `Answer ${shortId(reply.envelope.id)} recorded in reply to ${id}; awaiting confirmation from the native question hook. It is not composer input.`);
+    const binding = readJson(join(dir, `binding-${blake3Hex(to)}.json`));
+    if (!binding?.socket_path) return outcome(EXIT_STORED, 'Answer recorded but NOT delivered: this launch has no native question endpoint. Nothing was typed.');
+    let result;
+    try { result = await this.codexAnswer({ socketPath: binding.socket_path, threadId: parseAddress(to).session, answer: { question: question.native, answers: reply.answers } }); }
+    catch (error) { result = { delivered: false, reason: error.code ?? 'native-question-error' }; }
+    if (result?.delivered === true) {
+      const filed = this.store.findIn(to, reply.envelope.id);
+      if (filed?.state === 'unread') this.store.markRead(to, filed.path);
+      try { createPrivate(dir, path('delivered'), Date.now()); } catch (error) { if (error.code !== 'EEXIST') throw error; }
+      return outcome(0, `Answer ${shortId(reply.envelope.id)} delivered to native question ${id}.`);
+    }
+    return outcome(EXIT_STORED, `Answer recorded but NOT confirmed by the native question: ${JSON.stringify(result?.reason ?? null)}. It will not be typed or automatically resent.`);
+  }
+
+  // ---- the send log and its guards ---------------------------------------------------------------------------------
+
+  #sentDir(sender) { return join(this.mailRoot, 'sent', blake3Hex(sender).slice(0, 24)); }
+  #sentMarker(sender, id) { return join(this.#sentDir(sender), id); }
+
+  #logOf(sender) {
+    let text = '';
+    try { text = readFileSync(join(this.#sentDir(sender), 'log.jsonl'), 'utf8'); } catch { return []; }
+    return text.split('\n').map((line) => { try { return JSON.parse(line); } catch { return null; } }).filter(Boolean);
+  }
+
+  #sentIds(sender) { return this.#logOf(sender).map((entry) => entry.id).filter((id) => typeof id === 'string'); }
+  #sentThread(sender, id) { return this.#logOf(sender).find((entry) => entry.id === id && typeof entry.thread === 'string')?.thread ?? null; }
+
+  /** The thread any author on this machine sent `id` in, as its send log keeps it. */
+  #sentThreadHere(id) {
+    let names = [];
+    try { names = readdirSync(join(this.mailRoot, 'sent')); } catch { return null; }
+    for (const name of names) {
+      let text = '';
+      try { text = readFileSync(join(this.mailRoot, 'sent', name, 'log.jsonl'), 'utf8'); } catch { continue; }
+      for (const line of text.split('\n')) { let entry = null; try { entry = JSON.parse(line); } catch { continue; } if (entry?.id === id && typeof entry.thread === 'string') return entry.thread; }
+    }
+    return null;
+  }
+
+  /** The thread `parent` is filed in on this machine (mailbox.rs `filed_thread`). */
+  #filedThread(parent) {
+    const found = this.store.find(parent).find((item) => item.stored.envelope.id === parent);
+    return found ? threadOf(found.stored.envelope) : null;
+  }
+
+  /** The thread a reply to `parent` joins, sent by `sender` to `recipient` here (mail_send.rs `reply_thread`). */
+  #replyThread(sender, recipient, parent, carried) {
+    const parsed = parseAddress(recipient);
+    const main = parsed?.harness === AGENT_HARNESS ? this.agents.load(parsed.session)?.main_session ?? null : null;
+    const known = this.#filedThread(parent) ?? this.#sentThread(recipient, parent) ?? (main ? this.#sentThread(main, parent) : null) ?? this.#sentThread(sender, parent) ?? this.#sentThreadHere(parent);
+    if (known) return known;
+    if (typeof carried === 'string' && carried.trim() && !this.#filedThread(carried) && !this.agents.thread(carried)) return carried;
+    return parent;
+  }
+
+  /** How deep the reply chain ending at `answered` runs between `a` and `b`, read from both mailboxes' folders. */
+  #replyChainDepth(a, b, answered) {
+    const links = new Map([...this.store.links(a), ...this.store.links(b)]);
+    let depth = 0, current = answered;
+    while (current != null && depth <= REPLY_CHAIN_LIMIT && links.has(current)) { depth += 1; current = links.get(current); }
+    return depth;
+  }
+
+  #recordSend(sender, to, id, thread) {
+    try {
+      mkdirSync(this.#sentDir(sender), { recursive: true });
+      appendFileSync(join(this.#sentDir(sender), 'log.jsonl'), `${JSON.stringify({ to, at_ms: Date.now(), id, thread })}\n`);
+    } catch { /* the log is best kept */ }
+  }
+
+  /** A terminal's acknowledgement from the native watch's retained receipts, never from a filing (mail_send.rs
+   *  `delivery_receipt`). */
+  #deliveryReceipt(address, id, terminal) {
+    if (!terminal) return { delivered: true, message_ids: [id], receipt: 'native-mail' };
+    const parsed = parseAddress(address);
+    const recipient = `${parsed.harness}:${parsed.session}`;
+    let names = [];
+    try { names = readdirSync(join(this.mailRoot, 'terminal-delivery')); } catch { /* none yet */ }
+    for (const name of names) {
+      const state = readJson(join(this.mailRoot, 'terminal-delivery', name, 'queue.json'));
+      if (state?.recipient !== recipient) continue;
+      const receipt = (Array.isArray(state.receipts) ? state.receipts : []).find((item) => Array.isArray(item?.message_ids) && item.message_ids.includes(id));
+      if (receipt) return receipt;
+      return { delivered: false, queued: true, message_ids: [id], reason: state.active?.error ?? null };
+    }
+    return { delivered: false, queued: true, message_ids: [id], reason: 'awaiting terminal mailbox' };
+  }
+
+  // ---- the names ledger --------------------------------------------------------------------------------------------
+
+  /** The session a name last meant here, listed by it within NAME_KEPT_MS (mail_route.rs `remembered_address`). */
+  remembered(name) { return this.#rememberedAddress(name); }
+
+  #rememberedAddress(name) {
+    const record = readJson(join(this.mailRoot, 'names.json'))?.[name];
+    if (!record || Date.now() - Math.max(record.seen_ms ?? 0, record.since_ms ?? 0) > NAME_KEPT_MS) return null;
+    return parseAddress(record.address)?.address ?? null;
+  }
+
+  /** Each running session's name recorded (mail_route.rs `remember_names`): a name two sessions carry is left as it was;
+   *  written only when a name is new, names another session, or its last listing is an hour old. */
+  rememberNames(sessions) {
+    const path = join(this.mailRoot, 'names.json');
+    let names;
+    try { names = JSON.parse(readFileSync(path, 'utf8')); } catch (error) { if (error.code !== 'ENOENT') return; names = {}; }
+    if (!names || typeof names !== 'object') return;
+    const carried = new Map();
+    for (const row of sessions) {
+      const name = row.name.split('@')[0];
+      if (name && !name.startsWith(RELAY_NAME_PREFIX)) carried.set(name, [...(carried.get(name) ?? []), row.address]);
+    }
+    const now = Date.now();
+    const latest = (address) => Object.entries(names).filter(([, record]) => record.address === address).sort((x, y) => y[1].since_ms - x[1].since_ms)[0]?.[0] ?? null;
+    let changed = false;
+    for (const [name, addresses] of carried) {
+      if (addresses.length !== 1) continue;
+      const [address] = addresses;
+      const record = names[name];
+      const current = record?.address === address && now - Math.max(record.seen_ms ?? 0, record.since_ms ?? 0) < NAME_SEEN_EVERY_MS;
+      if (current && latest(address) === name) continue;
+      const renewed = record?.address === address && latest(address) === name;
+      names[name] = { address, since_ms: renewed ? record.since_ms : now, seen_ms: now };
+      changed = true;
+    }
+    if (!changed) return;
+    const staged = `${path}.${process.pid}.tmp`;
+    try { writeFileSync(staged, JSON.stringify(names)); renameSync(staged, path); } catch { /* kept for the next listing */ }
+  }
+}
+
+/** A native question's answer from a reply's body (mail_question.rs `answers`): one question takes plain text, several a
+ *  JSON object of their ids; every id shown is answered, with non-empty text, and no other. */
+function questionAnswers(question, body) {
+  const questions = question?.native?.questions;
+  if (!Array.isArray(questions)) throw new Error('question has no native inputs');
+  let values;
+  if (questions.length === 1 && !body.trimStart().startsWith('{')) values = { [questions[0]?.id ?? '']: body };
+  else values = JSON.parse(body);
+  const out = {};
+  for (const item of questions) {
+    if (typeof item?.id !== 'string') throw new Error('native question id missing');
+    const value = values?.[item.id];
+    if (typeof value !== 'string' || !value.trim()) throw new Error(`answer ${item.id} with nonempty text`);
+    out[item.id] = { answers: [value] };
+  }
+  if (!values || typeof values !== 'object' || Object.keys(values).length !== Object.keys(out).length) throw new Error('answer only the question ids shown');
+  return out;
+}
+
+/** A file made once, owner-only, written whole and synced (mail_question.rs `create`). */
+function createPrivate(dir, path, value) {
+  mkdirSync(dir, { recursive: true });
+  try { chmodSync(dir, 0o700); } catch { /* not ours to set */ }
+  const fd = openSync(path, 'wx', 0o600);
+  try { writeSync(fd, JSON.stringify(value)); fsyncSync(fd); } finally { closeSync(fd); }
+}