pactive 0.0.2-alpha.1 → 0.0.4-alpha.1

package/bin/pactive.mjs

@@ -18,13 +18,36 @@ const PKG_ROOT = path.resolve(CLI_DIR, '..');
 const FALLBACK_VERSION = '0.0.2-alpha.1';
 const STALE_LOCK_MS = 30 * 60 * 1000;
 
-function usage(io) {
-  io.write(`pactive — proactive companion for Pi / OPCteam / DSH
+function usage(out) {
+  out.write(`pactive — 主动助手：默认全部用自然语言操作，命令只是"可复制的一行"
 
-Usage:
+你可以直接对助手说：
+  「我现在闲不闲？」                      → 看空闲判定与 reason
+  「10 分钟后提醒我喝水」                 → 登记定时任务
+  「主动提醒开启了吗？」                  → 看开关状态
+  「帮我开启主动提醒」                    → 给出可复制命令（人工确认后才生效）
+  「再给我加一个盯盘的助理」              → 给出可复制命令（人工确认后才生效）
+  「我有几个助理？各自开了吗？」          → 列出助理、开关、下次到期
+
+命令（高级/运维）：
   pactive <host> [args...]        run a host with pactive injected (stdio inherited)
   pactive --print-plan <host>     print the launch plan as JSON (no side effects)
   pactive doctor [--json]         diagnose hosts, state root and permissions (read-only)
+  pactive config get [<key>]      print current values and defaults (read-only)
+  pactive config set <key> <value> --confirm   write one config key (human gate)
+  pactive schedule "<prompt>" --when <when> [--assistant <name|id>]   register a timed task
+  pactive tasks [--assistant <name|id>] [--json]   list scheduled tasks (id / kind / due / owner)
+  pactive tick [--assistant <name|id>] [--ensure-fleet] [--json]   one round → ledger（--ensure-fleet 先补 pane）
+  pactive fleet up [--assistant <name|id>] [--all] [--host pi|opcteam|dsh] [--tab <label>] [--dry-run] [--json]
+  pactive fleet ls [--json]                     助理 ↔ herdr pane_id ↔ agent 名 ↔ 状态 ↔ 最近投递
+  pactive fleet down [--assistant <name|id>] [--all]  只关 pane，不动助理（I75）
+  pactive fleet open --assistant <name|id>      焦点到该助理的 pane
+  pactive assistant add <name> [--title …] [--role …] [--scope <glob>] --confirm
+  pactive assistant ls|show <name|id>              list assistants / show one (read-only)
+  pactive assistant enable|disable <name|id> --confirm
+  pactive assistant rename <name|id> <newName> --confirm
+  pactive assistant rm <name|id> --confirm         remove an assistant and its tasks
+  pactive cancel <taskId>         cancel one task
   pactive install <host>          register pactive with a host (idempotent)
   pactive uninstall <host>        unregister pactive and remove pactive state residue
   pactive --version | -v          print the pactive version
@@ -38,6 +61,7 @@ Environment:
   PACTIVE_PI_BIN        override the pi executable
   PACTIVE_OPCTEAM_BIN   override the opcteam executable
   PACTIVE_DSH_BIN       override the dsh executable
+  PACTIVE_HERDR_BIN     override the herdr executable（fleet 复用 herdr；无 herdr 时 fleet 明确拒绝）
 `);
 }
 
@@ -222,6 +246,882 @@ async function doctorReport(env) {
   };
 }
 
+// ─────────────────── 自然语言面向的子命令（契约 §2.1 / I57–I60） ───────────────────
+//
+// 这里是**唯一的人工闸门**：写配置必须显式 --confirm，缺了就 exit 2 且零写盘。
+// stdout 只放 --json，人类可读文本一律走 stderr（沿用 I37）。
+
+const CONFIRM_REFUSAL = 'pactive: refusing to write without --confirm (human gate)';
+const HOST_KIND = 'pi'; // the state root is host-agnostic; 'pi' keeps doctor/CLI on one spelling.
+function parseDurationMs(text) {
+  const m = /^(\d+)\s*(s|sec|secs|m|min|mins|h|hour|hours|d|day|days)$/i.exec(String(text ?? '').trim());
+  if (!m) return null;
+  const unit = m[2].toLowerCase();
+  const factor = unit.startsWith('s') ? 1000 : unit.startsWith('m') ? 60000 : unit.startsWith('h') ? 3600000 : 86400000;
+  return Number(m[1]) * factor;
+}
+
+/** `10m` / `18:30` / ISO 8601 / `every 1h` → a spec that `core.schedule.add` accepts directly. */
+function parseWhen(when, now = Date.now()) {
+  const text = String(when ?? '').trim();
+  if (text === '') return { kind: 'in', when: '10m', delayMs: 10 * 60000 };
+  const every = /^every\s+(.+)$/i.exec(text);
+  if (every) {
+    const everyMs = parseDurationMs(every[1]);
+    if (everyMs === null || everyMs <= 0) return null;
+    return { kind: 'every', when: text, everyMs };
+  }
+  const delayMs = parseDurationMs(text);
+  if (delayMs !== null) return { kind: 'in', when: text, delayMs };
+  const clock = /^(\d{1,2}):(\d{2})$/.exec(text);
+  if (clock) {
+    const at = new Date(now);
+    at.setHours(Number(clock[1]), Number(clock[2]), 0, 0);
+    if (at.getTime() <= now) at.setDate(at.getDate() + 1);
+    return { kind: 'at', when: text, at: at.getTime() };
+  }
+  const iso = Date.parse(text);
+  if (!Number.isNaN(iso)) return { kind: 'at', when: text, at: iso };
+  return null;
+}
+
+/** Pull `--name <value>` / `--name=<value>` out of args. */
+function takeOption(args, name) {
+  const rest = [];
+  let value = null;
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === name) {
+      value = args[i + 1] ?? null;
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith(`${name}=`)) {
+      value = arg.slice(name.length + 1);
+      continue;
+    }
+    rest.push(arg);
+  }
+  return { value, args: rest };
+}
+
+/** JSON on stdout, human lines on stderr — never both for the same payload. */
+function emit(io, asJson, payload, humanLines) {
+  if (asJson) io.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+  else for (const line of humanLines) io.stderr.write(`${line}\n`);
+  return 0;
+}
+
+/**
+ * Listings (`assistant ls` / `show`) are the answer to a query, not diagnostics: they go to
+ * stdout so `pactive assistant ls | wc -l` counts assistants (same reasoning as `--help`).
+ */
+function emitListing(io, asJson, payload, lines) {
+  if (asJson) io.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+  else for (const line of lines) io.stdout.write(`${line}\n`);
+  return 0;
+}
+
+function configKeys(core) {
+  const described = core.config.describe();
+  return { described, keys: Object.keys(described.defaults) };
+}
+
+function coerceValue(spec, raw) {
+  const text = String(raw).trim();
+  if (spec.type === 'boolean') {
+    if (text === 'true') return { ok: true, value: true };
+    if (text === 'false') return { ok: true, value: false };
+    return { ok: false, reason: 'expected true|false' };
+  }
+  if (spec.type === 'number') {
+    const n = Number(text);
+    if (text === '' || !Number.isFinite(n)) return { ok: false, reason: 'expected a number' };
+    if (typeof spec.min === 'number' && n < spec.min) return { ok: false, reason: `expected >= ${spec.min}` };
+    return { ok: true, value: n };
+  }
+  if (spec.type === 'string|null') {
+    if (text === '' || text.toLowerCase() === 'null' || text.toLowerCase() === 'none') return { ok: true, value: null };
+    return { ok: true, value: text };
+  }
+  return { ok: false, reason: `unsupported type ${spec.type}` };
+}
+
+async function configGetCmd(args, env, io) {
+  const asJson = args.includes('--json');
+  // `--assistant <name|id>` reads that assistant's override first, then falls back to global (I63).
+  const assistantOpt = takeOption(args.filter((a) => a !== '--json'), '--assistant');
+  const keys = assistantOpt.args;
+  const core = await loadCore();
+  const { described, keys: known } = configKeys(core);
+  if (keys.length > 1) {
+    io.stderr.write('pactive: usage: pactive config get [<key>] [--assistant <name|id>] [--json]\n');
+    return 2;
+  }
+  const key = keys[0];
+  if (key !== undefined && !known.includes(key)) {
+    io.stderr.write(`pactive: unknown config key '${key}'\npactive: known keys: ${known.join(', ')}\n`);
+    return 2;
+  }
+  const state = core.loadState(core.resolvePaths(HOST_KIND, env));
+  let assistantId = '';
+  if (assistantOpt.value !== null) {
+    const record = core.assistants.resolve(state, assistantOpt.value);
+    if (!record) return unknownAssistant(core, state, assistantOpt.value, io);
+    assistantId = record.assistantId;
+  }
+  const targets = key === undefined ? known : [key];
+  const values = targets.map((k) => ({
+    key: k,
+    value: core.config.get(state, k, assistantId),
+    default: described.defaults[k],
+    humanGated: described.schema[k].humanGated === true,
+  }));
+  const payload = key === undefined ? { values } : values[0];
+  // Single key → the bare value on its own line (so `config get idle.enabled | grep -qx false` works),
+  // then the default; the full key list keeps one "key = value" line each.
+  const human = key === undefined
+    ? values.map(
+      (v) => `${v.key} = ${JSON.stringify(v.value)}${JSON.stringify(v.value) === JSON.stringify(v.default) ? ' (default)' : ''}`,
+    )
+    : [`${JSON.stringify(values[0].value)}`, `${key} (default: ${JSON.stringify(values[0].default)})`];
+  return emit(io, asJson, payload, human);
+}
+
+async function configSetCmd(args, env, io) {
+  const asJson = args.includes('--json');
+  const confirm = args.includes('--confirm');
+  const assistantOpt = takeOption(args.filter((a) => a !== '--json' && a !== '--confirm'), '--assistant');
+  const rest = assistantOpt.args;
+  const [key, raw] = rest;
+  const core = await loadCore();
+  const { described, keys: known } = configKeys(core);
+
+  // Validity first (a usage error must not read as "gate refused"), then the gate.
+  if (key === undefined || raw === undefined || rest.length > 2) {
+    io.stderr.write('pactive: usage: pactive config set <key> <value> [--assistant <name|id>] --confirm\n');
+    return 2;
+  }
+  if (!known.includes(key)) {
+    io.stderr.write(`pactive: unknown config key '${key}'\npactive: known keys: ${known.join(', ')}\n`);
+    return 2;
+  }
+  if (!confirm) {
+    io.stderr.write(`${CONFIRM_REFUSAL}\n`);
+    io.stderr.write(`pactive: re-run with --confirm: pactive config set ${key} ${raw} --confirm\n`);
+    return 2;
+  }
+  const coerced = coerceValue(described.schema[key], raw);
+  if (!coerced.ok) {
+    io.stderr.write(`pactive: invalid value for ${key}: ${coerced.reason}\n`);
+    return 2;
+  }
+
+  const paths = core.resolvePaths(HOST_KIND, env);
+  let assistantId = '';
+  if (assistantOpt.value !== null) {
+    const overridable = described.assistantKeys ?? [];
+    if (!overridable.includes(key)) {
+      io.stderr.write(`pactive: ${key} cannot be overridden per assistant\n`);
+      io.stderr.write(`pactive: per-assistant keys: ${overridable.join(', ')}\n`);
+      return 2;
+    }
+    const record = core.assistants.resolve(core.loadState(paths), assistantOpt.value);
+    if (!record) return unknownAssistant(core, core.loadState(paths), assistantOpt.value, io);
+    assistantId = record.assistantId;
+  }
+
+  let applied = null;
+  await core.mutateState(paths, (state) => {
+    applied = core.config.setHumanGated(state, key, coerced.value, { confirm: true, assistantId });
+    if (!applied.ok) throw new PactiveError(`config refused: ${applied.reason}`, { code: 'CONFIG_REFUSED', exitCode: 1 });
+    return state;
+  });
+  return emit(
+    io,
+    asJson,
+    { ok: true, key, value: coerced.value, assistantId: assistantId || null, stateFile: paths.stateFile },
+    [
+      `${key} = ${JSON.stringify(coerced.value)}${assistantId ? ` (assistant ${assistantId})` : ''}`,
+      `pactive: wrote ${paths.stateFile}`,
+    ],
+  );
+}
+
+// ─────────────────── 助理舰队（契约 §3 / I61–I66） ───────────────────
+//
+// 写操作一律 --confirm：缺了就 exit 2、零写盘、stdout 干净（与 config set 同一道人工闸门）。
+// 解析助理（名字或 id）在写之前完成：未知名直接 exit 2 并列出已有助理，绝不新建一个同名幽灵。
+
+const ASSISTANT_SUBS = ['add', 'ls', 'show', 'enable', 'disable', 'rm', 'rename'];
+const ASSISTANT_WRITE_SUBS = new Set(['add', 'enable', 'disable', 'rm', 'rename']);
+const ASSISTANT_USAGE = 'pactive: usage: pactive assistant add|ls|show|enable|disable|rm|rename ...';
+
+function unknownAssistant(core, state, ref, io) {
+  const names = core.assistants.list(state).map((a) => a.name);
+  io.stderr.write(`pactive: unknown assistant '${ref}'\n`);
+  io.stderr.write(
+    `pactive: known assistants: ${names.length > 0 ? names.join(', ') : '(none yet)'}\n`,
+  );
+  if (names.length === 0) io.stderr.write('pactive: create one with: pactive assistant add <name> --confirm\n');
+  return 2;
+}
+
+function nextDueAt(state, assistantId) {
+  const times = [];
+  for (const task of state.tasks ?? []) {
+    if (!task || task.active === false || task.assistantId !== assistantId) continue;
+    if (Number.isFinite(task.dueAt)) times.push(task.dueAt);
+  }
+  return times.length > 0 ? Math.min(...times) : null;
+}
+
+function assistantRow(core, state, record) {
+  const tasks = core.schedule.list(state, record.assistantId).filter((t) => t.active !== false);
+  return {
+    assistantId: record.assistantId,
+    name: record.name,
+    title: record.title,
+    enabled: record.enabled === true,
+    tasks: tasks.length,
+    firedCount: Number.isFinite(record.firedCount) ? record.firedCount : 0,
+    lastFiredAt: Number.isFinite(record.lastFiredAt) ? record.lastFiredAt : 0,
+    nextDueAt: nextDueAt(state, record.assistantId),
+    policy: record.policy ?? {},
+  };
+}
+
+function humanAssistant(row) {
+  const next = row.nextDueAt ? new Date(row.nextDueAt).toISOString() : '-';
+  return `${row.name}  ${row.assistantId}  enabled=${row.enabled}  tasks=${row.tasks}  fires=${row.firedCount}  next=${next}`;
+}
+
+async function assistantCmd(args, env, io) {
+  const asJson = args.includes('--json');
+  const confirm = args.includes('--confirm');
+  const [sub, ...tail] = args;
+
+  if (sub === undefined || !ASSISTANT_SUBS.includes(sub)) {
+    io.stderr.write(`${ASSISTANT_USAGE}\n`);
+    return 2;
+  }
+  // The gate is checked before anything touches the filesystem (same order as config set).
+  if (ASSISTANT_WRITE_SUBS.has(sub) && !confirm) {
+    io.stderr.write(`${CONFIRM_REFUSAL}\n`);
+    io.stderr.write(`pactive: re-run with --confirm: pactive assistant ${sub} ${tail.join(' ')} --confirm\n`);
+    return 2;
+  }
+
+  const core = await loadCore();
+  const paths = core.resolvePaths(HOST_KIND, env);
+  const state = core.loadState(paths);
+
+  if (sub === 'ls') {
+    const rows = core.assistants.list(state).map((a) => assistantRow(core, state, a));
+    return emitListing(
+      io,
+      asJson,
+      { count: rows.length, assistants: rows },
+      rows.length === 0 ? ['pactive: no assistants yet — add one with: pactive assistant add <name> --confirm'] : rows.map(humanAssistant),
+    );
+  }
+
+  if (sub === 'show') {
+    const ref = tail[0];
+    if (ref === undefined) {
+      io.stderr.write('pactive: usage: pactive assistant show <name|id>\n');
+      return 2;
+    }
+    const record = core.assistants.resolve(state, ref);
+    if (!record) return unknownAssistant(core, state, ref, io);
+    const row = assistantRow(core, state, record);
+    const keys = core.config.describe().assistantKeys ?? [];
+    const policy = Object.fromEntries(keys.map((k) => [k, core.config.get(state, k, record.assistantId)]));
+    return emitListing(
+      io,
+      asJson,
+      { ...row, role: record.role, scope: record.scope, delivery: record.delivery, resolvedPolicy: policy },
+      [
+        humanAssistant(row),
+        `title: ${record.title}`,
+        `role: ${record.role || '-'}`,
+        `scope: ${record.scope?.globs?.length ? record.scope.globs.join(', ') : '(whole project)'}`,
+        `policy: ${Object.entries(policy).map(([k, v]) => `${k}=${JSON.stringify(v)}`).join(' ')}`,
+      ],
+    );
+  }
+
+  if (sub === 'add') {
+    const titleOpt = takeOption(tail, '--title');
+    const roleOpt = takeOption(titleOpt.args, '--role');
+    const scopeOpt = takeOption(roleOpt.args, '--scope');
+    const name = scopeOpt.args[0];
+    if (name === undefined) {
+      io.stderr.write('pactive: usage: pactive assistant add <name> [--title "…"] [--role "…"] [--scope <glob>] --confirm\n');
+      return 2;
+    }
+    if (core.assistants.resolve(state, name)) {
+      io.stderr.write(`pactive: assistant '${name}' already exists\n`);
+      return 2;
+    }
+    let created;
+    await core.mutateState(paths, (current) => {
+      created = core.assistants.add(current, {
+        name,
+        title: titleOpt.value ?? undefined,
+        role: roleOpt.value ?? undefined,
+        scope: scopeOpt.value ? { globs: [scopeOpt.value] } : undefined,
+      }, Date.now());
+      return current;
+    });
+    return emit(
+      io,
+      asJson,
+      { ok: true, confirmed: confirm, ...assistantRow(core, state, created) },
+      [humanAssistant(assistantRow(core, state, created)), 'pactive: 新建助理默认是关的（装上不等于打扰）—— 要开：pactive assistant enable ' + created.name + ' --confirm'],
+    );
+  }
+
+  // Remaining subcommands all name one existing assistant.
+  const ref = tail[0];
+  if (ref === undefined) {
+    io.stderr.write(`pactive: usage: pactive assistant ${sub} <name|id>${sub === 'rename' ? ' <newName>' : ''} --confirm\n`);
+    return 2;
+  }
+  const record = core.assistants.resolve(state, ref);
+  if (!record) return unknownAssistant(core, state, ref, io);
+
+  if (sub === 'rename') {
+    const newName = tail[1];
+    if (newName === undefined) {
+      io.stderr.write('pactive: usage: pactive assistant rename <name|id> <newName> --confirm\n');
+      return 2;
+    }
+    let renamed;
+    await core.mutateState(paths, (current) => {
+      renamed = core.assistants.rename(current, record.assistantId, newName);
+      return current;
+    });
+    // The record could have been removed between the read and the lock: say so, do not crash.
+    if (!renamed) return unknownAssistant(core, state, ref, io);
+    return emit(
+      io,
+      asJson,
+      { ok: true, confirmed: confirm, ...assistantRow(core, state, renamed) },
+      [`pactive: renamed ${record.name} → ${renamed.name}`, `id 不变：${renamed.assistantId}`],
+    );
+  }
+
+  if (sub === 'enable' || sub === 'disable') {
+    let updated;
+    await core.mutateState(paths, (current) => {
+      updated = core.assistants.setEnabled(current, record.assistantId, sub === 'enable');
+      return current;
+    });
+    if (!updated) return unknownAssistant(core, state, ref, io);
+    return emit(
+      io,
+      asJson,
+      { ok: true, confirmed: confirm, ...assistantRow(core, state, updated) },
+      [`pactive: ${updated.name} enabled=${updated.enabled}`],
+    );
+  }
+
+  // rm: the assistant AND its tasks go away together — no orphan tasks (I65), and no orphan
+  // pane either: an assistant's pane is closed first (best effort — herdr may be absent).
+  let paneClosed = null;
+  if (record.pane) {
+    const herdr = await loadHerdr();
+    const closed = herdr.close(record.pane.paneId, { env });
+    paneClosed = closed.ok ? closed.state : `skipped:${closed.reason}`;
+  }
+  let removed;
+  await core.mutateState(paths, (current) => {
+    removed = core.assistants.remove(current, record.assistantId);
+    return current;
+  });
+  if (!removed) return unknownAssistant(core, state, ref, io);
+  return emit(
+    io,
+    asJson,
+    { ok: true, confirmed: confirm, removed: removed.removed.name, assistantId: record.assistantId, tasksRemoved: removed.tasks, paneClosed },
+    [
+      `pactive: removed ${removed.removed.name} (${record.assistantId})`,
+      `pactive: ${removed.tasks} task(s) removed with it; the ledger keeps the history`,
+      ...(paneClosed === null ? [] : [`pactive: pane ${record.pane.paneId} → ${paneClosed}`]),
+    ],
+  );
+}
+
+// ─────────────────── 助理舰队 ↔ herdr pane（契约 §2.1 / I74–I79） ───────────────────
+//
+// pactive 只**复用** herdr：这里不建 PTY、不画 UI，只组装 `herdr` 的 argv 并读回它的 JSON（I74）。
+// 三条纪律：① 无 herdr → 明确拒绝 + 替代路径（I78）② 投递成功只认 agent 面（I77）
+// ③ 一个助理至多一个活 pane，`fleet up` 幂等（I79）。
+
+const FLEET_SUBS = ['up', 'ls', 'down', 'open'];
+const FLEET_USAGE = 'pactive: usage: pactive fleet up|ls|down|open [--assistant <name|id>] [--all] [--host <h>] [--tab <label>] [--dry-run] [--json]';
+const IDLE_PROMPT = '（pactive 空闲触发：请汇报当前进展与待办）';
+
+async function loadHerdr() {
+  return import(new URL('../src/hosts/herdr/index.mjs', import.meta.url));
+}
+
+function fleetRefused(io, probe, action) {
+  io.stderr.write(`pactive: fleet ${action} 拒绝执行 —— herdr 不可用\n`);
+  for (const r of probe.reasons) io.stderr.write(`pactive:   ${r.code}: ${r.reason}\n`);
+  io.stderr.write(`pactive: ${probe.hint}\n`);
+  io.stderr.write('pactive: 替代路径：pactive schedule "<prompt>" --when 10m（outbox）+ pactive tick（补投）\n');
+  return probe.reasons.some((r) => r.code === 'HOST_MISSING') ? 127 : 1;
+}
+
+/** `--assistant <ref>` or `--all`; both absent is a usage error (never "guess one"). */
+function fleetTargets(core, state, options) {
+  if (options.all) return core.assistants.list(state);
+  if (options.ref === null) return null;
+  const record = core.assistants.resolve(state, options.ref);
+  return record ? [record] : [];
+}
+
+function takeFleetOptions(args, flags = []) {
+  const bare = args.filter((a) => !flags.includes(a));
+  const a = takeOption(bare, '--assistant');
+  const h = takeOption(a.args, '--host');
+  const t = takeOption(h.args, '--tab');
+  return { ref: a.value, host: h.value, tab: t.value, extra: t.args };
+}
+
+function humanFleetRow(row) {
+  const status = row.status === null || row.status === undefined ? 'unobserved' : row.status;
+  const last = row.lastDeliveryAt ? `${row.lastDeliveryEvent}@${new Date(row.lastDeliveryAt).toISOString()}` : '-';
+  return `${row.name}  ${row.assistantId}  pane=${row.paneId ?? '-'}  agent=${row.agentName ?? '-'}  host=${row.host ?? '-'}  status=${status}  last=${last}`;
+}
+
+async function fleetUpCmd(args, env, io) {
+  const asJson = args.includes('--json');
+  const dryRun = args.includes('--dry-run');
+  const all = args.includes('--all');
+  const options = takeFleetOptions(args, ['--json', '--dry-run', '--all']);
+  if (options.extra.length > 0 || (options.ref === null && !all)) {
+    io.stderr.write('pactive: usage: pactive fleet up [--assistant <name|id>] [--all] [--host pi|opcteam|dsh] [--tab <label>] [--dry-run] [--json]\n');
+    return 2;
+  }
+  const core = await loadCore();
+  const herdr = await loadHerdr();
+  const paths = core.resolvePaths(HOST_KIND, env);
+  const state = core.loadState(paths);
+  const targets = fleetTargets(core, state, { ref: options.ref, all });
+  if (targets === null) return 2;
+  if (targets.length === 0) return unknownAssistant(core, state, options.ref, io);
+
+  // I78: the gate runs before any herdr call *and* before any state write.
+  const probe = herdr.available({ env });
+  if (!probe.ok) return fleetRefused(io, probe, 'up');
+
+  if (options.host !== null && !HOSTS.includes(options.host)) {
+    io.stderr.write(`pactive: unknown host '${options.host}'\npactive: known hosts: ${HOSTS.join(', ')}\n`);
+    return 2;
+  }
+  const cwd = path.resolve(env.PACTIVE_FLEET_CWD ?? process.cwd());
+  const ctx = { env };
+
+  if (dryRun) {
+    const plans = targets.map((target) => {
+      const host = options.host ?? target.delivery?.host ?? 'pi';
+      const plan = herdr.planSpawn({ assistantId: target.assistantId, host, tab: options.tab, cwd });
+      return {
+        assistantId: target.assistantId,
+        name: target.name,
+        host,
+        surface: plan.surface,
+        agentName: plan.agentName,
+        // `text` is the exact shell line, so a judge can grep the JSON for "pane split".
+        commands: plan.steps.map((step) => {
+          const argv = [probe.exec, ...step.argv];
+          return { argv, text: argv.join(' ') };
+        }),
+      };
+    });
+    return emit(
+      io,
+      asJson,
+      { ok: true, dryRun: true, executed: false, plans },
+      plans.flatMap((p) => [
+        `pactive: [dry-run] ${p.name} → host=${p.host} surface=${p.surface} agent=${p.agentName}`,
+        ...p.commands.map((c) => `  + ${c.text}`),
+      ]),
+    );
+  }
+
+  const results = [];
+  for (const target of targets) {
+    const host = options.host ?? target.delivery?.host ?? 'pi';
+    const existing = state.assistants?.[target.assistantId]?.pane ?? target.pane ?? null;
+    // I79: an already-bound assistant with a live pane is reused, never double-opened.
+    if (existing && existing.paneId) {
+      const alive = herdr.paneAlive(existing.paneId, ctx);
+      if (alive.alive === true) {
+        results.push({ assistantId: target.assistantId, name: target.name, host, state: 'reused', ...existing });
+        continue;
+      }
+      // Dead pane → drop the stale binding first (a rebuild must not look like a second pane).
+      await core.mutateState(paths, (current) => {
+        core.assistants.unbindPane(current, target.assistantId);
+        return current;
+      });
+    }
+    const spawned = herdr.spawn({ assistantId: target.assistantId, host, tab: options.tab, cwd }, ctx);
+    if (!spawned.ok) {
+      results.push({ assistantId: target.assistantId, name: target.name, host, state: spawned.state, reason: spawned.reason });
+      continue;
+    }
+    await core.mutateState(paths, (current) => {
+      core.assistants.bindPane(current, target.assistantId, spawned.binding);
+      return current;
+    });
+    results.push({ assistantId: target.assistantId, name: target.name, host, state: spawned.state ?? 'bound', ...spawned.binding });
+  }
+
+  const ok = results.every((r) => r.state === 'bound' || r.state === 'reused' || r.state === 'adopted');
+  emit(
+    io,
+    asJson,
+    { ok, executed: true, bound: results.filter((r) => r.state === 'bound').length, reused: results.filter((r) => r.state === 'reused').length, adopted: results.filter((r) => r.state === 'adopted').length, results },
+    results.map(
+      (r) => (r.state === 'reused'
+        ? `pactive: reused ${r.name} → pane ${r.paneId} (agent ${r.agentName ?? '-'}, host ${r.host})`
+        : r.state === 'bound' || r.state === 'adopted'
+          ? `pactive: ${r.state} ${r.name} → pane ${r.paneId} (agent ${r.agentName ?? '-'}, surface ${r.surface}, host ${r.host})`
+          : `pactive: FAILED ${r.name} — ${r.state}: ${r.reason}`),
+    ),
+  );
+  return ok ? 0 : 1;
+}
+
+async function fleetLsCmd(args, env, io) {
+  const asJson = args.includes('--json');
+  const core = await loadCore();
+  const { fleetPayload } = await import(new URL('../src/hosts/herdr/fleet-view.mjs', import.meta.url));
+  const paths = core.resolvePaths(HOST_KIND, env);
+  const state = core.loadState(paths);
+  const payload = fleetPayload(core, state, paths, env);
+  if (!asJson) {
+    if (!payload.herdr.available) {
+      io.stderr.write(`pactive: herdr 不可用（${payload.herdr.reason}）—— status 标为 unobserved，绑定关系仍来自 state\n`);
+    } else if (payload.herdr.reason) {
+      io.stderr.write(`pactive: herdr agent list failed: ${payload.herdr.reason}\n`);
+    }
+  }
+  return emitListing(
+    io,
+    asJson,
+    payload,
+    payload.rows.length === 0 ? ['pactive: no assistants yet'] : payload.rows.map(humanFleetRow),
+  );
+}
+
+async function fleetDownCmd(args, env, io) {
+  const asJson = args.includes('--json');
+  const all = args.includes('--all');
+  const options = takeFleetOptions(args, ['--json', '--all']);
+  if (options.extra.length > 0 || (options.ref === null && !all)) {
+    io.stderr.write('pactive: usage: pactive fleet down [--assistant <name|id>] [--all] [--json]\n');
+    return 2;
+  }
+  const core = await loadCore();
+  const herdr = await loadHerdr();
+  const paths = core.resolvePaths(HOST_KIND, env);
+  const state = core.loadState(paths);
+  const targets = fleetTargets(core, state, { ref: options.ref, all });
+  if (targets === null) return 2;
+  if (targets.length === 0) return unknownAssistant(core, state, options.ref, io);
+  const probe = herdr.available({ env });
+  if (!probe.ok) return fleetRefused(io, probe, 'down');
+
+  const results = [];
+  for (const target of targets) {
+    const pane = target.pane ?? null;
+    if (!pane) {
+      results.push({ assistantId: target.assistantId, name: target.name, state: 'not-bound' });
+      continue;
+    }
+    const closed = herdr.close(pane.paneId, { env });
+    if (closed.ok) {
+      // I75: only the binding goes — the assistant, its tasks and its history stay.
+      await core.mutateState(paths, (current) => {
+        core.assistants.unbindPane(current, target.assistantId);
+        return current;
+      });
+    }
+    results.push({ assistantId: target.assistantId, name: target.name, paneId: pane.paneId, state: closed.state, reason: closed.reason ?? null });
+  }
+  const ok = results.every((r) => r.state === 'closed' || r.state === 'already-closed' || r.state === 'not-bound');
+  emit(
+    io,
+    asJson,
+    { ok, results },
+    results.map((r) => (r.state === 'not-bound'
+      ? `pactive: ${r.name} 没有绑定 pane（助理仍在）`
+      : r.state === 'closed' || r.state === 'already-closed'
+        ? `pactive: closed ${r.name} pane ${r.paneId}（助理仍在：pactive assistant ls）`
+        : `pactive: FAILED ${r.name} — ${r.state}: ${r.reason}`)),
+  );
+  return ok ? 0 : 1;
+}
+
+async function fleetOpenCmd(args, env, io) {
+  const asJson = args.includes('--json');
+  const options = takeFleetOptions(args, ['--json']);
+  if (options.ref === null || options.extra.length > 0) {
+    io.stderr.write('pactive: usage: pactive fleet open --assistant <name|id> [--json]\n');
+    return 2;
+  }
+  const core = await loadCore();
+  const herdr = await loadHerdr();
+  const paths = core.resolvePaths(HOST_KIND, env);
+  const state = core.loadState(paths);
+  const record = core.assistants.resolve(state, options.ref);
+  if (!record) return unknownAssistant(core, state, options.ref, io);
+  if (!record.pane) {
+    io.stderr.write(`pactive: ${record.name} 没有绑定 pane —— 先跑 pactive fleet up --assistant ${record.name}\n`);
+    return 1;
+  }
+  const probe = herdr.available({ env });
+  if (!probe.ok) return fleetRefused(io, probe, 'open');
+  const focused = herdr.focus(record.pane, { env });
+  emit(
+    io,
+    asJson,
+    { ok: focused.ok, ...focused, assistantId: record.assistantId },
+    focused.ok
+      ? [`pactive: focused ${record.name} → pane ${focused.paneId ?? record.pane.paneId} (agent ${focused.agentName})`]
+      : [`pactive: cannot focus ${record.name} — ${focused.reason}`],
+  );
+  return focused.ok ? 0 : 1;
+}
+
+async function fleetCmd(args, env, io) {
+  const [sub, ...rest] = args;
+  if (sub === undefined || !FLEET_SUBS.includes(sub)) {
+    io.stderr.write(`${FLEET_USAGE}\n`);
+    return 2;
+  }
+  return { up: fleetUpCmd, ls: fleetLsCmd, down: fleetDownCmd, open: fleetOpenCmd }[sub](rest, env, io);
+}
+
+/**
+ * I79/I75 helper: give every enabled assistant a live pane before a tick delivers.
+ * Never fatal — herdr absent means "keep going on the outbox path", said out loud (I78).
+ */
+async function ensureFleet(core, herdr, paths, state, env, io) {
+  const probe = herdr.available({ env });
+  if (!probe.ok) {
+    io.stderr.write(`pactive: --ensure-fleet 跳过 —— herdr 不可用（${probe.reason}）；继续按 outbox 投递\n`);
+    return { skipped: true, reason: probe.reason, bound: 0, reused: 0, failed: 0 };
+  }
+  const cwd = path.resolve(env.PACTIVE_FLEET_CWD ?? process.cwd());
+  const report = { skipped: false, reason: null, bound: 0, reused: 0, failed: 0 };
+  for (const target of core.assistants.list(state)) {
+    if (target.enabled !== true) continue;
+    const existing = target.pane ?? null;
+    if (existing && existing.paneId && herdr.paneAlive(existing.paneId, { env }).alive === true) {
+      report.reused += 1;
+      continue;
+    }
+    if (existing) {
+      await core.mutateState(paths, (current) => {
+        core.assistants.unbindPane(current, target.assistantId);
+        return current;
+      });
+    }
+    const host = target.delivery?.host ?? 'pi';
+    const spawned = herdr.spawn({ assistantId: target.assistantId, host, cwd }, { env });
+    if (!spawned.ok) {
+      report.failed += 1;
+      io.stderr.write(`pactive: --ensure-fleet 未能给 ${target.name} 建 pane — ${spawned.reason}\n`);
+      continue;
+    }
+    await core.mutateState(paths, (current) => {
+      core.assistants.bindPane(current, target.assistantId, spawned.binding);
+      return current;
+    });
+    report.bound += 1;
+  }
+  return report;
+}
+
+/** One drive round: due tasks + idle sweep, every attempt lands in the ledger. */
+async function tickCmd(args, env, io) {
+  const asJson = args.includes('--json');
+  const wantFleet = args.includes('--ensure-fleet');
+  const assistantOpt = takeOption(args.filter((a) => a !== '--json' && a !== '--ensure-fleet'), '--assistant');
+  const core = await loadCore();
+  const paths = core.resolvePaths(HOST_KIND, env);
+  const state = core.loadState(paths);
+
+  let assistantId = null;
+  if (assistantOpt.value !== null) {
+    const record = core.assistants.resolve(state, assistantOpt.value);
+    if (!record) return unknownAssistant(core, state, assistantOpt.value, io);
+    assistantId = record.assistantId;
+  }
+
+  // §2.3: with a daemon absent, `--ensure-fleet` is the opt-in "repair the panes, then deliver".
+  const herdr = await loadHerdr();
+  const fleetReport = wantFleet ? await ensureFleet(core, herdr, paths, state, env, io) : null;
+
+  // §2.2/I77: a bound pane gets the prompt through the agent surface and the *receipt* decides
+  // whether the ledger says `delivered`, `queued` or `unreachable`.
+  const probe = herdr.available({ env });
+  const receipts = { accepted: 0, queued: 0, unreachable: 0 };
+  const paneDeliver = (delivery) => {
+    if (!probe.ok) return { state: 'queued', reason: `herdr-unavailable:${probe.reasons[0]?.code ?? 'unknown'}` };
+    const receipt = herdr.deliver(
+      { agentName: delivery.pane.agentName, paneId: delivery.pane.paneId, text: delivery.prompt ?? IDLE_PROMPT },
+      { env },
+    );
+    receipts[receipt.state] = (receipts[receipt.state] ?? 0) + 1;
+    return receipt;
+  };
+
+  let report = null;
+  await core.mutateState(paths, (current) => {
+    report = core.runTick(current, Date.now(), { ledgerFile: paths.ledgerFile, assistantId, paneDeliver });
+    return current;
+  });
+
+  const blocks = report.blocks ?? [];
+  const queuedEvents = report.queued_events ?? [];
+  const unreachableEvents = report.unreachable_events ?? [];
+  return emit(
+    io,
+    asJson,
+    { ...report, receipts, fleet: fleetReport, ledgerFile: paths.ledgerFile, stateFile: paths.stateFile },
+    [
+      `pactive: tick — delivered=${report.delivered} queued=${report.queued} unreachable=${report.unreachable} blocked=${report.blocked} pending=${report.pending} assistants=${report.assistants}`,
+      ...report.deliveries.map((d) => `  delivered ${d.assistantId}${d.paneId ? ` pane=${d.paneId}` : ''}${d.taskId ? ` ${d.taskId}` : ''}${d.prompt ? ` — ${d.prompt}` : ''}`),
+      ...queuedEvents.map((q) => `  queued ${q.assistantId} pane=${q.paneId ?? '-'} reason=${q.reason}`),
+      ...unreachableEvents.map((u) => `  unreachable ${u.assistantId} pane=${u.paneId ?? '-'} reason=${u.reason}（绑定已清空，可 fleet up 重开）`),
+      ...blocks.map((b) => `  blocked ${b.assistantId}${b.taskId ? ` ${b.taskId}` : ''} reason=${b.reason}`),
+    ],
+  );
+}
+
+async function scheduleCmd(args, env, io) {
+  const asJson = args.includes('--json');
+  const confirm = args.includes('--confirm');
+  const assistantOpt = takeOption(args.filter((a) => a !== '--json' && a !== '--confirm'), '--assistant');
+  const taken = takeOption(assistantOpt.args, '--when');
+  const prompt = taken.args.join(' ').trim();
+  if (prompt === '') {
+    io.stderr.write('pactive: usage: pactive schedule "<prompt>" --when <when> [--assistant <name|id>] [--confirm]\n');
+    return 2;
+  }
+  const now = Date.now();
+  const spec = parseWhen(taken.value ?? '10m', now);
+  if (!spec) {
+    io.stderr.write(`pactive: cannot parse --when '${taken.value}' (try 10m / 18:30 / ISO 8601 / every 1h)\n`);
+    return 2;
+  }
+  const core = await loadCore();
+  const paths = core.resolvePaths(HOST_KIND, env);
+  // An unknown assistant is refused before the write: a typo must not invent a new assistant.
+  let assistantId = null;
+  if (assistantOpt.value !== null) {
+    const record = core.assistants.resolve(core.loadState(paths), assistantOpt.value);
+    if (!record) return unknownAssistant(core, core.loadState(paths), assistantOpt.value, io);
+    assistantId = record.assistantId;
+  }
+  const next = await core.mutateState(paths, (state) => {
+    // Unqualified tasks land on the `default` assistant, created on first use (never enabled).
+    const targetId = assistantId ?? core.assistants.ensureDefault(state).assistantId;
+    core.schedule.add(state, { ...spec, prompt, content: prompt, owner: state.identity?.agentId, assistantId: targetId }, now);
+    return state;
+  });
+  const list = core.schedule.list(next, assistantId ?? undefined);
+  const created = list[list.length - 1] ?? null;
+  return emit(
+    io,
+    asJson,
+    {
+      ok: true,
+      confirmed: confirm,
+      taskId: created?.id ?? null,
+      assistantId: created?.assistantId ?? assistantId,
+      dueAt: created?.dueAt ?? null,
+      kind: spec.kind,
+      when: spec.when,
+      tasks: list.length,
+    },
+    [
+      `pactive: registered ${created?.id ?? '?'} (${spec.when} → ${new Date(created?.dueAt ?? now).toISOString()})`,
+      `assistant: ${created?.assistantId ?? assistantId ?? 'default'}`,
+      `prompt: ${prompt}`,
+    ],
+  );
+}
+
+async function tasksCmd(args, env, io) {
+  const asJson = args.includes('--json');
+  const assistantOpt = takeOption(args.filter((a) => a !== '--json'), '--assistant');
+  const core = await loadCore();
+  const state = core.loadState(core.resolvePaths(HOST_KIND, env));
+  let assistantId;
+  if (assistantOpt.value !== null) {
+    const record = core.assistants.resolve(state, assistantOpt.value);
+    if (!record) return unknownAssistant(core, state, assistantOpt.value, io);
+    assistantId = record.assistantId;
+  }
+  const list = core.schedule.list(state, assistantId);
+  const rows = list.map((t) => ({
+    id: t.id,
+    assistantId: t.assistantId ?? '',
+    kind: t.kind,
+    dueAt: t.dueAt,
+    due: new Date(t.dueAt).toISOString(),
+    owner: t.owner ?? '',
+    active: t.active !== false,
+    prompt: t.prompt ?? '',
+  }));
+  return emit(
+    io,
+    asJson,
+    { count: rows.length, assistantId: assistantId ?? null, tasks: rows },
+    rows.length === 0
+      ? ['pactive: no scheduled tasks']
+      : rows.map(
+        (r) => `[${r.id}] ${r.kind} ${r.due} assistant=${r.assistantId || '-'} owner=${r.owner || '-'} ${r.active ? 'active' : 'inactive'}${r.prompt ? ` — ${r.prompt}` : ''}`,
+      ),
+  );
+}
+
+async function cancelCmd(args, env, io) {
+  const asJson = args.includes('--json');
+  const confirm = args.includes('--confirm');
+  const id = args.filter((a) => a !== '--json' && a !== '--confirm')[0];
+  if (id === undefined) {
+    io.stderr.write('pactive: usage: pactive cancel <taskId> [--confirm]\n');
+    return 2;
+  }
+  const core = await loadCore();
+  const paths = core.resolvePaths(HOST_KIND, env);
+  const before = core.schedule.list(core.loadState(paths));
+  if (!before.some((t) => t.id === id)) {
+    io.stderr.write(`pactive: unknown task id '${id}'\n`);
+    return 1;
+  }
+  const next = await core.mutateState(paths, (state) => {
+    core.schedule.cancel(state, id);
+    return state;
+  });
+  return emit(
+    io,
+    asJson,
+    { ok: true, confirmed: confirm, cancelled: id, tasks: core.schedule.list(next).length },
+    [`pactive: cancelled ${id} (${core.schedule.list(next).length} left)`],
+  );
+}
+
 function printPlan(args, env, io) {
   const host = args[0];
   if (!host) {
@@ -396,12 +1296,25 @@ export async function main(argv, env = process.env, io = { stdout: process.stdou
       return 0;
     case '--help':
     case '-h':
-      usage(io.stderr);
+      // Explicit help goes to stdout: it is the requested output, not host noise
+      // (I37 protects the stdout of a *spawned host*; `--help | head -8` must be greppable).
+      usage(io.stdout);
       return 0;
     case '--print-plan':
       return printPlan(rest, env, io);
     case 'doctor':
       return doctorCmd(rest, env, io);
+    case 'config':
+      return rest[0] === 'set' ? configSetCmd(rest.slice(1), env, io) : configGetCmd(rest[0] === 'get' ? rest.slice(1) : rest, env, io);
+    case 'schedule':
+    case 'tasks':
+    case 'cancel':
+    case 'tick':
+      return { schedule: scheduleCmd, tasks: tasksCmd, cancel: cancelCmd, tick: tickCmd }[cmd](rest, env, io);
+    case 'assistant':
+      return assistantCmd(rest, env, io);
+    case 'fleet':
+      return fleetCmd(rest, env, io);
     case 'install':
       return installCmd(rest, env, io, 'install');
     case 'uninstall':