@twinsearth/w2m-dsh-plugin 0.6.3 → 0.8.0

package/src/chatops/account.mjs

@@ -0,0 +1,361 @@
+/**
+ * Account identity, the serial number, and the hardware fingerprint (v0.7.5).
+ *
+ * ## What this is
+ *
+ * Stage 1 of `docs/ACCOUNT-FLEET-DESIGN.md`: the root of the whole scheme. Everything later —
+ * the device keypair, the relay's authorisation model, the fleet-scoped dispatch — depends on
+ * knowing *which account* a machine belongs to and *which machine* it is. Neither existed before
+ * this file: `machine_id` was a bare `randomUUID()` with no account and no hardware in it.
+ *
+ * ## The identity source is read, not fetched
+ *
+ * The account code comes from `ctx.deepseekAccount.getDeviceIdentity()`, whose contract is
+ * *"read existing login identity without creating a device or returning credentials"*. It
+ * returns `{ deviceId?, userId?, osVersion }`, and `userId` is the account's unique identifier.
+ *
+ * So there is **no account API call here**, and there is deliberately **no way to set the account
+ * code from configuration**. That second point is not a limitation to work around: a value an
+ * operator can type is a value an attacker can type, so a hand-entered "account code" would be a
+ * forgeable account code. The only accepted source is the one the host authenticates.
+ *
+ * ## Three things this file refuses to pretend
+ *
+ * **1. The serial number is not a credential.** It is computed from local inputs, so anyone who
+ * knows or guesses an account id can produce a well-formed one. It exists to be **displayed** and
+ * to be **grouped by prefix**, and the relay must never trust it. `isWellFormedSn` validates
+ * *shape*, and its name says shape — it is not and must not be called an authorisation check.
+ *
+ * **2. The timestamp is not what makes an SN unique.** Uniqueness is `(ACCT, HWID)`. The timestamp
+ * distinguishes a re-registration of the same hardware from a second machine, and makes the string
+ * auditable. Calling it a security feature would be an overclaim.
+ *
+ * **3. A fingerprint that changes is worse than none.** It makes one machine look like two, which
+ * fragments a fleet. So sources that change in normal use — MAC addresses, IPs, mount points,
+ * installed-package lists — are **excluded on purpose**, and each exclusion is a choice with a
+ * reason rather than an omission.
+ */
+
+import { createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { promisify } from 'node:util';
+
+const run = promisify(execFile);
+
+/** SN shape. `W2M-` then three dash-separated hex groups of 8, 12 and 14 characters. */
+export const SN_PATTERN = /^W2M-([0-9a-f]{8})-([0-9a-f]{12})-(\d{14})$/;
+
+/** How much of a hash goes into the account code. 8 hex = 32 bits. See the collision note below. */
+export const ACCT_HEX = 8;
+/** How much goes into the hardware code. 12 hex = 48 bits. */
+export const HWID_HEX = 12;
+
+/**
+ * Derive the account code.
+ *
+ * **Hashed, not raw.** The `userId` is an account identifier, and this code ends up in places a
+ * login identifier should not: device lists, log lines, chat messages, `w2m_devices` output.
+ * Taking a truncated hash keeps the one property grouping needs — the same account hashes the
+ * same way on every machine — without shipping the identifier itself around.
+ *
+ * **The cost of 32 bits, stated rather than hidden.** Two different accounts colliding would
+ * merge two fleets. That needs roughly 2^16 distinct accounts on one relay before it is likely,
+ * which is far beyond any real deployment; the design document records the detection step for the
+ * case where it is not.
+ */
+export function accountCode(userId) {
+  if (typeof userId !== 'string' || userId.trim() === '') return null;
+  return createHash('sha256').update(userId.trim(), 'utf8').digest('hex').slice(0, ACCT_HEX);
+}
+
+/**
+ * Hash a fingerprint string into the hardware code.
+ *
+ * Normalised first — trimmed, lower-cased, and with runs of whitespace collapsed — because the
+ * same machine reports the same value with different spacing depending on the tool that read it,
+ * and a fingerprint that changes with its reader is a fingerprint that changes.
+ */
+export function hardwareCode(...parts) {
+  const material = parts
+    .filter((p) => typeof p === 'string' && p.trim() !== '')
+    .map((p) => p.trim().toLowerCase().replace(/\s+/g, ' '))
+    .join('\n');
+  if (material === '') return null;
+  return createHash('sha256').update(material, 'utf8').digest('hex').slice(0, HWID_HEX);
+}
+
+/** `YYYYMMDDhhmmss`, UTC. */
+export function timeCode(when = new Date()) {
+  const d = when instanceof Date ? when : new Date(when);
+  if (Number.isNaN(d.getTime())) throw new TypeError('timeCode needs a valid date');
+  const p = (n, width = 2) => String(n).padStart(width, '0');
+  return (
+    `${d.getUTCFullYear()}${p(d.getUTCMonth() + 1)}${p(d.getUTCDate())}` +
+    `${p(d.getUTCHours())}${p(d.getUTCMinutes())}${p(d.getUTCSeconds())}`
+  );
+}
+
+/**
+ * Build the serial number.
+ *
+ * `W2M-<ACCT>-<HWID>-<TS>`. Refuses to produce a partial one: an SN missing its account code
+ * would be a machine that claims no fleet, and silently emitting that is how a machine ends up
+ * in the wrong pool.
+ */
+export function buildSn({ accountCode: acct, hardwareCode: hwid, at = new Date() } = {}) {
+  if (typeof acct !== 'string' || !/^[0-9a-f]{8}$/.test(acct)) {
+    throw new TypeError('buildSn needs an 8-hex account code; without one a machine claims no fleet');
+  }
+  if (typeof hwid !== 'string' || !/^[0-9a-f]{12}$/.test(hwid)) {
+    throw new TypeError('buildSn needs a 12-hex hardware code');
+  }
+  return `W2M-${acct}-${hwid}-${timeCode(at)}`;
+}
+
+/**
+ * Does this string have the shape of an SN?
+ *
+ * **Shape, not authorisation.** The name is deliberate: this answers "is it well formed", and a
+ * caller that treats a `true` here as proof of anything is misusing it. Nothing about an SN is
+ * verifiable by inspection, because it was computed by the party being checked.
+ */
+export function isWellFormedSn(value) {
+  return typeof value === 'string' && SN_PATTERN.test(value);
+}
+
+/** The parts of an SN, or null if it is not well formed. */
+export function parseSn(value) {
+  const m = typeof value === 'string' ? SN_PATTERN.exec(value) : null;
+  if (m === null) return null;
+  return { accountCode: m[1], hardwareCode: m[2], timeCode: m[3] };
+}
+
+/** The account prefix an SN belongs to, for grouping. Null when the SN is malformed. */
+export function fleetOf(value) {
+  const parts = parseSn(value);
+  return parts === null ? null : parts.accountCode;
+}
+
+/**
+ * Hardware sources, per platform, in priority order.
+ *
+ * Each entry says how to read a stable machine identity. `key` names the field in the returned
+ * diagnostic so an operator can see *which* source was used — a fingerprint whose origin is
+ * unknown is one nobody can debug when it changes unexpectedly.
+ *
+ * **What is deliberately absent, and why:**
+ *   * **MAC addresses / IPs** — change with a cable, a dock, a VPN, or a Wi-Fi toggle. A machine
+ *     that re-fingerprints after a network change becomes a second device in the fleet.
+ *   * **Mount points / partition layout** — change when a disk is added or a volume is resized.
+ *   * **Installed packages / versions** — change on every update, so the fingerprint would churn.
+ *   * **Hostname alone** — user-editable in one command on every platform.
+ */
+export const HW_SOURCES = Object.freeze({
+  win32: Object.freeze([
+    Object.freeze({ key: 'MachineGuid', kind: 'registry', path: 'HKLM\\SOFTWARE\\Microsoft\\Cryptography', name: 'MachineGuid' }),
+    Object.freeze({ key: 'SMBIOS-UUID', kind: 'exec', file: 'powershell', args: Object.freeze(['-NoProfile', '-Command', '(Get-CimInstance Win32_ComputerSystemProduct).UUID']) }),
+  ]),
+  darwin: Object.freeze([
+    Object.freeze({ key: 'IOPlatformUUID', kind: 'exec', file: 'ioreg', args: Object.freeze(['-rd1', '-c', 'IOPlatformExpertDevice']), extract: /"IOPlatformUUID"\s*=\s*"([^"]+)"/ }),
+  ]),
+  linux: Object.freeze([
+    Object.freeze({ key: 'machine-id', kind: 'file', path: '/etc/machine-id' }),
+    Object.freeze({ key: 'dbus-machine-id', kind: 'file', path: '/var/lib/dbus/machine-id' }),
+  ]),
+});
+
+/**
+ * Values that mean "this source gave nothing useful".
+ *
+ * A machine with no SMBIOS UUID reports all-zeroes or a placeholder depending on firmware, and
+ * hashing that would give **every such machine the same hardware code** — a far worse failure
+ * than having none, because it silently merges distinct machines.
+ */
+const USELESS = new Set([
+  '',
+  '0',
+  'none',
+  'null',
+  'undefined',
+  '00000000-0000-0000-0000-000000000000',
+  'ffffffff-ffff-ffff-ffff-ffffffffffff',
+  '03000200-0400-0500-0006-000700080009',
+  'to be filled by o.e.m.',
+  'default string',
+  'system serial number',
+]);
+
+/** Is this a value worth hashing? */
+export function isUsefulHardwareValue(value) {
+  if (typeof value !== 'string') return false;
+  const v = value.trim().toLowerCase();
+  return v !== '' && !USELESS.has(v);
+}
+
+/**
+ * Read the raw hardware values, in priority order, and report which were usable.
+ *
+ * Everything is injectable so a test can drive a Windows-shaped machine on Linux, or a Darwin
+ * fixture in CI, without the host having that platform's tools — the alternative is a suite that
+ * only exercises whichever platform it happens to run on.
+ *
+ * @param {object} [options]
+ * @param {string} [options.platform]
+ * @param {(spec: object) => Promise<string|null>} [options.read] Default reader; override wholly in tests.
+ * @param {(file: string, args: string[]) => Promise<string>} [options.exec]
+ * @param {(path: string) => Promise<string>} [options.readFile]
+ * @param {(event: string, detail?: object) => void} [options.audit]
+ */
+export async function readHardwareValues(options = {}) {
+  const platform = options.platform ?? process.platform;
+  const sources = HW_SOURCES[platform] ?? [];
+  const execImpl = options.exec ?? (async (file, args) => {
+    const { stdout } = await run(file, args, { windowsHide: true, timeout: 5000 });
+    return stdout;
+  });
+  const readFileImpl = options.readFile ?? ((path) => readFile(path, 'utf8'));
+  const audit = options.audit ?? (() => {});
+
+  const readOne = options.read ?? (async (spec) => {
+    if (spec.kind === 'file') return readFileImpl(spec.path);
+    if (spec.kind === 'exec') {
+      const out = await execImpl(spec.file, spec.args);
+      if (spec.extract) {
+        const m = spec.extract.exec(out);
+        return m === null ? null : m[1];
+      }
+      return out;
+    }
+    if (spec.kind === 'registry') {
+      // `reg query` is used rather than a native call so there is no dependency beyond Windows
+      // itself, and so the same `exec` seam covers every source.
+      const out = await execImpl('reg', ['query', spec.path, '/v', spec.name]);
+      const m = /REG_SZ\s+(\S+)/.exec(out);
+      return m === null ? null : m[1];
+    }
+    return null;
+  });
+
+  const values = [];
+  for (const spec of sources) {
+    let raw = null;
+    try {
+      raw = await readOne(spec);
+    } catch (error) {
+      // A source that cannot be read is not a failure of the fingerprint: the next source is the
+      // point of having a list. It is recorded so an operator can see the list was cut short.
+      audit('hw/source-failed', { source: spec.key, detail: error instanceof Error ? error.message : String(error) });
+      continue;
+    }
+    const value = typeof raw === 'string' ? raw.trim() : '';
+    if (!isUsefulHardwareValue(value)) {
+      audit('hw/source-unusable', { source: spec.key, value: value.slice(0, 40) });
+      continue;
+    }
+    values.push({ source: spec.key, value });
+  }
+  return { platform, values };
+}
+
+/**
+ * The host-facing identity service.
+ *
+ * `getDeviceIdentity()` is read off the context rather than imported, because it is a Cordis
+ * service and an optional one: a host without it must produce a named refusal, not a crash. That
+ * is what `ctx.get('deepseekAccount')` is for.
+ *
+ * @param {object} options
+ * @param {object} [options.ctx] A Cordis context exposing `get('deepseekAccount')`.
+ * @param {object} [options.account] The service itself, injected directly in tests.
+ * @param {string} [options.platform]
+ * @param {object} [options.hardware] Overrides for `readHardwareValues`.
+ * @param {object} [options.stored] An SN already on disk, so it is never regenerated.
+ * @param {(event: string, detail?: object) => void} [options.audit]
+ */
+export function createAccountIdentity(options = {}) {
+  const audit = options.audit ?? (() => {});
+  const platform = options.platform ?? process.platform;
+
+  function accountService() {
+    if (options.account) return options.account;
+    if (typeof options.ctx?.get === 'function') return options.ctx.get('deepseekAccount') ?? null;
+    return null;
+  }
+
+  /**
+   * The account's own identifier, or a named reason there is none.
+   *
+   * `signed-out` is a **normal state**, not an error: a machine with no account has no fleet, and
+   * the design says it must not be given a random one instead. Fabricating a placeholder here
+   * would put two unrelated machines in the same pool, which is the exact defect being removed.
+   */
+  async function identify() {
+    const service = accountService();
+    if (service === null || typeof service.getDeviceIdentity !== 'function') {
+      return { ok: false, reason: 'no_account_service', detail: 'the host exposes no deepseekAccount service' };
+    }
+    let identity;
+    try {
+      identity = await service.getDeviceIdentity();
+    } catch (error) {
+      return { ok: false, reason: 'identity_read_failed', detail: error instanceof Error ? error.message : String(error) };
+    }
+    const userId = typeof identity?.userId === 'string' && identity.userId.trim() !== '' ? identity.userId : null;
+    if (userId === null) {
+      return { ok: false, reason: 'signed-out', detail: 'no DeepSeek account is signed in on this machine' };
+    }
+    const acct = accountCode(userId);
+    if (acct === null) return { ok: false, reason: 'bad_account_id', detail: 'the account id hashed to nothing' };
+    audit('account/identified', { account_code: acct });
+    return { ok: true, accountCode: acct, deviceId: identity.deviceId ?? null, osVersion: identity.osVersion ?? null };
+  }
+
+  /** The hardware code, and which source produced it. */
+  async function fingerprint() {
+    const { values } = await readHardwareValues({ platform, ...options.hardware });
+    if (values.length === 0) {
+      return { ok: false, reason: 'no_hardware_source', detail: `no usable hardware identity on ${platform}` };
+    }
+    const hwid = hardwareCode(...values.map((v) => v.value));
+    if (hwid === null) return { ok: false, reason: 'no_hardware_source', detail: 'the values hashed to nothing' };
+    return { ok: true, hardwareCode: hwid, sources: values.map((v) => v.source) };
+  }
+
+  /**
+   * The identity this machine should present.
+   *
+   * A stored SN is returned unchanged, always. Regenerating it would change the machine's identity
+   * on every start — every restart would look like a new device, and the fleet would fill with
+   * ghosts of one machine.
+   */
+  async function resolve() {
+    if (options.stored !== undefined && options.stored !== null) {
+      const parsed = parseSn(options.stored);
+      if (parsed === null) {
+        return { ok: false, reason: 'stored_sn_malformed', detail: options.stored };
+      }
+      return { ok: true, sn: options.stored, ...parsed, reused: true };
+    }
+    const account = await identify();
+    if (!account.ok) return account;
+    const hardware = await fingerprint();
+    if (!hardware.ok) return hardware;
+    const sn = buildSn({ accountCode: account.accountCode, hardwareCode: hardware.hardwareCode, at: options.at ?? new Date() });
+    audit('account/sn-created', { sn, sources: hardware.sources });
+    return {
+      ok: true,
+      sn,
+      accountCode: account.accountCode,
+      hardwareCode: hardware.hardwareCode,
+      timeCode: parseSn(sn).timeCode,
+      hardwareSources: hardware.sources,
+      reused: false,
+    };
+  }
+
+  return { identify, fingerprint, resolve };
+}
+
+/** The config keys an SN needs in order to survive a restart. */
+export const SN_STATE_KEY = 'sn';

package/src/chatops/actions.mjs

@@ -0,0 +1,227 @@
+/**
+ * The action set the chat bridge calls, and how a fleet result becomes a sentence (v0.7.2).
+ *
+ * ## What this file is for
+ *
+ * `bridge.mjs` takes an `actions` object and hands it to `commands.mjs`. Until now nothing
+ * produced one for the real fleet, so `/run` could only ever answer "this install has no fleet".
+ * This is that producer: it takes the executor from `fleet.mjs` and the DSH-facing operations
+ * the host supplies, and returns something a command handler can call.
+ *
+ * ## The formatting rule
+ *
+ * A chat reply is read on a phone, once, and often while walking. So a verdict is never
+ * paraphrased into "done" or "failed" — the relay's own word is shown, with the machine names
+ * that produced it, because `divergent-platform` and `divergent` mean different things and
+ * collapsing them turns a platform difference into a bug report. Long output is truncated at a
+ * line boundary with the omission **stated**, never silently cut.
+ *
+ * ## What is injected and what is real
+ *
+ * The fleet half is real: it talks to the relay. The session half (`listSessions`, `bind`,
+ * `tail`, `prompt`, `setPolicy`) is the DSH host's, because only the host knows its sessions —
+ * so it is injected, and a host that supplies none gets named refusals rather than silence.
+ */
+
+import { CAPABILITY } from './commands.mjs';
+
+/** How much of a task's output is worth putting on a phone. */
+export const DEFAULT_TAIL_LINES = 24;
+
+/** Truncate at a line boundary and say so. A silent cut reads as "that was all of it". */
+export function tailLines(text, limit = DEFAULT_TAIL_LINES) {
+  const lines = String(text ?? '').split('\n');
+  if (lines.length <= limit) return lines.join('\n');
+  const kept = lines.slice(-limit);
+  return [`…（省略前 ${lines.length - limit} 行）`, ...kept].join('\n');
+}
+
+/**
+ * A one-line-per-machine summary, using the field names a live relay actually returns.
+ *
+ * Measured on a report: each row carries `machine_name`, `outcome` (the per-machine verdict),
+ * `status` (what the process did — `nonzero_exit`, `ok`), `lease_state`, and `exit_code`. The
+ * first version of this read `machine`/`verdict`, which are both `undefined` in a real response,
+ * so every machine would have printed as `?: ?` while the task completed perfectly.
+ */
+export function describeMachines(body) {
+  const rows = [];
+  for (const key of ['machines', 'leases', 'results']) {
+    if (Array.isArray(body?.[key])) {
+      rows.push(...body[key]);
+      break;
+    }
+  }
+  if (rows.length === 0 && body && typeof body === 'object' && !Array.isArray(body)) {
+    // A map keyed by machine name, which some shapes use. An empty object is not a map of zero
+    // machines and must not be reported as one — `[]` and "no per-machine shape at all" are the
+    // same answer, and the empty case is the one an unstarted task produces.
+    const entries = Object.entries(body).filter(([, v]) => v && typeof v === 'object');
+    if (entries.length > 0 && entries.every(([, v]) => 'verdict' in v || 'status' in v || 'outcome' in v)) {
+      rows.push(...entries.map(([name, value]) => ({ machine_name: name, ...value })));
+    }
+  }
+  return rows.map((entry) => {
+    const name = entry.machine_name ?? entry.machine ?? entry.name ?? entry.machine_id ?? '?';
+    // The per-machine verdict is `outcome`; `status` is what the process did, which is a
+    // different fact and is shown alongside rather than instead of it.
+    const parts = [`${name}: ${entry.outcome ?? entry.verdict ?? entry.lease_state ?? '?'}`];
+    if (entry.status !== undefined && entry.status !== entry.outcome) parts.push(`status ${entry.status}`);
+    if (entry.exit_code !== undefined && entry.exit_code !== null) parts.push(`exit ${entry.exit_code}`);
+    return parts.join('  ');
+  });
+}
+
+/**
+ * Turn a completed wait into the sentence that goes to the phone.
+ *
+ * Kept separate from the executor so it is testable without a relay, and so the wording lives
+ * in one place instead of being assembled at three call sites.
+ */
+export function formatRunResult({ taskId, wait, report = null, argv = [] }) {
+  if (!wait?.ok) return `派发失败：${wait?.text ?? wait?.reason ?? '未知原因'}`;
+  const verdict = wait.verdict ?? 'unknown';
+  const lines = [`任务 ${String(taskId).slice(0, 8)} — ${verdict}`];
+  if (argv.length > 0) lines.push(`命令：${argv.join(' ')}`);
+
+  const machines = describeMachines(wait.body) ?? [];
+  if (machines.length > 0) lines.push(...machines);
+
+  if (!wait.terminal) {
+    // Said plainly, because "no verdict" and "a verdict of timeout" are different and the
+    // operator can act on only one of them.
+    lines.push(`（等满 ${Math.round((wait.maxMs ?? 0) / 1000)}s 仍未结束，任务还在跑）`);
+  }
+  if (report) {
+    const failures = (report.failed ?? []).slice(0, 5);
+    if (failures.length > 0) {
+      lines.push('失败机器：');
+      for (const f of failures) lines.push(`  ${f.machine ?? f.machine_name ?? '?'}: ${f.reason ?? f.detail ?? '?'}`);
+    }
+  }
+  const output = report?.stdout ?? wait.body?.stdout ?? null;
+  if (typeof output === 'string' && output.trim() !== '') {
+    lines.push('输出：', tailLines(output));
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Build the action set.
+ *
+ * @param {object} options
+ * @param {object} options.executor From `createFleetExecutor`.
+ * @param {object} [options.host] The DSH-facing half: listSessions, boundSession, bind, tail,
+ *        prompt, setPolicy. Anything absent becomes a named refusal.
+ * @param {object} [options.policy] From `policy.mjs`, for /trust and /untrust.
+ * @param {number} [options.waitMs] How long /run will hold the phone before answering.
+ * @param {boolean} [options.autoWait] Whether /run waits at all, or only dispatches.
+ * @param {(event: string, detail?: object) => void} [options.audit]
+ */
+export function createChatopsActions(options) {
+  const executor = options.executor;
+  if (!executor) throw new TypeError('createChatopsActions requires an executor');
+  const host = options.host ?? {};
+  const policy = options.policy ?? null;
+  const waitMs = options.waitMs ?? 90_000;
+  const autoWait = options.autoWait !== false;
+  const audit = options.audit ?? (() => {});
+
+  /** A host operation that is absent, named rather than silently returning nothing. */
+  const missing = (what) => () => {
+    throw new Error(`这个安装没有接入 ${what}`);
+  };
+
+  const actions = {
+    // ---- the DSH half: injected, because only the host knows its sessions ----
+    listSessions: typeof host.listSessions === 'function' ? host.listSessions : missing('会话列表'),
+    boundSession: typeof host.boundSession === 'function' ? host.boundSession : async () => null,
+    bind: typeof host.bind === 'function' ? host.bind : missing('会话绑定'),
+    tail: typeof host.tail === 'function' ? host.tail : missing('会话输出'),
+    prompt: typeof host.prompt === 'function' ? host.prompt : undefined,
+    setPolicy: typeof host.setPolicy === 'function' ? host.setPolicy : missing('策略设置'),
+
+    // ---- the fleet half: real, and the reason this release exists ----
+
+    /** Machines, mapped onto the shape `/machines` prints. */
+    async listMachines() {
+      const result = await executor.devices();
+      if (!result.ok) throw new Error(result.text ?? result.reason);
+      return result.devices.map((device) => ({
+        id: device.machine_id ?? device.id ?? '?',
+        name: device.name ?? device.machine_name ?? '?',
+        os: device.platform ?? device.os ?? null,
+        arch: device.arch ?? null,
+        online: device.online !== false && device.state !== 'stale',
+      }));
+    },
+
+    /**
+     * `/run` — dispatch, then either wait or say where to look.
+     *
+     * The argv is passed through untouched. It is **not** joined into a shell string anywhere:
+     * a chat message is attacker-influenced text, and the whole reason this fleet takes an argv
+     * array is that no shell ever sees it.
+     */
+    async dispatch(argv) {
+      const dispatched = await executor.run(argv);
+      if (!dispatched.ok) return { taskId: null, summary: dispatched.text };
+      audit('chatops/run-dispatched', { task_id: dispatched.taskId, argv });
+
+      if (!autoWait) {
+        return {
+          taskId: dispatched.taskId,
+          summary: `已派发：${argv.join(' ')}\n任务 ${String(dispatched.taskId).slice(0, 8)}，用 /report ${String(dispatched.taskId).slice(0, 8)} 查看结果。`,
+        };
+      }
+
+      const waited = await executor.wait(dispatched.taskId, { maxMs: waitMs });
+      let report = null;
+      if (waited.ok && waited.terminal) {
+        const fetched = await executor.report(dispatched.taskId);
+        if (fetched.ok) report = fetched.raw;
+      }
+      return {
+        taskId: dispatched.taskId,
+        summary: formatRunResult({ taskId: dispatched.taskId, wait: { ...waited, maxMs: waitMs }, report, argv }),
+      };
+    },
+
+    /** `/where` — which machine answered, and with what. */
+    async where(taskId) {
+      const read = await executor.status(taskId);
+      if (!read.ok) return { text: read.text ?? read.reason };
+      const body = read.raw ?? {};
+      const verdict = body.verdict ?? body.status ?? 'unknown';
+      const lines = [`任务 ${String(taskId).slice(0, 8)} — ${verdict}`];
+      const machines = describeMachines(body);
+      if (machines.length > 0) lines.push(...machines);
+      else lines.push('（还没有机器回报）');
+      return { text: lines.join('\n') };
+    },
+
+    /** `/report` — the full per-machine report, truncated for a phone. */
+    async fullReport(taskId) {
+      const fetched = await executor.report(taskId);
+      if (!fetched.ok) return { text: fetched.text ?? fetched.reason };
+      const body = fetched.raw ?? {};
+      const lines = [`任务 ${String(taskId).slice(0, 8)} 报告`];
+      const verdict = body.verdict ?? body.status ?? null;
+      if (verdict) lines.push(`结论：${verdict}`);
+      const machines = describeMachines(body);
+      if (machines.length > 0) lines.push(...machines);
+      const output = body.stdout ?? body.output ?? null;
+      if (typeof output === 'string' && output.trim() !== '') lines.push('输出：', tailLines(output));
+      return { text: lines.join('\n') };
+    },
+
+    // ---- trust, delegated to policy so there is one source of truth ----
+    trust: policy ? (channel, id) => policy.trust(channel, id) : () => ({ ok: false, reason: 'no policy is wired' }),
+    distrust: policy ? (channel, id) => policy.distrust(channel, id) : () => ({ ok: false, reason: 'no policy is wired' }),
+  };
+
+  return actions;
+}
+
+/** Capabilities a chat identity holds once admitted. Re-exported so the host has one import. */
+export const OWNER = CAPABILITY;