@volter/supercode-teams 0.3.185 → 0.3.188

package/bin/workspace/published-install.mjs

@@ -0,0 +1,46 @@
+// The registry input writer owns a lease independently of the installer that
+// started it. Installer loss cannot release cleanup over a still-running npm.
+import { spawn, spawnSync } from 'node:child_process';
+import { readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { releaseStateLease } from './release-state.mjs';
+
+const [service, directory, version] = process.argv.slice(2);
+if (!service || !directory || !/^\d+\.\d+\.\d+$/.test(version)
+  || dirname(resolve(directory)) !== resolve(service, 'published')) throw new Error('invalid published input');
+const close = await releaseStateLease(join(service, 'published'));
+let child;
+let killed = false;
+const kill = () => {
+  if (!child?.pid || killed) return;
+  killed = true;
+  try {
+    if (process.platform === 'win32') spawnSync('taskkill', ['/PID', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
+    else process.kill(-child.pid, 'SIGKILL');
+  } catch {}
+};
+process.once('exit', () => { kill(); close(); });
+for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP', ...(process.platform === 'win32' ? [] : ['SIGALRM'])]) {
+  process.once(signal, () => { kill(); process.exit(1); });
+}
+const marker = join(directory, 'published-input.json');
+const original = JSON.parse(await readFile(marker, 'utf8'));
+if (original.version !== 1 || original.service !== resolve(service) || original.release !== version) throw new Error('published input ownership differs');
+const receipt = async state => {
+  const temporary = `${marker}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, JSON.stringify({ ...original, owner: process.pid, state }) + '\n', { mode: 0o600 });
+    await rename(temporary, marker);
+  } finally { await rm(temporary, { force: true }); }
+};
+await receipt('installing');
+const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+child = spawn(npm, ['install', '--prefix', directory, '--install-strategy=nested', '--ignore-scripts', '--omit=dev', '--no-audit', '--no-fund', `@volter/supercode@${version}`],
+  { stdio: 'ignore', detached: process.platform !== 'win32', windowsHide: true, shell: process.platform === 'win32' });
+const timer = setTimeout(kill, 8000);
+const code = await new Promise(done => { child.once('error', () => done(1)); child.once('close', code => done(code ?? 1)); });
+clearTimeout(timer);
+child = null;
+await receipt(code === 0 ? 'complete' : 'failed');
+process.exitCode = code;

package/bin/workspace/release-state.mjs

@@ -0,0 +1,82 @@
+// Service-owned artifacts, serialized with release preparation. Never prune
+// mail originals, unknown directories, a pending writer or a referenced release.
+import { DatabaseSync } from 'node:sqlite';
+import { mkdir, readFile, readdir, rm } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+
+const json = async path => { try { return JSON.parse(await readFile(path, 'utf8')); } catch (error) { if (error.code === 'ENOENT') return null; throw error; } };
+const entries = async path => { try { return await readdir(path, { withFileTypes: true }); } catch (error) { if (error.code === 'ENOENT') return []; 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 !== 'ESRCH'; } };
+
+export async function releaseStateLease(service) {
+  await mkdir(service, { recursive: true, mode: 0o700 });
+  const owner = new DatabaseSync(join(service, 'release-state-owner.sqlite'));
+  try { owner.exec('PRAGMA busy_timeout = 0; BEGIN EXCLUSIVE'); }
+  catch (error) { owner.close(); throw new Error(`another release preparation owns this service: ${error.message}`); }
+  return () => owner.close();
+}
+
+// Caller holds releaseStateLease. An activation checkpoint is needed only
+// until readiness or restoration. Retain one completed failure for diagnosis;
+// unresolved failures remain untouched until explicit recovery.
+export async function pruneReleaseState(service, { pinned = null, activation = null } = {}) {
+  const history = await json(join(service, 'release-history.json'));
+  const active = await json(join(service, 'active-release.json'));
+  const keep = new Set([pinned, history?.candidate, history?.previous, history?.refused, active?.release]
+    .filter(Boolean).map(release => resolve(release.root)));
+  for (const item of await entries(join(service, 'releases'))) {
+    if (!item.isDirectory()) continue;
+    if (item.name.includes('.pending-')) {
+      const directory = join(service, 'releases', item.name), pending = await json(join(directory, 'pending-release.json'));
+      if (pending?.version === 1 && pending.service === resolve(service) && !alive(pending.owner)) await rm(directory, { recursive: true });
+      continue;
+    }
+    const directory = join(service, 'releases', item.name), receipt = await json(join(directory, 'retained-release.json'));
+    if (receipt?.version !== 3 || resolve(receipt.root) !== resolve(directory, 'package') || keep.has(resolve(receipt.root))) continue;
+    await rm(directory, { recursive: true });
+  }
+  // An npm child can outlive its installer. Its independent input lease,
+  // rather than the parent's service lease, protects both complete and partial
+  // input trees. Unknown old partial inputs remain untouched.
+  let inputsClose;
+  try { inputsClose = await releaseStateLease(join(service, 'published')); } catch {}
+  if (inputsClose) {
+    try {
+      for (const item of await entries(join(service, 'published'))) {
+        if (!item.isDirectory()) continue;
+        const directory = join(service, 'published', item.name);
+        const input = await json(join(directory, 'published-input.json'));
+        if (input?.version === 1 && input.service === resolve(service) && /^\d+\.\d+\.\d+$/.test(input.release) && !alive(input.owner)) {
+          await rm(directory, { recursive: true });
+        } else if (/^\d+\.\d+\.\d+$/.test(item.name)) {
+          const packageJson = await json(join(directory, 'node_modules', '@volter', 'supercode', 'package.json'));
+          if (packageJson?.name === '@volter/supercode' && packageJson.version === item.name) await rm(directory, { recursive: true });
+        }
+      }
+    } finally { inputsClose(); }
+  }
+  const failures = [];
+  for (const item of await entries(join(service, 'activations'))) {
+    if (!item.isDirectory()) continue;
+    const directory = join(service, 'activations', item.name);
+    if (resolve(directory) === activation) continue;
+    const receipt = await json(join(directory, 'receipt.json'));
+    if (!receipt) continue;
+    if (receipt.state === 'activated') await rm(directory, { recursive: true });
+    else if (receipt.restored === true) failures.push({ directory, at: receipt.at_ms });
+  }
+  failures.sort((a, b) => b.at - a.at);
+  for (const failure of failures.slice(activation ? 0 : 1)) await rm(failure.directory, { recursive: true });
+  for (const item of await entries(join(service, 'handoffs'))) {
+    if (!item.isFile() || !item.name.endsWith('.json')) continue;
+    const path = join(service, 'handoffs', item.name), receipt = await json(path);
+    if (Number.isSafeInteger(receipt?.supervisor) && Number.isSafeInteger(receipt.previous_pid) && !alive(receipt.supervisor)) await rm(path);
+  }
+}
+
+export async function cleanupReleaseState(service, options) {
+  let close;
+  try { close = await releaseStateLease(service); await pruneReleaseState(service, options); }
+  catch (error) { process.stderr.write(`supercode: service artifact cleanup deferred: ${error.message}\n`); }
+  finally { close?.(); }
+}

package/bin/workspace/retain-release.mjs

@@ -0,0 +1,186 @@
+// A service must not execute the replaceable npm tree. Retain the full release
+// and its dependencies, and retain the observed previous published version.
+import { createRequire } from 'node:module';
+import { copyFile, mkdir, readFile, readdir, readlink, realpath, rename, rm, symlink, writeFile } from 'node:fs/promises';
+import { constants, createReadStream, existsSync, readFileSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { releaseStateLease, pruneReleaseState } from './release-state.mjs';
+
+const json = async path => { try { return JSON.parse(await readFile(path, 'utf8')); } catch (error) { if (error.code === 'ENOENT') return null; throw error; } };
+const nativeName = process.platform === 'win32' ? 'supercode.exe' : 'supercode';
+const platformPackage = `@volter/supercode-cli-${process.platform}-${process.arch}`;
+
+async function copyEntries(entries, copy) {
+  let next = 0;
+  const workers = Array.from({ length: Math.min(32, entries.length) }, async () => {
+    while (next < entries.length) await copy(entries[next++]);
+  });
+  // Every copy must settle before cleanup or publication, including when one
+  // fails. A rejected copy cannot leave other writers racing the pending tree.
+  const outcomes = await Promise.allSettled(workers);
+  const failed = outcomes.find(outcome => outcome.status === 'rejected');
+  if (failed) throw failed.reason;
+}
+
+function releaseRoot(entry) {
+  for (let dir = dirname(entry); dirname(dir) !== dir; dir = dirname(dir)) {
+    try { if (JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).name === '@volter/supercode') return dir; } catch {}
+  }
+  throw new Error('retained connector installation requires a complete @volter/supercode release');
+}
+
+async function retain(root, native, service) {
+  root = await realpath(root);
+  native = await realpath(native);
+  const version = (await json(join(root, 'package.json'))).version;
+  // The complete dependency closure is immutable, including Node modules.
+  // A version or the native alone cannot distinguish changed daemon code.
+  const hash = createHash('sha256').update('retained-release-v3');
+  const links = [], directories = [''], files = [];
+  const fingerprint = async directory => {
+    const entries = (await readdir(directory, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
+    for (const item of entries) {
+      const path = join(directory, item.name);
+      hash.update(JSON.stringify([relative(root, path), item.isDirectory() ? 'directory' : item.isSymbolicLink() ? 'link' : 'file']));
+      if (item.isDirectory()) {
+        directories.push(relative(root, path));
+        await fingerprint(path);
+      }
+      else if (item.isSymbolicLink()) {
+        const link = await readlink(path), target = await realpath(resolve(dirname(path), link));
+        if (!target.startsWith(root + sep)) throw new Error('a retained release dependency links outside its complete installation');
+        const replacement = relative(dirname(path), target);
+        hash.update(JSON.stringify(replacement));
+        links.push({ path: relative(root, path), replacement });
+      } else if (item.isFile()) {
+        files.push(relative(root, path));
+        for await (const bytes of createReadStream(path)) hash.update(bytes);
+      } else throw new Error('a retained release contains a non-regular dependency');
+    }
+  };
+  await fingerprint(root);
+  const digest = hash.digest('hex').slice(0, 24);
+  const target = join(service, 'releases', `${version}-${digest}`);
+  const marker = join(target, 'retained-release.json');
+  const kept = await json(marker);
+  if (kept) return kept;
+  const temporary = `${target}.pending-${randomUUID()}`;
+  await mkdir(dirname(temporary), { recursive: true, mode: 0o700 });
+  try {
+    await mkdir(temporary, { mode: 0o700 });
+    await writeFile(join(temporary, 'pending-release.json'), JSON.stringify({ version: 1, service: resolve(service), owner: process.pid }) + '\n', { mode: 0o600 });
+    const packageRoot = join(temporary, 'package');
+    // fingerprint already enumerated and validated the complete closure.
+    // fs.cp repeated serial metadata/realpath/timestamp work for every file on
+    // first startup. Copy that manifest directly with bounded concurrency;
+    // clone where supported, falling back to an ordinary exact byte copy.
+    await copyEntries(directories, path => mkdir(join(packageRoot, path), { recursive: true, mode: 0o700 }));
+    await copyEntries(files, path => copyFile(join(root, path), join(packageRoot, path), constants.COPYFILE_FICLONE));
+    await copyEntries(links, link => symlink(link.replacement, join(packageRoot, link.path)));
+    // Give the retained release its own PATH front door. The native's stable
+    // command ownership check can then resolve this complete installation.
+    const launchers = join(temporary, 'package', 'bin');
+    if (process.platform === 'win32') {
+      const quote = value => value.replaceAll('%', '%%');
+      await writeFile(join(launchers, 'supercode.cmd'), `@"${quote(process.execPath)}" "${quote(join(target, 'package', 'bin', 'supercode.js'))}" %*\r\n`);
+    } else {
+      await rm(join(launchers, 'supercode'), { force: true });
+      await symlink('supercode.js', join(launchers, 'supercode'));
+    }
+    const sourceEntry = createRequire(join(root, 'package.json')).resolve('@volter/supercode-teams/bin');
+    if (!sourceEntry.startsWith(root + sep)) throw new Error('the daemon dependency is outside its complete release');
+    const entry = join(target, 'package', relative(root, sourceEntry));
+    const binary = join(target, 'package', relative(root, native));
+    if (relative(root, native).startsWith('..')) throw new Error('the native binary is outside its complete release');
+    const supportsReady = existsSync(join(dirname(sourceEntry), 'teams-supervised.mjs'));
+    const cli = existsSync(join(dirname(sourceEntry), 'teams-cli.mjs')) ? 'teams-cli.mjs' : 'teams-original.mjs';
+    if (supportsReady) {
+      const stagedEntry = join(temporary, 'package', relative(root, sourceEntry));
+      if (cli === 'teams-original.mjs' && !existsSync(join(dirname(sourceEntry), cli))) {
+        await rename(stagedEntry, join(dirname(stagedEntry), 'teams-original.mjs'));
+      }
+      // These imports belong to the generated bin entry, not this workspace
+      // module. Quote its paths as source values; keep the supervisor named
+      // beside this module so packed-file inspection still checks that asset.
+      const supervisor = new URL('./upgrade-supervisor.mjs', import.meta.url);
+      const supervisorImport = JSON.stringify(`./workspace/${supervisor.pathname.split('/').at(-1)}`);
+      const cliImport = JSON.stringify(`./${cli}`);
+      await writeFile(stagedEntry, `#!/usr/bin/env node\nconst args = process.argv.slice(2);\nconst verbs = args[0] === 'teams' ? args.slice(1) : args;\nif ((verbs[0] === 'connect' && !verbs.includes('--install') && !verbs.includes('--add-root')) || (verbs[0] === 'machine' && verbs[1] === 'start')) {\n  const { runRetainedConnector } = await import(${supervisorImport});\n  await runRetainedConnector(args);\n} else await import(${cliImport});\n`);
+    }
+    const receipt = { version: 3, release: version, root: join(target, 'package'),
+      entry: supportsReady ? join(dirname(entry), cli) : entry,
+      native: binary, supervised: entry, supports_ready: supportsReady };
+    await writeFile(join(temporary, 'retained-release.json'), JSON.stringify(receipt) + '\n', { mode: 0o600 });
+    try { await rename(temporary, target); } catch (error) { if (!['EEXIST', 'ENOTEMPTY'].includes(error.code)) throw error; }
+    return await json(marker);
+  } finally { await rm(temporary, { recursive: true, force: true }); }
+}
+
+async function published(version, service) {
+  if (!/^\d+\.\d+\.\d+$/.test(version)) throw new Error('the serving release version is unreadable; activation is deferred');
+  const inputs = join(service, 'published');
+  let prefix = join(inputs, version);
+  const releaseGuard = await releaseStateLease(inputs);
+  try {
+    if ((await json(join(prefix, 'node_modules', '@volter', 'supercode', 'package.json')))?.version !== version) {
+      prefix = null;
+      for (const name of await readdir(inputs)) {
+        if (!name.startsWith(`${version}.pending-`)) continue;
+        const directory = join(inputs, name), receipt = await json(join(directory, 'published-input.json'));
+        if (receipt?.version === 1 && receipt.service === resolve(service) && receipt.release === version && receipt.state === 'complete'
+          && (await json(join(directory, 'node_modules', '@volter', 'supercode', 'package.json')))?.version === version) { prefix = directory; break; }
+      }
+      if (!prefix) {
+        prefix = join(inputs, `${version}.pending-${randomUUID()}`);
+        await mkdir(prefix, { mode: 0o700 });
+        await writeFile(join(prefix, 'published-input.json'), JSON.stringify({ version: 1, service: resolve(service), release: version, owner: process.pid, state: 'prepared' }) + '\n', { mode: 0o600 });
+      }
+    }
+  } finally { releaseGuard(); }
+  const root = join(prefix, 'node_modules', '@volter', 'supercode');
+  if (!(await json(join(root, 'package.json')))?.version) {
+    await new Promise((done, reject) => {
+      const worker = fileURLToPath(new URL('./published-install.mjs', import.meta.url));
+      const child = spawn(process.execPath, [worker, service, prefix, version], { stdio: 'ignore', windowsHide: true });
+      child.once('error', reject);
+      child.once('close', code => code === 0 ? done() : reject(new Error(`previous published release could not be retained: input worker exited ${code}; ${prefix}`)));
+    });
+  }
+  if ((await json(join(root, 'package.json')))?.version !== version) throw new Error('the retained published version differs from the serving receipt');
+  const native = createRequire(join(root, 'package.json')).resolve(`${platformPackage}/bin/${nativeName}`);
+  return retain(root, native, service);
+}
+
+export async function prepareRetainedRelease({ teamsHome, native, entry = fileURLToPath(new URL('../teams.mjs', import.meta.url)), allowFetch = true }) {
+  const service = join(resolve(teamsHome), 'service');
+  const close = await releaseStateLease(service);
+  try {
+  const historyPath = join(service, 'release-history.json');
+  const history = await json(historyPath);
+  const active = await json(join(service, 'active-release.json'));
+  const running = await json(join(teamsHome, 'machine.json'));
+  let previous = active?.release ?? history?.previous ?? history?.candidate ?? null;
+  // TypeScript-only releases deliberately reuse an older native binary.
+  const observed = running?.release?.supercode ?? /^supercode (\d+\.\d+\.\d+)\b/.exec(running?.release?.native ?? '')?.[1];
+  const root = releaseRoot(entry);
+  const candidateVersion = (await json(join(root, 'package.json'))).version;
+  if (observed && observed !== candidateVersion && previous?.release !== observed) {
+    previous = history?.candidate?.release === observed ? history.candidate
+      : history?.previous?.release === observed ? history.previous : allowFetch ? await published(observed, service) : null;
+  }
+  if (allowFetch && running && !observed && !previous) throw new Error('the serving release has no retained version receipt; activation is deferred');
+  if (previous && previous.version !== 3) previous = allowFetch ? await published(previous.release, service) : null;
+  const candidate = await retain(root, native, service);
+  if (!candidate.supports_ready || !existsSync(candidate.supervised)) throw new Error('candidate has no retained startup supervisor');
+  if (previous?.native === candidate.native) previous = history?.previous ?? null;
+  await mkdir(service, { recursive: true, mode: 0o700 });
+  const temporary = `${historyPath}.${randomUUID()}.tmp`;
+  await writeFile(temporary, JSON.stringify({ version: 1, candidate, previous, ...(history?.refused ? { refused: history.refused } : {}) }) + '\n', { mode: 0o600 });
+  await rename(temporary, historyPath);
+  await pruneReleaseState(service, { pinned: candidate });
+  return { ...candidate, previous };
+  } finally { close(); }
+}

