dsh-foreman 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,73 +1,8 @@
 # Changelog
 
-本仓库的历史从本项目自己的初始提交开始，**不携带上游 git 历史**（见 README 的「由来与致谢」）。
-下面 `0.2.0` 一节是从代码基线 `dsh-superagent-local` 沿袭下来的、那一份代码相对上游
-`dsh-superagent-prototype` 的改动记录，保留它是为了说明基线里已经有什么；**它不是本项目的发布版本**。
+本仓库是 dsh-foreman（研究方向原型）的本地改造版。下面是相对上游 0.1.0 的改动。
 
-本项目自己的版本从 `0.1.0` 开始。
-
-## 0.1.0 — 2026-11-07
-
-首个公开发布。**一个常驻主 loop，把工单派给多台在线设备上各自完整运行的 DSH，账本只有一份。**
-
-### 新增：设备与派单
-
-- **设备注册表**（`src/foreman/devices.ts`）：同一份 SQLite 里的 `foreman-device:` 家族，
-  令牌只存 SHA-256。加设备、换令牌、吊销都不需要重启主 loop。
-  CLI：`scripts/add-device.mjs add | list | rotate | revoke`。
-- **Selector**（`src/foreman/selector.ts`）：纯函数。吊销的、离线的、没有对应项目 root 的设备先出局；
-  显式点名或标签要求再收窄；剩下的按在跑数量最少，平局取最近心跳。
-- **选择落在 accept 上**：`Ticket.target` 在 accept 时确定，`newAssignment` 复制到
-  `Assignment.target`。选设备在 `prepareTicket` 缝上，**不在** Executor 里——Executor 没有写库通道。
-- **ForemanExecutor**（`src/foreman/executor.ts`）：本机目标原样交给 `DshExecutor`；
-  远端目标变成一个 `assign` 帧。设备不可达时报 `blocked`，**不伪造 failed，也不悄悄改成本机执行**。
-- **Foreman Hub**（`src/foreman/hub.ts` + `ws.ts`）：设备主动外连，`ws` 只出现在一个文件里，
-  只监听 `127.0.0.1`（对外由隧道终结 TLS）。握手校验令牌与协议版本；吊销在下一帧就生效。
-- **文本渲染**（`src/foreman/render.ts`）：任务文本在主 loop 侧定稿，**不带任何主 loop 路径**；
-  附件走 base64 字节，按编码后大小卡 256 KiB 上限。
-
-### 新增：断线与恢复
-
-- **断线绝不自动重派**。`assignmentInterrupted` 会走 `Tickets.restart` 立刻重开一张，
-  而设备可能还在跑——那是「同一件事执行两遍」。超时只转 `blocked`，交给人。
-- Hub 重启时，在飞的远端 assignment 一律先转 `blocked`，等设备 `hello` 对齐；
-  `DshExecutor.resume()` 按 target 跳过远端项。
-- 设备重连后先 `hello` 报「我在跑哪些」，Hub 对齐而不是假设。
-
-### 新增：设备侧插件（另一个包）
-
-- [`dsh-foreman-node`](https://www.npmjs.com/package/dsh-foreman-node)：连出去、接单、回报三件事。
-  job 会话是 `job-<assignmentId>`，权限是 **`workspace-write`**（不是主 loop 自己的 `danger-full-access`：
-  笔记本前没人，弹审批等于卡死）。
-- 设备上注册 `foreman_report` 工具（`progress` / `ready` / `blocked` / `failed`）。
-  **`dropped` 不允许**：那是判断，设备没有判断权。
-
-### 新增：面板
-
-- 「设置 › 设备」：在线点、在跑数、最近活动、项目名（**不显示设备自己的路径**）、吊销与换令牌。
-
-### 新增：飞书群即项目
-
-- Policy 的 `routing.chats`：群 → 工作区，同时约束设备选择（内网群只选带 `intranet` 标签的设备）。
-  映射按 settings 修订号缓存，改了对新到的消息生效。
-
-### 新增：迁移
-
-- `scripts/migrate.mjs`：`plan` / `checkpoint` / `pack` / `verify`。
-  必须先 checkpoint——库跑在 WAL 模式，只拷 `.sqlite` 会**静默丢掉**最近的工单。
-- [docs/migration.md](docs/migration.md) 五步 runbook。
-
-### 依赖
-
-- 唯一新增的运行时依赖是 `ws@8`。
-- `@deepseek-ai/*` 全是 `peerDependencies`，由装了本插件的 DSH 实例提供。
-
----
-
-## 0.2.0 — 2026-11-01（上游基线，非本项目发布）
-
-> 这一节记录的是代码基线 `dsh-superagent-local` 相对上游 `dsh-superagent-prototype` 的改动。
-> 本项目的 `0.1.0` 已包含其中全部内容。
+## 0.2.0 — 2026-11-01
 
 ### 新增：需求来自本机操作者
 

package/cordis.patch.yml

@@ -6,11 +6,11 @@
       name: dsh-foreman
     - id: dsh-foreman-github
       name: dsh-foreman/github-watch
-    # 椋炰功 IM 鏉ユ簮锛氱兢娑堟伅涓庣鑱婅繘宸ュ崟銆傛病鏈夐厤缃満鍣ㄤ汉 CLI 鏃跺畠鑷繁鎶ャ€屾湭璁剧疆鏈哄櫒浜?CLI銆嶏紝
-    # 涓嶅奖鍝嶅埆鐨勬潵婧愶紝鎵€浠ラ粯璁ゅ紑鐫€锛岃浜鸿兘鐩存帴鍦ㄨ缃噷濉€?
+    # 飞书 IM 来源：群消息与私聊进工单。没有配置机器人 CLI 时它自己报「未设置机器人 CLI」，
+    # 不影响别的来源，所以默认开着，让人能直接在设置里填。
     - id: dsh-foreman-feishu
       name: dsh-foreman/feishu-watch
-    # 鏈湴 Source锛氭妸鎿嶄綔鑰呭湪涓讳細璇濋噷璇寸殑璇濆綋浣滈渶姹傛潵婧愶紱涓€涓疄渚嬭鐩栨墍鏈夊伐浣滃尯銆?
+    # 本地 Source：把操作者在主会话里说的话当作需求来源；一个实例覆盖所有工作区。
     - id: dsh-foreman-dsh
       name: dsh-foreman/local-watch
     # The agent preset of every Executor Session (WORKER_PRESET in src/app/sessions.ts); the main Session has its own, below.
@@ -24,8 +24,8 @@
       name: '@deepseek-ai/dsh-agent-preset'
       config:
         id: dsh-foreman-worker
-        name: dsh-foreman 鎵ц鍣?
-        description: dsh-foreman 鐨勬墽琛屽櫒 Session 涓撶敤锛屼笉渚涙墜鍔ㄩ€夋嫨銆傚墠鍙板懡浠よ秴 5 绉掕浆鍏ュ悗鍙帮紝鍙惈鎵ц宸ヤ綔鎵€闇€鐨勫伐鍏枫€?
+        name: dsh-foreman 执行器
+        description: dsh-foreman 的执行器 Session 专用，不供手动选择。前台命令超 5 秒转入后台，只含执行工作所需的工具。
         order: 90
         plugins:
           - id: persona
@@ -129,8 +129,8 @@
       name: '@deepseek-ai/dsh-agent-preset'
       config:
         id: dsh-foreman-router
-        name: dsh-foreman 涓?Session
-        description: dsh-foreman 鐨勪富 Session 涓撶敤锛屼笉渚涙墜鍔ㄩ€夋嫨銆傚墠鍙板懡浠ゅ拰浠诲姟绛夊緟瓒?5 绉掕浆鍏ュ悗鍙帮紝鍙惈璺敱鎵€闇€鐨勫伐鍏枫€?
+        name: dsh-foreman 主 Session
+        description: dsh-foreman 的主 Session 专用，不供手动选择。前台命令和任务等待超 5 秒转入后台，只含路由所需的工具。
         order: 91
         plugins:
           - id: agent-instructions

package/lib/client.js

@@ -4598,7 +4598,18 @@ window.__ModuleLoader__.load({
 			devicesOnline: ["在线", "Online"],
 			devicesRunning: ["在跑", "Running"],
 			devicesEmpty: ["还没有登记任何设备", "No device is registered yet"],
-			devicesEmptyHint: ["在服务器上运行 dsh-foreman 的注册命令生成令牌，再把域名、设备 id 与令牌填进设备自己的配置。", "Mint a token with the hub's registration command, then put the address, device id and token into that device's own configuration."],
+			devicesEmptyHint: ["在下面登记一台设备，它会给出三样东西填进那台设备的配置页。", "Register a machine below; it gives you the three values to put on that machine's own configuration page."],
+			devicesAdd: ["登记一台设备", "Register a machine"],
+			devicesAddHint: ["登记后这台设备才能接单。登记不会连上它——连接由那台设备自己发起。", "A machine takes work only after it is registered here. Registering does not connect it: the machine dials out itself."],
+			devicesAddId: ["设备 id", "Device id"],
+			devicesAddName: ["显示名", "Display name"],
+			devicesAddRoots: ["它能接的项目", "Projects it can take"],
+			devicesAddRoot: ["加一个项目", "Add a project"],
+			devicesAddProject: ["项目名", "Project"],
+			devicesAddPath: ["那台机器上的路径", "Path on that machine"],
+			devicesAddSubmit: ["登记", "Register"],
+			devicesAddMinted: ["把这四样填进那台设备的配置页", "Put these values on that machine's configuration page"],
+			devicesAddMintedHint: ["令牌只显示这一次，库里只存哈希。关掉或刷新这一页就再也拿不回来了；丢了只能换一个。", "The token is shown once; only its hash is stored. Closing or refreshing this page loses it for good, and the only way back is a new one."],
 			deviceOnline: ["在线", "Online"],
 			deviceRevoked: ["已吊销", "Revoked"],
 			deviceRunning: ["在跑 {count} 件", "{count} running"],
@@ -5545,7 +5556,7 @@ window.__ModuleLoader__.load({
 		//#endregion
 		//#region src/client/devices.tsx
 		/** Devices settings group: which machines may take work, whether each is online, and what it is running. */
-		/** The device list, read-only apart from revoking and rotating a token. */
+		/** The device list, the registration form, and the two token actions. */
 		function DevicesSettings() {
 			const { t, call } = usePanel();
 			const { data, error, reload } = usePoll(() => call("GET devices"), []);
@@ -5585,6 +5596,9 @@ window.__ModuleLoader__.load({
 						})
 					]
 				}),
+				/* @__PURE__ */ (0, react_jsx_runtime.jsx)(AddDevice, { onAdded: () => {
+					reload();
+				} }),
 				/* @__PURE__ */ (0, react_jsx_runtime.jsx)(Section, {
 					title: t("devicesList"),
 					children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ListSection, {
@@ -5697,6 +5711,143 @@ window.__ModuleLoader__.load({
 				})]
 			});
 		}
+		/**
+		* Registering a machine, in place.
+		*
+		* The three values the machine needs are shown together and once: the hub keeps only a token hash, so a token that
+		* leaves this card is gone. That is why the card is not dismissible: closing it is losing the token, and the page
+		* says so instead of letting someone find out at the device.
+		*/
+		function AddDevice({ onAdded }) {
+			const { t, call } = usePanel();
+			const { data: state } = usePoll(() => call("GET state"), []);
+			const [id, setId] = (0, react.useState)("");
+			const [name, setName] = (0, react.useState)("");
+			const [roots, setRoots] = (0, react.useState)([]);
+			const [minted, setMinted] = (0, react.useState)();
+			const [refusal, setRefusal] = (0, react.useState)();
+			const [busy, setBusy] = (0, react.useState)(false);
+			const register = async () => {
+				setBusy(true);
+				setRefusal(void 0);
+				try {
+					const result = await call("POST devices", { body: {
+						id: id.trim(),
+						name: name.trim(),
+						labels: [],
+						roots: roots.map((root) => ({
+							project: root.project.trim(),
+							path: root.path.trim()
+						}))
+					} });
+					setMinted({
+						id: result.id,
+						token: result.token
+					});
+					setId("");
+					setName("");
+					setRoots([]);
+					onAdded();
+				} catch (error) {
+					setRefusal(errorText(error));
+				} finally {
+					setBusy(false);
+				}
+			};
+			const edit = (index, patch) => {
+				setRoots((current) => current.map((root, at) => at === index ? {
+					...root,
+					...patch
+				} : root));
+			};
+			const hubPort = state?.setup.machine.hubPort ?? 0;
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)(Card, {
+				title: t("devicesAdd"),
+				hint: t("devicesAddHint"),
+				children: [
+					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)(FieldGrid, { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(Field, {
+						label: t("devicesAddId"),
+						required: true,
+						children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Input, {
+							value: id,
+							onChange: (event) => setId(event.target.value),
+							placeholder: "laptop"
+						})
+					}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Field, {
+						label: t("devicesAddName"),
+						required: true,
+						children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Input, {
+							value: name,
+							onChange: (event) => setName(event.target.value)
+						})
+					})] }),
+					roots.length > 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(FieldGrid, { children: roots.map((root, index) => /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react.Fragment, { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(Field, {
+						label: index === 0 ? t("devicesAddProject") : `${t("devicesAddProject")} ${index + 1}`,
+						children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Input, {
+							value: root.project,
+							onChange: (event) => edit(index, { project: event.target.value }),
+							placeholder: "shop"
+						})
+					}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Field, {
+						label: index === 0 ? t("devicesAddPath") : `${t("devicesAddPath")} ${index + 1}`,
+						children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Input, {
+							value: root.path,
+							onChange: (event) => edit(index, { path: event.target.value }),
+							placeholder: "F:\\\\dsh\\\\shop"
+						})
+					})] }, index)) }),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+						className: "dt-form-actions",
+						children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(Button, {
+							size: "sm",
+							onClick: () => setRoots((current) => [...current, {
+								project: "",
+								path: ""
+							}]),
+							children: t("devicesAddRoot")
+						}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Button, {
+							size: "sm",
+							variant: "primary",
+							busy,
+							disabled: id.trim() === "" || name.trim() === "",
+							onClick: () => {
+								register();
+							},
+							children: t("devicesAddSubmit")
+						})]
+					}),
+					refusal !== void 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ErrorLine, {
+						error: refusal,
+						title: t("loadFailed")
+					})
+				]
+			}), minted && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(Card, {
+				title: t("devicesAddMinted"),
+				tone: "warn",
+				children: [
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)(Hint, { children: t("devicesAddMintedHint") }),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)(KeyValues, { rows: mintedRows(minted, hubPort) }),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("code", {
+						className: "dt-mono",
+						"data-device-token": true,
+						children: minted.token
+					})
+				]
+			})] });
+		}
+		/**
+		* The rows a device needs, with the hub's real port.
+		*
+		* A hub with `hubPort: 0` has its listener switched off, so no address a card could print would work; saying so is
+		* more use than a plausible-looking port that nothing listens on.
+		*/
+		function mintedRows(minted, hubPort) {
+			return [
+				["url", hubPort > 0 ? `ws://127.0.0.1:${hubPort}` : "the hub is off: set hubPort in the plugin configuration"],
+				["deviceId", minted.id],
+				["token", minted.token]
+			];
+		}
 		//#endregion
 		//#region src/client/logs.tsx
 		/**

package/lib/index.js

@@ -8802,6 +8802,10 @@ var RouteError = class extends Error {
 		this.status = status;
 	}
 };
+/** Whether a registration failed because the id is taken, the only failure that is the caller's to fix. */
+function isDuplicateDevice(error) {
+	return error instanceof Error && /is already registered/.test(error.message);
+}
 async function readBody(req, maxBytes = 131072) {
 	let size = 0;
 	const chunks = [];
@@ -8924,12 +8928,13 @@ function failure(error, internal) {
 		id
 	}];
 }
