getbotons 0.0.0-stage → 0.1.0

package/payload/scripts/install-backup-timer.ts

@@ -0,0 +1,52 @@
+// `npm run backup:install [-- --app <dir> --dir <unit dir>]`: writes the nightly backup units. It enables nothing.
+import '../server/src/env-init.ts';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const repo = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+/** Writes botons-backup.service and botons-backup.timer (or `name`.*) into `unitDir`, running `app`'s backup with `node`. Returns their paths. */
+export function writeBackupUnits(o: { app: string; unitDir: string; name?: string; node?: string; log?: (line: string) => void }): string[] {
+  const name = o.name ?? 'botons-backup';
+  if (!/^[\w@.-]+$/.test(name)) throw new Error(`--name ${name}: use letters, digits and - _ . @ only`);
+  mkdirSync(o.unitDir, { recursive: true });
+  const out: string[] = [];
+  for (const [template, unit] of [['botons-backup.service', `${name}.service`], ['botons-backup.timer', `${name}.timer`]]) {
+    const text = readFileSync(join(repo, 'scripts', template), 'utf8')
+      .replaceAll('@NODE@', o.node ?? process.execPath)
+      .replaceAll('@REPO@', o.app)
+      .replaceAll('@TIMER@', `${name}.timer`)
+      .replaceAll('@SERVICE@', `${name}.service`);
+    writeFileSync(join(o.unitDir, unit), text);
+    (o.log ?? console.log)(`Wrote ${join(o.unitDir, unit)}`);
+    out.push(join(o.unitDir, unit));
+  }
+  return out;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const arg = (name: string) => {
+    const at = process.argv.indexOf(name);
+    return at > 0 && process.argv[at + 1] ? process.argv[at + 1] : null;
+  };
+  const dir = resolve(arg('--dir') ?? join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'systemd', 'user'));
+  const name = arg('--name') ?? 'botons-backup';
+  try {
+    writeBackupUnits({ app: resolve(arg('--app') ?? repo), unitDir: dir, name });
+  } catch (err) {
+    console.error((err as Error).message);
+    process.exit(1);
+  }
+  if (!process.argv.includes('--quiet')) console.log(`
+Turn on the nightly backup (03:30, or at the next boot if that was missed):
+  systemctl --user daemon-reload
+  systemctl --user enable --now ${name}.timer
+
+Check it:
+  systemctl --user list-timers ${name}.timer
+  systemctl --user start ${name}.service && journalctl --user -u ${name}.service -n 20
+
+Run this again after moving the app folder or changing the Node version.`);
+}

package/payload/scripts/install-service.ts

