dsh-foreman 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -6,6 +6,28 @@
 
 本项目自己的版本从 `0.1.0` 开始。
 
+## 0.1.1 — 2026-11-07
+
+修的是 `0.1.0` 发布时才暴露的两个问题，都是真机验证（上海服务器 srv-02）发现的。
+
+### 修复：运维脚本没有进包
+
+`0.1.0` 的 `files` 漏了 `scripts/`，于是装完 `dsh-foreman@0.1.0` 之后
+`node scripts/add-device.mjs` **不存在** —— 而那是加设备的唯一入口，
+文档里却写着让人这么跑。现在随包发三个脚本：
+
+- `scripts/add-device.mjs`（加设备 / 换令牌 / 吊销）
+- `scripts/migrate.mjs`（迁机打包与自检）
+- `scripts/dsh-foreman`（服务脚本）
+
+`scripts/sync-wsl.sh`、`scripts/deploy-preview.sh` 是开发用的，**不发布**。
+
+### 修复：一个不带正文的帧会崩掉握手
+
+`ws.ts` 把收到的任何消息一律 `.toString()`，于是 payload 缺失时会得到字符串 `"undefined"`，
+再被当成帧去解析。现在只接受真的带文本的帧（字符串 / Buffer / Buffer[]），
+其余直接忽略，并在握手阶段给出可读原因。
+
 ## 0.1.0 — 2026-11-07
 
 首个公开发布。**一个常驻主 loop，把工单派给多台在线设备上各自完整运行的 DSH，账本只有一份。**

package/lib/index.js

