@volter/supercode-teams 0.3.151 → 0.3.152

package/README.md

@@ -14,7 +14,7 @@ evidence without installing Volter Harness on each developer's machine. Start wi
 [Teams guide](../../docs/guides/teams.md); the design is
 [Teams server, CLI and API](../../docs/plans/teams-server.md).
 
-The server uses SQLite and requires Node 22.13 or newer. Package exports: `.` (the daemon,
+The server and machine daemon use SQLite and require Node 22.13.0 or newer. Package exports: `.` (the daemon,
 channel and client), `/machine`, `/client`, `/admission`, `/fleet`, `/server`,
 `/workspace-client`, `/connector`, `/connector/native-continuation` and `/contracts`. The
 workspace client is browser-safe and takes explicit credentials. Native capture and execution use
@@ -40,6 +40,19 @@ and [implementation specification](../../docs/plans/teams-server-build/README.md
 the same daemon enrolled to the selected Teams context, adding catalog sync and the server link.
 The daemon owns one `supercode harness serve` and the tmux terminal host.
 
+It alone opens `<supercode home>/mail.sqlite` in WAL mode. A separate SQLite writer lease lasts until shutdown.
+Clients and native pane wrappers ask its socket for mail and launch bindings. At the first start, it imports the
+legacy Maildir from a private snapshot and removes only successfully imported, byte-verified sources; unknown or
+unreadable files remain diagnostics. Mail and launch requests are refused until import completes. A live older Codex
+wrapper that still writes legacy bindings prevents migration. Ordinary reads never reopen the retired folder.
+Settled read bodies expire after 30 days, with explicit placeholders and retained thread headers; pending mail keeps
+its originals. Expired read headers are capped at 1,000,000 and carrier/terminal event log tables at 10,000 rows each. Read the
+[dated qualification scope](../../docs/evidence/sqlite-mail-store-2026-10-08.md) before inferring platform support.
+
+`supercode teams rpc mail.statistics` reads local storage counts and import/retention receipts. It is refused remotely
+and through the app door. Writer groups count stored envelope copies, not call attempts or quotas; database page
+counts exclude physical WAL size. Successful imports record their actual source reads, bytes, batch sizes and time.
+
 Two doors reach it:
 
 - **Local**: an owner-only Unix socket, `$SUPERCODE_HOME/teams/machine.sock` (or, when that path

package/bin/teams.mjs

@@ -490,12 +490,20 @@ async function main() {
       // (order 3 PR 3): what `message list`, `show` and the board read instead of asking those machines
       return withNode(async (rpc) => out(await rpc.call('machine.records', {})));
     case 'rpc': {
+      if (!sub) die('rpc <method> [JSON params] [--machine NAME]');
+      const method = sub.startsWith('harness.v1.') ? sub : `harness.v1.${sub}`;
+      const params = rest[0] ? JSON.parse(rest[0]) : {};
       const channel = await machineChannel();
+      // Mail operations were ported to the node door. Keep their operator CLI
+      // on that door; native sessions.* requests retain the harness transport.
+      if (method.startsWith('harness.v1.mail.')) {
+        try { out(await (await nodeRpc(channel)).call(method, params)); }
+        finally { channel.close(); }
+        return;
+      }
       const client = new SupercodeHarnessClient({ transport: harnessTransport(channel) });
       try {
         await client.start?.();
-        const params = rest[0] ? JSON.parse(rest[0]) : {};
-        const method = sub.startsWith('harness.v1.') ? sub : `harness.v1.${sub}`;
         out(await client.request(method, params));
       } finally {
         await client.close?.();

package/machine.mjs

@@ -36,7 +36,7 @@ import { openMachine, normalMachineName } from '@volter/teams/machine-door';
 import { RecordHolder, RecordProducer, RECENT_PER_MAILBOX, RECORDS_NOT_GRANTED } from './machine-records.mjs';
 import { LiveSessions, ACTING_VARIABLES } from './live-sessions.mjs';
 import { checkRemoteClose } from './remote-close.mjs';
-import { MailStore } from './mail/store.mjs';
+import { SqliteMailStore } from './mail/sqlite-store.mjs';
 import { MailReads, panePrompt } from './mail/reads.mjs';
 import { render } from './mail/envelope.mjs';
 import { Agents } from './mail/agents.mjs';
@@ -99,6 +99,7 @@ import { DEFAULT_RANK, normalizeRank, judge } from './attention.mjs';
 import { popupTerminal, openPopup } from './popup-terminals.mjs';
 import { JobOwner, executionCapabilities, streamProgram, serveWorkspace } from './execution.mjs';
 import { TerminalMailbox, retainedTerminalMail } from './terminal-mail.mjs';
+import { nativeLaunchKey } from './native-launch-binding.mjs';
 import { confirmNativeInitialInput } from './native-initial-input.mjs';
 import { sessionPeople } from './session-people.mjs';
 import { canonicalCodexFolderTrust, codexProgram, codexStartupArguments, codexUpdatePrompt, codexVersion, codexWindowsPastes, settleCodexHookReview } from './codex-startup.mjs';
@@ -560,7 +561,6 @@ export class TeamsMachine extends MachineCore {
     // `stop()` can abandon it rather than leave a timer running past the daemon.
     this.voiceProcesses = new Map(); // session address -> optional voice pack child
     this.terminalMailboxes = new Map();
-    this.terminalMailRoot = join(this.env.SUPERCODE_HOME || join(this.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'supercode'), 'mail');
     this.terminalMailTimer = setInterval(() => {
       if (this.terminalMailWork) return;
       this.terminalMailWork = this.#drainTerminalMail().catch(error => this.emit('mail-watch-stderr', `terminal mailbox: ${error.message}`)).finally(() => { this.terminalMailWork = null; });
@@ -649,20 +649,33 @@ export class TeamsMachine extends MachineCore {
   // ---- lifecycle ------------------------------------------------------------
 
   async beforeListen() {
-    this.bornAt ??= Date.now();
-    mkdirSync(this.portsDir, { recursive: true }); // the port table's announce directory exists before any pane launches
-    this.#startServe();
-    if (this.#pendingNotices().length) this.#watchEnds();
-    this.jobs = new JobOwner({ home: this.home, env: this.env, log: (row) => this.log.append({ principal: null, cap: 'exec', target: `job:${row.job}`, outcome: row.outcome, detail: row.reason }) });
-    this.jobs.reapOrphans();
+    try {
+      this.bornAt ??= Date.now();
+      this.mailStore = new SqliteMailStore({ mailRoot: join(supercodeHome(this.env), 'mail'), machine: machineName(this.env), log: (line) => this.emit('records-log', line) });
+      this.mailStore.acquire();
+      mkdirSync(this.portsDir, { recursive: true }); // the port table's announce directory exists before any pane launches
+      this.#startServe();
+      if (this.#pendingNotices().length) this.#watchEnds();
+      this.jobs = new JobOwner({ home: this.home, env: this.env, log: (row) => this.log.append({ principal: null, cap: 'exec', target: `job:${row.job}`, outcome: row.outcome, detail: row.reason }) });
+      this.jobs.reapOrphans();
+    } catch (error) {
+      await this.afterStop();
+      throw error;
+    }
   }
 
   async afterListen() {
+    try {
+      this.#startLive();
+      await this.#startMail();
+      this.mailReady = true;
+    } catch (error) {
+      await this.stop();
+      throw error;
+    }
     // Web apps on this machine reach it through the app door when the person has turned it on (app-door.mjs).
     this.appDoor = serveAppDoor({ home: this.home, open: () => { const [page, daemon] = inProcessPair(); void this.acceptLocal(daemon, { appDoor: true }); return page; }, log: (row) => this.log.append({ principal: 'app-door', cap: 'app-door', target: row.origin ?? '*', outcome: row.outcome, detail: row.detail }) });
     this.#startHealth();
-    this.#startLive();
-    this.#startMail();
     this.#startRecords();
     if(Object.keys(this.inputRepairs).length)this.#watchInputRepairs();
   }
@@ -754,12 +767,12 @@ export class TeamsMachine extends MachineCore {
   }
 
   // ---- this machine's mail (mail/; docs/architecture/overview.md, "The mail operations") ---------------------------
-  #startMail() {
+  async #startMail() {
     const mailRoot = join(supercodeHome(this.env), 'mail');
     // the Messages API a Claude relay talks to (step 4a: the daemon's, in process; the native watch served it)
-    this.relayEndpoint = serveRelayEndpoint(mailRoot, { log: (line) => this.emit('mail-log', line) })
+    await this.mailStore.start();
+    this.relayEndpoint = serveRelayEndpoint(this.mailStore, { log: (line) => this.emit('mail-log', line) })
       .catch((error) => { this.emit('mail-log', `relay endpoint: not served (${error.message}); a Claude session cannot be sent mail until the daemon starts again`); return null; });
-    this.mailStore = new MailStore({ mailRoot, machine: machineName(this.env), log: (line) => this.emit('records-log', line) }).start();
     // the session index's rows by address (its descriptors, as the records' index subscription hands them over)
     this.sessionDescriptors = new Map();
     const live = this.live;
@@ -771,18 +784,18 @@ export class TeamsMachine extends MachineCore {
         self: machineName(this.env),
       }),
       // the transcripts of every Claude home the map follows, and the native-question records beside the mail
-      homes: { get claudeProjects() { return [...live.claudeDirs.keys()].map((dir) => join(dirname(dir), 'projects')); }, mailRoot },
+      homes: { get claudeProjects() { return [...live.claudeDirs.keys()].map((dir) => join(dirname(dir), 'projects')); }, store: this.mailStore },
       paneQuestion: async (pane) => { const session = await this.#paneByContext(pane); return session ? panePrompt(await this.host.capture(session.id, { lines: 60 })) : null; },
       askMachine: (machine, request) => this.#askMailDoor(machine, request),
       log: (line) => this.emit('mail-log', line),
     });
     // a send to a session, for every entry (3b-1): its routing on the live map, an agent's plan and its doors
     const machine = machineName(this.env);
-    this.agents = new Agents({ mailRoot, machine, supercodeBin: this.supercodeBin, env: this.env,
+    this.agents = new Agents({ store: this.mailStore, machine, supercodeBin: this.supercodeBin, env: this.env,
       discover: (params) => this.#serveRequest('harness.v1.sessions.discover', params, 10_000),
       recordedConfig: (locator) => this.#serveRequest('harness.v1.sessions.recorded_config', { locator }, 15_000) });
     // a relay's hooks (`message gate`, `relay-receipt`, `relay-inbound`) run the machine's stable supercode: its front door
-    this.relays = new Relays({ mailRoot, machine, supercodeBin: this.#stableSupercode(), hooksServed: () => this.#frontDoorServes('message gate'), serve: (method, params, timeoutMs) => this.#serveRequest(method, params, timeoutMs),
+    this.relays = new Relays({ mailRoot, store: this.mailStore, machine, supercodeBin: this.#stableSupercode(), hooksServed: () => this.#frontDoorServes('message gate'), serve: (method, params, timeoutMs) => this.#serveRequest(method, params, timeoutMs),
       runtimeOf: (harness, id) => live.runtimeReceipt(harness, id), runtimeNamed: (receiptId) => live.receiptNamed(receiptId),
       runtimesIn: (harness, cwd) => live.runtimesIn(harness, cwd),
       endpointOf: async () => (await this.relayEndpoint)?.url ?? null,
@@ -790,6 +803,7 @@ export class TeamsMachine extends MachineCore {
       log: (line) => this.emit('mail-log', line) });
     // a turn or a wake typed into a daemon pane's empty composer, in process (as `panes.turn` types one)
     const typeTurn = async (pane, harness, text, messageIds) => {
+      if (this.stopping) throw new Error('the daemon is stopping; no pane input was submitted');
       const session = await this.#paneByContext(pane);
       if (!session) throw new Error(`no pane with context ${pane}`);
       const result = await this.#paneTurn(session, pane, text, { messageIds, harness });
@@ -842,11 +856,12 @@ export class TeamsMachine extends MachineCore {
     const turnsWaiting = new Map(); // address → timer
     const typeWaiting = async (address) => {
       clearTimeout(turnsWaiting.get(address)); turnsWaiting.delete(address);
+      if (this.stopping) return;
       const session = live.sessions().find((row) => row.address === address);
       const pane = session ? this.mail.paneOf(session) : null;
       if (!pane || !this.mailStore.userTurns(address).length) return;
       try { await this.mailSend.typeUserTurns(address, pane); } catch (error) { this.emit('mail-log', `the user's turns for ${address} wait: ${error.message}`); }
-      if (this.mailStore.userTurns(address).length) { const timer = setTimeout(() => void typeWaiting(address), 2000); timer.unref?.(); turnsWaiting.set(address, timer); }
+      if (!this.stopping && this.mailStore.userTurns(address).length) { const timer = setTimeout(() => void typeWaiting(address), 2000); timer.unref?.(); turnsWaiting.set(address, timer); }
     };
     this.mailStore.on('changed', (address) => { if (address && !turnsWaiting.has(address)) void typeWaiting(address); });
     // the turns already waiting when this listener came (the store read every mailbox at its start, before it), and every
@@ -854,6 +869,7 @@ export class TeamsMachine extends MachineCore {
     const everyMailbox = () => { for (const address of this.mailStore.addresses()) if (!turnsWaiting.has(address)) void typeWaiting(address); };
     everyMailbox();
     this.turnsSweep = setInterval(everyMailbox, 300_000); this.turnsSweep.unref?.();
+    this.stopWaitingTurns = () => { clearInterval(this.turnsSweep); for (const timer of turnsWaiting.values()) clearTimeout(timer); turnsWaiting.clear(); };
     // an agent's verbs (3b-2): its threads, a delegation, its record
     this.agentVerbs = new AgentVerbs({ machine, store: this.mailStore, agents: this.agents, live, supercodeBin: this.supercodeBin, env: this.env,
       paneOf: (session) => this.mail.paneOf(session), mailRoot,
@@ -868,17 +884,19 @@ export class TeamsMachine extends MachineCore {
     live.on('changed', () => {
       // while the Codex sessions are not known (a start, a serve restart) a Codex session missing has not ended: the last
       // known view stands until they are known again
-      if (!live.codexKnown) return;
+      if (this.stopping || !live.codexKnown) return;
       const now = new Map(live.sessions().map((row) => [row.address, row.name]));
       // a Codex session that leaves the map has not provably ended (idle over a day, it is no longer followed): kept
       for (const [address, name] of wasLive) if (!now.has(address) && address.split(':')[2] !== 'codex') void this.relays.retire(address, name).catch(() => {});
       wasLive = now;
     });
     void live.whenCodexKnown(120_000).then((known) => {
+      if (this.stopping) return;
       if (!known) { this.emit('mail-log', 'relays: the live sessions were not known within two minutes of start; relays of ended sessions are retired at their next end'); return; }
       return this.relays.sweepAtStart((address) => live.sessions().some((row) => row.address === address));
     }).catch((error) => this.emit('mail-log', `relays: the start sweep failed: ${error.message}`));
     live.on('changed', () => {
+      if (this.stopping) return;
       if (naming) return;
       naming = setTimeout(() => { naming = null; try { this.mailSend.rememberNames(live.sessions()); } catch { /* kept at the next change */ } }, 1000);
       naming.unref?.();
@@ -1132,6 +1150,8 @@ export class TeamsMachine extends MachineCore {
   }
 
   async beforeClose() {
+    this.mailReady = false;
+    this.#stopMailWorkers();
     this.#stopHealth();
     clearInterval(this.terminalMailTimer); await this.terminalMailWork;
     clearInterval(this.processTimer); await this.processWork;
@@ -1164,14 +1184,10 @@ export class TeamsMachine extends MachineCore {
     for (const child of this.voiceProcesses.values()) child.kill('SIGTERM');
     this.voiceProcesses.clear();
     this.jobs?.stopAll();
-    void this.relayEndpoint?.then((endpoint) => endpoint?.close()).catch(() => {});
-    this.carrier?.stop();
+    await this.relayEndpoint?.then((endpoint) => endpoint?.close()).catch(() => {});
     this.stopLiveFollow?.();
+    this.#stopMailWorkers();
     this.mailStore?.stop();
-    clearInterval(this.hookSpoolTimer);
-    this.idleNotices?.stop();
-    this.agentUpkeep?.stop();
-    this.nativeQuestions?.stop();
     clearInterval(this.turnsSweep);
     this.stoppingServe = true;
     clearTimeout(this.serveRestart);
@@ -1181,6 +1197,22 @@ export class TeamsMachine extends MachineCore {
     this.host.dispose();
   }
 
+  #stopMailWorkers() {
+    if (this.mailWorkersStopped) return;
+    this.mailWorkersStopped = true;
+    this.mailSend?.stop();
+    this.agents?.stop();
+    this.agentVerbs?.stop();
+    this.carrier?.stop();
+    clearInterval(this.hookSpoolTimer);
+    this.idleNotices?.stop();
+    this.agentUpkeep?.stop();
+    this.nativeQuestions?.stop();
+    this.mailHooks?.stop();
+    this.relays?.stop();
+    this.stopWaitingTurns?.();
+  }
+
   connectionClosed(index) {
     for (const [key, owners] of this.routes) { owners.delete(index); if (owners.size === 0) this.routes.delete(key); }
   }
@@ -1540,6 +1572,9 @@ export class TeamsMachine extends MachineCore {
   }
 
   #serveMail(entry, stream, accept, refuse,requestOverride=null) {
+    if (!this.mailReady || this.stopping) return refuse(this.stopping
+      ? 'this machine daemon is stopping'
+      : 'this machine daemon is preparing its mail database; retry once migration completes');
     // One message into a session on this machine, delivered by this daemon's own send (mail/send.mjs) through the same
     // doors a local send uses. The receiver is the
     // target: `mail:*` reaches every session here, `mail:<address>` one of them; a
@@ -2032,9 +2067,8 @@ export class TeamsMachine extends MachineCore {
       if (claude && params.initialInput) throw Object.assign(new Error('Claude first input requires the native SessionStart receipt hook; this front door does not serve it'), { code: 503 });
       return launchCommand(params.program, args);
     }
-    const mailHome = this.env.SUPERCODE_HOME || join(this.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'supercode');
+    const mailHome = dirname(this.mailStore.root);
     const dir = join(mailHome, 'mail', 'native-launches');
-    mkdirSync(dir, { recursive: true, mode: 0o700 });
     // A reused pane key still gets a new receipt baseline. A late hook from
     // its previous process cannot publish evidence for this launch.
     const binding = join(dir, `${pane}-${randomBytes(9).toString('base64url')}.json`);
@@ -2045,14 +2079,14 @@ export class TeamsMachine extends MachineCore {
       !args.some((arg) => arg === '--remote' || arg.startsWith('--remote=')) ? prompt : null;
     const claudeInput = claude && prompt ? { kind: params.kind, text: prompt, startedAt: Date.now(),
       deadlineMs: Date.now() + INITIAL_INPUT_READY_DEADLINE_MS + 10_000, typed: true } : null;
-    writeFileSync(binding, JSON.stringify({ key: params.key, kind: params.kind, pane, by, program: params.program, arguments: args, initialInput, claudeInput }), { mode: 0o600 });
+    this.mailStore.putRecord('native_launches', basename(binding), { key: params.key, kind: params.kind, pane, by, program: params.program, arguments: args, initialInput, claudeInput });
     // The first input is durable before createSession can start the program.
     // Its body stays in the private binding, never in the launch journal.
     if (claudeInput) {
       this.launches.record({ ...this.launches.find(params.key), nativeInputBinding: binding });
       nativeInput({ ...claudeInput, binding });
     }
-    else if (initialInput) nativeInput({ binding, kind: params.kind, text: initialInput, startedAt: Date.now() });
+    else nativeInput({ binding, kind: params.kind, text: initialInput, startedAt: Date.now() });
     if (params.kind === 'claude-code') {
       // Claude's exec-form hook passes each argument unchanged on all platforms.
       // A Windows .cmd shim is resolved to its Node executable and front door.
@@ -2079,7 +2113,7 @@ export class TeamsMachine extends MachineCore {
     // door. Give this pane its own native server, through Codex's --remote
     // Unix endpoint; never attach to another running session by inference.
     if (args.some((arg) => arg === '--remote' || arg.startsWith('--remote='))) return launchCommand(params.program, args);
-    return launchCommand(process.execPath, [fileURLToPath(new URL('./native-codex-pane.mjs', import.meta.url)), binding]);
+    return launchCommand(process.execPath, [fileURLToPath(new URL('./native-codex-pane.mjs', import.meta.url)), binding, this.home]);
   }
 
   /**
@@ -2258,10 +2292,11 @@ export class TeamsMachine extends MachineCore {
    *  before this was kept carries the same files. A Codex session has no such hook here and no origin: its resumed pane
    *  stays its resumer's. */
   #sessionOrigin(session) {
-    let lines, names;
-    const dir = join(this.env.SUPERCODE_HOME || join(this.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'supercode'), 'mail', 'native-launches');
-    try { lines = readFileSync(this.launches.path, 'utf8').split('\n'); names = readdirSync(dir); } catch { return null; }
-    const read = (name) => { try { return JSON.parse(readFileSync(join(dir, name), 'utf8')); } catch { return null; } };
+    let lines;
+    try { lines = readFileSync(this.launches.path, 'utf8').split('\n'); } catch { return null; }
+    const bindings = new Map(this.mailStore.records('native_launches').map(({ key, value }) => [key, value]));
+    const names = [...bindings.keys()];
+    const read = (name) => bindings.get(name) ?? null;
     const started = (entry) => names.some((name) => {
       if (!name.startsWith(`${entry.pane}-`) || !/^[^.]+\.json$/.test(name)) return false;
       const seed = read(name);
@@ -2430,6 +2465,19 @@ export class TeamsMachine extends MachineCore {
       const launch = this.launches.find(key);
       if (launch?.pane !== contextKey) return;
       this.launches.record({ ...launch, ...facts, status: launch.status });
+      const binding = nativeInput?.binding ?? launch.nativeInputBinding;
+      if (!this.stopping && facts.inputDelivered === true && binding) {
+        try {
+          const bindingKey = basename(binding);
+          const seed = this.mailStore.record('native_launches', bindingKey);
+          if (seed?.key === key && seed.pane === contextKey && seed.by === by && seed.input_settled_at_ms == null) {
+            this.mailStore.putRecord('native_launches', bindingKey, { ...seed, input_settled_at_ms: Date.now() });
+          }
+        } catch (error) {
+          // Retaining extra text never changes the native delivery receipt.
+          this.emit('records-log', `confirmed launch input retained: settlement could not be recorded (${error.message})`);
+        }
+      }
     };
     const abort = new AbortController();
     const task = (async () => {
@@ -2463,7 +2511,7 @@ export class TeamsMachine extends MachineCore {
         }
       }
       if (nativeInput) {
-        const result = await confirmNativeInitialInput(nativeInput, { signal: abort.signal,
+        const result = await confirmNativeInitialInput(nativeInput, { signal: abort.signal, store: this.mailStore,
           deadlineMs: Date.now() + INITIAL_INPUT_READY_DEADLINE_MS, live: async () => Boolean(await this.#paneByContext(contextKey)) });
         recordInput({ key, pane: contextKey, kind, by, ...resumed, ...executable, inputDelivered: result.delivered,
           inputReadyBy: nativeReadyBy, ...(result.delivered ? { inputReceipt: result.receipt } : { inputError: result.reason }),
@@ -2500,7 +2548,7 @@ export class TeamsMachine extends MachineCore {
     let identity;
     while (!signal.aborted && Date.now() < deadline) {
       if ((await this.#paneByContext(contextKey))?.id !== session.id) return { delivered: false, reason: 'pane-gone' };
-      const start = readJson(input.binding.replace(/\.json$/, '.session.json'));
+      const start = this.mailStore.record('native_launches', basename(input.binding).replace(/\.json$/, '.session.json'));
       const id = /([0-9a-f]{8}-[0-9a-f-]{27})\.jsonl$/i.exec(String(start?.path ?? ''))?.[1];
       if (id && Number.isSafeInteger(start.offset) && start.offset >= 0) {
         identity = { kind: 'claude-code', path: start.path, sessionId: id, offset: start.offset };
@@ -2528,7 +2576,7 @@ export class TeamsMachine extends MachineCore {
       if ((onlyKey && launch.key !== onlyKey) || launch.kind !== 'claude-code' || !launch.nativeInputBinding ||
         launch.inputDelivered || launch.inputRefused || this.pendingInitialInputs.has(launch.key) ||
         !['issued', 'ready'].includes(launch.status)) continue;
-      const seed = readJson(launch.nativeInputBinding);
+      const seed = this.mailStore.record('native_launches', basename(launch.nativeInputBinding));
       if (seed?.key !== launch.key || seed.pane !== launch.pane || seed.by !== launch.by || !seed.claudeInput?.text) continue;
       const session = panes.find(row => row.contextKey === launch.pane && !row.dead);
       if (!session) {
@@ -2544,9 +2592,10 @@ export class TeamsMachine extends MachineCore {
   }
 
   async #drainTerminalMail() {
+    if (!this.mailReady || this.stopping) return;
     // One pane listing per tick, shared by every mailbox: a listing per mailbox each second was most of this
     // daemon's tmux spawns (8 retained mailboxes, about 70 tmux processes a second, t_23e47b73).
-    const retained = retainedTerminalMail(this.terminalMailRoot);
+    const retained = retainedTerminalMail(this.mailStore);
     if (this.initialInputsRecovered && !retained.length && !this.terminalMailboxes.size) return;
     const panes = await this.host.listSessions();
     if (!this.initialInputsRecovered) {
@@ -2558,7 +2607,7 @@ export class TeamsMachine extends MachineCore {
       if (this.terminalMailboxes.has(saved.recipient) || !saved.binding) continue;
       const session = paneByContext(saved.binding.context);
       if (!session || session.rootPid !== saved.binding.pid) continue;
-      const queue = new TerminalMailbox(this.terminalMailRoot, saved.recipient, receipt => this.#recordTerminalReceipt(saved.binding.context, receipt),
+      const queue = new TerminalMailbox(this.mailStore, saved.recipient, receipt => this.#recordTerminalReceipt(saved.binding.context, receipt),
         (locator, options) => this.#serveRequest('harness.v1.sessions.load', { locator, options: { ...options, include_subagents: false } }, 10000));
       queue.identity = saved.binding.identity; queue.host = this.host; queue.session = session;
       // A tmux host remints its client IDs after restart. Context and the live
@@ -2583,10 +2632,10 @@ export class TeamsMachine extends MachineCore {
     if (!receipt.delivered && !receipt.refused) return;
     for (const id of receipt.message_ids ?? []) {
       if (!/^first-[A-Za-z0-9_-]+$/.test(id)) continue;
-      const path = join(this.terminalMailRoot, 'native-launches', `${id.slice(6)}.json`);
-      const seed = readJson(path), launch = seed?.key && this.launches.find(seed.key);
+      const key = `${id.slice(6)}.json`;
+      const seed = this.mailStore.record('native_launches', key), launch = seed?.key && this.launches.find(seed.key);
       if (!launch || seed.pane !== contextKey || launch.pane !== contextKey) continue;
-      const native = /([0-9a-f]{8}-[0-9a-f-]{27})\.jsonl$/i.exec(String(readJson(path.replace(/\.json$/, '.session.json'))?.path ?? ''))?.[1];
+      const native = /([0-9a-f]{8}-[0-9a-f-]{27})\.jsonl$/i.exec(String(this.mailStore.record('native_launches', key.replace(/\.json$/, '.session.json'))?.path ?? ''))?.[1];
       const { t: _previousAt, ...facts } = launch;
       this.launches.record({ ...facts, inputDelivered: receipt.delivered, inputPending: false, inputRefused: receipt.refused === true,
         ...(receipt.delivered ? { inputReceipt: receipt.receipt, inputError: null, ...(native ? { native_session: native } : {}) } : { inputError: receipt.reason }) });
@@ -2594,6 +2643,7 @@ export class TeamsMachine extends MachineCore {
   }
 
   async #terminalMail(session, contextKey, kind, text, options, identity = null) {
+    if (this.stopping) throw new Error('the daemon is stopping; no terminal mail was submitted');
     // Mail a queue of this terminal already holds (the watch asking again after the same message ids) is answered from
     // that queue, which types it once the composer frees: nothing is asked of the harness again for it.
     const ids = options.messageIds ?? [];
@@ -2625,7 +2675,7 @@ export class TeamsMachine extends MachineCore {
     }
     if ((!locator && !['codex', 'claude-code'].includes(kind)) || (['codex', 'claude-code'].includes(kind) && !path)) return { delivered: false, reason: 'native-transcript-unresolved' };
     if (!queue) {
-      queue = new TerminalMailbox(this.terminalMailRoot, key, receipt => this.#recordTerminalReceipt(contextKey, receipt),
+      queue = new TerminalMailbox(this.mailStore, key, receipt => this.#recordTerminalReceipt(contextKey, receipt),
         (locator, options) => this.#serveRequest('harness.v1.sessions.load', { locator, options: { ...options, include_subagents: false } }, 10000));
       this.terminalMailboxes.set(key, queue);
     }
@@ -2764,6 +2814,7 @@ export class TeamsMachine extends MachineCore {
   async #deliverPaneText(session, contextKey, text, options = {}) {
     const kind = this.#paneKind(contextKey, session);
     if (kind === 'codex' && codexUpdatePrompt(await this.host.capture(session.id, { lines: 120 }))) return { delivered: false, reason: 'codex-update-prompt: delivery refused; restart Codex with check_for_update_on_startup=false' };
+    if (this.stopping) throw new Error('the daemon is stopping; no pane input was submitted');
     if(this.inputRepairs[contextKey])return {delivered:false,reason:'input-cleanup-pending',cleanup_required:true};
     if (['claude-code', 'codex', 'grok', 'gemini', 'goose', 'opencode', 'pi', 'hermes', 'openclaw'].includes(kind)) return this.#terminalMail(session, contextKey, kind, submission(text, false), options);
     if (this.inputInFlight.has(session.id)) return { delivered: false, reason: 'input-in-flight' };
@@ -2838,6 +2889,7 @@ export class TeamsMachine extends MachineCore {
       // still holds refuses the turn at once and the session waits again, for the next turn to try.
       const queued = [...this.terminalMailboxes.values()].some(queue => queue.session?.id === session.id && (queue.state.active || queue.state.pending.length));
       if (draftKind === 'claude-code' && !this.inputInFlight.has(session.id) && !queued && claudeUsageLimitWait(await this.host.capture(session.id, { lines: 60 }))) {
+        if (this.stopping) throw new Error('the daemon is stopping; no pane input was submitted');
         await this.host.sendInput(session.id, '\u001b', { submitMode: 'single', deadlineMs: Date.now() + 5_000 });
         await new Promise(resolve => setTimeout(resolve, COMPOSER_RECHECK_MS));
       }
@@ -3260,6 +3312,7 @@ export class TeamsMachine extends MachineCore {
       }
       entry.admitted = fresh;
     }
+    if (!this.mailReady || this.stopping) throw Object.assign(new Error(this.stopping ? 'this machine daemon is stopping' : 'this machine daemon is preparing its mail database; retry once migration completes'), { code: 503 });
     const { admitted, principal } = entry;
     const operator = admitted.class === 'operator';
     const need = (cap, target) => {
@@ -3433,7 +3486,7 @@ export class TeamsMachine extends MachineCore {
       case 'harness.v1.sessions.people': {
         if (!operator) throw Object.assign(new Error('session people are for operators'), { code: 403 });
         if (!Array.isArray(params.sessions) || params.sessions.length > 200) throw Object.assign(new Error('sessions: up to 200 { harness, path, id }'), { code: 400 });
-        return { people: await sessionPeople(params.sessions, { launchesDir: join(this.terminalMailRoot, 'native-launches'), journalPath: this.p.launches }) };
+        return { people: await sessionPeople(params.sessions, { store: this.mailStore, journalPath: this.p.launches }) };
       }
       // A harness's standing instructions, as the person edits them (ChatGPT's custom instructions): the user tier
       // (instruction-doors.mjs: Claude Code's CLAUDE.md, Codex's AGENTS.md) or a project's own file in its directory.
@@ -3630,6 +3683,12 @@ export class TeamsMachine extends MachineCore {
         this.launches.record({ key, pane: contextKey, kind: params.kind ?? null, by, ...resumed, ...executable,
           status: createdExit ? createdExit.failed ? 'exited' : 'finished' : 'ready',
           ...(createdExit?.failed === false ? { completion: createdExit } : {}), ...(agent ? { agent } : {}) });
+        if (nativeInput?.binding && !createdExit) {
+          const bindingKey = basename(nativeInput.binding);
+          const seed = this.mailStore.record('native_launches', bindingKey);
+          if (seed) this.mailStore.putRecord('native_launches', bindingKey, { ...seed,
+            launchReceipt: { pane: contextKey, terminal: session.id, rootPid: session.rootPid } });
+        }
         if (params.kind === 'codex' && (params.arguments ?? []).includes('--dangerously-bypass-hook-trust')) this.#settleCodexStartup(key, contextKey, session, act);
         act('launch', `pane:${contextKey}`, 'ok', params.kind ?? params.program);
         if (typeof params.name === 'string' && params.name.trim()) {
@@ -4183,6 +4242,28 @@ export class TeamsMachine extends MachineCore {
         return { address, messages };
       }
       // the harnesses' mail hooks (step 1b): the hook's input in, what the hook prints out (`print`, null for nothing)
+      case 'harness.v1.mail.native_launch': {
+        if (entry.principal !== 'local' || entry.appDoor) throw Object.assign(new Error('a native launch binding is read by this machine\'s own processes'), { code: 403 });
+        const key = nativeLaunchKey(params.binding, this.mailStore.root);
+        let seed = this.mailStore.record('native_launches', key);
+        if (!seed) throw Object.assign(new Error('this native launch binding is absent; no native program was started'), { code: 404 });
+        if (params.socket_path == null) return { seed };
+        // The Unix wrapper publishes only its own endpoint. This is a process
+        // reading, not proof of a Codex thread or permission to act as one.
+        const pid = Number(params.claim?.pid);
+        if (process.platform === 'win32' || !entry.socket || !await peerIs(entry.socket, pid)) throw Object.assign(new Error('the native endpoint publisher could not be bound to this connection'), { code: 403 });
+        const pane = await this.#paneByContext(seed.pane);
+        seed = this.mailStore.record('native_launches', key);
+        if (!seed) throw Object.assign(new Error('this native launch binding ended before endpoint publication'), { code: 404 });
+        const receipt = seed.launchReceipt;
+        if (!receipt && this.launches.find(seed.key)?.status === 'issued') throw Object.assign(new Error('this launch\'s creation receipt is not published yet'), { code: 425 });
+        if (!pane || !receipt || receipt.pane !== seed.pane || receipt.terminal !== pane.id || receipt.rootPid !== pid || pane.rootPid !== pid) throw Object.assign(new Error('this native endpoint publisher is not the live launch root'), { code: 403 });
+        if (seed.kind !== 'codex' || typeof params.socket_path !== 'string' || !isAbsolute(params.socket_path) || !statSync(params.socket_path).isSocket()) throw Object.assign(new Error('the native endpoint must be this Codex wrapper\'s Unix socket'), { code: 400 });
+        if (seed.ownerPid != null && (seed.ownerPid !== pid || seed.socketPath !== params.socket_path)) throw Object.assign(new Error('this native launch already recorded another endpoint'), { code: 409 });
+        const recorded = { ...seed, socketPath: params.socket_path, ownerPid: pid };
+        this.mailStore.putRecord('native_launches', key, recorded);
+        return { seed: recorded };
+      }
       case 'harness.v1.mail.hook': case 'harness.v1.mail.relay_gate': case 'harness.v1.mail.relay_receipt': case 'harness.v1.mail.relay_inbound': case 'harness.v1.mail.question_hook': {
         if (entry.principal !== 'local' || entry.appDoor) throw Object.assign(new Error('a mail hook is answered here for this machine\'s own processes'), { code: 403 });
         const input = params.input && typeof params.input === 'object' ? params.input : {};
@@ -4287,6 +4368,10 @@ export class TeamsMachine extends MachineCore {
         if (entry.principal !== 'local' || entry.appDoor) throw Object.assign(new Error('mail is read here by this machine\'s own processes'), { code: 403 });
         return { code: 0, rows: method === 'harness.v1.mail.waiting' ? this.carrier.waiting() : this.carrier.expired() };
       }
+      case 'harness.v1.mail.statistics': {
+        if (entry.principal !== 'local' || entry.appDoor) throw Object.assign(new Error('mail storage diagnostics are read only by this machine\'s own processes'), { code: 403 });
+        return this.mailStore.statistics();
+      }
       // Who a local client is, from its claim (live-sessions.mjs callerOf): what a command acting on another machine sends
       // there as its caller, resolved here, where the map that holds it is. Local only; never the app door's.
       // The pane this daemon launched that a local process runs in, and who started that pane: what a process with no