package/bin/workspace/upgrade-supervisor.mjs

@@ -0,0 +1,234 @@
+import { spawn } from 'node:child_process';
+import { connect } from 'node:net';
+import { mkdir, readFile, readdir, rename, rm, writeFile as writeNewFile } from 'node:fs/promises';
+import { delimiter, dirname, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { requireUpgradeAdmission } from '../../mail/upgrade-admission.mjs';
+import { checkpoint, restore } from '../../mail/upgrade-state.mjs';
+import { MailOwner } from '../../mail/sqlite.mjs';
+import { cleanupReleaseState } from './release-state.mjs';
+
+const writeFile = async (path, bytes, options) => {
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  try { await writeNewFile(temporary, bytes, options); await rename(temporary, path); }
+  finally { await rm(temporary, { force: true }); }
+};
+const json = async path => { try { return JSON.parse(await readFile(path, 'utf8')); } catch (error) { if (error.code === 'ENOENT') return null; throw error; } };
+const answers = socket => new Promise(done => {
+  if (typeof socket !== 'string') return done(false);
+  const probe = connect(socket), timer = setTimeout(() => { probe.destroy(); done(false); }, 200);
+  probe.once('connect', () => { clearTimeout(timer); probe.destroy(); done(true); });
+  probe.once('error', () => { clearTimeout(timer); done(false); });
+});
+
+export async function runRetainedConnector(args) {
+  const explicitHome = args.indexOf('--home');
+  const inlineHome = args.find(arg => arg.startsWith('--home='));
+  const defaultHome = process.env.SUPERCODE_HOME || join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'supercode');
+  const teamsHome = resolve(explicitHome >= 0 ? args[explicitHome + 1] : inlineHome ? inlineHome.slice(7) : process.env.SUPERCODE_TEAMS_HOME || join(defaultHome, 'teams'));
+  const home = dirname(teamsHome);
+  const readyFile = join(teamsHome, 'service', 'active-release.json');
+  let pinned = null;
+  for (let parent = dirname(fileURLToPath(import.meta.url)); dirname(parent) !== parent; parent = dirname(parent)) {
+    pinned = await json(join(parent, 'retained-release.json'));
+    if (pinned) break;
+  }
+  if (!pinned?.entry) throw new Error('connector supervisor is outside a retained complete release');
+  let history = await json(join(teamsHome, 'service', 'release-history.json'));
+  if (!history?.candidate?.entry) throw new Error('retained connector has no release-history receipt');
+  // Preparing a new release cannot change what an existing unit executes.
+  // A failed activation explicitly redirects only its own retained wrapper.
+  if (history.candidate.native !== pinned.native && history.refused?.native !== pinned.native) {
+    history = { ...history, candidate: pinned,
+      previous: history.previous?.native === pinned.native ? null : history.previous };
+  }
+  let active = await json(readyFile);
+  // Readiness commits a state floor. An older wrapper or stale history can
+  // never roll that state back on an ordinary service restart.
+  if (active?.release?.entry) {
+    if (history.candidate.native === active.release.native) history.previous = active.release;
+    else if (history.candidate.native !== pinned.native || history.previous?.native !== active.release.native) {
+      history = { ...history, candidate: active.release, previous: active.release };
+    }
+  }
+  const established = active?.release?.native === history.candidate.native;
+  const directory = join(teamsHome, 'service', 'activations', randomUUID());
+  let child = null, stopping = false;
+  const stop = () => { stopping = true; child?.kill('SIGTERM'); };
+  for (const signal of ['SIGINT', 'SIGTERM', ...(process.platform === 'win32' ? ['SIGBREAK'] : [])]) process.once(signal, stop);
+  const start = (release, activating = false, recovery = false) => {
+    const selectedArgs = [...args];
+    const nativeAt = selectedArgs.indexOf('--supercode');
+    if (nativeAt >= 0) selectedArgs[nativeAt + 1] = release.native;
+    const inlineNative = selectedArgs.findIndex(arg => arg.startsWith('--supercode='));
+    if (inlineNative >= 0) selectedArgs[inlineNative] = `--supercode=${release.native}`;
+    const env = { ...process.env };
+    delete env.SUPERCODE_UPGRADE_HANDOFF;
+    delete env.SUPERCODE_UPGRADE_OLD_PID;
+    child = spawn(process.execPath, [release.entry, ...selectedArgs], { stdio: 'inherit', env: { ...env,
+      SUPERCODE_BIN: release.native, SUPERCODE_TEAMS_ENTRY: release.entry,
+      SUPERCODE_RELEASE_VERSION: release.release,
+      SUPERCODE_UPGRADE_READY_FILE: readyFile,
+      SUPERCODE_UPGRADE_RELEASE_RECEIPT: JSON.stringify(release),
+      PATH: [join(release.root, 'bin'), process.env.PATH].filter(Boolean).join(delimiter),
+      SUPERCODE_UPGRADE_SUPERVISOR: String(process.pid),
+      SUPERCODE_UPGRADE_ACTIVATING: activating ? '1' : '',
+      SUPERCODE_MAIL_COMMITTED: release.native === active?.release?.native ? '1' : '',
+      SUPERCODE_MAIL_STARTUP_RECOVERY: !activating || recovery ? '1' : '' },
+      detached: process.platform !== 'win32', windowsHide: true });
+    return child;
+  };
+  const cleanupAfterServing = (daemon, release, activation = null) => {
+    void (async () => {
+      while (!stopping && daemon.exitCode === null && daemon.signalCode === null) {
+        const record = await json(join(teamsHome, 'machine.json'));
+        if (record?.pid === daemon.pid && (release.supports_ready ? record.mail_ready === true : await answers(record.socket))) {
+          await cleanupReleaseState(join(teamsHome, 'service'), { pinned, activation });
+          return;
+        }
+        await new Promise(done => setTimeout(done, 50));
+      }
+    })().catch(error => process.stderr.write(`supercode: post-start cleanup deferred: ${error.message}\n`));
+  };
+  if (process.env.SUPERCODE_UPGRADE_HANDOFF) {
+    const handoff = resolve(process.env.SUPERCODE_UPGRADE_HANDOFF), previousPid = Number(process.env.SUPERCODE_UPGRADE_OLD_PID);
+    if (dirname(handoff) !== resolve(teamsHome, 'service', 'handoffs') || !Number.isSafeInteger(previousPid) || previousPid <= 0) throw new Error('invalid upgrade handoff');
+    await mkdir(dirname(handoff), { recursive: true, mode: 0o700 });
+    await writeFile(handoff, JSON.stringify({ supervisor: process.pid, previous_pid: previousPid }) + '\n', { mode: 0o600 });
+    const deadline = Date.now() + 8000;
+    while (!stopping && Date.now() < deadline) {
+      const serving = await json(join(teamsHome, 'machine.json'));
+      if (!serving || !(await answers(serving.socket))) break;
+      if (serving.pid !== previousPid) throw new Error('upgrade handoff refused: another daemon took this home');
+      await new Promise(done => setTimeout(done, 25));
+    }
+    await rm(handoff, { force: true });
+  }
+  if (stopping) return;
+  const serving = await json(join(teamsHome, 'machine.json'));
+  if (serving && await answers(serving.socket)) throw new Error('another daemon already serves this home; startup state is untouched');
+  let owner;
+  for (let attempt = 0; !owner; attempt++) {
+    try { owner = new MailOwner(join(teamsHome, 'service', 'activation-owner.sqlite')); }
+    catch (error) { if (attempt >= 40) throw error; await new Promise(done => setTimeout(done, 50)); }
+  }
+  process.once('exit', () => owner.close());
+  // A stopped first activation never becomes an ordinary downgrade. A
+  // durable commit wins; otherwise its checkpoint restores the pre-start state
+  // before a later start can choose a release.
+  let unfinished = [];
+  try { unfinished = await readdir(join(teamsHome, 'service', 'activations')); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  for (const name of unfinished) {
+    const prior = join(teamsHome, 'service', 'activations', name);
+    const receipt = await json(join(prior, 'receipt.json'));
+    if (!['checking', 'prepared', 'starting'].includes(receipt?.state)) continue;
+    let running = false;
+    try { process.kill(receipt.owner, 0); running = true; } catch (error) { running = error.code !== 'ESRCH'; }
+    if (running) continue;
+    active = await json(readyFile);
+    if (active?.supervisor === receipt.owner || (active?.release && receipt.previous?.native !== active.release.native)) {
+      await writeFile(join(prior, 'receipt.json'), JSON.stringify({ ...receipt, state: 'activated', at_ms: Date.now() }) + '\n', { mode: 0o600 });
+      continue;
+    }
+    const before = await json(join(prior, 'before.json'));
+    if (before) await restore(home, prior, before, teamsHome);
+    await writeFile(join(prior, 'receipt.json'), JSON.stringify({ ...receipt, state: 'interrupted', restored: true, at_ms: Date.now() }) + '\n', { mode: 0o600 });
+  }
+  const recover = async (state, outcome, before = null) => {
+    await writeFile(join(directory, 'receipt.json'), JSON.stringify({ version: 1, state, outcome,
+      candidate: history.candidate, previous: history.previous, at_ms: Date.now() }) + '\n', { mode: 0o600 });
+    if (before) await restore(home, directory, before, teamsHome);
+    await writeFile(join(directory, 'receipt.json'), JSON.stringify({ version: 1, state, outcome, restored: true,
+      candidate: history.candidate, previous: history.previous, at_ms: Date.now() }) + '\n', { mode: 0o600 });
+    if (!history.previous?.entry) {
+      process.stderr.write('supercode: no predecessor is retained; serving this release with a private mail recovery view\n');
+      const daemon = start(history.candidate, false, true);
+      const result = await new Promise(done => { daemon.once('error', () => done(1)); daemon.once('exit', code => done(code ?? 1)); });
+      process.exitCode = stopping ? 0 : result;
+      return;
+    }
+    const historyPath = join(teamsHome, 'service', 'release-history.json');
+    if ((await json(historyPath))?.candidate?.native === history.candidate.native) {
+      const temporary = `${historyPath}.${randomUUID()}.tmp`;
+      await writeFile(temporary, JSON.stringify({ version: 1,
+        candidate: history.previous, previous: history.previous, refused: history.candidate, activation: directory }) + '\n', { mode: 0o600 });
+      await rename(temporary, historyPath);
+    }
+    process.stderr.write(`supercode: candidate ${state}; serving retained release ${history.previous.release}; evidence ${directory}\n`);
+    if (stopping) return;
+    const previous = start(history.previous);
+    cleanupAfterServing(previous, history.previous, resolve(directory));
+    const result = await new Promise(done => { previous.once('error', () => done(1)); previous.once('exit', code => done(code ?? 1)); });
+    process.exitCode = stopping ? 0 : result || 1;
+  };
+  if (established || !history.previous?.entry || history.candidate.native === history.previous.native) {
+    // No admission, checkpoint or first-activation deadline after commit.
+    // Native indexing is allowed to answer later while the same mail serves.
+    const daemon = start(history.candidate);
+    cleanupAfterServing(daemon, history.candidate);
+    const result = await new Promise(done => { daemon.once('error', () => done(1)); daemon.once('exit', code => done(code ?? 1)); });
+    process.exitCode = stopping ? 0 : result;
+    return;
+  }
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const journal = async state => writeFile(join(directory, 'receipt.json'), JSON.stringify({ version: 1, state,
+    owner: process.pid, candidate: history.candidate, previous: history.previous, at_ms: Date.now() }) + '\n', { mode: 0o600 });
+  await journal('checking');
+  try { await requireUpgradeAdmission({ home: teamsHome, entry: history.candidate.entry }); }
+  catch (error) { await recover('admission_refused', { error: error.message }); return; }
+  if (stopping) return;
+  const before = await checkpoint(home, directory);
+  await journal('prepared');
+  await journal('starting');
+  const candidate = start(history.candidate, true);
+  let finished = false, ready = false;
+  const exit = new Promise(done => {
+    candidate.once('error', error => { finished = true; done({ error: error.message }); });
+    candidate.once('exit', (code, signal) => { finished = true; done({ code, signal }); });
+  });
+  const deadline = Date.now() + 8000;
+  while (!stopping && !finished && Date.now() < deadline) {
+    const record = await json(join(teamsHome, 'machine.json'));
+    if (record?.pid === candidate.pid && await answers(record.socket)) {
+      // The daemon publishes mail_ready only after its afterListen work; a
+      // listening socket alone is not a serving mailbox.
+      const committed = await json(readyFile);
+      if (record.mail_ready === true && committed?.pid === candidate.pid && committed.supervisor === process.pid) { ready = true; break; }
+    }
+    await new Promise(done => setTimeout(done, 50));
+  }
+  if (stopping) {
+    await exit;
+    if ((await json(readyFile))?.pid !== candidate.pid) {
+      await restore(home, directory, before, teamsHome);
+      await writeFile(join(directory, 'receipt.json'), JSON.stringify({ version: 1, state: 'stopped_before_ready', restored: true, at_ms: Date.now() }) + '\n', { mode: 0o600 });
+    }
+    await cleanupReleaseState(join(teamsHome, 'service'), { pinned });
+    return;
+  }
+  if (ready) {
+    await writeFile(join(directory, 'receipt.json'), JSON.stringify({ version: 1, state: 'activated', candidate: history.candidate, at_ms: Date.now() }) + '\n', { mode: 0o600 });
+    await writeFile(join(teamsHome, 'service', 'last-activation.json'), JSON.stringify({ version: 1, state: 'activated', candidate: history.candidate, at_ms: Date.now() }) + '\n', { mode: 0o600 });
+    await cleanupReleaseState(join(teamsHome, 'service'), { pinned });
+    // No rollback of state a caller could have used. Its retained release is
+    // restarted by the service's normal lifecycle on a later process failure.
+    const outcome = await exit;
+    process.exitCode = stopping ? 0 : outcome.code || 1;
+    return;
+  }
+  {
+    // This group was created by this supervisor at spawn; it includes only
+    // this candidate's children, never foreign harness serves or panes.
+    try { process.platform === 'win32' ? candidate.kill('SIGKILL') : process.kill(-candidate.pid, 'SIGKILL'); } catch {}
+  }
+  const outcome = await exit;
+  if ((await json(readyFile))?.pid === candidate.pid) {
+    process.stderr.write('supercode: candidate committed mail readiness before exit; its state is retained for service restart\n');
+    process.exitCode = 1;
+    return;
+  }
+  await recover('startup_failed', outcome, before);
+}

package/bin/workspace/upgrade-watch.mjs

@@ -38,7 +38,7 @@ export function watchCodeChange(files, onChange) {
 
 /**
  * Move this connector to the upgraded code: run `cli` (the upgraded CLI's install, in a session of its own), then
- * leave `exit()` to run a minute on, for the service manager to restart this connector under what it installed. A CLI
+ * only on successful installer exit leave `exit()` to run a minute on, for the service manager to restart this connector under what it installed. A CLI
  * that cannot be run (absent: ENOENT, raised after spawn returns; not a whole executable: EBADMACHO, thrown by it)
  * moves nothing: the exit is not left, `resume()` watches on, and this connector keeps serving on its old code.
  */
@@ -48,8 +48,11 @@ export function moveToUpgrade(cli, args, options, { exit = null, resume, log })
   let child;
   try { child = spawn(cli, args, options); } catch (error) { failed(error); return; }
   child.once('error', failed);
+  child.once('exit', (code, signal) => {
+    if (code !== 0 || signal) { failed(new Error(`installer exited ${code ?? signal}`)); return; }
+    if (exit) left = setTimeout(exit, 60_000);
+  });
   child.unref();
-  if (exit) left = setTimeout(exit, 60_000);
 }
 
 const alive = (pid) => { try { process.kill(pid, 0); return true; } catch (error) { return error.code === 'EPERM'; } };

package/bin/workspace.mjs

@@ -25,6 +25,8 @@ import { loadOrCreateKeyPair, publicKeyId } from '@volter/teams/identity';
 import { duration, parseArgs, positiveInteger, requireArgs, usage } from './workspace/args.mjs';
 import { reserveArtifactDirectory, reserveProtected, writeProtected } from './workspace/files.mjs';
 import { acquireLifecycle, activeSocket, lifecycleHeld, requestStop } from './workspace/lifecycle.mjs';
+import { prepareRetainedRelease } from './workspace/retain-release.mjs';
+import { requireUpgradeAdmission } from '../mail/upgrade-admission.mjs';
 import { moveToUpgrade, retireLinklessDaemon, watchCodeChange } from './workspace/upgrade-watch.mjs';
 
 /** How long a service-run connector's machine link may stay down before the connector restarts itself. */
@@ -1108,20 +1110,22 @@ async function connectorCommand(verb, { flags, rest, output, client, context, te
     if (flags.install || (!flags.foreground && process.stdin.isTTY && process.stdout.isTTY)) {
       const serviceBin = process.env.SUPERCODE_BIN;
       if (!serviceBin) unsupported('--install requires invocation through the native supercode CLI');
-      const serviceEnv = { ...process.env, SUPERCODE_TEAMS_ENTRY: fileURLToPath(new URL('./teams.mjs', import.meta.url)) };
+      await requireUpgradeAdmission({ home: teamsHome() });
+      const retained = await prepareRetainedRelease({ teamsHome: teamsHome(), native: serviceBin,
+        entry: fileURLToPath(new URL('./teams.mjs', import.meta.url)) });
+      const serviceEnv = { ...process.env, SUPERCODE_TEAMS_ENTRY: retained.supervised };
       // Refuse source-backed installs before Windows stops the running connector.
       try {
-        execFileSync(serviceBin, ['__teams-connector-service', 'validate', contextName, servicePath, context.server_id, context.team_id], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], env: serviceEnv });
+        execFileSync(retained.native, ['__teams-connector-service', 'validate', contextName, servicePath, context.server_id, context.team_id], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], env: serviceEnv });
       } catch (error) {
         // In particular, an older native CLI may not have the validation door.
         // Its support-report child must not keep a refused Windows install alive.
         await core.close();
         throw error;
       }
