elanous 0.2.12 → 0.2.14

package/scripts/hq/standby-promote.ts

@@ -0,0 +1,173 @@
+#!/usr/bin/env bun
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { chmodSync, copyFileSync, lstatSync, mkdirSync, readFileSync, readlinkSync, realpathSync, rmSync, statSync, utimesSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { debug } from '../../src/debug/log.js';
+import type { Tier } from './standby-snapshot.js';
+
+interface Generation { tier: Tier; name: string; dir: string; files: string[] }
+interface Options { to: string; standby: string; tiers: Tier[]; hqConfig?: string; dryRun: boolean; json: boolean }
+
+function contained(base: string, name: string): string {
+  if (!name || isAbsolute(name) || name.includes('\\')) throw new Error(`invalid relative path: ${name}`);
+  const path = resolve(base, name);
+  const rel = relative(base, path);
+  if (!rel || rel === '..' || rel.startsWith(`..${sep}`)) throw new Error(`path escapes generation: ${name}`);
+  return path;
+}
+
+function expand(path: string): string { return path.startsWith('~/') ? join(homedir(), path.slice(2)) : path; }
+
+export function parsePromoteArgs(argv: string[]): Options {
+  const options: Options = { to: '', standby: join(homedir(), '.elanous-standby'), tiers: ['core', 'big'], dryRun: false, json: false };
+  for (let i = 0; i < argv.length; i++) {
+    const flag = argv[i];
+    if (flag === '--dry-run') { options.dryRun = true; continue; }
+    if (flag === '--json') { options.json = true; continue; }
+    if (!['--to', '--standby', '--tiers', '--hq-config'].includes(flag)) throw new Error(`unknown option: ${flag}`);
+    const value = argv[++i];
+    if (!value || value.startsWith('--')) throw new Error(`${flag} requires a value`);
+    if (flag === '--to') options.to = resolve(expand(value));
+    if (flag === '--standby') options.standby = resolve(expand(value));
+    if (flag === '--hq-config') options.hqConfig = resolve(expand(value));
+    if (flag === '--tiers') {
+      const tiers = value.split(',');
+      if (tiers.some(t => !['core', 'big', 'obs'].includes(t)) || new Set(tiers).size !== tiers.length) throw new Error('--tiers must be core,big,obs without duplicates');
+      options.tiers = tiers as Tier[];
+    }
+  }
+  if (!options.to) throw new Error('--to is required');
+  return options;
+}
+
+function isInside(base: string, path: string): boolean {
+  const rel = relative(base, path);
+  return !rel || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+
+async function sha256(path: string): Promise<string> {
+  const hash = createHash('sha256');
+  for await (const chunk of createReadStream(path)) hash.update(chunk);
+  return hash.digest('hex');
+}
+
+function checkedFile(dir: string, name: string): string {
+  const path = contained(dir, name);
+  let current = dir;
+  for (const part of relative(dir, path).split(sep)) {
+    current = join(current, part);
+    if (lstatSync(current).isSymbolicLink()) throw new Error(`symlink in generation: ${name}`);
+  }
+  if (!lstatSync(path).isFile()) throw new Error(`not a file: ${name}`);
+  return path;
+}
+
+async function readGeneration(standby: string, tier: Tier): Promise<Generation> {
+  const base = join(standby, tier);
+  const name = readlinkSync(join(base, 'latest'));
+  const dir = contained(base, name);
+  if (relative(base, dir) !== name || !lstatSync(dir).isDirectory()) throw new Error(`${tier}: invalid latest`);
+  const manifest = JSON.parse(readFileSync(checkedFile(dir, 'MANIFEST.json'), 'utf8')) as { generation?: string; tier?: string; entries?: Array<{ path: string; sha256: string }> };
+  if (manifest.generation !== name || manifest.tier !== tier || !Array.isArray(manifest.entries)) throw new Error(`${tier}: invalid manifest`);
+  const lines = readFileSync(checkedFile(dir, 'SHA256SUMS'), 'utf8').trimEnd().split('\n');
+  const files: string[] = [];
+  const seen = new Set<string>();
+  for (const line of lines) {
+    const match = /^([a-fA-F0-9]{64})  (.+)$/.exec(line);
+    if (!match || seen.has(match[2]) || ['MANIFEST.json', 'SHA256SUMS'].includes(match[2])) throw new Error(`${tier}: invalid SHA256SUMS`);
+    seen.add(match[2]);
+    const file = checkedFile(dir, match[2]);
+    if (await sha256(file) !== match[1].toLowerCase()) throw new Error(`${tier}: checksum mismatch: ${match[2]}`);
+    files.push(match[2]);
+  }
+  if (manifest.entries.length !== files.length || manifest.entries.some(e => !e || !seen.has(e.path) || !lines.includes(`${e.sha256}  ${e.path}`))) throw new Error(`${tier}: manifest/checksum list mismatch`);
+  return { tier, name, dir, files };
+}
+
+function objectConfig(path: string): Record<string, unknown> {
+  const value: unknown = JSON.parse(readFileSync(path, 'utf8'));
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`config is not an object: ${path}`);
+  return value as Record<string, unknown>;
+}
+
+function pollerOff(value: unknown): Record<string, unknown> {
+  if (value === undefined) return { enabled: false };
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('poller config is not an object');
+  return { ...value, enabled: false };
+}
+
+export async function promote(options: Options, writeConfig: (path: string, contents: string) => void = writeFileSync): Promise<{ to: string; tiers: Record<string, string>; files: number; features: 'yes' | 'no'; pollers: 'off'; hq: string; seconds: number; dryRun: boolean }> {
+  const started = Date.now();
+  const to = resolve(options.to);
+  const parent = realpathSync(dirname(to));
+  const targetPath = join(parent, relative(dirname(to), to));
+  if (isInside(realpathSync(options.standby), targetPath)) throw new Error('--to must be outside --standby');
+  if (options.hqConfig && isInside(realpathSync(options.hqConfig), targetPath)) throw new Error('--to must be outside --hq-config');
+  // Verify each tier before creating the target, so a bad big copy cannot leave a promoted core.
+  const generations: Generation[] = [];
+  for (const tier of options.tiers) generations.push(await readGeneration(options.standby, tier));
+  try { lstatSync(to); throw new Error(`target already exists: ${to}`); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+  const files = generations.reduce((n, g) => n + g.files.length, 0);
+  const tiers = Object.fromEntries(generations.map(g => [g.tier, g.name]));
+  const configSource = [...generations].reverse().find(g => g.files.includes('config.json'));
+  let config: Record<string, unknown> | undefined;
+  let hq = '-';
+  if (!options.dryRun && configSource) {
+    config = objectConfig(checkedFile(configSource.dir, 'config.json'));
+    config.telegram = pollerOff(config.telegram);
+    config.discord = pollerOff(config.discord);
+    if (options.hqConfig) {
+      const hostConfig = objectConfig(join(options.hqConfig, 'config.json'));
+      const block = hostConfig.hq;
+      if (!block || typeof block !== 'object' || Array.isArray(block) || typeof (block as Record<string, unknown>).hostName !== 'string' || !(block as Record<string, unknown>).hostName) throw new Error('--hq-config has no hq.hostName');
+      config.hq = block;
+      hq = (block as { hostName: string }).hostName;
+    }
+  }
+  const summary = { to, tiers, files, features: generations.some(g => g.files.includes('release/features.sqlite')) ? 'yes' as const : 'no' as const, pollers: 'off' as const, hq, seconds: 0, dryRun: options.dryRun };
+  if (options.dryRun) return summary;
+  mkdirSync(to, { mode: 0o700 });
+  try {
+    chmodSync(to, 0o700);
+    for (const generation of generations) {
+      for (const name of generation.files) {
+        const source = checkedFile(generation.dir, name);
+        const dest = contained(to, name);
+        mkdirSync(dirname(dest), { recursive: true, mode: 0o700 });
+        copyFileSync(source, dest);
+        const stats = statSync(source);
+        chmodSync(dest, stats.mode);
+        utimesSync(dest, stats.atime, stats.mtime);
+      }
+    }
+    if (config && configSource) {
+      copyFileSync(join(to, 'config.json'), join(to, 'config.json.pre-promote'));
+      writeConfig(join(to, 'config.json'), `${JSON.stringify(config, null, 2)}\n`);
+    }
+    summary.seconds = Math.round((Date.now() - started) / 1000);
+    return summary;
+  } catch (error) {
+    rmSync(to, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+if (import.meta.main) {
+  let options: Options | undefined;
+  try {
+    options = parsePromoteArgs(process.argv.slice(2));
+    const result = await promote(options);
+    if (!result.dryRun) debug.log('hq.standby', 'promoted', { tiers: result.tiers, files: result.files, reason: 'promoted' });
+    console.log(options.json ? JSON.stringify(result) : result.dryRun
+      ? `promotion plan ${result.to} ${Object.entries(result.tiers).map(([t, g]) => `${t}=${g}`).join(' ')} files=${result.files}`
+      : `promoted ${result.to} core=${result.tiers.core ?? '-'} big=${result.tiers.big ?? '-'} files=${result.files} features=${result.features} pollers=off hq=${result.hq} ${result.seconds}s`);
+  } catch (error) {
+    const reason = String(error);
+    debug.log('hq.standby', 'promote-refused', { tiers: options?.tiers ?? [], files: 0, reason });
+    console.error(`promotion refused: ${reason}`);
+    process.exitCode = 1;
+  }
+}

package/scripts/hq/standby-role.ts

@@ -0,0 +1,59 @@
+#!/usr/bin/env bun
+// HQ-REP direction — which way does this host replicate? (OP 10-04 10:09 · «되돌리기 방향»)
+// The lease holder is the source and the other host is the standby: once node-b holds the lease, node-b → mbp.
+//   · a lease record exists, or the arbiter cannot be read → `fenced`: the caller runs the copy under
+//     `elanous hq fence --role cron`, which alone decides (holder · generation · arbiter-down rules, src/hq/lease.ts).
+//   · no lease record yet (before HQ-HB acquires one) → `direct` on the default source host only, `skip` elsewhere,
+//     so the mbp → node-b copy keeps running until the first lease exists (OP 10:12 bootstrap rule).
+//   · TC 10:12: a host that has ever seen a lease generation treats a missing record as «unknown» and skips — otherwise
+//     a lost arbiter file after the drill would turn mbp back into the source while node-b is HQ (split-brain).
+//     «Seen» = `~/.elanous-hq/seen-generation` (HQ-HB writes it) or a generation in the local lease state (hq/local.json).
+// Usage: bun scripts/hq/standby-role.ts --default-source <host> [--config-dir <dir>] [--me <host>] [--json]   → prints `direct` | `fenced` | `skip`
+import { existsSync } from 'node:fs';
+import { homedir, hostname } from 'node:os';
+import { join } from 'node:path';
+import { debug } from '../../src/debug/log.js';
+import { getElanousConfigDir, setElanousConfigDir } from '../../src/elanous-config-dir.js';
+import { hqLease, readLocal } from '../../src/hq/hq.js';
+import { getUserConfig } from '../../src/user-config.js';
+import type { LeaseRecord } from '../../src/hq/lease.js';
+
+export type ReplicationRole = 'direct' | 'fenced' | 'skip';
+export interface RoleDecision { role: ReplicationRole; reason: 'lease-exists' | 'lease-unreadable' | 'no-lease-default-source' | 'no-lease-not-default' | 'no-lease-after-seen'; holder?: string }
+
+/** `defaultSource` may list aliases (`MacBookProM5,mbp`) — the lease name is `hq.hostName` when set, else the OS host name. */
+export function decideReplicationRole(input: { me: string; defaultSource: string; record: LeaseRecord | null | 'unreadable'; seenGeneration?: boolean }): RoleDecision {
+  const { me, defaultSource, record } = input;
+  if (record === 'unreadable') return { role: 'fenced', reason: 'lease-unreadable' };
+  if (record) return { role: 'fenced', reason: 'lease-exists', holder: record.holder };
+  if (input.seenGeneration) return { role: 'skip', reason: 'no-lease-after-seen' };
+  const aliases = defaultSource.split(',').map(s => s.trim()).filter(Boolean);
+  return aliases.includes(me) ? { role: 'direct', reason: 'no-lease-default-source' } : { role: 'skip', reason: 'no-lease-not-default' };
+}
+
+/** Has this host ever seen a lease generation? (TC 10:12 · see the header.) */
+export function hasSeenGeneration(home: string = homedir(), localPath: string = join(getElanousConfigDir(), 'hq', 'local.json')): boolean {
+  if (existsSync(join(home, '.elanous-hq', 'seen-generation'))) return true;
+  return typeof readLocal(localPath).generation === 'number';
+}
+
+/** Same host name the lease uses (src/hq/hq.ts resolve): `hq.hostName`, else the OS host name without `.local`. */
+export function leaseHostName(configured: string | undefined = getUserConfig().hq?.hostName, raw: string = hostname()): string {
+  return configured ?? raw.replace(/\.local$/, '');
+}
+
+if (import.meta.main) {
+  const argv = process.argv.slice(2);
+  const arg = (name: string) => { const i = argv.indexOf(name); return i >= 0 ? argv[i + 1] : undefined; };
+  const defaultSource = arg('--default-source');
+  if (!defaultSource) { console.error('standby-role: --default-source <host> required'); process.exit(2); }
+  // Same lease name and local state as HQ-HB: the config dir moves only by this setter (an env var is ignored).
+  const configDir = arg('--config-dir');
+  if (configDir) setElanousConfigDir(configDir);
+  const me = arg('--me') ?? leaseHostName();
+  let record: LeaseRecord | null | 'unreadable';
+  try { record = hqLease('status').record; } catch { record = 'unreadable'; }
+  const decided = decideReplicationRole({ me, defaultSource, record, seenGeneration: hasSeenGeneration() });
+  debug.log('hq.standby', 'role', { me, defaultSource, ...decided });
+  console.log(argv.includes('--json') ? JSON.stringify({ me, defaultSource, ...decided }) : decided.role);
+}

package/scripts/hq/standby-snapshot.ts

@@ -0,0 +1,226 @@
+#!/usr/bin/env bun
+// HQ-REP — standby snapshots for the HQ move (mbp → node-b). OP design 10-04 08:33 (channel #23032):
+//   ① canonical ledgers every 10 min · ② observation DBs every hour · ③ secrets host-to-host only · ④ runtime is not copied.
+//   Never `cp` a live SQLite file: take `.backup` snapshots, number the generation, list sha256 for every file,
+//   then rsync into `<host>:~/.elanous-standby/<tier>/<generation>/` (not the live folder) and move `latest` only
+//   after the receiver verifies the checksums.
+// Usage:
+//   bun scripts/hq/standby-snapshot.ts --tier core|big|obs [--push <host>] [--survival <host>,s3://bucket/prefix] [--keep N] [--dry-run] [--json]
+//   대표 10-04 08:4x: no whole-copy of big DBs every 10 minutes — core (≤20MB) every 10 min, big and obs four times a day,
+//   and each push sends only changed blocks (`rsync --inplace` into `current/`, then a clone becomes the generation).
+import { createHash } from 'node:crypto';
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { homedir, hostname } from 'node:os';
+import { dirname, join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { debug } from '../../src/debug/log.js';
+
+export type Tier = 'core' | 'big' | 'obs';
+/** 대표 10-04 08:4x: only ledgers at or under this size go every 10 minutes; larger canonical DBs go four times a day. */
+export const SMALL_LEDGER_BYTES = 20 * 1024 * 1024;
+export interface PlanItem { rel: string; kind: 'sqlite' | 'file'; survival: boolean }
+export interface ManifestEntry { path: string; bytes: number; sha256: string; kind: PlanItem['kind']; reused?: boolean }
+export interface Manifest { generation: string; tier: Tier; createdAt: string; source: string; host: string; entries: ManifestEntry[] }
+
+/** Secrets never leave the host pair through a survival copy (cloud-vm · bucket), whatever the tier. */
+export function isSecretPath(rel: string): boolean {
+  const lower = rel.toLowerCase();
+  return /(^|\/)(secrets?|backup-key|acp-token)(\/|$|\.)/.test(lower)
+    || /(^|\/)auth\.json/.test(lower)
+    || /\.(p8|pem|key|env)$/.test(lower)
+    || /(token|credential|password|session)[^/]*$/.test(lower);
+}
+
+// ① canonical — small, consistency matters. `survival` = also kept on cloud-vm and the ops bucket.
+const CORE_FILES: Array<[string, boolean]> = [
+  ['release/features.sqlite', true], ['schedules.db', true], ['tasks/tasks.db', false], ['directives/directives.db', true],
+  ['scheduler/scheduler.db', false], ['task-cards/index.db', false], ['knowledge.db', false], ['memory/knowledge.db', false],
+  ['config.json', false],
+];
+const CORE_DIRS: Array<[string, boolean]> = [
+  ['decisions', true], ['budget', false], ['seat-loop', false], ['seat-requests', false], ['test-diet', false],
+  ['consult-requests', false], ['outputs', false],
+  // HQ drill round-trip marker (runbook «되돌리기»): one line written on the new HQ must come back to the old one.
+  ['hq-drill', false],
+];
+// ② observation — large, append-only, losable.
+const OBS_FILES = ['logs/logs.db', 'memory/surface_events.db'];
+
+function walkFiles(root: string, dir: string): string[] {
+  if (!existsSync(join(root, dir))) return [];
+  const out: string[] = [];
+  for (const name of readdirSync(join(root, dir))) {
+    const rel = join(dir, name);
+    const st = lstatSync(join(root, rel));
+    if (st.isSymbolicLink()) continue;
+    if (st.isDirectory()) out.push(...walkFiles(root, rel));
+    else if (st.isFile() && !/\.(tmp|lock)$|-wal$|-shm$|-journal$/.test(name)) out.push(rel);
+  }
+  return out;
+}
+
+const isSqlite = (rel: string) => /\.(db|sqlite|sqlite3)$/.test(rel);
+
+export function planSnapshot(root: string, tier: Tier): PlanItem[] {
+  const items: PlanItem[] = [];
+  const add = (rel: string, survival: boolean) => {
+    if (!existsSync(join(root, rel))) return;
+    items.push({ rel, kind: isSqlite(rel) ? 'sqlite' : 'file', survival: survival && !isSecretPath(rel) });
+  };
+  if (tier === 'obs') { for (const rel of OBS_FILES) add(rel, false); return items; }
+  for (const [rel, survival] of CORE_FILES) add(rel, survival);
+  for (const [dir, survival] of CORE_DIRS) for (const rel of walkFiles(root, dir)) add(rel, survival);
+  // Trading ledgers are canonical too (OP 08:4x) — FENCE keeps execution on one host only.
+  for (const rel of walkFiles(root, 'conatus')) if (isSqlite(rel)) add(rel, false);
+  // Release ledgers: per-version checklist and manifest only — gate logs are rebuildable and large.
+  if (existsSync(join(root, 'release'))) {
+    for (const version of readdirSync(join(root, 'release'))) {
+      for (const name of ['checklist.json', 'manifest.json']) add(join('release', version, name), true);
+    }
+  }
+  const sized = items.filter(item => !isSecretPath(item.rel) || !item.survival);
+  const big = (item: PlanItem) => statSync(join(root, item.rel)).size > SMALL_LEDGER_BYTES;
+  return tier === 'big' ? sized.filter(big) : sized.filter(item => !big(item));
+}
+
+const sha256 = (path: string) => createHash('sha256').update(readFileSync(path)).digest('hex');
+
+/** Consistent copy: SQLite through `.backup` (never a live-file copy), other files byte-for-byte. */
+/** Host-specific settings that must never ride a replicated `config.json` (OP 10-04 12:02 · drill step 5:
+ *  mbp's `hq.hostName=mbp` reached node-b's promoted universe and made node-b call itself mbp). */
+export const HOST_LOCAL_CONFIG_KEYS = ['hq'] as const;
+
+/** `config.json` without the host-local blocks; unparsable text is copied as is (the copy must not fail on it). */
+export function stripHostLocalConfig(text: string): string {
+  let parsed: unknown;
+  try { parsed = JSON.parse(text); } catch { return text; }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return text;
+  const obj = { ...(parsed as Record<string, unknown>) };
+  let removed = false;
+  for (const key of HOST_LOCAL_CONFIG_KEYS) if (key in obj) { delete obj[key]; removed = true; }
+  return removed ? `${JSON.stringify(obj, null, 2)}\n` : text;
+}
+
+export function snapshotItem(root: string, out: string, item: PlanItem, sqlite3 = 'sqlite3'): void {
+  const dest = join(out, item.rel);
+  mkdirSync(dirname(dest), { recursive: true });
+  if (item.kind === 'sqlite') {
+    const r = spawnSync(sqlite3, [join(root, item.rel), `.backup '${dest.replace(/'/g, "''")}'`], { encoding: 'utf8' });
+    if (r.status !== 0) throw new Error(`sqlite backup failed: ${item.rel}: ${(r.stderr || '').trim()}`);
+  } else if (item.rel === 'config.json') {
+    const original = readFileSync(join(root, item.rel), 'utf8');
+    const stripped = stripHostLocalConfig(original);
+    if (stripped !== original) debug.log('hq.standby', 'config-host-local-stripped', { keys: [...HOST_LOCAL_CONFIG_KEYS] });
+    writeFileSync(dest, stripped);
+  } else cpSync(join(root, item.rel), dest);
+}
+
+export function generationId(now = new Date()): string {
+  return now.toISOString().replace(/[-:]/g, '').replace(/\.\d+Z$/, 'Z');
+}
+
+/** Build one generation in `out`. SQLite files whose source is unchanged since `previous` are reused (hard link target). */
+export function buildGeneration(opts: { root: string; out: string; tier: Tier; previous?: Manifest | null; previousDir?: string; host?: string; now?: Date; sqlite3?: string }): Manifest {
+  const { root, out, tier } = opts;
+  mkdirSync(out, { recursive: true });
+  const entries: ManifestEntry[] = [];
+  const prev = new Map((opts.previous?.entries ?? []).map(e => [e.path, e]));
+  const prevAt = opts.previous ? Date.parse(opts.previous.createdAt) : NaN;
+  for (const item of planSnapshot(root, tier)) {
+    const old = prev.get(item.rel);
+    const mtime = statSync(join(root, item.rel)).mtimeMs;
+    if (item.kind === 'sqlite' && old && opts.previousDir && Number.isFinite(prevAt) && mtime < prevAt && existsSync(join(opts.previousDir, item.rel))) {
+      mkdirSync(dirname(join(out, item.rel)), { recursive: true });
+      cpSync(join(opts.previousDir, item.rel), join(out, item.rel));
+      entries.push({ ...old, reused: true });
+      continue;
+    }
+    snapshotItem(root, out, item, opts.sqlite3);
+    const dest = join(out, item.rel);
+    entries.push({ path: item.rel, bytes: statSync(dest).size, sha256: sha256(dest), kind: item.kind });
+  }
+  const manifest: Manifest = { generation: generationId(opts.now), tier, createdAt: (opts.now ?? new Date()).toISOString(), source: root, host: opts.host ?? hostname().replace(/\.local$/, ''), entries };
+  writeFileSync(join(out, 'MANIFEST.json'), `${JSON.stringify(manifest, null, 2)}\n`);
+  writeFileSync(join(out, 'SHA256SUMS'), entries.map(e => `${e.sha256}  ${e.path}`).join('\n') + '\n');
+  return manifest;
+}
+
+/** Survival subset: what cloud-vm and the bucket get. Secrets are excluded by construction. */
+export function survivalPaths(manifest: Manifest, root: string): string[] {
+  const plan = new Map(planSnapshot(root, manifest.tier).map(i => [i.rel, i]));
+  return manifest.entries.map(e => e.path).filter(p => plan.get(p)?.survival === true && !isSecretPath(p));
+}
+
+function run(cmd: string, args: string[]): { ok: boolean; out: string } {
+  const r = spawnSync(cmd, args, { encoding: 'utf8' });
+  return { ok: r.status === 0, out: `${r.stdout ?? ''}${r.stderr ?? ''}`.trim() };
+}
+
+/** Delta push: `rsync --inplace` into a fixed `current/` (only changed blocks travel), verify, then clone it to `<gen>/`. */
+function pushToHost(host: string, local: string, tier: Tier, gen: string, keep: number): void {
+  const base = `.elanous-standby/${tier}`;
+  run('ssh', ['-o', 'BatchMode=yes', host, `mkdir -p ${base}/current`]);
+  const r = run('rsync', ['-a', '--inplace', '--no-whole-file', '--delete', `${local}/`, `${host}:${base}/current/`]);
+  if (!r.ok) throw new Error(`rsync to ${host} failed: ${r.out}`);
+  const verify = run('ssh', ['-o', 'BatchMode=yes', host, `cd ${base}/current && (shasum -a 256 -c SHA256SUMS >/dev/null 2>&1 || sha256sum -c SHA256SUMS >/dev/null 2>&1) && echo verified`]);
+  if (verify.out !== 'verified') throw new Error(`checksum verify failed on ${host}:${base}/current`);
+  // APFS clone on macOS (no extra space until files diverge), hard links on Linux.
+  const clone = run('ssh', ['-o', 'BatchMode=yes', host, `cd ${base} && (cp -cR current ${gen} 2>/dev/null || cp -al current ${gen}) && ln -sfn ${gen} latest.new && (mv -fh latest.new latest 2>/dev/null || mv -fT latest.new latest) && ls -1d 2*Z | sort | awk -v k=${keep} '{a[NR]=$0} END {for (i=1;i<=NR-k;i++) print a[i]}' | xargs rm -rf; echo cloned`]);
+  if (!clone.out.endsWith('cloned')) throw new Error(`generation clone failed on ${host}: ${clone.out}`);
+}
+
+function pushSurvival(target: string, local: string, manifest: Manifest, root: string): void {
+  const paths = survivalPaths(manifest, root);
+  const staging = `${local}.survival`;
+  rmSync(staging, { recursive: true, force: true });
+  for (const p of paths) { mkdirSync(dirname(join(staging, p)), { recursive: true }); cpSync(join(local, p), join(staging, p)); }
+  const sub = manifest.entries.filter(e => paths.includes(e.path));
+  writeFileSync(join(staging, 'SHA256SUMS'), sub.map(e => `${e.sha256}  ${e.path}`).join('\n') + '\n');
+  writeFileSync(join(staging, 'MANIFEST.json'), `${JSON.stringify({ ...manifest, entries: sub }, null, 2)}\n`);
+  if (target.startsWith('s3://')) {
+    const r = run('aws', ['s3', 'sync', staging, `${target.replace(/\/$/, '')}/${manifest.generation}/`, '--sse', 'AES256', '--only-show-errors']);
+    if (!r.ok) throw new Error(`s3 sync failed: ${r.out}`);
+  } else {
+    const base = `.elanous-standby/survival`;
+    run('ssh', ['-o', 'BatchMode=yes', target, `mkdir -p ${base}`]);
+    const r = run('rsync', ['-a', `${staging}/`, `${target}:${base}/${manifest.generation}/`]);
+    if (!r.ok) throw new Error(`rsync survival to ${target} failed: ${r.out}`);
+  }
+  rmSync(staging, { recursive: true, force: true });
+}
+
+if (import.meta.main) {
+  const argv = process.argv.slice(2);
+  const val = (k: string) => { const i = argv.indexOf(k); return i >= 0 ? argv[i + 1] : undefined; };
+  const tier = (val('--tier') ?? 'core') as Tier;
+  if (tier !== 'core' && tier !== 'big' && tier !== 'obs') { console.error('--tier core|big|obs'); process.exit(2); }
+  const root = process.env.ELANOUS_STATE_DIR ?? join(homedir(), '.elanous');
+  const stagingRoot = join(homedir(), '.elanous-standby-staging', tier);
+  const started = Date.now();
+  try {
+    if (argv.includes('--dry-run')) {
+      const plan = planSnapshot(root, tier);
+      console.log(JSON.stringify({ tier, items: plan.length, survival: plan.filter(i => i.survival).length, plan }, null, argv.includes('--json') ? 0 : 2));
+      process.exit(0);
+    }
+    mkdirSync(stagingRoot, { recursive: true });
+    // One clock reading names both the pushed folder and MANIFEST.generation — a big tier takes seconds to snapshot,
+    // and two readings drifted apart (10-04 12:13 big: folder 031304Z · manifest 031309Z · caught by standby-verify).
+    const now = new Date();
+    const gen = generationId(now);
+    const out = join(stagingRoot, 'current');
+    const manifest = buildGeneration({ root, out, tier, now });
+    const host = val('--push');
+    const keep = Number(val('--keep') ?? (tier === 'core' ? 36 : 8));
+    if (host) pushToHost(host, out, tier, gen, keep);
+    for (const target of (val('--survival') ?? '').split(',').filter(Boolean)) pushSurvival(target, out, manifest, root);
+    const bytes = manifest.entries.reduce((n, e) => n + e.bytes, 0);
+    const summary = { generation: gen, tier, files: manifest.entries.length, reused: manifest.entries.filter(e => e.reused).length, bytes, pushed: host ?? null, survival: (val('--survival') ?? '').split(',').filter(Boolean), seconds: Math.round((Date.now() - started) / 1000) };
+    debug.log('hq.standby', 'generation', summary);
+    console.log(argv.includes('--json') ? JSON.stringify(summary) : `standby ${tier} ${gen}: ${summary.files} files (${summary.reused} reused) · ${(bytes / 1e6).toFixed(1)} MB · push ${host ?? '-'} · survival ${summary.survival.join(',') || '-'} · ${summary.seconds}s`);
+  } catch (error) {
+    debug.log('hq.standby', 'failed', { tier, error: String(error).slice(0, 300) });
+    console.error(`standby ${tier} FAILED: ${String(error)}`);
+    process.exit(1);
+  }
+}