@volter/supercode-teams 0.3.151 → 0.3.152

package/mail/relay-endpoint.mjs

@@ -7,33 +7,29 @@
 // - a send turn gets one `SendMessage` tool call carrying the queued `to` and `message`, byte for byte;
 // - the turn after a tool result, or with nothing queued, gets RELAY_STATUS_LINE and ends.
 // No model runs and nothing is billed. The gate hook still checks every tool call against the queue, and the receipt is
-// still Claude's own `SendMessage` result. A relay's API key names its folder under `<mail root>/relays/`. The machine
-// daemon serves it on loopback, on the port recorded in `<mail root>/relay-endpoint.json` (a restarted daemon binds the
-// same port again).
+// still Claude's own `SendMessage` result. A relay's API key names its record in
+// the mail database. The loopback port is recorded there too, so a restarted
+// daemon can bind the same port again.
 import { createServer } from 'node:http';
 import { randomBytes } from 'node:crypto';
-import { mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
 
 /** The text every relay turn ends with. Claude quotes a session's last line in its idle notices, so this is where the
  *  correction reaches the agent. */
 export const RELAY_STATUS_LINE = "relay, not the session's status";
 
-const readJson = (path) => { try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return null; } };
 const newId = () => `m-${randomBytes(12).toString('hex')}`;
 
 /**
- * Serve the endpoint for `mailRoot`'s relays: answers `{ url, close() }` once it listens. The port the record names is
+ * Serve the endpoint for `store`'s relays: answers `{ url, close() }` once it listens. The port the record names is
  * taken again when it is free, so relays started before a restart keep reaching it.
  */