@@ -0,0 +1,206 @@
+// `npm run service:install [-- --app <dir> --name <name> --dir <unit dir> --env-path <file>]`: writes the
+// systemd user unit, and the environment file if there is none. It starts nothing.
+import '../server/src/env-init.ts';
+import { accessSync, constants, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, dirname, isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CONFIG_DIRS, UNITS, applyLegacyEnv } from '../shared/legacy-names.mjs';
+import { DEFAULT_DRAIN_MS, isBotonsSetting, parseDuration } from '../server/src/config.ts';
+
+const repo = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const configHome = () => process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
+
+/** The service's environment file, unless --env-path names another: ~/.config/botons/env, or a deprecated one until the upgrade moves it (server/src/legacy-upgrade.ts). */
+export function defaultEnvPath(): string {
+  const now = join(configHome(), 'botons', 'env');
+  return existsSync(now) ? now : (CONFIG_DIRS.map((d) => join(configHome(), d, 'env')).find((p) => existsSync(p)) ?? now);
+}
+
+export const unitDirDefault = () => join(configHome(), 'systemd', 'user');
+
+/** The server's unit: botons, or the deprecated unit an install still runs under until the upgrade moves it (server/src/legacy-upgrade.ts). */
+export function defaultUnitName(unitDir = unitDirDefault()): string {
+  if (existsSync(join(unitDir, 'botons.service'))) return 'botons';
+  return UNITS.find((u) => existsSync(join(unitDir, `${u.service}.service`)))?.service ?? 'botons';
+}
+
+/** systemd expands % specifiers in unit settings; a literal % is %%. */
+const escapeUnit = (s: string) => s.replaceAll('%', '%%');
+
+const quoteEnv = (v: string) => (/^[\w@%+=:,./-]*$/.test(v) ? v : `"${v.replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`);
+
+/** The first executable `cmd` on `path`, or `cmd` itself when it is a path. */
+function which(cmd: string, path: string): string | null {
+  const executable = (file: string) => {
+    try {
+      accessSync(file, constants.X_OK);
+      return statSync(file).isFile();
+    } catch {
+      return false;
+    }
+  };
+  if (cmd.includes('/')) return executable(resolve(cmd)) ? resolve(cmd) : null;
+  for (const dir of path.split(delimiter)) {
+    if (dir && isAbsolute(dir) && executable(join(dir, cmd))) return join(dir, cmd);
+  }
+  return null;
+}
+
+/** KEY=value pairs of an environment file (comments and blank lines skipped, quotes removed). */
+export function readEnvFile(text: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const raw of text.split('\n')) {
+    const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/.exec(raw);
+    if (!m) continue;
+    let v = m[2];
+    if (/^".*"$/.test(v)) v = v.slice(1, -1).replace(/\\(["\\])/g, '$1');
+    else if (/^'.*'$/.test(v)) v = v.slice(1, -1);
+    out[m[1]] = v;
+  }
+  return out;
+}
+
+/**
+ * The environment a server-side script acts with. BOTONS_HOME set means "this server"; otherwise the BOTONS_* and
+ * PORT (and PATH, for finding the CLIs) of the service's env file win, as for deploy and backup. Throws only when a
+ * file named by `named` can't be read.
+ */
+export function serverEnv(named: string | undefined, base: NodeJS.ProcessEnv = process.env): { env: NodeJS.ProcessEnv; from: string | null } {
+  if (base.BOTONS_HOME?.trim()) return { env: base, from: null };
+  const envPath = resolve(named ?? defaultEnvPath());
+  let file: Record<string, string>;
+  try {
+    file = readEnvFile(readFileSync(envPath, 'utf8'));
+  } catch {
+    if (named !== undefined) throw new Error(`Cannot read ${envPath}.`);
+    return { env: base, from: null };
+  }
+  applyLegacyEnv(file);
+  const env: NodeJS.ProcessEnv = { ...base };
+  for (const [k, v] of Object.entries(file)) if (isBotonsSetting(k) || k === 'PORT' || k === 'PATH' || k === 'DISABLE_AUTOUPDATER' || k === 'DISABLE_UPDATES') env[k] = v;
+  applyLegacyEnv(env);
+  return { env, from: envPath };
+}
+
+function arg(name: string): string | null {
+  const at = process.argv.indexOf(name);
+  return at > 0 && process.argv[at + 1] ? process.argv[at + 1] : null;
+}
+
+export interface ServiceUnitOptions {
+  /** The unit's name, without .service. */
+  name: string;
+  /** The Botons folder the unit runs. */
+  app: string;
+  envPath: string;
+  unitDir: string;
+  /** The Node binary (default: this one). */
+  node?: string;
+  /** The user's home, for writing the default env file's path as %h (default: this user's). */
+  userHome?: string;
+  log?: (line: string) => void;
+}
+
+/** Writes the environment file if there is none, then the unit (both starting nothing). Returns the unit file's path. */
+export function writeServiceUnit(o: ServiceUnitOptions): string {
+  const { name, app, envPath, unitDir } = o;
+  const log = o.log ?? ((line: string) => console.log(line));
+  if (!/^[\w@.-]+$/.test(name)) throw new Error(`--name ${name}: use letters, digits and - _ . @ only`);
+  // %h when it is the default file, which the backup unit reads too.
+  const envInUnit = envPath === join(o.userHome ?? homedir(), '.config', 'botons', 'env') ? '%h/.config/botons/env' : escapeUnit(envPath);
+  const node = o.node ?? process.execPath;
+
+  if (!existsSync(join(app, 'server', 'src', 'index.ts'))) throw new Error(`${app} has no server/src/index.ts; pass --app <the Botons folder>`);
+
+  if (!existsSync(envPath)) {
+    const path = process.env.PATH ?? '';
+    const claude = which(process.env.BOTONS_CLAUDE_BIN || 'claude', path);
+    const codex = which(process.env.BOTONS_CODEX_BIN || 'codex', path);
+    // node's and the CLIs' folders, the shell's PATH without what npm adds for scripts, then the system folders.
+    const npmAdded = (d: string) => /[/\\]node_modules[/\\]|[/\\]node_modules$|node-gyp-bin/.test(d);
+    const dirs = [dirname(node), ...[claude, codex].flatMap((p) => (p ? [dirname(p)] : [])), ...path.split(delimiter).filter((d) => !npmAdded(d)), '/usr/local/bin', '/usr/bin', '/bin'];
+    const servicePath = [...new Set(dirs.filter((d) => d && isAbsolute(d)))].join(delimiter);
+    const line = (k: string, v: string | null, what: string) => (v ? `${k}=${quoteEnv(v)}` : `# ${k}=/path/to/${what}   (not found on PATH when this file was written)`);
+    mkdirSync(dirname(envPath), { recursive: true, mode: 0o700 });
+    writeFileSync(
+      envPath,
+      `# Environment for the Botons server (${name}.service) and its nightly backup.
+# Written by \`npm run service:install\`; edit freely,
+# then: systemctl --user restart ${name}
+#
+# systemd does not read your shell profile, so PATH must name every folder the
+# server and your Botons need: node, the claude and codex CLIs, and the tools
+# Botons run (git, gh, ...).
+PATH=${quoteEnv(servicePath)}
+${line('BOTONS_CLAUDE_BIN', claude, 'claude')}
+${line('BOTONS_CODEX_BIN', codex, 'codex')}
+#
+# Other settings (see "Configuration" in the README), for example:
+# BOTONS_HOME=/home/you/.botons
+# BOTONS_PORT=7777
+# BOTONS_PUBLIC_URL=http://yourhost.your-tailnet.ts.net:7777
+`,
+      { mode: 0o600 },
+    );
+    log(`Wrote ${envPath}`);
+    if (!claude || !codex) log(`  ${[!claude && 'claude', !codex && 'codex'].filter(Boolean).join(' and ')} not found on PATH: set the path in that file if you use it.`);
+  } else {
+    const env = readEnvFile(readFileSync(envPath, 'utf8'));
+    applyLegacyEnv(env);
+    const missing = ['PATH', 'BOTONS_CLAUDE_BIN', 'BOTONS_CODEX_BIN'].filter((k) => !env[k]);
+    log(`Kept ${envPath}${missing.length ? ` (it does not set ${missing.join(', ')}; the service needs PATH to find node's tools and the CLIs)` : ''}`);
+  }
+  // The stop timeout is the drain budget plus 30s to stop the agents and close.
+  const fileEnv = readEnvFile(readFileSync(envPath, 'utf8'));
+  applyLegacyEnv(fileEnv);
+  const drainMs = parseDuration(fileEnv.BOTONS_DRAIN_MS ?? '');
+  const stopTimeoutSec = Math.ceil((Number.isNaN(drainMs) ? DEFAULT_DRAIN_MS : drainMs) / 1000) + 30;
+
+  mkdirSync(unitDir, { recursive: true });
+  const unitFile = join(unitDir, `${name}.service`);
+  const unit = readFileSync(join(repo, 'scripts', 'botons.service'), 'utf8')
+    .replaceAll('@DESCRIPTION@', name === 'botons' ? 'Botons server' : `Botons server (${name})`)
+    .replaceAll('@APP@', escapeUnit(app))
+    .replaceAll('@NODE@', escapeUnit(node))
+    .replaceAll('@ENV_FILE@', envInUnit)
+    .replaceAll('@STOP_TIMEOUT@', String(stopTimeoutSec))
+    .replaceAll('@NAME@', name);
+  writeFileSync(unitFile, unit);
+  log(`Wrote ${unitFile}`);
+  return unitFile;
+}
+
+function main() {
+  const unitDir = resolve(arg('--dir') ?? unitDirDefault());
+  const name = arg('--name') ?? 'botons';
+  if (!arg('--name') && defaultUnitName(unitDir) !== 'botons') {
+    throw new Error(`This install's service still runs under a deprecated name (${defaultUnitName(unitDir)}.service). Run \`npm run migrate:names\` first: it moves it to botons.service. Nothing was changed.`);
+  }
+  const app = resolve(arg('--app') ?? repo);
+  const envPath = resolve(arg('--env-path') ?? defaultEnvPath());
+  writeServiceUnit({ name, app, envPath, unitDir });
+  if (process.argv.includes('--quiet')) return;
+  console.log(`  runs ${process.execPath} ${join(app, 'server/src/index.ts')}
+
+Start it now and at every boot (stop any other Botons server on the same data
+folder first):
+  systemctl --user daemon-reload
+  systemctl --user enable --now ${name}
+
+Check it:
+  systemctl --user status ${name}
+  journalctl --user -u ${name} -f
+
+Run this again after moving the app folder, changing the Node version or
+changing BOTONS_DRAIN_MS (the unit's stop timeout follows it).`);
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    main();
+  } catch (err) {
+    console.error((err as Error).message);
+    process.exit(1);
+  }
+}

package/payload/scripts/login.ts

@@ -0,0 +1,17 @@
+import '../server/src/env-init.ts';
+import { spawnSync } from 'node:child_process';
+import { loadConfig } from '../server/src/config.ts';
+import { cliHomesEnv, prepareCliHomes } from '../server/src/cli-homes.ts';
+import { agentEnv } from '../server/src/providers/process.ts';
+const kind = process.argv[2];
+if (kind !== 'codex' && kind !== 'claude') {
+  console.error('Usage: botons login codex | botons login claude');
+  process.exitCode = 2;
+} else {
+  const cfg = loadConfig();
+  prepareCliHomes();
+  const result = spawnSync(kind === 'codex' ? cfg.codexBin : cfg.claudeBin,
+    kind === 'codex' ? ['login', '--device-auth'] : ['auth', 'login'],
+    { env: { ...agentEnv({}), ...cliHomesEnv(process.env, true) }, stdio: 'inherit' });
+  process.exitCode = result.status ?? 1;
+}

package/payload/scripts/migrate-names.ts

@@ -0,0 +1,47 @@
+// `npm run migrate:names [-- --rollback | --no-start | --undo]`: moves an install off deprecated names (see
+// server/src/legacy-upgrade.ts and shared/legacy-names.mjs). Part of the legacy-names module: it goes with it.
+import '../server/src/env-init.ts';
+import { spawnSync } from 'node:child_process';
+import { ConfigError } from '../server/src/config.ts';
+import { NameUpgradeError, rollbackNames, undoService, upgradeDataFolder, upgradeService } from '../server/src/legacy-upgrade.ts';
+import { DataDirInUseError } from '../server/src/lock.ts';
+
+const USAGE = `Usage: npm run migrate:names [-- --rollback]
+
+Moves an install whose data folder, settings file, service or database still
+have a deprecated name to the current ones: it stops the service, backs the
+data up, moves the folders (leaving a link at each earlier path), writes
+~/.config/botons/env with each setting under its current name, and starts
+botons.service in place of the earlier unit, which it disables. Running it
+again finishes what is missing and changes nothing else. The server and
+\`npm run deploy\` do the same by themselves; this is for doing it now.
+
+--rollback undoes it: the earlier unit, folders and database name come back,
+and it names the backup taken first.`;
+
+const exec = async (cmd: string, args: string[]) => {
+  const r = spawnSync(cmd, args, { stdio: 'inherit' });
+  if (r.error) throw r.error;
+  if (r.status !== 0) throw new Error(`${cmd} ${args.join(' ')} exited ${r.status}`);
+};
+const log = (line: string) => console.log(line);
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.includes('--help') || args.includes('-h')) return console.log(USAGE);
+  if (args.includes('--rollback')) return void (await rollbackNames({ exec, log }));
+  // The installer's own: --no-start leaves starting botons.service to it, and --undo puts the earlier unit back if that fails.
+  if (args.includes('--undo')) return undoService({ exec, log });
+  const done = await upgradeService({ exec, log, start: !args.includes('--no-start') });
+  if (done.nothing) {
+    const data = upgradeDataFolder({ log, explicit: true });
+    if (!data.moved && !data.db) log('Nothing has a deprecated name: nothing to do.');
+  }
+}
+
+main().catch((err) => {
+  if (err instanceof ConfigError) console.error(err.errors.join('\n'));
+  else if (err instanceof NameUpgradeError || err instanceof DataDirInUseError) console.error(err.message);
+  else console.error(err);
+  process.exit(1);
+});

package/payload/scripts/pair.ts

@@ -0,0 +1,163 @@
+import '../server/src/env-init.ts';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { parseArgs } from 'node:util';
+import type { AccessMode } from '../shared/types.ts';
+import { type AuditEntry, HOST_ACTOR, recordAudit } from '../server/src/audit.ts';
+import { approvePairingRequest, deleteAllDevices, deleteDevice, listDevices, pendingPairingRequests } from '../server/src/auth.ts';
+import { type Config, loadConfig, botonsHome } from '../server/src/config.ts';
+import { ACCESS_MODES, accessModeProblem, approveCommand, isAccessMode, readAccessMode, writeAccessMode } from '../server/src/setup.ts';
+import { dbFileIn } from '../server/src/backup.ts';
+import { serverEnv } from './install-service.ts';
+
+const USAGE = `Usage:
+  npm run pair                          how to pair a device, and the requests waiting now
+  npm run pair -- --approve <code>      approve the device that shows this code (it signs in at once)
+  npm run pair -- --approve <code> --label "Work iPad"
+                                        the same, and name the device
+  npm run pair -- --list                list paired devices
+  npm run pair -- --revoke <id>         revoke one device
+  npm run pair -- --revoke-all          revoke every device
+  npm run pair -- --access-mode <mode>  which networks may connect: local, tailscale, lan, public,
+                                        or none (only the listeners decide); takes effect at once
+
+To pair a device, open Botons on it: it shows a code. Approve only a code you
+are reading off the screen of the device you want to pair. A Boton can ask to
+pair too, so never approve a code that reached you in a chat or a message.
+
+Uses the data folder in BOTONS_HOME if it is set; otherwise the one the
+service's environment file sets (--env-path, default ~/.config/botons/env);
+otherwise ~/.botons.`;
+
+function fail(message: string, code = 1): never {
+  console.error(message);
+  process.exit(code);
+}
+
+let args;
+try {
+  args = parseArgs({
+    allowPositionals: false,
+    options: {
+      label: { type: 'string' },
+      approve: { type: 'string' },
+      list: { type: 'boolean' },
+      revoke: { type: 'string' },
+      'revoke-all': { type: 'boolean' },
+      'access-mode': { type: 'string' },
+      'env-path': { type: 'string' },
+      help: { type: 'boolean', short: 'h' },
+    },
+  }).values;
+} catch (err) {
+  fail(`${(err as Error).message}\n\n${USAGE}`, 2);
+}
+if (args.help) {
+  console.log(USAGE);
+  process.exit(0);
+}
+
+let env: NodeJS.ProcessEnv;
+let from: string | null;
+try {
+  ({ env, from } = serverEnv(args['env-path']));
+} catch (err) {
+  fail((err as Error).message);
+}
+
+let home: string;
+try {
+  home = botonsHome(env);
+} catch (err) {
+  fail((err as Error).message);
+}
+const dbPath = dbFileIn(home);
+if (!existsSync(dbPath)) {
+  fail(
+    `There is no Botons database at ${dbPath}${from ? ` (BOTONS_HOME as ${from} sets it, or the default)` : ''}. Start the server once (it creates it), or set BOTONS_HOME to the data folder it uses.`,
+  );
+}
+const db = new DatabaseSync(dbPath);
+db.exec('pragma busy_timeout = 5000; pragma foreign_keys = on;');
+
+const when = (iso: string | null) => (iso ? new Date(iso).toLocaleString() : 'never');
+// Someone at this machine, with the data folder: the owner. A database the server hasn't upgraded yet has no audit log.
+const audit = (entry: AuditEntry) => {
+  if (db.prepare("select 1 from sqlite_master where type = 'table' and name = 'audit_events'").get()) recordAudit(db, HOST_ACTOR, entry);
+};
+const hasRequests = () => !!db.prepare("select 1 from sqlite_master where type = 'table' and name = 'pairing_requests'").get();
+const config = (): Config | null => {
+  try {
+    return loadConfig(env, undefined, { create: false });
+  } catch (err) {
+    console.warn(`(Could not read the server's settings: ${(err as Error).message})`);
+    return null;
+  }
+};
+
+try {
+  if (args.list) {
+    const devices = listDevices(db);
+    if (!devices.length) console.log('No paired devices. Open Botons on a device and approve the code it shows with `npm run pair -- --approve <code>`.');
+    for (const d of devices) console.log(`${d.id}  ${d.label}  (paired ${when(d.createdAt)}, last used ${when(d.lastUsedAt)})`);
+  } else if (args['access-mode'] !== undefined) {
+    const raw = args['access-mode'].trim().toLowerCase();
+    const to: AccessMode | null = raw === 'none' ? null : isAccessMode(raw) ? raw : fail(`--access-mode must be one of ${ACCESS_MODES.join(', ')} or none; got "${raw}"`, 2);
+    const cfg = to === 'lan' || to === 'public' ? config() : null;
+    if (to === 'lan' || to === 'public') {
+      if (!cfg) fail(`Fix the server's settings before choosing ${to}.`);
+      const problem = accessModeProblem(to, cfg);
+      if (problem) fail(problem);
+    }
+    const from = readAccessMode(db);
+    writeAccessMode(db, to);
+    if (from !== to) audit({ action: 'access_mode.changed', details: { from, to } });
+    console.log(to === null ? 'No access mode: only the listeners (BOTONS_HOST, the published port) decide who connects.' : `Access mode: ${to}. A running server applies it to its next request.`);
+  } else if (args.revoke !== undefined) {
+    const device = listDevices(db).find((d) => d.id === args.revoke);
+    if (!device || !deleteDevice(db, device.id)) fail(`No paired device with id ${args.revoke}. \`npm run pair -- --list\` shows them.`);
+    audit({ action: 'device.revoked', target: { kind: 'device', id: device.id, label: device.label } });
+    console.log(`Revoked ${device.id} (${device.label}). Its next request is refused, and an open web app on it is signed out within half a minute.`);
+  } else if (args['revoke-all']) {
+    const n = deleteAllDevices(db);
+    audit({ action: 'devices.revoked_all', details: { count: n } });
+    console.log(`Revoked ${n} device${n === 1 ? '' : 's'}. To pair one again, open Botons on it and approve the code it shows with \`npm run pair -- --approve <code>\`.`);
+  } else if (args.approve !== undefined) {
+    if (!hasRequests()) fail('This database has no pairing requests yet: start the server once (it upgrades the database), then open Botons on the device.');
+    const approved = approvePairingRequest(db, args.approve, args.label ?? '');
+    if (!approved) {
+      fail(
+        'No device is waiting with that code. Check it against the device\'s screen: a code lasts 15 minutes, works once, and belongs to the Botons server with its data in ' +
+          `${home}.`,
+      );
+    }
+    audit({ action: 'pairing_request.approved', details: { label: approved.label, requestedAt: approved.createdAt } });
+    console.log(`Approved "${approved.label}" (asked ${when(approved.createdAt)}). It signs in within a few seconds.`);
+  } else {
+    if (args.label !== undefined) fail('--label names the device you approve: use it with --approve <code>.', 2);
+    // Only for the URLs to show: a bad setting elsewhere must not stop you getting back in.
+    let urls: string[] = [];
+    try {
+      const cfg = loadConfig(env, undefined, { create: false });
+      // BOTONS_PUBLIC_URL first: in a container or behind a proxy it is the only address a device can open.
+      urls = [...new Set([cfg.publicUrl, ...cfg.urls])];
+    } catch (err) {
+      console.warn(`(Not listing the server's URLs: ${(err as Error).message})`);
+    }
+    console.log(`\n  To pair a device with the Botons server whose data is in ${home}:`);
+    console.log('  1. Open Botons on that device. It shows a code:');
+    for (const u of urls) console.log(`       ${u}`);
+    console.log(`  2. Approve that code here:  ${approveCommand({ container: env.BOTONS_CONTAINER === '1' })}`);
+    console.log('\n  Approve only a code you read off the screen of the device you are pairing. A Boton');
+    console.log('  can ask to pair too, so never approve a code that reached you in a chat or a message.\n');
+    const waiting = hasRequests() ? pendingPairingRequests(db).filter((r) => !r.approved) : [];
+    if (waiting.length) {
+      console.log(`  Waiting now (newest last; codes show only on the devices):`);
+      for (const r of waiting) console.log(`    ${r.label || 'Unnamed device'}  (asked ${when(r.createdAt)})`);
+      console.log('');
+    }
+  }
+} finally {
+  db.close();
+}

package/payload/scripts/restore.ts

@@ -0,0 +1,108 @@
+// `npm run restore -- <backup> [--yes]`: put a backup made by `npm run backup` back into BOTONS_HOME.
+// The server must be stopped. Nothing is deleted: the current database and folders move to before-restore-<time>/.
+// BOTONS_HOME may not exist yet (a new machine): it is created, private, with --yes.
+import '../server/src/env-init.ts';
+import { accessSync, constants, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { userInfo } from 'node:os';
+import { dirname, join } from 'node:path';
+import { parseArgs } from 'node:util';
+import { listBackups, planRestore, restore } from '../server/src/backup.ts';
+import { botonsHome } from '../server/src/config.ts';
+import { DataDirInUseError, lockDataDir } from '../server/src/lock.ts';
+import { SCHEMA_VERSION } from '../server/src/schema.ts';
+import { defaultUnitName, serverEnv } from './install-service.ts';
+
+const USAGE = `Usage:
+  npm run restore -- --list              list the backups in BOTONS_HOME/backups, oldest first
+  npm run restore -- <backup>            show what restoring <backup> would do (changes nothing)
+  npm run restore -- <backup> --yes      restore it (the server must be stopped)
+
+<backup> is a folder name from --list, "latest", or the path of a backup folder.
+Uses the data folder in BOTONS_HOME if it is set; otherwise the one the
+service's environment file sets (--env-path, default ~/.config/botons/env);
+otherwise ~/.botons. In Docker, see docs/DOCKER.md.`;
+
+function fail(message: string, code = 1): never {
+  console.error(message);
+  process.exit(code);
+}
+
+let parsed;
+try {
+  parsed = parseArgs({ allowPositionals: true, options: { yes: { type: 'boolean' }, list: { type: 'boolean' }, 'env-path': { type: 'string' }, help: { type: 'boolean', short: 'h' } } });
+} catch (err) {
+  fail(`${(err as Error).message}\n\n${USAGE}`, 2);
+}
+const { values: args, positionals } = parsed;
+if (args.help) {
+  console.log(USAGE);
+  process.exit(0);
+}
+
+let home: string;
+try {
+  home = botonsHome(serverEnv(args['env-path']).env);
+} catch (err) {
+  fail((err as Error).message);
+}
+if (args.list) {
+  const names = listBackups(join(home, 'backups'));
+  if (!names.length) console.log(`No backups in ${join(home, 'backups')}. \`npm run backup\` makes one.`);
+  for (const n of names) {
+    let about = '';
+    try {
+      const m = JSON.parse(readFileSync(join(home, 'backups', n, 'manifest.json'), 'utf8'));
+      about = `  schema v${m.schemaVersion}${m.workspaces ? ', workspaces' : ', database only'}`;
+    } catch {}
+    console.log(`${n}${about}`);
+  }
+  process.exit(0);
+}
+if (positionals.length !== 1) fail(USAGE, 2);
+
+let plan;
+try {
+  plan = planRestore({ home, backup: positionals[0], maxSchema: SCHEMA_VERSION });
+} catch (err) {
+  fail(`Cannot restore: ${(err as Error).message}`);
+}
+const fresh = !existsSync(home);
+console.log(`Restore ${plan.from}
+  into     ${home}${fresh ? ' (it does not exist yet: created, private)' : ''}
+  database schema v${plan.schemaVersion}${plan.schemaVersion < SCHEMA_VERSION ? ` (the server upgrades it to v${SCHEMA_VERSION} at its next start)` : ''}
+  ${plan.workspaces ? 'workspaces, shared, templates and browser profiles from workspaces.tar.gz' : 'no workspaces.tar.gz: the database only; the folders now in place are set aside too'}
+  moves    ${plan.moves.length ? `${plan.moves.join(', ')} to ${plan.setAside}` : 'nothing: the data folder is empty'}`);
+
+// The data folder, or the nearest folder it would be created in, must be writable by this user: say so before anything moves.
+let writable = home;
+while (!existsSync(writable) && dirname(writable) !== writable) writable = dirname(writable);
+try {
+  accessSync(writable, constants.W_OK | constants.X_OK);
+} catch {
+  fail(
+    `\nCannot restore: ${writable} is not writable by this user (${userInfo().username}). Nothing was changed. Run the restore as the user that owns the data folder (the one the server runs as), or give that user write access to it (for example chmod u+rwx ${writable}), then run it again.`,
+  );
+}
+if (!args.yes) {
+  console.log('\nNothing was changed. Stop the server, then run this again with --yes.');
+  process.exit(0);
+}
+
+let lock: ReturnType<typeof lockDataDir> | undefined;
+try {
+  if (fresh) mkdirSync(home, { recursive: true, mode: 0o700 });
+  lock = lockDataDir(home);
+  restore(home, plan);
+} catch (err) {
+  lock?.release();
+  if (err instanceof DataDirInUseError) fail(`${err.message.replace('Nothing was changed.', '')}Stop the server first (systemctl --user stop ${defaultUnitName()}, or docker compose stop botons). Nothing was changed.`);
+  const message = (err as Error).message;
+  const next = /No space left on device|ENOSPC/.test(message)
+    ? `\nFree space on the disk that holds ${home} (df -h ${home}), or restore onto a larger disk, then run this again.`
+    : /Permission denied|EACCES|EPERM/.test(message)
+      ? `\nGive the user running this (${userInfo().username}) write access to everything in ${home}, or run it as the user that owns it, then run this again.`
+      : '';
+  fail(`${message}${next}`);
+}
+lock.release();
+console.log(`\nRestored.${plan.moves.length ? ` The previous state is in ${plan.setAside} (delete it once you are happy).` : ''} Start the server again.`);

package/payload/server/bin/botons

@@ -0,0 +1,4 @@
+#!/bin/sh
+# BOTONS_NODE is the server's Node, so this works where node is not on PATH (as under systemd).
+here="$(cd "$(dirname "$0")" && pwd)"
+exec "${BOTONS_NODE:-node}" --no-warnings "$here/../src/cli/botons.ts" "$@"

package/payload/server/bin/legacy/minion

@@ -0,0 +1,4 @@
+#!/bin/sh
+# LEGACY NAMES (see shared/legacy-names.mjs): a deprecated name of `botons`, on a turn's PATH for one release so
+# agents' saved scripts and instructions keep working. It goes with that module.
+exec "$(cd "$(dirname "$0")" && pwd)/../botons" "$@"

package/payload/server/bin/legacy/tots

@@ -0,0 +1,4 @@
+#!/bin/sh
+# LEGACY NAMES (see shared/legacy-names.mjs): a deprecated name of `botons`, on a turn's PATH for one release so
+# agents' saved scripts and instructions keep working. It goes with that module.
+exec "$(cd "$(dirname "$0")" && pwd)/../botons" "$@"

package/payload/server/src/acting.ts

@@ -0,0 +1,16 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+// The turn a Boton's request to the server came from, while the server handles it: so what the request posts in the
+// chat (a memory saved, a file shared...) is known to be that turn's. Set only for a Boton's own token, from the turn
+// the engine is running for it, never from anything in the request.
+const acting = new AsyncLocalStorage<{ botId: string; turnId: string }>();
+
+export function asTurn<T>(botId: string, turnId: string | null | undefined, fn: () => T): T {
+  return turnId ? acting.run({ botId, turnId }, fn) : fn();
+}
+
+/** The turn of the Boton's request being handled, if it is `botId`'s: else null (the owner, the server). */
+export function actingTurn(botId: string): string | null {
+  const a = acting.getStore();
+  return a && a.botId === botId ? a.turnId : null;
+}