-      // Ending a Windows task ends only the console host it started, never the connector under it, so the task
-      // would refuse its new run while the old connector went on: the running one is asked to stop first.
-      if (process.platform === 'win32') await stopRunningConnector(saved);
-      try { service = JSON.parse(execFileSync(serviceBin, ['__teams-connector-service', 'install', contextName, servicePath, context.server_id, context.team_id], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], env: serviceEnv })); }
+      // Installation performs candidate admission before changing the service.
+      // The previous Windows connector is stopped only after that succeeds.
+      try { service = JSON.parse(execFileSync(retained.native, ['__teams-connector-service', 'install', contextName, servicePath, context.server_id, context.team_id], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], env: serviceEnv })); }
       catch (error) {
         // A platform with no service manager still connects: here, for as long as this terminal runs it. Anything else is an error.
         if (flags.install || !/no service manager/.test(String(error.stderr ?? error.message))) { core.close(); throw error; }
@@ -1129,6 +1133,9 @@ async function connectorCommand(verb, { flags, rest, output, client, context, te
       }
     }
     if (service) {
+      // Native installation admits the candidate before changing the task. End
+      // the previous Windows process only after installation succeeds.
+      if (process.platform === 'win32') await stopRunningConnector(saved);
       saved = state.update(current => ({ ...current, service }));
       core.close();
       if (!flags.json) {
@@ -1257,6 +1264,12 @@ async function connectorCommand(verb, { flags, rest, output, client, context, te
     // It exits non-zero, which every service manager here restarts.
     // A service-run connector restarts on request through the machine's door: it exits non-zero, which every service
     // manager here restarts (the Windows task's minute trigger starts it whatever the exit).
+    if (saved.service) machine.restartAdmission = () => {
+      let committed = null;
+      try { committed = JSON.parse(readFileSync(join(daemonHome, 'service', 'active-release.json'), 'utf8')); } catch {}
+      if (committed?.release?.native === machine.supercodeBin) return;
+      return requireUpgradeAdmission({ home: daemonHome });
+    };
     if (saved.service) machine.restartHandler = (reason) => {
       process.stderr.write(`supercode teams: restart requested through the machine door${reason ? ` (${reason})` : ''}\n`);
       void (async () => { await stopConnector?.(); process.exit(75); })();