@volter/supercode-teams 0.3.185 → 0.3.187

package/machine.mjs

@@ -559,7 +559,7 @@ export class TeamsMachine extends MachineCore {
       try {
         const record = readJson(this.p.machine, null);
         if (record?.pid !== process.pid) return;
-        writeJson(this.p.machine, { ...record, release: this.#release() });
+        writeJson(this.p.machine, { ...record, release: this.#release(), mail_ready: false });
       } catch { /* its record says no release */ }
     });
     // the panes' stable porthole hook and the machine's stable supercode brought up to this release's at start, under
@@ -714,7 +714,7 @@ export class TeamsMachine extends MachineCore {
     try {
       requireSessionIndexRuntime();
       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 = new SqliteMailStore({ mailRoot: join(supercodeHome(this.env), 'mail'), machine: machineName(this.env), committed: this.env.SUPERCODE_MAIL_COMMITTED === '1', startupRecovery: this.env.SUPERCODE_MAIL_STARTUP_RECOVERY === '1', log: (line) => this.emit('records-log', line) });
       this.mailStore.acquire();
       await this.mailStore.start();
       this.sessionIndex = new SessionIndexOwner({ database: this.mailStore.database, env: this.env, log: (line) => this.emit('records-log', line) });
@@ -738,18 +738,29 @@ export class TeamsMachine extends MachineCore {
 
   async afterListen() {
     try {
+      // First activation must prove its native before any delivery. Later
+      // restarts keep serving the committed mail while native indexing starts.
+      if (this.env.SUPERCODE_UPGRADE_ACTIVATING === '1') await this.#serveRequest('harness.v1.harnesses.list', {}, 4000);
       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.#startRecords();
     if(Object.keys(this.inputRepairs).length)this.#watchInputRepairs();
+    const readyRecord = readJson(this.p.machine, null);
+    if (readyRecord?.pid !== process.pid) throw new Error('daemon startup lost its machine record before mail readiness');
+    writeJson(this.p.machine, { ...readyRecord, mail_ready: true, mail_recovery: this.mailStore.deferred === true,
+      ...(this.env.SUPERCODE_UPGRADE_SUPERVISOR ? { upgrade_supervisor: Number(this.env.SUPERCODE_UPGRADE_SUPERVISOR) } : {}) });
+    if (!this.mailStore.deferred && this.env.SUPERCODE_UPGRADE_READY_FILE) writeJson(this.env.SUPERCODE_UPGRADE_READY_FILE, { pid: process.pid,
+      supervisor: Number(this.env.SUPERCODE_UPGRADE_SUPERVISOR),
+      release: JSON.parse(this.env.SUPERCODE_UPGRADE_RELEASE_RECEIPT), at_ms: Date.now() });
+    this.mailReady = true;
+    if (!this.mailStore.deferred) this.activateMail();
+    } catch (error) {
+      await this.stop();
+      throw error;
+    }
   }
 
   // ---- this machine's records (order 3 PR 3, machine-records.mjs) -------------
@@ -845,8 +856,6 @@ export class TeamsMachine extends MachineCore {
   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(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; });
     // 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;
@@ -911,27 +920,23 @@ export class TeamsMachine extends MachineCore {
     // a relay's inbound mail its hook kept while this daemon did not answer (the front door's spool): filed now, each
     // minute, and before each relay's inbound call
     this.hookSpool = join(supercodeHome(this.env), 'hook-spool', 'relay-inbound');
-    this.mailHooks.drainSpool(this.hookSpool);
-    this.mailHooks.drainPoolReplies();
-    this.hookSpoolTimer = setInterval(() => this.mailHooks.drainSpool(this.hookSpool), 60_000); this.hookSpoolTimer.unref?.();
     // the mailbox's own delivery (step 4b): each wake attempted by its session's door, or carried to its machine
-    this.carrier = new MailCarrier({ machine, mailRoot, store: this.mailStore, live,
+    const carrier = new MailCarrier({ machine, mailRoot, store: this.mailStore, live,
       handOver: (address, id) => this.mailSend.handOver(address, id),
       typeTurn, typeUserTurns: (address, pane) => this.mailSend.typeUserTurns(address, pane), paneOf: (session) => this.mail.paneOf(session),
       askMachine: (to, request) => this.#askMailDoor(to, request, MAIL_SEND_MS),
-      log: (line) => this.emit('mail-log', line) }).start();
+      log: (line) => this.emit('mail-log', line) });
     // idle notices and final replies (step 4c): each subscribed session's activity followed through harness serve
-    this.idleNotices = new IdleNotices({ machine, store: this.mailStore, live,
+    const idleNotices = new IdleNotices({ machine, store: this.mailStore, live,
       serveRequest: (method, params, ms) => this.#serveRequest(method, params, ms),
       locatorOf: (address) => this.sessionDescriptors?.get(address)?.locator ?? null,
-      log: (line) => this.emit('mail-log', line) }).start();
+      log: (line) => this.emit('mail-log', line) });
     // native Codex questions as mail (step 4c): the poll of each launched Codex pane's own app-server, in process
-    this.nativeQuestions.start();
     // an agent's upkeep (step 4d): folder sessions become threads, typed lines reach their CC, idle launched threads end
-    this.agentUpkeep = new AgentUpkeep({ machine, mailRoot, store: this.mailStore, agents: this.agents, live,
+    const agentUpkeep = new AgentUpkeep({ machine, mailRoot, store: this.mailStore, agents: this.agents, live,
       claudeProjects: () => [...live.claudeDirs.keys()].map((dir) => join(dirname(dir), 'projects')),
       lastMessageAt: (address) => this.sessionDescriptors?.get(address)?.updated_at_ms ?? null,
-      program: this.supercodeBin, env: this.env, log: (line) => this.emit('mail-log', line) }).start();
+      program: this.supercodeBin, env: this.env, log: (line) => this.emit('mail-log', line) });
     // User turns share the persisted delivery schedule; only their own raw-input door types them.
     // 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,
@@ -941,9 +946,18 @@ export class TeamsMachine extends MachineCore {
     // the names sessions ran under (`<mail>/names.json`): a name an agent was given reaches the same session after it
     // runs under another, kept from the map's changes (at most once a second)
     let naming = null;
-    void this.relays.sweepAtStart().catch((error) => this.emit('mail-log', `relay pool: predecessors retained (${error.message})`));
+    this.activateMail = () => {
+      this.relayEndpoint = serveRelayEndpoint(this.mailStore, { log: line => this.emit('mail-log', line) })
+        .catch(error => { this.emit('mail-log', `relay endpoint: not served (${error.message})`); return null; });
+      this.mailHooks.drainSpool(this.hookSpool);
+      this.mailHooks.drainPoolReplies();
+      this.hookSpoolTimer = setInterval(() => this.mailHooks.drainSpool(this.hookSpool), 60_000); this.hookSpoolTimer.unref?.();
+      this.carrier = carrier.start(); this.idleNotices = idleNotices.start();
+      this.nativeQuestions.start(); this.agentUpkeep = agentUpkeep.start();
+      void this.relays.sweepAtStart().catch(error => this.emit('mail-log', `relay pool: predecessors retained (${error.message})`));
+    };
     live.on('changed', () => {
-      if (this.stopping) return;
+      if (this.stopping || !this.mailReady || this.mailStore.deferred) return;
       if (naming) return;
       naming = setTimeout(() => { naming = null; try { this.mailSend.rememberNames(live.sessions()); } catch { /* kept at the next change */ } }, 1000);
       naming.unref?.();
@@ -1901,6 +1915,7 @@ export class TeamsMachine extends MachineCore {
     // receiver named rather than addressed needs `mail:*`.
     const { admitted, principal } = entry;
     const request = requestOverride??stream.params?.request;
+    if (this.mailStore.deferred && !['list', 'show', 'status', 'history'].includes(request?.op)) return refuse('mail migration is deferred; this daemon serves reads from retained originals while damaged operational records await repair');
     if (request?.op === 'turn') return this.#serveTurn(entry, request, stream, accept, refuse);
     if (request?.op === 'history') return this.#serveMailHistory(entry, request, stream, accept, refuse);
     const to = typeof request?.to === 'string' ? request.to : '*';
@@ -2303,7 +2318,7 @@ export class TeamsMachine extends MachineCore {
       const answer = spawnSync(this.supercodeBin, ['--version'], { env: this.env, encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] });
       native = answer.status === 0 ? answer.stdout.trim() || null : null;
     } catch { /* unread */ }
-    return { teams, native };
+    return { teams, native, supercode: this.env.SUPERCODE_RELEASE_VERSION ?? null };
   }
 
   #portholeHook() {
@@ -3633,6 +3648,9 @@ 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 });
+    if (this.mailStore.deferred && ((method.startsWith('harness.v1.mail.') && !['list', 'show', 'statistics', 'names', 'tools', 'changes'].some(name => method === `harness.v1.mail.${name}`)) || method === 'harness.v1.agent.declare')) {
+      throw Object.assign(new Error('mail migration is deferred; public mail reads remain available, delivery and acknowledgement await operational-state repair'), { code: 503 });
+    }
     const { admitted, principal } = entry;
     const operator = admitted.class === 'operator';
     const need = (cap, target) => {
@@ -3842,6 +3860,7 @@ export class TeamsMachine extends MachineCore {
         // never needing a person at it. Only a daemon its service manager brings back may go: one run by hand would not return.
         if (!operator) { this.log.append({ principal, cap: method, target: '*', outcome: 'refused' }); throw Object.assign(new Error('only an operator restarts the machine daemon'), { code: 403 }); }
         if (!this.restartHandler) throw Object.assign(new Error('this daemon runs without a service manager, so nothing would start it again; restart it where it runs'), { code: 'unsupported' });
+        await this.restartAdmission?.();
         act(method, '*', 'ok', params.reason ? String(params.reason).slice(0, 200) : null);
         // The answer goes out first; the service manager starts the next daemon.
         setTimeout(() => this.restartHandler(params.reason ? String(params.reason) : null), 500).unref?.();

package/mail/import-maildir.mjs

@@ -48,7 +48,7 @@ async function* logRecords(stream, start) {
   else if (fragments.length) yield { bytes: assembled(), offset: position };
 }
 
-export async function importMaildir(database, root, { log = () => {}, legacyRoot = root } = {}) {
+export async function importMaildir(database, root, { log = () => {}, legacyRoot = root, deferOperational = false } = {}) {
   const began = performance.now();
   const work = { source_reads: 0, source_bytes: 0, committed_batches: 0, max_queued_operations: 0, resumed_directories: 0, resumed_entries: 0, resumed_log_bytes: 0, elapsed_ms: 0 };
   const complete = database.metadata('maildir_import');
@@ -85,13 +85,13 @@ export async function importMaildir(database, root, { log = () => {}, legacyRoot
     if (pending.length >= 256) flush();
   };
   const errors = database.statement('INSERT INTO mail_import_errors(source, mailbox, detail, critical) VALUES (?, ?, ?, ?) ON CONFLICT(source) DO UPDATE SET mailbox = excluded.mailbox, detail = excluded.detail, critical = excluded.critical');
-  const failed = (path, error, mailbox = null) => {
+  const failed = (path, error, mailbox = null, { diagnostic = false } = {}) => {
     const source = relative(root, path);
     const parts = source.split(/[\\/]/);
-    const critical = ['agents', 'threads', 'native-questions', 'native-launches', 'relays', 'machines', 'sent'].includes(parts[0])
+    const critical = !diagnostic && (['agents', 'threads', 'native-questions', 'native-launches', 'relays', 'machines'].includes(parts[0])
       || ['claims', 'subscriptions', 'wake'].includes(parts[1])
       || parts[0] === 'names.json' || parts[0] === 'relay-endpoint.json'
-      || (parts[0] === 'terminal-delivery' && parts.at(-1) === 'queue.json');
+      || (parts[0] === 'terminal-delivery' && parts.at(-1) === 'queue.json'));
     queue(() => errors.run(source, mailbox, String(error.message ?? error), critical ? 1 : 0));
     result.skipped++;
     log(`mail import: retained unreadable source ${source}: ${error.message ?? error}`);
@@ -194,7 +194,7 @@ export async function importMaildir(database, root, { log = () => {}, legacyRoot
       if (!entry.isFile() || !entry.name.endsWith('.json')) continue;
       const path = join(dir, 'claims', entry.name), id = basename(entry.name, '.json');
       const claim = await json(path, address);
-      if (claim && !present(id)) { failed(path, 'claim has no imported message', address); continue; }
+      if (claim && !present(id)) { failed(path, 'claim has no imported message', address, { diagnostic: true }); continue; }
       if (claim) queue(() => database.statement('INSERT INTO claims(mailbox, message, record) VALUES (?, ?, ?) ON CONFLICT(mailbox, message) DO NOTHING').run(address, id, JSON.stringify(claim)));
     }
     for await (const entry of entries(join(dir, 'subscriptions'))) {
@@ -384,11 +384,12 @@ export async function importMaildir(database, root, { log = () => {}, legacyRoot
   result.records = database.statement('SELECT count(*) AS count FROM mail_records').get().count;
   result.skipped = database.statement('SELECT count(*) AS count FROM mail_import_errors').get().count;
   work.elapsed_ms = Math.round(performance.now() - began);
+  database.statement("UPDATE mail_import_errors SET critical = 0 WHERE source LIKE 'sent/%/log.jsonl' OR detail = 'claim has no imported message'").run();
   const blocked = database.statement('SELECT source FROM mail_import_errors WHERE critical = 1 ORDER BY source').all();
-  if (blocked.length) {
+  if (blocked.length && !deferOperational) {
     throw Object.assign(new Error(`mail migration cannot activate with ${blocked.length} unreadable operational records (${blocked.slice(0, 3).map(({ source }) => source).join(', ')}); original files are retained for repair`), { code: 'mail_import_incomplete' });
   }
-  result.complete = true;
+  result.complete = blocked.length === 0;
   database.setMetadata('maildir_import', result);
   log(`mail import complete: ${result.messages} envelopes, ${result.records} operational records, ${result.skipped} retained unreadable sources; ${work.source_reads} source reads, ${work.source_bytes} bytes, ${work.committed_batches} batches in ${work.elapsed_ms} ms`);
   return result;

package/mail/recovery-view.mjs

@@ -0,0 +1,36 @@
+// When there is no earlier release to serve, retain the source stores and
+// answer reads from a disposable private view. Never activate damaged routing
+// records or run delivery against an incomplete migration.
+import { DatabaseSync } from 'node:sqlite';
+import { mkdir, lstat, rm } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { MailDatabase } from './sqlite.mjs';
+import { importMaildir } from './import-maildir.mjs';
+
+export async function recoveryMailView(root, { log = () => {} } = {}) {
+  const home = dirname(root), directory = join(home, 'teams', 'service', 'mail-recovery');
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const path = join(directory, 'mail.sqlite');
+  // The caller holds this home's mail owner lease. This is its own disposable
+  // view, never the source SQLite database or an archived original.
+  for (const suffix of ['', '-wal', '-shm']) await rm(path + suffix, { force: true });
+  const live = join(home, 'mail.sqlite');
+  try {
+    await lstat(live);
+    const reader = new DatabaseSync(live, { readOnly: true });
+    try { reader.prepare('VACUUM INTO ?').run(path); } finally { reader.close(); }
+  } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  const database = new MailDatabase(path);
+  try {
+    const retired = database.metadata('maildir_retirement');
+    let input = root;
+    try { await lstat(input); }
+    catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      if (retired?.archive && dirname(resolve(retired.archive)) === resolve(home, 'mail-retired')) input = retired.archive;
+    }
+    await importMaildir(database, input, { legacyRoot: root, deferOperational: true, log });
+    log('mail migration is deferred; original stores retained, public mail reads use a private recovery view, delivery is unavailable');
+    return database;
+  } catch (error) { database.close(); throw error; }
+}

package/mail/retire-maildir.mjs

@@ -1,10 +1,10 @@
-// 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 and validate while the legacy store stays at its original path. Only
+// a complete, unchanged import can retire it. Keep originals for recovery;
+// retiring mail is never permission to delete another release's readable data.
 import { createReadStream } from 'node:fs';
-import { lstat, mkdir, readdir, rename, rmdir, unlink } from 'node:fs/promises';
+import { lstat, mkdir, rename } from 'node:fs/promises';
 import { createHash, randomUUID } from 'node:crypto';
-import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
 import { importMaildir } from './import-maildir.mjs';
 import { requireLegacyMaildirReady } from './migration-readiness.mjs';
 
@@ -12,95 +12,84 @@ const stat = async (path) => {
   try { return await lstat(path); }
   catch (error) { if (error.code === 'ENOENT') return null; throw error; }
 };
+
+export async function verifyImportedMaildir(database, root) {
+  for (const { key, value } of database.statement("SELECT key, value FROM mail_metadata WHERE key LIKE 'maildir_directory:%'").all()) {
+    const saved = JSON.parse(value), path = resolve(root, key.slice('maildir_directory:'.length));
+    if (path !== root && !path.startsWith(root + sep)) throw new Error('mail import directory receipt is outside its source');
+    const current = await stat(path);
+    const stamp = current && { device: current.dev, inode: current.ino, mtime: current.mtimeMs, ctime: current.ctimeMs };
+    if (JSON.stringify(saved.stamp) !== JSON.stringify(stamp)) throw new Error(`mail source directory changed before retirement: ${path}`);
+  }
+  const sources = database.statement('SELECT source, sha256 FROM mail_import_sources WHERE source > ? ORDER BY source LIMIT 256');
+  let cursor = '';
+  for (;;) {
+    const batch = sources.all(cursor);
+    if (!batch.length) return;
+    for (const row of batch) {
+      const path = resolve(root, row.source);
+      if (isAbsolute(row.source) || !path.startsWith(root + sep)) throw new Error('an imported source is outside its Maildir');
+      let parent = dirname(path);
+      while (parent !== root) {
+        if (!(await stat(parent))?.isDirectory()) throw new Error(`mail source directory changed before retirement: ${row.source}`);
+        parent = dirname(parent);
+      }
+      if (!(await stat(path))?.isFile()) throw new Error(`mail source changed before retirement: ${row.source}`);
+      const hash = createHash('sha256');
+      for await (const bytes of createReadStream(path)) hash.update(bytes);
+      if (hash.digest('hex') !== row.sha256) throw new Error(`mail source bytes changed before retirement: ${row.source}`);
+    }
+    cursor = batch.at(-1).source;
+  }
+}
+
 /** Called only while this daemon holds the mail owner lease. */
-export async function migrateMaildir(database, root, { log = () => {} } = {}) {
+export async function migrateMaildir(database, root, { log = () => {}, committed = false } = {}) {
   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 requireLegacyMaildirReady(root);
-    retirement = { source: root, archive: source ? join(dirname(root), 'mail-retired', randomUUID()) : null, started_at_ms: Date.now(), complete: false };
+    retirement = { version: 2, 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`);
+    if (source && !committed) 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) log(`committed SQLite mailbox remains serving; recreated legacy records at ${root} are retained for explicit recovery`);
     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 });
+    database.setMetadata('maildir_retirement', { ...retirement, complete: true, completed_at_ms: Date.now(), originals_retained: true });
     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');
+  if (source && snapshot) throw new Error(`the retired Maildir was recreated at ${root}; both stores are retained for explicit recovery`);
+  if (!source && !snapshot) throw new Error('the incomplete mail migration source is missing; originals cannot be reconstructed');
+  const input = snapshot ? archive : root;
+  if (!(snapshot ?? source).isDirectory()) throw new Error('the migration source is not a regular directory');
+  if (snapshot && retirement.inode != null && (retirement.inode !== snapshot.ino || retirement.device !== snapshot.dev)) throw new Error('the migration snapshot differs from its ownership receipt');
+  // Version-one receipts may already have moved the source before validation.
+  // Resume that snapshot, retaining it even when an operational input refuses.
+  const imported = await importMaildir(database, input, { log, legacyRoot: root });
+  if (snapshot && await stat(root)) throw new Error(`a legacy writer recreated ${root} during migration; both stores are retained`);
+  if (!snapshot) {
     await requireLegacyMaildirReady(root);
+    await verifyImportedMaildir(database, root);
+    const current = await stat(root);
+    if (current?.ino !== source.ino || current?.dev !== source.dev) throw new Error('mail root changed before retirement');
     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}`);
+  database.setMetadata('maildir_retirement', { ...retirement, inode: snapshot.ino, device: snapshot.dev,
+    complete: true, completed_at_ms: Date.now(), originals_retained: true });
+  log(`mail retired after complete import; original files retained at ${archive}`);
   return imported;
 }

package/mail/sqlite-store.mjs

@@ -6,6 +6,7 @@ import { dirname, join, resolve } from 'node:path';
 import { blake3Hex } from './envelope.mjs';
 import { MailDatabase, MailOwner, RETAINED_BODY } from './sqlite.mjs';
 import { migrateMaildir } from './retire-maildir.mjs';
+import { recoveryMailView } from './recovery-view.mjs';
 
 export const MIN_PREFIX_DIGITS = 4;
 export { RETAINED_BODY };
@@ -30,13 +31,15 @@ const validId = (id) => typeof id === 'string' && /^[A-Za-z0-9_-]+$/.test(id);
 const OFFLINE_CEILING_MS = 30 * 24 * 60 * 60_000;
 
 export class SqliteMailStore extends EventEmitter {
-  constructor({ mailRoot, machine = null, log = () => {}, database = null, retention } = {}) {
+  constructor({ mailRoot, machine = null, log = () => {}, database = null, retention, committed = false, startupRecovery = false } = {}) {
     super();
     this.root = resolve(mailRoot);
     this.machine = machine;
     this.log = log;
     this.database = database;
     this.retention = retention;
+    this.committed = committed;
+    this.startupRecovery = startupRecovery;
     this.unread = null;
   }
 
@@ -50,14 +53,21 @@ export class SqliteMailStore extends EventEmitter {
   async start() {
     if (!this.owner) throw new Error('mail cannot open without this daemon\'s writer lease');
     this.database ??= new MailDatabase(join(dirname(this.root), 'mail.sqlite'), { retention: this.retention });
-    this.imported = await migrateMaildir(this.database, this.root, { log: this.log });
-    this.database.retain();
-    this.reconcileDeliverySchedule();
+    try { this.imported = await migrateMaildir(this.database, this.root, { log: this.log, committed: this.committed || (this.startupRecovery && this.database.metadata('maildir_retirement')?.complete === true) }); }
+    catch (error) {
+      if (!this.startupRecovery) throw error;
+      this.log(`startup migration refused: ${error.message}`);
+      this.database.close();
+      this.database = await recoveryMailView(this.root, { log: this.log });
+      this.deferred = true;
+    }
+    if (!this.deferred) this.database.retain();
+    if (!this.deferred) this.reconcileDeliverySchedule();
     this.database.on('message', (address) => this.emit('changed', address));
     this.database.on('wake', ({ address, id }) => this.emit('wake', { address, id }));
     this.database.on('subscriptions', (address) => this.emit('subscriptions', address));
     this.retentionTimer = setInterval(() => {
-      try { this.database.retain(); }
+      try { if (!this.deferred) this.database.retain(); }
       catch (error) { this.log(`mail retention failed: ${error.message}`); }
     }, 3_600_000);
     this.retentionTimer.unref?.();

package/mail/upgrade-admission.mjs

@@ -0,0 +1,44 @@
+// All upgrade entrypoints ask the candidate release, never the old daemon's
+// cached modules. The candidate cannot modify the serving home's state.
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { resolve, join } from 'node:path';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+
+export async function requireUpgradeAdmission({ home, entry = new URL('../bin/teams.mjs', import.meta.url), env = process.env } = {}) {
+  const path = entry instanceof URL ? fileURLToPath(entry) : resolve(entry);
+  const scratch = await mkdtemp(join(tmpdir(), 'supercode-upgrade-'));
+  try { return await new Promise((done, reject) => {
+    const child = spawn(process.execPath, [path, 'mail', 'upgrade-inspect', '--home', resolve(home), '--json'],
+      { env: { ...env, SUPERCODE_UPGRADE_SCRATCH: scratch }, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+    let stdout = '', stderr = '', refused = false;
+    const refuse = (reason) => {
+      if (refused) return;
+      refused = true;
+      // Only the admission child we just started is ended, by its handle.
+      child.kill('SIGKILL');
+      clearTimeout(timer);
+      const error = Object.assign(new Error(`upgrade admission refused: ${reason}; the serving daemon must remain running`), { code: 'upgrade_not_ready' });
+      if (child.exitCode !== null || child.signalCode !== null || !child.pid) reject(error);
+      else child.once('close', () => reject(error));
+    };
+    const timer = setTimeout(() => refuse('candidate did not complete the existing-state check within 8 seconds'), 8000);
+    const collect = (which, bytes) => {
+      if (which === 'out') stdout += bytes; else stderr += bytes;
+      if (stdout.length + stderr.length > 64 * 1024) refuse('candidate returned an oversized admission response');
+    };
+    child.stdout.on('data', bytes => collect('out', bytes));
+    child.stderr.on('data', bytes => collect('err', bytes));
+    child.once('error', error => refuse(error.message));
+    child.once('close', (code, signal) => {
+      clearTimeout(timer);
+      if (refused) return;
+      if (code !== 0 || signal) return refuse(stderr.trim() || `candidate exited ${code ?? signal}`);
+      let receipt;
+      try { receipt = JSON.parse(stdout); } catch { return refuse('candidate returned no admission receipt'); }
+      if (receipt.stage !== 'upgrade_admission' || receipt.admitted !== true || receipt.home !== resolve(home, '..')) return refuse('candidate returned an invalid admission receipt');
+      done(receipt);
+    });
+  }); } finally { await rm(scratch, { recursive: true, force: true }); }
+}

package/mail/upgrade-readiness.mjs

@@ -0,0 +1,59 @@
+// Upgrade admission is a candidate command, before the serving daemon exits.
+// It opens live state read-only and applies this release's import/schema work
+// only to a private database. A refusal leaves the current service serving.
+import { DatabaseSync } from 'node:sqlite';
+import { lstat } from 'node:fs/promises';
+import { join, dirname, resolve } from 'node:path';
+import { MailDatabase } from './sqlite.mjs';
+import { importMaildir } from './import-maildir.mjs';
+import { requireLegacyMaildirReady } from './migration-readiness.mjs';
+import { verifyImportedMaildir } from './retire-maildir.mjs';
+import { requireSessionIndexRuntime } from '../session-index-owner.mjs';
+
+const exists = async (path) => {
+  try { return await lstat(path); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+};
+
+export async function inspectUpgradeReadiness(teamsHome, directory) {
+  requireSessionIndexRuntime();
+  // Resolve all daemon modules before admission, without starting its carrier,
+  // binding a socket or executing any retained delivery against a real session.
+  await import('../machine.mjs');
+  const home = dirname(teamsHome), root = join(home, 'mail');
+  const guard = await requireLegacyMaildirReady(root);
+  if (!directory) throw new Error('upgrade inspection requires its private admission directory');
+  let database;
+  try {
+    const live = join(home, 'mail.sqlite'), candidate = join(directory, 'mail.sqlite');
+    if (await exists(live)) {
+      const reader = new DatabaseSync(live, { readOnly: true });
+      try {
+        // SQLite creates a coherent snapshot, including committed WAL pages;
+        // copying the db/WAL files independently cannot establish that.
+        reader.prepare('VACUUM INTO ?').run(candidate);
+      } finally { reader.close(); }
+    }
+    database = new MailDatabase(candidate);
+    const retirement = database.metadata('maildir_retirement');
+    const source = await exists(root);
+    let input = root;
+    if (retirement?.source && retirement.source !== root) throw new Error('mail migration source differs from its stored receipt');
+    if (retirement?.archive && dirname(resolve(retirement.archive)) !== resolve(home, 'mail-retired')) throw new Error('migration snapshot is outside this home');
+    if (retirement?.archive && await exists(retirement.archive)) {
+      if (source) throw new Error('both the original migration snapshot and a recreated Maildir exist; explicit recovery is required before activation');
+      input = retirement.archive;
+    } else if (retirement?.complete && source) {
+      throw new Error('a retired Maildir was recreated; explicit recovery is required before activation');
+    } else if (retirement?.archive && !source && !retirement.complete) {
+      throw new Error('the incomplete mail migration source is missing');
+    }
+    const imported = await importMaildir(database, input, { legacyRoot: root });
+    if (!retirement?.complete && await exists(input)) await verifyImportedMaildir(database, input);
+    return { version: 1, stage: 'upgrade_admission', admitted: true, home,
+      messages: imported.messages, records: imported.records, retained_diagnostics: imported.skipped,
+      legacy_wrappers: guard.live.length, schema: database.metadata('schema_version') };
+  } finally {
+    database?.close();
+  }
+}