-function machineView({ stateDir, promptMaxChars, admissionContextMaxPages, admissionContextTimeoutMs }) {
+function machineView({ stateDir, promptMaxChars, admissionContextMaxPages, admissionContextTimeoutMs, hubPort }) {
 	return {
 		stateDir,
 		promptMaxChars: promptMaxChars.get(),
 		admissionContextMaxPages: admissionContextMaxPages.get(),
-		admissionContextTimeoutMs: admissionContextTimeoutMs.get()
+		admissionContextTimeoutMs: admissionContextTimeoutMs.get(),
+		hubPort
 	};
 }
 /** Every setup problem the panel shows: global first, then the ones that pause a single Source, each with that Source's title. */
@@ -9169,6 +9174,24 @@ function routes(runtime) {
 			devices: runtime.devices(),
 			online: runtime.onlineDevices()
 		}),
+		/** 登记一台新设备。令牌只在这一次响应里出现，刷新就没了。 */
+		"POST devices": async (input) => {
+			const body = z.object({
+				id: z.string().trim().min(1),
+				name: z.string().trim().min(1),
+				labels: z.array(z.string().trim().min(1)).optional(),
+				roots: z.array(z.object({
+					project: z.string().trim().min(1),
+					path: z.string().trim().min(1)
+				}))
+			}).parse(await input.body());
+			try {
+				return runtime.addDevice(body);
+			} catch (error) {
+				if (isDuplicateDevice(error)) throw new RouteError(400, error.message);
+				throw error;
+			}
+		},
 		/** 吊销一台设备：登记保留（审计要看），下一次心跳就断开。 */
 		"POST devices/:id/revoke": ({ params }) => {
 			runtime.revokeDevice(decodeURIComponent(params.id));
@@ -9962,7 +9985,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 +10054,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 +10083,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: ""
@@ -12358,6 +12399,14 @@ var Runtime = class extends Service {
 			models: () => this.ctx.sessionController.modelCatalog(),
 			devices: () => runtime.devices.list(),
 			onlineDevices: () => runtime.hub?.snapshot() ?? [],
+			/** 登记一台设备并铸一枚令牌；和 `scripts/add-device.mjs` 走同一个 `Devices.add`。 */
+			addDevice: (input) => {
+				const { device, token } = runtime.devices.add(input);
+				return {
+					id: device.id,
+					token
+				};
+			},
 			revokeDevice: (id) => {
 				runtime.devices.revoke(id);
 				runtime.hub?.detach(id);

package/package.json

@@ -2,7 +2,7 @@
   "name": "dsh-foreman",
   "author": "niechao136",
   "license": "MIT",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "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": {
@@ -59,7 +62,7 @@
   },
   "packageManager": "pnpm@11.7.0",
   "dependencies": {
-    "dsh-foreman-node": "0.1.0",
+    "dsh-foreman-node": "0.2.0",
     "proper-lockfile": "4.1.2",
     "ws": "8.22.0",
     "zod": "4.4.3"

package/prompts/admission.md

@@ -28,7 +28,6 @@ The host posts it as a reply to the triggering message; do not quote that messag
 Return rule_assessments with exactly one entry for every enabled rule: rule_id, matched and a factual reason.
 Include negative judgments as matched=false; a reason saying that a rule does not apply cannot be a positive match.
 Never include disabled, unknown or repeated rule IDs.
-Fill device only when the request itself says where the work has to happen — a named machine, an office-only system, a machine the person says they are at. Otherwise leave it out: the host picks the least busy online machine that can reach the project, and a guess here can send work to a machine that cannot do it.
 The host derives positive-only matches from those booleans.
 One source message produces at most one ticket.
 If matching rules conflict or the scope is ambiguous, ignore quietly.

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)
+}