@@ -9962,7 +9962,8 @@ var SocketChannel = class {
 	constructor(socket) {
 		this.socket = socket;
 		socket.on("message", (data) => {
-			const text = typeof data === "string" ? data : data.toString();
+			const text = textOf(data);
+			if (text === void 0) return;
 			if (this.messages.length === 0) {
 				this.pending.push(text);
 				return;
@@ -10030,6 +10031,18 @@ async function serve(input) {
 	};
 }
 /**
+* The text of one frame, or undefined when the frame carries none.
+*
+* `ws` hands over a string, a Buffer, an array of Buffers, or — for a binary frame this protocol never sends — a raw
+* Buffer. Converting blindly would turn an absent payload into the literal string "undefined", which then reaches a
+* parser as a malformed frame.
+*/
+function textOf(data) {
+	if (typeof data === "string") return data;
+	if (Buffer.isBuffer(data)) return data.toString("utf8");
+	if (Array.isArray(data)) return Buffer.concat(data).toString("utf8");
+}
+/**
 * The device id the first frame claims, and why it is missing when it is.
 *
 * Reading it here rather than in the hub keeps `Hub` free of `ws` types without weakening the handshake: the hub
@@ -10047,7 +10060,12 @@ function firstFrame(socket) {
 		const timer = setTimeout(() => settle({ reason: "the connection did not open with a hello within 10 seconds" }), 1e4);
 		const closed = () => settle({ reason: "the connection closed before it said hello" });
 		socket.once("message", (data) => {
-			const deviceId = deviceIdOf(typeof data === "string" ? data : data.toString());
+			const text = textOf(data);
+			if (text === void 0) {
+				settle({ reason: "the first frame carried no text" });
+				return;
+			}
+			const deviceId = deviceIdOf(text);
 			settle(deviceId === void 0 ? { reason: "the first frame must be a hello naming a device" } : {
 				deviceId,
 				reason: ""

package/package.json

@@ -2,7 +2,7 @@
   "name": "dsh-foreman",
   "author": "niechao136",
   "license": "MIT",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "dsh-foreman：主 loop 在多设备上派单的 DSH bundle：需求来自本机操作者的主会话而不是 GitHub/飞书，每个工作区各有一条主会话，主会话只负责路由，真正的活儿派给 Worker 在该工作区目录里执行。",
   "type": "module",
   "main": "lib/index.js",
@@ -27,7 +27,10 @@
     "CHANGELOG.md",
     "README.md",
     "prompts",
-    "skills"
+    "skills",
+    "scripts/add-device.mjs",
+    "scripts/migrate.mjs",
+    "scripts/dsh-foreman"
   ],
   "dsh": {
     "bundle": {

package/scripts/add-device.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+/**
+ * Register a device on the hub, or manage the ones already registered.
+ *
+ * Adding a device must not mean editing plugin configuration and restarting the hub — that is an anti-goal of the
+ * design — so this writes the registry row directly and the running hub picks it up on the device's next hello.
+ *
+ * Plain ESM on `node:sqlite`, no dependencies: it has to run on a server where only the hub is installed.
+ *
+ *   node scripts/add-device.mjs add --home <dir> --id laptop --name "公司笔记本" \
+ *        --root shop=/home/me/work/shop --label intranet
+ *   node scripts/add-device.mjs list  --home <dir>
+ *   node scripts/add-device.mjs rotate --home <dir> --id laptop
+ *   node scripts/add-device.mjs revoke --home <dir> --id laptop
+ */
+import { createHash, randomBytes } from 'node:crypto'
+import { existsSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { DatabaseSync } from 'node:sqlite'
+
+const DATABASE = 'state/superagent/orchestrator.sqlite'
+const PREFIX = 'foreman-device:'
+
+const usage = `Usage:
+  add    --id <id> --name <name> [--label <label>]... [--root <project>=<path>]...
+  list
+  rotate --id <id>
+  revoke --id <id>
+All commands take --home <dir> (default: $DSH_HOME, else ~/.dsh) and --db <path> to override the database.`
+
+const hashToken = token => createHash('sha256').update(token, 'utf8').digest('hex')
+
+/** Reads repeating and single `--name value` options into a list of pairs. */
+function options(argv) {
+  const single = new Map()
+  const many = { label: [], root: [] }
+  for (let index = 0; index < argv.length; index++) {
+    const name = argv[index]
+    if (!name.startsWith('--')) throw new Error(`unexpected argument ${name}\n\n${usage}`)
+    const key = name.slice(2)
+    const value = argv[index + 1]
+    if (value === undefined || value.startsWith('--')) throw new Error(`${name} needs a value\n\n${usage}`)
+    if (key in many) many[key].push(value)
+    else single.set(key, value)
+    index++
+  }
+  return { single, many }
+}
+
+/** Opens the hub's database, refusing a path that is not one so a typo cannot write anywhere. */
+function open(single) {
+  const home = resolve(single.get('home') ?? process.env.DSH_HOME ?? join(process.env.HOME ?? process.env.USERPROFILE ?? '.', '.dsh'))
+  const path = single.get('db') ? resolve(single.get('db')) : join(home, DATABASE)
+  if (!existsSync(path)) throw new Error(`no hub database at ${path}; is --home the DSH home of the loop instance?`)
+  const db = new DatabaseSync(path)
+  // The registry is a kv family, so this works without importing the hub's schema: the key format is the contract.
+  db.exec('CREATE TABLE IF NOT EXISTS kv (key TEXT PRIMARY KEY, value TEXT NOT NULL)')
+  return { db, path }
+}
+
+const read = (db, id) => {
+  const row = db.prepare('SELECT value FROM kv WHERE key=?').get(PREFIX + id)
+  return row === undefined ? undefined : JSON.parse(String(row.value))
+}
+const write = (db, record) => {
+  db.prepare('INSERT INTO kv VALUES (?,?) ON CONFLICT(key) DO UPDATE SET value=excluded.value').run(PREFIX + record.id, JSON.stringify(record))
+}
+const all = db => db.prepare('SELECT value FROM kv WHERE key LIKE ? ORDER BY key').all(`${PREFIX}%`).map(row => JSON.parse(String(row.value)))
+
+/** `project=path`, split on the first `=` so a Windows path's own `=` survives. */
+function rootsOf(values) {
+  return values.map(value => {
+    const at = value.indexOf('=')
+    if (at <= 0) throw new Error(`--root needs <project>=<path>, not ${value}`)
+    return { project: value.slice(0, at), path: value.slice(at + 1) }
+  })
+}
+
+const [command, ...rest] = process.argv.slice(2)
+if (command === undefined || ['-h', '--help', 'help'].includes(command)) {
+  console.log(usage)
+  process.exit(0)
+}
+try {
+  const { single, many } = options(rest)
+  const { db, path } = open(single)
+  let output
+  try {
+    if (command === 'add') {
+      const id = single.get('id'), name = single.get('name')
+      if (!id) throw new Error('add needs --id')
+      if (read(db, id) !== undefined) throw new Error(`a device with id ${id} is already registered; use rotate to replace its token`)
+      const token = randomBytes(32).toString('hex')
+      write(db, { id, name: name ?? id, labels: many.label, roots: rootsOf(many.root), tokenHash: hashToken(token) })
+      // The token is printed once and never stored in readable form: there is nothing to look it up from later.
+      output = JSON.stringify({ device: id, token, note: 'this token is shown once; only its hash is stored' }, null, 2)
+    } else if (command === 'list') {
+      output = all(db).map(({ tokenHash: _hidden, ...record }) => record)
+        .map(record => JSON.stringify(record)).join('\n') || '(no device is registered)'
+    } else if (command === 'rotate') {
+      const id = single.get('id')
+      const device = id === undefined ? undefined : read(db, id)
+      if (device === undefined) throw new Error(`no device with id ${String(id)}`)
+      const token = randomBytes(32).toString('hex')
+      write(db, { ...device, tokenHash: hashToken(token) })
+      output = JSON.stringify({ device: device.id, token }, null, 2)
+    } else if (command === 'revoke') {
+      const id = single.get('id')
+      const device = id === undefined ? undefined : read(db, id)
+      if (device === undefined) throw new Error(`no device with id ${String(id)}`)
+      write(db, { ...device, revokedAt: new Date().toISOString() })
+      output = `revoked ${device.id}: its next frame is refused and its connection is dropped`
+    } else throw new Error(`unknown command ${command}\n\n${usage}`)
+  } finally {
+    db.close()
+  }
+  console.log(output)
+  if (command !== 'list') console.log(`\ndatabase: ${path}\nthe running hub needs no restart; the device picks this up when it next connects.`)
+} catch (error) {
+  console.error(`add-device: ${error instanceof Error ? error.message : String(error)}`)
+  process.exit(1)
+}

package/scripts/dsh-foreman

@@ -0,0 +1,250 @@
+#!/usr/bin/env python3
+"""Manage a local dsh-foreman service (one DSH profile, default `superagent`) without affecting other tmux sessions.
+
+`status`, `start`, and `restart` exit 0 while the service runs normally; 1 when it is stopped, duplicated, unreachable, or
+reporting a runtime error, which `restart` may fix; 2 when it runs while a component such as a Source reports an error;
+and 3 when it runs and waits for setup. A restart fixes neither 2 nor 3: they need a person.
+"""
+
+import argparse
+import fcntl
+import json
+import os
+from pathlib import Path
+import re
+import shlex
+import shutil
+import signal
+import subprocess
+import sys
+import time
+import urllib.error
+import urllib.request
+
+ROOT = Path(__file__).resolve().parent.parent
+ARTIFACTS = ROOT / '.artifacts'
+CONTROL = ARTIFACTS / 'control'
+KEEP_LOGS = 20
+
+
+def control(profile):
+    """Return the control directory for `profile`, creating it if needed."""
+    directory = CONTROL / 'profiles' / profile
+    directory.mkdir(parents=True, exist_ok=True)
+    return directory
+
+
+def stopped(profile):
+    """Return whether `profile` was intentionally stopped."""
+    return (control(profile) / 'manually-stopped').exists()
+
+
+def serves(args, profile):
+    """Return whether command-line arguments belong to the main DSH service process for `profile`."""
+    words, matched, value = [], False, False
+    for word in args[1:]:
+        if value:
+            matched, value = matched or word == profile, False
+        elif word == '--profile':
+            value = True
+        elif word == '--profile=' + profile:
+            matched = True
+        elif not word.startswith('-'):
+            words.append(word)
+    return matched and 'plugin' not in words
+
+
+def ps(*options, check=False):
+    """Yield `(pid, comm, args)` tuples from `ps`; arguments are split on whitespace, so paths with spaces become several words and only `--profile` and subcommands are inspected."""
+    result = subprocess.run(['ps', '-ww', *options, '-o', 'pid=,ucomm=,args='], check=check, capture_output=True, text=True)
+    for line in result.stdout.splitlines():
+        parts = line.split(None, 2)
+        if len(parts) == 3 and parts[0].isdigit():
+            yield int(parts[0]), parts[1], parts[2].split()
+
+
+def running(pid, profile):
+    """Return whether `pid` is currently running the DSH service for `profile` (`ps -p` returns nothing once exited)."""
+    return any(found == pid and name in ('node', 'dsh') and serves(args, profile) for found, name, args in ps('-p', str(pid)))
+
+
+def processes(profile):
+    """Return PIDs of all running DSH service processes for `profile`, including instances started outside this script and the recorded `service.pid` while still running."""
+    found = [pid for pid, name, args in ps('-ax', check=True) if name in ('node', 'dsh') and serves(args, profile)]
+    try:
+        pid = int((control(profile) / 'service.pid').read_text())
+    except (OSError, ValueError):
+        return found
+    return found + [pid] if pid not in found and running(pid, profile) else found
+
+
+def state(url):
+    """Fetch health and setup status from the management API, or return None if unreachable."""
+    request = urllib.request.Request(url.rstrip('/') + '/orchestrator/api/state',
+                                     headers={'x-orchestrator-request': '1'})
+    try:
+        with urllib.request.urlopen(request, timeout=2) as response:
+            value = json.load(response)
+        # Keys omitted by another version read as empty so the service is not mistaken for unreachable.
+        health, setup = value.get('health') or {}, value.get('setup') or {}
+        entries = {name: entry if isinstance(entry, dict) else {} for name, entry in health.items()}
+        return {'health': {name: entry.get('state') for name, entry in entries.items()},
+                'errors': {name: str(entry.get('detail', '')) for name, entry in entries.items() if entry.get('state') == 'error'},
+                'setup': setup.get('problem'), 'feishu': setup.get('feishuProblem')}
+    except (OSError, ValueError, AttributeError):
+        return None
+
+
+PART_ERROR = 2
+SETUP_WAITS = 3
+
+
+def runtime_up(current):
+    """Return whether the runtime is ready or paused awaiting operator action; a component still starting (such as history recovery) does not hold this up."""
+    return current is not None and current['health'].get('runtime') in ('ready', 'paused')
+
+
+def part_errors(current):
+    """Return non-runtime components that are in an error state."""
+    return {name: detail for name, detail in sorted(current['errors'].items()) if name != 'runtime'}
+
+
+def outcome(pids, current):
+    """Compute the CLI exit code from running PIDs and management API state."""
+    if len(pids) != 1 or not runtime_up(current):
+        return 1
+    if current['setup']:
+        return SETUP_WAITS
+    # A component's lasting error, unlike a Feishu bot check that failed during setup, requires operator action.
+    return PART_ERROR if part_errors(current) else 0
+
+
+def status(args):
+    pids = processes(args.profile)
+    current = state(args.url) if pids else None
+    print(json.dumps({'pids': pids, 'cwd': str(ROOT), 'url': args.url,
+                      'manually_stopped': stopped(args.profile), 'health': current and current['health'],
+                      'errors': current and current['errors'], 'setup': current and current['setup'],
+                      'feishu': current and current['feishu']}, ensure_ascii=False, indent=2))
+    return outcome(pids, current)
+
+
+def stop(args, intentional=True):
+    """Stop the service gracefully, recording a manual stop marker when `intentional` is True."""
+    pids = processes(args.profile)
+    if len(pids) > 1:
+        raise RuntimeError('Multiple dsh-foreman processes found; refusing to choose one.')
+    # Write the stop marker before waiting so monitors respect the intentional stop even if graceful shutdown times out.
+    if intentional:
+        (control(args.profile) / 'manually-stopped').write_text(time.strftime('%Y-%m-%dT%H:%M:%S%z') + '\n')
+    for pid in pids:
+        os.kill(pid, signal.SIGINT)
+    deadline = time.monotonic() + args.stop_timeout
+    while any(running(pid, args.profile) for pid in pids):
+        if time.monotonic() >= deadline:
+            raise RuntimeError('Graceful stop timed out; no forced kill was sent. Check status.')
+        time.sleep(0.5)
+    (control(args.profile) / 'service.pid').unlink(missing_ok=True)
+    print('dsh-foreman stopped. Automatic recovery is paused until start/restart.' if intentional else 'dsh-foreman stopped.')
+
+
+def prune_logs(profile):
+    """Retain only the newest `KEEP_LOGS` log files for `profile`."""
+    name = re.compile(re.escape(f'dsh-foreman-{profile}-') + r'\d{8}-\d{6}-\d+\.log')
+    logs = sorted((path for path in ARTIFACTS.iterdir() if name.fullmatch(path.name)), key=lambda path: path.stat().st_mtime)
+    for path in logs[:-KEEP_LOGS]:
+        path.unlink(missing_ok=True)
+
+
+def start(args):
+    session = 'dsh-' + args.profile
+    pids = processes(args.profile)
+    if len(pids) > 1:
+        raise RuntimeError('Multiple dsh-foreman processes found; refusing to start another.')
+    if not pids:
+        dsh = shutil.which('dsh')
+        if not dsh or not shutil.which('tmux'):
+            raise RuntimeError('Both dsh and tmux must be on PATH.')
+        exists = subprocess.run(['tmux', 'has-session', '-t', '=' + session],
+                                capture_output=True).returncode == 0
+        if state(args.url) is not None:
+            raise RuntimeError('An existing orchestrator answers at this URL; refusing duplicate startup.')
+        stamp = time.strftime('%Y%m%d-%H%M%S')
+        log = ARTIFACTS / f'dsh-foreman-{args.profile}-{stamp}-{os.getpid()}.log'
+        log.touch()
+        prune_logs(args.profile)
+        # `exec` replaces the shell so the pane PID printed by tmux is the DSH service process itself.
+        command = ('umask 077; exec ' + shlex.join([dsh, '--profile', args.profile, '--no-open'])
+                   + ' >> ' + shlex.quote(str(log)) + ' 2>&1')
+        # Reuse an existing tmux session without disturbing other windows.
+        target = ['new-window', '-t', '=' + session + ':'] if exists else ['new-session', '-s', session]
+        pane = subprocess.run(['tmux', *target, '-d', '-P', '-F', '#{pane_pid}', '-n', 'server', '-c', str(ROOT), command],
+                              check=True, capture_output=True, text=True).stdout.strip()
+        if pane.isdigit():
+            (control(args.profile) / 'service.pid').write_text(pane + '\n')
+        print('Log: ' + str(log), flush=True)
+    else:
+        (control(args.profile) / 'service.pid').write_text(f'{pids[0]}\n')
+        print(f'dsh-foreman already running (PID {pids[0]}); no duplicate started.', flush=True)
+    (control(args.profile) / 'manually-stopped').unlink(missing_ok=True)
+    deadline = time.monotonic() + args.timeout
+    while time.monotonic() < deadline:
+        current = state(args.url)
+        if processes(args.profile) and runtime_up(current):
+            code = status(args)
+            if current['setup']:
+                print('dsh-foreman is waiting for setup: ' + str(current['setup'].get('detail', '')))
+                print('Open the URL DSH printed in the log, then the dsh-foreman overview.')
+            if current['feishu']:
+                print('dsh-foreman runs without Feishu: ' + str(current['feishu'].get('detail', '')))
+                print('Fix it on the Feishu card of the Source settings.')
+            for name, detail in part_errors(current).items():
+                print(f'{name} reports an error, which a restart does not fix: {detail}')
+            return code
+        time.sleep(1)
+    status(args)
+    raise RuntimeError('Startup health check timed out; inspect the log. Any running process was left intact.')
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('action', choices=['start', 'stop', 'restart', 'status'])
+    parser.add_argument('--profile', default=os.environ.get('DSH_SUPERAGENT_PROFILE') or 'superagent',
+                        help='DSH profile that loads dsh-foreman; its tmux session is dsh-<profile>.')
+    parser.add_argument('--url', default=os.environ.get('DSH_SUPERAGENT_URL') or 'http://127.0.0.1:3082',
+                        help='Health-check URL; override after changing the profile port.')
+    parser.add_argument('--timeout', type=float, default=60, help='Startup timeout in seconds.')
+    parser.add_argument('--stop-timeout', type=float, default=300,
+                        help='Graceful shutdown timeout in seconds; running Executor Sessions finish their step first.')
+    parser.add_argument('--respect-stop', action='store_true',
+                        help='For monitoring: never start/restart after an intentional stop.')
+    args = parser.parse_args()
+    if args.timeout <= 0 or args.stop_timeout <= 0:
+        parser.error('--timeout and --stop-timeout must be positive')
+    if not re.fullmatch(r'[A-Za-z0-9_][A-Za-z0-9_.-]*', args.profile):
+        parser.error('--profile must be a DSH profile name')
+    os.umask(0o077)
+    with (control(args.profile) / 'operation.lock').open('a') as lock:
+        try:
+            fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            raise RuntimeError('Another dsh-foreman control operation is in progress.') from None
+        if args.respect_stop and args.action in ('start', 'restart') and stopped(args.profile):
+            print('Intentional stop is active; automatic recovery skipped.')
+            return 0
+        if args.action == 'status':
+            return status(args)
+        if args.action in ('stop', 'restart'):
+            # Only a stop keeps automatic recovery off; a restart whose stop timed out leaves it on.
+            stop(args, intentional=args.action == 'stop')
+        if args.action in ('start', 'restart'):
+            return start(args)
+    return 0
+
+
+if __name__ == '__main__':
+    try:
+        sys.exit(main())
+    except (OSError, RuntimeError, subprocess.CalledProcessError) as error:
+        print(str(error), file=sys.stderr)
+        sys.exit(1)

package/scripts/migrate.mjs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+/**
+ * Pack and verify a hub migration.
+ *
+ * Moving the hub is "stop, pack, copy, unpack at the same absolute paths, start". The one step that cannot be
+ * skipped is the SQLite checkpoint: the database runs in WAL mode, so the newest writes live in a `-wal` file, and
+ * copying only the `.sqlite` silently loses them. srv-01 has no `sqlite3` command, so the checkpoint goes through
+ * `node:sqlite` here.
+ *
+ * The script is plain ESM with no dependencies, because it has to run on a machine where the hub may not be
+ * installed. On Windows it only checkpoints and prints what to copy: `tar` is not guaranteed there, and a silent
+ * half-copy is worse than a printed list.
+ */
+import { spawnSync } from 'node:child_process'
+import { existsSync, lstatSync, mkdirSync, readdirSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { DatabaseSync } from 'node:sqlite'
+
+/** The directories a move must carry. `storages` is not optional: it holds the workspace UUIDs the main Sessions are keyed by. */
+const DIRECTORIES = ['state/superagent', 'storages', 'sessions', 'attachments', 'profiles']
+/** The database inside the state directory. */
+const DATABASE = 'state/superagent/orchestrator.sqlite'
+
+const usage = `Usage:
+  node scripts/migrate.mjs plan       --home <dir>
+  node scripts/migrate.mjs checkpoint --home <dir>
+  node scripts/migrate.mjs pack       --home <dir> --out <tar>
+  node scripts/migrate.mjs verify     --home <dir>
+
+--home is the DSH_HOME of the instance being moved (default: $DSH_HOME, else ~/.dsh).`
+
+/** Reads `--name value` pairs; a missing value is an error rather than an empty string. */
+function options(argv) {
+  const values = new Map()
+  for (let index = 0; index < argv.length; index++) {
+    const name = argv[index]
+    if (!name.startsWith('--')) throw new Error(`unexpected argument ${name}\n\n${usage}`)
+    const value = argv[index + 1]
+    if (value === undefined || value.startsWith('--')) throw new Error(`${name} needs a value\n\n${usage}`)
+    values.set(name.slice(2), value)
+    index++
+  }
+  return values
+}
+
+/** The DSH home to act on: `--home`, else `$DSH_HOME`, else `~/.dsh`. */
+function homeOf(values) {
+  const given = values.get('home') ?? process.env.DSH_HOME ?? join(process.env.HOME ?? process.env.USERPROFILE ?? '.', '.dsh')
+  return resolve(given)
+}
+
+/** Refuses a directory that is not a DSH home, so a typo cannot checkpoint or pack the wrong database. */
+function requireHome(home) {
+  const database = join(home, DATABASE)
+  if (!existsSync(database)) throw new Error(`${home} is not a DSH home: ${database} does not exist`)
+  return database
+}
+
+/**
+ * Checkpoints the WAL into the database file and closes it.
+ *
+ * `TRUNCATE` writes the frames back and empties the `-wal`, which is what makes a plain file copy complete. A
+ * checkpoint that reports it could not finish throws: packing a database that still has unmerged writes is exactly
+ * the silent data loss this step exists to prevent.
+ */
+function checkpoint(home) {
+  const database = requireHome(home)
+  const db = new DatabaseSync(database)
+  try {
+    const row = db.prepare('PRAGMA wal_checkpoint(TRUNCATE)').get()
+    // The pragma answers { busy, log, checkpointed }: `busy` non-zero means another connection still holds the WAL.
+    if (row && Number(row.busy) !== 0) throw new Error(`the database is still in use by another process (busy=${row.busy}); stop the hub first`)
+  } finally {
+    db.close()
+  }
+  return database
+}
+
+/** Prints what a move carries, with each directory's size, so a partial copy is visible before it happens. */
+function plan(home) {
+  requireHome(home)
+  const lines = [`home: ${home}`, `database: ${DATABASE}`, '']
+  let total = 0
+  for (const directory of DIRECTORIES) {
+    const path = join(home, directory)
+    if (!existsSync(path)) { lines.push(`  ${directory}: absent`); continue }
+    const bytes = sizeOf(path)
+    total += bytes
+    lines.push(`  ${directory}: ${bytes} bytes`)
+  }
+  lines.push('', `total: ${total} bytes`, '', 'Copy these to the same absolute paths on the new machine; the database must keep its path or the ledger\'s absolute paths break.')
+  return lines.join('\n')
+}
+
+/** Total bytes of a file or directory tree, without following links. */
+/**
+ * Total bytes under a path.
+ *
+ * Walks the tree itself rather than shelling out to `du`: `du -sb` is GNU-specific, and on a platform whose `du`
+ * lacks `-b` (macOS/BSD) the command fails and the old fallback reported only the directory inode's size — a number
+ * small enough to look like the tree was empty, on the one page an operator reads before deciding the copy is small.
+ * Links are counted as their own size and not followed, so a symlink loop cannot hang the walk.
+ */
+function sizeOf(path) {
+  let info
+  try { info = lstatSync(path) }
+  catch { return 0 }
+  if (!info.isDirectory()) return info.size
+  let total = info.size
+  let entries
+  try { entries = readdirSync(path) } catch { return total }
+  for (const name of entries) total += sizeOf(join(path, name))
+  return total
+}
+
+/** Packs the directories into a tar, after the checkpoint. Windows has no guaranteed `tar`, so it prints instead. */
+function pack(home, out) {
+  const database = checkpoint(home)
+  if (process.platform === 'win32') {
+    throw new Error(`on Windows this script only checkpoints (${database}); copy ${DIRECTORIES.join(', ')} to the new machine with the same absolute paths, then run verify there`)
+  }
+  mkdirSync(dirname(out), { recursive: true })
+  const existing = DIRECTORIES.filter(directory => existsSync(join(home, directory)))
+  const result = spawnSync('tar', ['-czf', out, '-C', home, ...existing], { stdio: 'inherit' })
+  if (result.status !== 0) throw new Error(`tar failed with status ${result.status}`)
+  return out
+}
+
+/**
+ * Checks that what a finished move produced is usable: the database opens, the checkpoint took, and the workspace
+ * copy is present. It prints counts rather than asserting a specific number, because the number depends on the
+ * instance — the operator compares it with the old machine's.
+ */
+function verify(home) {
+  const database = requireHome(home)
+  // Re-checkpointing is safe and tells us whether the WAL came back after the copy.
+  const db = new DatabaseSync(database)
+  let checkpointed
+  try {
+    checkpointed = db.prepare('PRAGMA wal_checkpoint(TRUNCATE)').get()
+    const busy = checkpointed ? Number(checkpointed.busy) : 0
+    if (busy !== 0) throw new Error('the database is in use; stop the hub before verifying a move')
+  } finally {
+    db.close()
+  }
+  const counts = {}
+  const counting = new DatabaseSync(database)
+  try {
+    for (const table of ['kv', 'trigger', 'ticket']) {
+      // A fresh or partially built database may lack a table; report that rather than failing the whole verify.
+      try { counts[table] = String(counting.prepare(`SELECT count(*) AS n FROM ${table}`).get()?.n ?? 0) } catch { counts[table] = 'absent' }
+    }
+  } finally {
+    counting.close()
+  }
+  const lines = [
+    `home: ${home}`,
+    'checkpoint ok',
+    `workspace.json: ${existsSync(join(home, 'storages/workspace.json')) ? 'present' : 'MISSING'}`,
+    `tickets: ${counts.ticket}`,
+    `rows: kv=${counts.kv} trigger=${counts.trigger} ticket=${counts.ticket}`,
+  ]
+  for (const directory of DIRECTORIES) {
+    if (!existsSync(join(home, directory))) lines.push(`missing directory: ${directory}`)
+  }
+  return lines.join('\n')
+}
+
+const [command, ...rest] = process.argv.slice(2)
+if (command === undefined || ['-h', '--help', 'help'].includes(command)) {
+  console.log(usage)
+  process.exit(0)
+}
+try {
+  const values = options(rest)
+  const home = homeOf(values)
+  if (command === 'plan') console.log(plan(home))
+  else if (command === 'checkpoint') console.log(`checkpoint ok: ${checkpoint(home)}`)
+  else if (command === 'pack') {
+    const out = values.get('out')
+    if (out === undefined) throw new Error(`pack needs --out <tar>\n\n${usage}`)
+    console.log(`packed: ${pack(home, resolve(out))}`)
+  } else if (command === 'verify') console.log(verify(home))
+  else throw new Error(`unknown command ${command}\n\n${usage}`)
+} catch (error) {
+  console.error(`migrate: ${error instanceof Error ? error.message : String(error)}`)
+  process.exit(1)
+}