-export async function serveRelayEndpoint(mailRoot, { log = () => {} } = {}) {
-  const record = join(mailRoot, 'relay-endpoint.json');
+export async function serveRelayEndpoint(store, { log = () => {} } = {}) {
   const server = createServer((request, response) => {
     const chunks = [];
     request.on('data', (chunk) => chunks.push(chunk));
     request.on('error', () => {});
     request.on('end', () => {
-      const [status, type, body] = answer(mailRoot, request, Buffer.concat(chunks));
+      const [status, type, body] = answer(store, request, Buffer.concat(chunks));
       response.writeHead(status, { 'content-type': type, 'content-length': Buffer.byteLength(body) });
       response.end(body);
     });
@@ -45,7 +41,7 @@ export async function serveRelayEndpoint(mailRoot, { log = () => {} } = {}) {
     server.once('error', failed); server.once('listening', done);
     server.listen(port, '127.0.0.1');
   });
-  const recorded = readJson(record)?.port;
+  const recorded = store.record('relay_endpoint', 'port')?.port;
   try { await listen(Number.isInteger(recorded) ? recorded : 0); }
   catch (error) {
     if (!Number.isInteger(recorded)) throw error;
@@ -53,33 +49,29 @@ export async function serveRelayEndpoint(mailRoot, { log = () => {} } = {}) {
     await listen(0);
   }
   const port = server.address().port;
-  mkdirSync(mailRoot, { recursive: true });
-  const staging = `${record}.tmp`;
-  writeFileSync(staging, JSON.stringify({ port }));
-  renameSync(staging, record);
+  store.putRecord('relay_endpoint', 'port', { port });
   return { url: `http://127.0.0.1:${port}`, port, close: () => new Promise((resolve) => server.close(() => resolve())) };
 }
 
 /** The relay folder an API key names, when it is one. */
-function relayFolder(mailRoot, request) {
+function relayKey(store, request) {
   const key = request.headers['x-api-key'];
   if (typeof key !== 'string' || !key || !/^[0-9a-fA-F]+$/.test(key)) return null;
-  const folder = join(mailRoot, 'relays', key);
-  try { return statSync(folder).isDirectory() ? folder : null; } catch { return null; }
+  return store.relayKnown(key) ? key : null;
 }
 
 /** One request's answer: `[status, content type, body]`. */
-function answer(mailRoot, request, raw) {
+function answer(store, request, raw) {
   const error = (status, message) => [status, 'application/json', JSON.stringify({ type: 'error', error: { type: 'invalid_request_error', message } })];
   if (request.method !== 'POST') return error(404, 'not found');
-  const folder = relayFolder(mailRoot, request);
-  if (!folder) return error(401, 'not a supercode relay');
+  const key = relayKey(store, request);
+  if (!key) return error(401, 'not a supercode relay');
   const path = String(request.url ?? '').split('?')[0];
   if (path.endsWith('/v1/messages/count_tokens')) return [200, 'application/json', JSON.stringify({ input_tokens: 1 })];
   if (!path.endsWith('/v1/messages')) return error(404, 'not found');
   let body;
   try { body = JSON.parse(raw.toString('utf8')); } catch { return error(400, 'unreadable request'); }
-  const queued = readJson(join(folder, 'queue.json'));
+  const queued = store.record('relays', `${key}/queue.json`);
   const content = queued && typeof queued.to === 'string' && typeof queued.message === 'string' && !afterToolResult(body)
     ? { type: 'tool_use', id: `toolu_${newId()}`, name: 'SendMessage', input: { to: queued.to, message: queued.message } }
     : { type: 'text', text: RELAY_STATUS_LINE };

package/mail/relay.mjs

@@ -1,15 +1,10 @@
-// A Claude session supercode does not control is reached through Claude's own SendMessage, made by a relay: a `claude
-// --print` runtime that speaks for the sender, hosted by this daemon's `harness serve` (crates/harness/src/claude_relay.rs).
-// The daemon drives a relay send through the relay's folder, as the native sender did: `queue.json` names the one send its
-// gate allows, the relay's hooks write Claude's answer to `receipt.json`, and the turn that makes the send goes in by
-// harness serve's own `runtimes.send_input`; its runtime is started and closed by `runtimes.start` and `runtimes.close`.
-// No native process runs per delivery. The relay's hooks (`message gate`, `relay-inbound`, `relay-receipt`) stay native
-// doors, run by the relay's Claude (docs/architecture/overview.md, "Pinned native doors"). Its folder is the native
-// sender's own (`<mail>/relays/<blake3(name)[..24]>/`, its record, settings and send log), so the native `message
-// watch`, which retires relays until step 4, reads what the daemon writes.
-import { mkdirSync, readFileSync, readdirSync, rmSync, statSync, watch, writeFileSync } from 'node:fs';
+// A Claude relay uses the stock harness's SendMessage door. This daemon owns
+// its queue, receipts and runtime records in SQLite; Claude reads only its hook
+// configuration in a separate runtime directory. Native runtime start/input/
+// close doors retain their observed-result and unanswered-operation semantics.
+import { mkdirSync, rmdirSync, unlinkSync, writeFileSync } from 'node:fs';
 import { connect } from 'node:net';
-import { join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import { blake3Hex, shortId } from './envelope.mjs';
 
 /** Model name a relay's requests carry; the relay endpoint answers them without any model. */
@@ -57,7 +52,6 @@ const CODEX_RELAY_KEPT_MS = 7 * 24 * 60 * 60_000;
 const LOST_START_KEPT_MS = 5 * 60_000;
 
 const alive = (pid) => { if (!Number.isInteger(pid) || pid <= 0) return false; try { process.kill(pid, 0); return true; } catch (error) { return error.code === 'EPERM'; } };
-const readJson = (path) => { try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return null; } };
 const shellQuote = (value) => `'${String(value).replaceAll("'", "'\\''")}'`;
 
 /** Registry name of the relay that represents `name` on `machine` (not `name@machine`: SendMessage refuses an `@`). */
@@ -91,8 +85,11 @@ export class Relays {
    * id)` the live-runtime receipt the live-session map holds for a runtime id (its file read whole), or null;
    * `runtimeNamed(receiptId)` one receipt read by its own name.
    */
-  constructor({ mailRoot, machine, supercodeBin, serve, runtimeOf, runtimeNamed = () => null, runtimesIn = () => [], endpointOf = async () => null, arrived = async () => false, hooksServed = () => true, log = () => {} }) {
-    Object.assign(this, { mailRoot, machine, supercodeBin, serve, runtimeOf, runtimeNamed, runtimesIn, endpointOf, arrived, hooksServed, log });
+  constructor({ mailRoot, store, machine, supercodeBin, serve, runtimeOf, runtimeNamed = () => null, runtimesIn = () => [], endpointOf = async () => null, arrived = async () => false, hooksServed = () => true, log = () => {} }) {
+    Object.assign(this, { mailRoot, store, machine, supercodeBin, serve, runtimeOf, runtimeNamed, runtimesIn, endpointOf, arrived, hooksServed, log });
+    this.runtimeRoot = join(dirname(mailRoot), 'relays');
+    this.stopped = false;
+    this.receipts = new Set();
     this.lost = new Map(); // relay folder → when a start of its runtime lost its answer (the runtime may run, unnamed)
     this.remoteKept = new Map(); // relay folder of a sender on another machine → the timer that retires it
     this.sending = new Map(); // relay folder → the send in progress through it (one at a time per relay)
@@ -103,6 +100,7 @@ export class Relays {
    *  daemon starts every relay and holds every relay's send lock, so it alone closes one (a closer that did not hold the
    *  lock closed relays mid-send, and every send after paid a relay's start). */
   #cap() {
+    if (this.stopped) return;
     const kept = [...this.running].sort(([, a], [, b]) => b.usedAt - a.usedAt);
     for (const [directory, relay] of kept.slice(RELAYS_RUNNING)) {
       if (this.sending.has(directory)) continue;
@@ -121,7 +119,7 @@ export class Relays {
     for (const [directory, lostAt] of this.lost) {
       if (Date.now() - lostAt > LOST_START_KEPT_MS) { this.lost.delete(directory); continue; }
       if (this.sending.has(directory)) continue;
-      const named = readJson(join(directory, 'relay.json'))?.runtime_id;
+      const named = this.store.record('relays', `${basename(directory)}/relay.json`)?.runtime_id;
       for (const ids of this.runtimesIn('claude-code', directory)) {
         if (ids.includes(named)) continue;
         void this.#locked(directory, async () => {
@@ -147,32 +145,43 @@ export class Relays {
 
   /** The address a relay folder speaks for, as its inbound hook names it (its settings), or null. */
   #representedOf(directory) {
-    try { return /relay-inbound '([^']+)'/.exec(readFileSync(join(directory, 'settings.json'), 'utf8'))?.[1] ?? null; } catch { return null; }
+    const settings = this.store.record('relays', `${basename(directory)}/settings.json`);
+    return /relay-inbound '([^']+)'/.exec(JSON.stringify(settings))?.[1] ?? null;
   }
 
   async #retireFolder(directory, expected = null) {
-    try { statSync(directory); } catch { return false; }
+    if (this.stopped) return false;
+    if (!this.store.relayKnown(basename(directory))) return false;
     if (expected && this.#representedOf(directory) !== expected) return false;
     return this.#locked(directory, async () => {
-      // read again under its lock: a send that ran meanwhile writes its own sender's settings
+      if (this.stopped) return false;
       if (expected && this.#representedOf(directory) !== expected) return false;
-      const record = readJson(join(directory, 'relay.json'));
+      const record = this.store.record('relays', `${basename(directory)}/relay.json`);
       if (record?.runtime_id) {
         try { await this.serve('harness.v1.runtimes.close', { connection: record.connection ?? '', runtime_id: record.runtime_id }, CLOSE_MS); }
         catch (error) {
-          // a runtime still live that could not be closed keeps its folder: it is retired again at the next end or start
-          if (this.runtimeOf('claude-code', record.runtime_id)) { this.log(`relay ${directory.split(/[\\/]/).pop()} was not retired: ${error.message}`); return false; }
+          if (this.runtimeOf('claude-code', record.runtime_id)) { this.log(`relay ${basename(directory)} was not retired: ${error.message}`); return false; }
         }
       }
+      if (this.stopped) return false;
       this.running.delete(directory); this.lost.delete(directory);
       clearTimeout(this.remoteKept.get(directory)); this.remoteKept.delete(directory);
-      try { rmSync(directory, { recursive: true, force: true }); } catch (error) { this.log(`relay ${directory.split(/[\\/]/).pop()}: its folder was not removed: ${error.message}`); return false; }
+      this.store.transaction(() => {
+        for (const file of ['relay.json', 'queue.json', 'receipt.json', 'sent.json', 'settings.json', 'turn.txt']) this.store.removeRecord('relays', `${basename(directory)}/${file}`);
+      });
+      // Only the configuration this daemon materializes is removed. Other
+      // runtime files are retained; an old Maildir is handled by the importer.
+      if (dirname(directory) === this.runtimeRoot) {
+        try { unlinkSync(join(directory, 'settings.json')); } catch (error) { if (error.code !== 'ENOENT') this.log(`relay configuration retained: ${error.message}`); }
+        try { rmdirSync(directory); } catch (error) { if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes(error.code)) this.log(`relay directory retained: ${error.message}`); }
+      }
       return true;
     });
   }
 
   /** A relay speaking for a sender on another machine is retired REMOTE_RELAY_KEPT_MS after its last send. */
   #keepRemote(directory, quietSinceMs = Date.now()) {
+    if (this.stopped) return;
     clearTimeout(this.remoteKept.get(directory));
     const timer = setTimeout(() => { this.remoteKept.delete(directory); void this.#retireFolder(directory); }, Math.max(0, quietSinceMs + REMOTE_RELAY_KEPT_MS - Date.now()));
     timer.unref?.();
@@ -185,22 +194,25 @@ export class Relays {
    * `running(address)` says whether a session here runs.
    */
   async sweepAtStart(running) {
-    let folders = [];
-    try { folders = readdirSync(join(this.mailRoot, 'relays')); } catch { return; }
+    if (this.stopped) return;
+    const records = this.store.records('relays');
+    const folders = [...new Set(records.map(({ key }) => key.split('/')[0]))];
+    const times = new Map(records.map(({ key, updated_at_ms }) => [key, updated_at_ms]));
     let retired = 0;
     for (const folder of folders) {
-      const directory = join(this.mailRoot, 'relays', folder);
+      if (this.stopped) return;
+      const directory = join(this.runtimeRoot, folder);
       const represented = this.#representedOf(directory);
       if (!represented) continue;
       const [, machine, harness] = represented.split(':');
       if (harness === 'board' || harness === 'operator') continue;
       if (machine !== this.machine) {
-        let last = 0; try { last = statSync(join(directory, 'receipt.json')).mtimeMs; } catch { /* never sent */ }
+        const last = times.get(`${folder}/receipt.json`) ?? 0;
         if (Date.now() - last < REMOTE_RELAY_KEPT_MS) { this.#keepRemote(directory, last); continue; }
       } else if (running(represented)) continue;
       else if (harness === 'codex') {
         // a Codex session the map does not hold may be idle, not ended: its relay is kept until unused for a week
-        let last = 0; for (const file of ['receipt.json', 'relay.json']) { try { last = Math.max(last, statSync(join(directory, file)).mtimeMs); } catch { /* none */ } }
+        const last = Math.max(times.get(`${folder}/receipt.json`) ?? 0, times.get(`${folder}/relay.json`) ?? 0);
         if (Date.now() - last < CODEX_RELAY_KEPT_MS) continue;
       } else if (harness !== 'claude-code') continue;
       // only a Claude session is provably ended when the map does not hold it (its registry lists every live Claude
@@ -218,7 +230,10 @@ export class Relays {
     const turn = previous.then(() => mine);
     this.sending.set(directory, turn);
     await previous;
-    try { return await work(); }
+    try {
+      if (this.stopped) throw new Error('the daemon is stopping; no relay operation was submitted');
+      return await work();
+    }
     finally {
       release();
       if (this.sending.get(directory) === turn) this.sending.delete(directory);
@@ -228,11 +243,12 @@ export class Relays {
   /** The relay that speaks for `represented`, known as `representedName`: its name and its files. */
   spec(represented, representedName) {
     const name = relayName(String(representedName).split('@')[0], String(represented).split(':')[1]);
-    const directory = join(this.mailRoot, 'relays', blake3Hex(name).slice(0, 24));
+    const key = blake3Hex(name).slice(0, 24);
+    const directory = join(this.runtimeRoot, key);
     return {
       represented, name, directory,
-      queue: join(directory, 'queue.json'), receipt: join(directory, 'receipt.json'), settings: join(directory, 'settings.json'),
-      record: join(directory, 'relay.json'), sent: join(directory, 'sent.json'),
+      queue: `${key}/queue.json`, receipt: `${key}/receipt.json`, settings: join(directory, 'settings.json'),
+      settingsKey: `${key}/settings.json`, record: `${key}/relay.json`, sent: `${key}/sent.json`,
     };
   }
 
@@ -261,7 +277,7 @@ export class Relays {
   #pid(spec, runtime) {
     const child = runtime?.metadata?.child_pid;
     if (Number.isInteger(child)) return child;
-    const record = readJson(spec.record);
+    const record = this.store.record('relays', spec.record);
     return record?.runtime_id === runtime?.runtime_session_id && Number.isInteger(record?.pid) ? record.pid : null;
   }
 
@@ -272,24 +288,25 @@ export class Relays {
     // build's native) would answer none of them, and every mail the relay is handed would be blocked unfiled
     if (!this.hooksServed()) throw new Error('relays run their hooks through the machine\'s stable supercode, and none here serves them (no stable supercode was found, or it is a dev or cargo build); install supercode from npm to send to Claude sessions by relay');
     const endpoint = await this.endpoint();
+    if (this.stopped) throw new Error('the daemon is stopping; no relay turn was submitted');
     step('relay endpoint');
     if (!endpoint) throw new Error('the relay endpoint is not served by this machine\'s daemon (its log says why); a Claude session can be sent mail once the daemon starts again');
     // written on every send: Claude Code reloads a changed settings file, so a running relay takes the hooks this
     // supercode installs
-    writeFileSync(spec.settings, JSON.stringify(this.#settings(spec), null, 2));
-    const record = readJson(spec.record);
+    const settings = this.#settings(spec);
+    this.store.putRecord('relays', spec.settingsKey, settings);
+    writeFileSync(spec.settings, JSON.stringify(settings, null, 2), { mode: 0o600 });
+    const record = this.store.record('relays', spec.record);
     if (record?.runtime_id) {
       const runtime = this.runtimeOf('claude-code', record.runtime_id);
-      if (!stale && runtime && alive(this.#pid(spec, runtime)) && record.connection && (record.endpoint === endpoint || await answers(Number(String(record.endpoint ?? '').split(':').pop())))) {
+      if (!stale && record.runtime_directory === spec.directory && runtime && alive(this.#pid(spec, runtime)) && record.connection && (record.endpoint === endpoint || await answers(Number(String(record.endpoint ?? '').split(':').pop())))) {
         step('runtime reused');
         return { runtime, connection: record.connection };
       }
       // why it is not reused, said in the timing line: a relay that should have been warm and was not shows here
       step(`runtime not reused (${stale ? 'it held a stale turn' : !runtime ? 'no live receipt' : !alive(this.#pid(spec, runtime)) ? 'its process ended' : !record.connection ? 'no connection' : 'endpoint moved'})`);
-      // closed through the owner's door even after its receipt went. One whose receipt is gone, or whose process is
-      // known and ended, is only serve's record of it: let go without holding this send (yuerans, 2026-10-06: 2.3-18 s
-      // of every send under load). One that may still run, its process unknown (no child pid, a record of another
-      // runtime) or alive, is closed before its successor starts in the same folder, as before.
+      // A possibly live predecessor is closed through its owner before this
+      // daemon starts a successor in the new runtime directory.
       const close = this.serve('harness.v1.runtimes.close', { connection: record.connection, runtime_id: record.runtime_id }, CLOSE_MS);
       const pid = runtime ? this.#pid(spec, runtime) : null;
       if (runtime && !(Number.isInteger(pid) && !alive(pid))) {
@@ -301,6 +318,7 @@ export class Relays {
         step('old runtime let go (runtimes.close, not waited on)');
       }
     }
+    if (this.stopped) throw new Error('the daemon is stopping; no successor relay was started');
     const key = spec.directory.split(/[\\/]/).pop();
     const started = await this.#start(spec, {
       harness: 'claude-code',
@@ -317,17 +335,15 @@ export class Relays {
     const connection = typeof started.connection === 'string' ? started.connection : '';
     const pid = Number.isInteger(started?.handle?.endpoint?.pid) ? started.handle.endpoint.pid : null;
     step('runtime started (runtimes.start)');
-    writeFileSync(spec.record, JSON.stringify({ runtime_id: runtimeId, pid, endpoint, connection }));
+    this.store.putRecord('relays', spec.record, { runtime_id: runtimeId, pid, endpoint, connection, runtime_directory: spec.directory });
     // the daemon's from its start: counted by the cap even when the rest of this start fails
     this.running.set(spec.directory, { connection, runtime_id: runtimeId, usedAt: Date.now() });
     // harness serve writes its receipt before it answers the start; the map learns it from its watch a moment later, so
     // one it does not hold yet is read by its own name (the receipt the runtime's terminal launch opens), never waited on
     const known = this.runtimeOf('claude-code', runtimeId);
     if (known) { step('its receipt held'); return { runtime: known, connection }; }
-    // its receipt, from whichever answers first: the map's watch (it learns the receipt file serve wrote before it
-    // answered the start, about a second later), or serve naming it (terminal instructions), each for at most
-    // RECEIPT_WAIT_MS. Serve alone, bounded at 5 s, refused every start on a loaded machine (yuerans, 2026-10-06:
-    // "the relay started but registered no live runtime").
+    // Either the live map or terminal instructions can identify the receipt
+    // written by serve. Neither timeout establishes that no runtime exists.
     let receiptId = null;
     this.serve('harness.v1.runtimes.terminal_instructions', { connection }, RECEIPT_WAIT_MS).then((answer) => {
       const launch = answer?.launch;
@@ -347,25 +363,39 @@ export class Relays {
     return { runtime, connection };
   }
 
-  /** Claude's receipt for the queued send, waited on by a watch of the relay's folder (and its process checked at least
-   *  every half second): a relay that ended or a send not confirmed within SEND_TIMEOUT_MS is said. */
+  /** The committed receipt wakes its waiter. The timer checks only whether
+   * the runtime ended; a deadline remains an unknown delivery outcome. */
   #receipt(spec, pid) {
     return new Promise((resolve) => {
-      let done = false, watcher = null, timer = null, deadline = null;
-      const finish = (answer) => { if (done) return; done = true; clearInterval(timer); clearTimeout(deadline); try { watcher?.close(); } catch { /* closed */ } resolve(answer); };
+      let done = false, timer = null, deadline = null;
+      const finish = (answer) => {
+        if (done) return;
+        done = true; clearInterval(timer); clearTimeout(deadline);
+        this.store.database.off('record', changed); this.receipts.delete(cancel);
+        resolve(answer);
+      };
       const check = () => {
-        const value = readJson(spec.receipt);
+        const value = this.store.record('relays', spec.receipt);
         if (value) return finish(readReceipt(value));
-        // not known either way: it may have sent before it ended
         if (pid && !alive(pid)) finish({ delivered: false, unknown: true, detail: 'the Claude relay process exited before confirming the send' });
       };
-      try { watcher = watch(spec.directory, () => check()); watcher.on('error', () => {}); } catch { /* checked on the timer */ }
+      const changed = ({ collection, key }) => { if (collection === 'relays' && key === spec.receipt) check(); };
+      const cancel = () => finish({ delivered: false, unknown: true, detail: 'the machine daemon stopped before confirming the send' });
+      this.receipts.add(cancel);
+      this.store.database.on('record', changed);
       timer = setInterval(check, 500);
       deadline = setTimeout(() => finish({ delivered: false, unknown: true, detail: `the Claude relay did not confirm the send within ${SEND_TIMEOUT_MS / 1000} seconds; it may still arrive` }), SEND_TIMEOUT_MS);
-      check();
+      if (this.stopped) cancel(); else check();
     });
   }
 
+  stop() {
+    this.stopped = true;
+    for (const timer of this.remoteKept.values()) clearTimeout(timer);
+    this.remoteKept.clear();
+    for (const cancel of this.receipts) cancel();
+  }
+
   /**
    * Send `message` to the Claude session `receiver` (`{ sessionId, name, socket }`) from `sender` through its relay
    * (claude_relay.rs `send_through_relay`): the receiver is named by its own socket (`uds:<path>`), unique to it, never
@@ -375,7 +405,8 @@ export class Relays {
    *  relay runtime outlives a daemon that ended mid-send and may still make it. (Not `sending`: that is the field of
    *  sends in progress, which would shadow it.) */
   queued(sender, senderName) {
-    try { return Date.now() - statSync(this.spec(sender, senderName).queue).mtimeMs < 2 * SEND_TIMEOUT_MS; } catch { return false; }
+    const row = this.store.statement("SELECT updated_at_ms FROM mail_records WHERE collection = 'relays' AND key = ?").get(this.spec(sender, senderName).queue);
+    return Boolean(row && Date.now() - row.updated_at_ms < 2 * SEND_TIMEOUT_MS);
   }
 
   /** Whether message `messageId` from `sender` landed in Claude session `sessionId`'s transcript, as a relay send reads
@@ -399,7 +430,8 @@ export class Relays {
   async #send(spec, receiver, message, messageId, asked, landed) {
     try {
       // made under its lock: a retire that held the lock meanwhile may have removed it
-      mkdirSync(spec.directory, { recursive: true });
+      if (this.stopped) return { delivered: false, detail: 'the machine daemon is stopping; no relay turn was submitted' };
+      mkdirSync(spec.directory, { recursive: true, mode: 0o700 });
       const queued = { to: receiver.socket ? `uds:${receiver.socket}` : receiver.name, message };
       const steps = [], began = asked;
       let mark = began;
@@ -407,8 +439,8 @@ export class Relays {
       step('lock');
       let { runtime, connection } = await this.#ensure(spec, step);
       this.#used(spec, connection);
-      rmSync(spec.receipt, { force: true });
-      writeFileSync(spec.queue, JSON.stringify(queued));
+      this.store.removeRecord('relays', spec.receipt);
+      this.store.putRecord('relays', spec.queue, queued);
       let receipt;
       for (let attempt = 0; ; attempt++) {
         // A hand-in whose answer did not come (its bound passed, serve ended mid-call, serve's own deadline on the
@@ -428,20 +460,22 @@ export class Relays {
             step(`relay still in a turn after ${TURN_END_MS / 1000} s, closed (${error.message})`);
             ({ runtime, connection } = await this.#ensure(spec, step, { stale: true }));
             this.#used(spec, connection);
-            rmSync(spec.receipt, { force: true });
+            this.store.removeRecord('relays', spec.receipt);
             continue;
           }
           receipt = { delivered: false, detail: `the Claude relay did not take the send: ${error.message}` };
         }
         if (!handed) break;
-        receipt = await this.#receipt(spec, this.#pid(spec, runtime)); step('Claude\'s receipt');
+        receipt = await this.#receipt(spec, this.#pid(spec, runtime));
+        if (this.stopped) return receipt;
+        step('Claude\'s receipt');
         const pid = this.#pid(spec, runtime);
         // only a relay proven dead is started again; one alive but slow may still deliver
         if (receipt.delivered || attempt === 1 || pid == null || alive(pid)) break;
         try { ({ runtime, connection } = await this.#ensure(spec, step)); this.#used(spec, connection); } catch (error) { receipt = { delivered: false, detail: error.message }; break; }
-        rmSync(spec.receipt, { force: true });
+        this.store.removeRecord('relays', spec.receipt);
       }
-      rmSync(spec.queue, { force: true });
+      this.store.removeRecord('relays', spec.queue);
       // an outcome not confirmed is read where it would have landed: the relay can no longer send it (its queue is
       // gone), so the receiver's transcript says whether it did
       if (!receipt.delivered && receipt.unknown) {
@@ -453,16 +487,16 @@ export class Relays {
         else receipt = { ...receipt, landed: false };
       }
       if (receipt.delivered) {
-        const sent = readJson(spec.sent) ?? {};
+        const sent = this.store.record('relays', spec.sent) ?? {};
         sent[receiver.sessionId] = messageId;
-        writeFileSync(spec.sent, JSON.stringify(sent));
+        this.store.putRecord('relays', spec.sent, sent);
       }
       // a slow relay send says where its time went, in the daemon's log (what a person reads of the connector)
       if (performance.now() - began > SLOW_SEND_MS) this.log(`relay send to ${receiver.name || receiver.sessionId} took ${Math.round(performance.now() - began)} ms: ${steps.join(', ')}`);
       return receipt;
     } catch (error) {
-      rmSync(spec.queue, { force: true });
-      return { delivered: false, detail: error.message };
+      if (!this.stopped) this.store.removeRecord('relays', spec.queue);
+      return { delivered: false, ...(this.stopped ? { unknown: true } : {}), detail: error.message };
     }
   }
 
@@ -474,6 +508,7 @@ export class Relays {
   async #handIn(connection, queued, step) {
     const asked = performance.now();
     for (;;) {
+      if (this.stopped) return Object.assign(new Error('the daemon is stopping; no relay turn was submitted'), { notAsked: true });
       try { await this.serve('harness.v1.runtimes.send_input', { connection, text: sendTurn(queued) }, 30_000); }
       catch (error) {
         if (answerLost(error) || !/already in progress/.test(error.message) || performance.now() - asked > TURN_END_MS) return error;
@@ -494,7 +529,7 @@ export class Relays {
 
   /** A relay this daemon runs, used now. */
   #used(spec, connection) {
-    const runtimeId = readJson(spec.record)?.runtime_id;
+    const runtimeId = this.store.record('relays', spec.record)?.runtime_id;
     if (typeof runtimeId === 'string') this.running.set(spec.directory, { connection, runtime_id: runtimeId, usedAt: Date.now() });
   }
 }

package/mail/retire-maildir.mjs

@@ -0,0 +1,122 @@
+// Migration owns a private snapshot before reading it. A successful import
+// retires only the exact bytes whose database writes completed. Unknown and
+// unreadable sources remain as named diagnostics, never as a read fallback.
+import { createReadStream } from 'node:fs';
+import { lstat, mkdir, readFile, readdir, rename, rmdir, unlink } from 'node:fs/promises';
+import { createHash, randomUUID } from 'node:crypto';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { importMaildir } from './import-maildir.mjs';
+
+const stat = async (path) => {
+  try { return await lstat(path); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+};
+const alive = (pid) => {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch (error) { return error.code === 'EPERM'; }
+};
+
+async function oldWrappers(root) {
+  const dir = join(root, 'native-launches');
+  let entries;
+  try { entries = await readdir(dir, { withFileTypes: true }); }
+  catch (error) { if (error.code === 'ENOENT') return; throw error; }
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith('.json') || entry.name.endsWith('.session.json')) continue;
+    const seed = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(await readFile(join(dir, entry.name))));
+    if (alive(seed.ownerPid)) throw new Error(`mail migration is waiting for the older native pane wrapper in ${entry.name} (PID ${seed.ownerPid}); it still writes in the Maildir. Close and relaunch that owned pane through supercode before upgrading this daemon. No pane was closed by migration.`);
+  }
+}
+
+/** Called only while this daemon holds the mail owner lease. */
+export async function migrateMaildir(database, root, { log = () => {} } = {}) {
+  root = resolve(root);
+  let retirement = database.metadata('maildir_retirement');
+  let source = await stat(root);
+  if (!retirement) {
+    if (source && !source.isDirectory()) throw new Error(`mail migration requires a regular directory at ${root}`);
+    if (source) await oldWrappers(root);
+    retirement = { source: root, archive: source ? join(dirname(root), 'mail-retired', randomUUID()) : null, started_at_ms: Date.now(), complete: false };
+    database.setMetadata('maildir_retirement', retirement);
+  }
+  if (retirement.source !== root) throw new Error('the mail migration source differs from its stored receipt');
+  if (retirement.complete) {
+    if (source) throw new Error(`the retired Maildir was recreated at ${root}; it is retained, and this daemon will not choose between two mail stores`);
+    return database.metadata('maildir_import');
+  }
+  if (!retirement.archive) {
+    if (source) throw new Error(`a legacy Maildir appeared after this home's SQLite owner started: ${root}; it is retained, and migration is refused`);
+    const imported = await importMaildir(database, root, { log });
+    database.setMetadata('maildir_retirement', { ...retirement, complete: true, completed_at_ms: Date.now(), retained_sources: 0 });
+    return imported;
+  }
+  const archiveRoot = resolve(dirname(root), 'mail-retired');
+  const archive = resolve(retirement.archive);
+  if (dirname(archive) !== archiveRoot) throw new Error('the stored migration snapshot is outside this home');
+  let snapshot = await stat(archive);
+  if (source) {
+    if (snapshot || retirement.complete) throw new Error(`the retired Maildir was recreated at ${root}; it is retained, and this daemon will not choose between two mail stores`);
+    if (!source.isDirectory()) throw new Error('mail migration source is no longer a regular directory');
+    await oldWrappers(root);
+    await mkdir(archiveRoot, { recursive: true, mode: 0o700 });
+    await rename(root, archive);
+    snapshot = await stat(archive);
+  }
+  if (!snapshot) {
+    if (!retirement.complete) throw new Error('the incomplete mail migration snapshot is missing; originals cannot be reconstructed');
+    return database.metadata('maildir_import');
+  }
+  if (!snapshot.isDirectory()) throw new Error('the migration snapshot is not a regular directory');
+  if (retirement.inode != null && (retirement.inode !== snapshot.ino || retirement.device !== snapshot.dev)) throw new Error('the migration snapshot differs from its ownership receipt');
+  retirement = { ...retirement, inode: snapshot.ino, device: snapshot.dev };
+  database.setMetadata('maildir_retirement', retirement);
+  const imported = await importMaildir(database, archive, { log, legacyRoot: root });
+  // No ordinary operation becomes ready if an old entrypoint created a second
+  // store during import. It is never silently reimported over the first one.
+  if (await stat(root)) throw new Error(`a legacy writer recreated ${root} during migration; originals are retained and mail is not activated`);
+  const sources = database.statement(`SELECT source, sha256 FROM mail_import_sources s WHERE purged = 0 AND source > ?
+    AND NOT EXISTS (SELECT 1 FROM mail_import_errors e WHERE e.source = s.source) ORDER BY source LIMIT 256`);
+  const purged = database.statement('UPDATE mail_import_sources SET purged = 1 WHERE source = ?');
+  let removed = 0;
+  let cursor = '';
+  for (;;) {
+    const batch = sources.all(cursor);
+    if (!batch.length) break;
+    const done = [];
+    for (const row of batch) {
+      const path = resolve(archive, row.source);
+      if (isAbsolute(row.source) || !path.startsWith(archive + sep)) throw new Error('an imported source is outside its migration snapshot');
+      let parent = dirname(path), regular = true;
+      while (parent !== archive) {
+        if (!(await stat(parent))?.isDirectory()) { regular = false; break; }
+        parent = dirname(parent);
+      }
+      if (!regular) { log(`mail migration retained linked source ${row.source}`); continue; }
+      const file = await stat(path);
+      if (!file) { done.push(row.source); continue; }
+      if (!file.isFile()) { log(`mail migration retained changed source ${row.source}`); continue; }
+      const hash = createHash('sha256');
+      for await (const bytes of createReadStream(path)) hash.update(bytes);
+      if (hash.digest('hex') !== row.sha256) { log(`mail migration retained changed bytes ${row.source}`); continue; }
+      await unlink(path);
+      done.push(row.source); removed++;
+    }
+    // An interruption between unlink and this commit is safe: the next start
+    // observes the absent original and records its retirement again.
+    database.transaction(() => { for (const source of done) purged.run(source); });
+    cursor = batch.at(-1).source;
+  }
+  let retained = 0;
+  async function tidy(dir) {
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+      const path = join(dir, entry.name);
+      if (entry.isDirectory()) await tidy(path);
+      else { retained++; log(`mail migration retained diagnostic source ${relative(archive, path)}`); }
+    }
+    try { await rmdir(dir); } catch (error) { if (!['ENOTEMPTY', 'EEXIST'].includes(error.code)) throw error; }
+  }
+  await tidy(archive);
+  database.setMetadata('maildir_retirement', { ...retirement, complete: true, completed_at_ms: Date.now(), retained_sources: retained });
+  log(`mail retired: ${removed} imported source files removed; ${retained} diagnostic sources retained at ${archive}`);
+  return imported;
+}