pactive 0.0.1-alpha.1 → 0.0.3-alpha.1

package/bin/pactive.mjs

@@ -0,0 +1,720 @@
+#!/usr/bin/env node
+// Pactive CLI — contract §3 / design §6.
+//
+// Output discipline (design §6.3): machine-readable results (--print-plan, doctor --json,
+// --version) go to stdout; every human/diagnostic Pactive text goes to stderr, so the stdout of a
+// spawned host is never polluted.
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync, realpathSync, rmSync, statSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { PactiveError } from '../src/hosts/errors.mjs';
+
+const HOSTS = ['pi', 'opcteam', 'dsh'];
+const CLI_DIR = path.dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = path.resolve(CLI_DIR, '..');
+const FALLBACK_VERSION = '0.0.2-alpha.1';
+const STALE_LOCK_MS = 30 * 60 * 1000;
+
+function usage(out) {
+  out.write(`pactive — 主动助手：默认全部用自然语言操作，命令只是"可复制的一行"
+
+你可以直接对助手说：
+  「我现在闲不闲？」                      → 看空闲判定与 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>    register a timed task (10m / 18:30 / ISO / every 1h)
+  pactive tasks [--json]          list scheduled tasks (id / kind / due / owner)
+  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
+  pactive --help | -h             show this help
+
+Hosts: ${HOSTS.join(', ')}
+
+Environment:
+  PACTIVE_HOME          package root override (default: this package)
+  PACTIVE_STATE_DIR     pactive state root override
+  PACTIVE_PI_BIN        override the pi executable
+  PACTIVE_OPCTEAM_BIN   override the opcteam executable
+  PACTIVE_DSH_BIN       override the dsh executable
+`);
+}
+
+function unknownHost(host, io) {
+  io.write(`pactive: unknown host '${host}'\n`);
+  io.write(`pactive: known hosts: ${HOSTS.join(', ')}\n`);
+}
+
+function resolvePkgRoot(env) {
+  return env.PACTIVE_HOME ? path.resolve(env.PACTIVE_HOME) : PKG_ROOT;
+}
+
+function pactiveVersion() {
+  try {
+    const pkg = JSON.parse(readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf8'));
+    if (typeof pkg.version === 'string') return pkg.version;
+  } catch {
+    // package.json not built yet — fall back to the contract version
+  }
+  return FALLBACK_VERSION;
+}
+
+async function loadAdapter(host) {
+  return import(new URL(`../src/hosts/${host}/index.mjs`, import.meta.url));
+}
+
+/** src/core is built by the pactive-core worker; until then the CLI degrades instead of faking it. */
+async function loadCore() {
+  try {
+    return await import(new URL('../src/core/index.mjs', import.meta.url));
+  } catch (err) {
+    throw new PactiveError('PACTIVE core not built yet', { code: 'CORE_MISSING', exitCode: 1, cause: err });
+  }
+}
+
+async function resolveStateRoot(env, warnings = []) {
+  if (env.PACTIVE_STATE_DIR) return path.resolve(env.PACTIVE_STATE_DIR);
+  try {
+    const core = await loadCore();
+    const paths = core.resolvePaths('pi', env);
+    if (paths?.root) return paths.root;
+    warnings.push('PACTIVE core returned no state root — using the default location');
+  } catch (err) {
+    warnings.push(`${err.message} — using the default state root`);
+  }
+  return path.join(os.homedir(), '.pactive');
+}
+
+function modeOf(p) {
+  return (statSync(p).mode & 0o777).toString(8).padStart(4, '0');
+}
+
+function probeVersion(exec) {
+  const res = spawnSync(exec, ['--version'], { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'pipe'] });
+  const out = `${res.stdout ?? ''}${res.stderr ?? ''}`.trim();
+  if (!out) return null;
+  return out.split(/\s+/)[0];
+}
+
+function majorOf(version) {
+  const major = Number.parseInt(String(version).split('.')[0], 10);
+  return Number.isNaN(major) ? null : major;
+}
+
+function isCompatible(found, supported) {
+  if (!found || !supported) return false;
+  const a = majorOf(found);
+  const b = majorOf(supported);
+  return a !== null && b !== null && a === b;
+}
+
+function countFiles(dir) {
+  if (!existsSync(dir)) return 0;
+  let n = 0;
+  for (const name of readdirSync(dir)) {
+    const abs = path.join(dir, name);
+    if (statSync(abs).isDirectory()) n += countFiles(abs);
+    else n += 1;
+  }
+  return n;
+}
+
+function stateStats(stateRoot) {
+  const stats = {
+    exists: existsSync(stateRoot),
+    perm: { dir: null, file: null },
+    idle: { enabled: false },
+    sessions: 0,
+    tasks: 0,
+    outbox: 0,
+    locksStale: 0,
+    fails: [],
+  };
+  if (!stats.exists) return stats;
+
+  stats.perm.dir = modeOf(stateRoot);
+  if (stats.perm.dir !== '0700') {
+    stats.fails.push(`state root ${stateRoot} has mode ${stats.perm.dir}, expected 0700`);
+  }
+
+  const stateFile = path.join(stateRoot, 'state.json');
+  if (existsSync(stateFile)) {
+    stats.perm.file = modeOf(stateFile);
+    if (stats.perm.file !== '0600') {
+      stats.fails.push(`state file ${stateFile} has mode ${stats.perm.file}, expected 0600`);
+    }
+    try {
+      const state = JSON.parse(readFileSync(stateFile, 'utf8'));
+      stats.idle.enabled = Boolean(state?.idle?.enabled);
+      if (Array.isArray(state?.tasks)) stats.tasks = state.tasks.length;
+    } catch {
+      stats.fails.push(`state file ${stateFile} is not valid JSON`);
+    }
+  }
+
+  const tasksFile = path.join(stateRoot, 'tasks.json');
+  if (existsSync(tasksFile)) {
+    try {
+      const tasks = JSON.parse(readFileSync(tasksFile, 'utf8'));
+      if (Array.isArray(tasks)) stats.tasks = tasks.length;
+    } catch {
+      stats.fails.push(`tasks file ${tasksFile} is not valid JSON`);
+    }
+  }
+
+  stats.sessions = countFiles(path.join(stateRoot, 'peers'));
+  stats.outbox = countFiles(path.join(stateRoot, 'outbox'));
+
+  const locksDir = path.join(stateRoot, 'locks');
+  if (existsSync(locksDir)) {
+    const now = Date.now();
+    for (const name of readdirSync(locksDir)) {
+      const abs = path.join(locksDir, name);
+      if (statSync(abs).isFile() && now - statSync(abs).mtimeMs > STALE_LOCK_MS) stats.locksStale += 1;
+    }
+  }
+  return stats;
+}
+
+async function doctorReport(env) {
+  const warnings = [];
+  const stateRoot = await resolveStateRoot(env, warnings);
+  const hosts = [];
+  for (const host of HOSTS) {
+    const mod = await loadAdapter(host);
+    let present = false;
+    let version = null;
+    let compatible = false;
+    try {
+      const exec = mod.resolveExec({ env });
+      present = true;
+      version = probeVersion(exec);
+      compatible = isCompatible(version, mod.SUPPORTED_VERSION);
+      if (!version) {
+        warnings.push(`host ${host}: installed but its version could not be read`);
+      } else if (!compatible) {
+        warnings.push(`host ${host}: version ${version} differs from the supported ${mod.SUPPORTED_VERSION}`);
+      }
+    } catch (err) {
+      if (err.code !== 'HOST_MISSING') throw err;
+      warnings.push(`host ${host}: not installed (set PACTIVE_${host.toUpperCase()}_BIN to override)`);
+    }
+    hosts.push({ host, present, version, mode: mod.MODE, compatible });
+  }
+
+  const stats = stateStats(stateRoot);
+  if (!stats.exists) warnings.push(`state root ${stateRoot} does not exist yet`);
+  for (const fail of stats.fails) warnings.push(`FAIL: ${fail}`);
+
+  return {
+    ok: stats.fails.length === 0,
+    hosts,
+    stateRoot,
+    perm: stats.perm,
+    idle: { enabled: stats.idle.enabled, source: 'core-timeline' },
+    sessions: stats.sessions,
+    tasks: stats.tasks,
+    outbox: stats.outbox,
+    locksStale: stats.locksStale,
+    secrets: { credentialsRead: false },
+    warnings,
+  };
+}
+
+// ─────────────────── 自然语言面向的子命令（契约 §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;
+}
+
+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');
+  const keys = args.filter((a) => a !== '--json');
+  const core = await loadCore();
+  const { described, keys: known } = configKeys(core);
+  if (keys.length > 1) {
+    io.stderr.write('pactive: usage: pactive config get [<key>] [--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));
+  const targets = key === undefined ? known : [key];
+  const values = targets.map((k) => ({
+    key: k,
+    value: core.config.get(state, k),
+    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 rest = args.filter((a) => a !== '--json' && a !== '--confirm');
+  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> --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 applied = null;
+  await core.mutateState(paths, (state) => {
+    applied = core.config.setHumanGated(state, key, coerced.value, { confirm: true });
+    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, stateFile: paths.stateFile },
+    [`${key} = ${JSON.stringify(coerced.value)}`, `pactive: wrote ${paths.stateFile}`],
+  );
+}
+
+async function scheduleCmd(args, env, io) {
+  const asJson = args.includes('--json');
+  const confirm = args.includes('--confirm');
+  const taken = takeOption(args.filter((a) => a !== '--json' && a !== '--confirm'), '--when');
+  const prompt = taken.args.join(' ').trim();
+  if (prompt === '') {
+    io.stderr.write('pactive: usage: pactive schedule "<prompt>" --when <when> [--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);
+  const next = await core.mutateState(paths, (state) => {
+    core.schedule.add(state, { ...spec, prompt, content: prompt, owner: state.identity?.agentId }, now);
+    return state;
+  });
+  const list = core.schedule.list(next);
+  const created = list[list.length - 1] ?? null;
+  return emit(
+    io,
+    asJson,
+    {
+      ok: true,
+      confirmed: confirm,
+      taskId: created?.id ?? null,
+      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()})`,
+      `prompt: ${prompt}`,
+    ],
+  );
+}
+
+async function tasksCmd(args, env, io) {
+  const asJson = args.includes('--json');
+  const core = await loadCore();
+  const state = core.loadState(core.resolvePaths(HOST_KIND, env));
+  const list = core.schedule.list(state);
+  const rows = list.map((t) => ({
+    id: t.id,
+    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, tasks: rows },
+    rows.length === 0
+      ? ['pactive: no scheduled tasks']
+      : rows.map(
+        (r) => `[${r.id}] ${r.kind} ${r.due} 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) {
+    unknownHost('', io.stderr);
+    return Promise.resolve(2);
+  }
+  if (!HOSTS.includes(host)) {
+    unknownHost(host, io.stderr);
+    return Promise.resolve(2);
+  }
+  return loadAdapter(host).then((mod) => {
+    const plan = mod.plan({ pkgRoot: resolvePkgRoot(env), env, userArgs: [] });
+    io.stdout.write(`${JSON.stringify(plan, null, 2)}\n`);
+    return 0;
+  });
+}
+
+function doctorCmd(args, env, io) {
+  const asJson = args.includes('--json');
+  return doctorReport(env).then((report) => {
+    if (asJson) {
+      io.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    } else {
+      io.stderr.write(`pactive doctor: ${report.ok ? 'OK' : 'FAIL'}\n`);
+      io.stderr.write(`state root: ${report.stateRoot} (dir ${report.perm.dir}, file ${report.perm.file})\n`);
+      for (const h of report.hosts) {
+        io.stderr.write(
+          `host ${h.host}: present=${h.present} version=${h.version ?? 'unknown'} mode=${h.mode} compatible=${h.compatible}\n`,
+        );
+      }
+      io.stderr.write(
+        `sessions=${report.sessions} tasks=${report.tasks} outbox=${report.outbox} locksStale=${report.locksStale} idle.enabled=${report.idle.enabled}\n`,
+      );
+      for (const w of report.warnings) io.stderr.write(`- ${w}\n`);
+    }
+    return report.ok ? 0 : 1;
+  });
+}
+
+function runHostCommand(exec, args) {
+  const res = spawnSync(exec, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  return { status: res.status ?? 1, stdout: res.stdout ?? '', stderr: res.stderr ?? '' };
+}
+
+function verifyRegistered(mod, exec, pkgRoot) {
+  const res = runHostCommand(exec, mod.verifyArgs({ pkgRoot }));
+  return mod.verifyMatch({ pkgRoot }, `${res.stdout}\n${res.stderr}`);
+}
+
+const OWNED_STATE_ENTRIES = ['state.json', 'tasks.json', 'ledger.jsonl', 'peers', 'inbox', 'outbox', 'locks'];
+
+function removeStateResidue(stateRoot) {
+  if (!existsSync(stateRoot)) return [];
+  for (const name of OWNED_STATE_ENTRIES) {
+    rmSync(path.join(stateRoot, name), { recursive: true, force: true });
+  }
+  for (const name of readdirSync(stateRoot)) {
+    if (/^(state|tasks)\.json\.corrupt-/.test(name)) {
+      rmSync(path.join(stateRoot, name), { recursive: true, force: true });
+    }
+  }
+  const left = [];
+  const walk = (dir, rel) => {
+    for (const name of readdirSync(dir)) {
+      const abs = path.join(dir, name);
+      const relPath = rel ? path.join(rel, name) : name;
+      if (statSync(abs).isDirectory()) walk(abs, relPath);
+      else left.push(relPath);
+    }
+  };
+  walk(stateRoot, '');
+  return left;
+}
+
+function installCmd(args, env, io, action) {
+  const host = args[0];
+  if (!host) {
+    unknownHost('', io.stderr);
+    return Promise.resolve(2);
+  }
+  if (!HOSTS.includes(host)) {
+    unknownHost(host, io.stderr);
+    return Promise.resolve(2);
+  }
+  return loadAdapter(host).then(async (mod) => {
+    const exec = mod.resolveExec({ env });
+    const pkgRoot = resolvePkgRoot(env);
+    if (action === 'uninstall' && typeof mod.isInstalled === 'function') {
+      let installed = true;
+      try { installed = mod.isInstalled({ pkgRoot, env }); } catch { installed = true; }
+      if (!installed) {
+        // 幂等：没装就什么都不跑（跑宿主 remove 会让 DSH 重建 profile，制造"删了又出现"的怪象）
+        if (typeof mod.cleanup === 'function') {
+          try { mod.cleanup({ pkgRoot, env }); } catch { /* residue 清理失败由下方 residue 检查兜底 */ }
+        }
+        io.stderr.write(`pactive: ${host} not installed — nothing to uninstall\n`);
+        return 0;
+      }
+    }
+    const argsFor = action === 'install' ? mod.installArgs({ pkgRoot }) : mod.uninstallArgs({ pkgRoot });
+    const res = runHostCommand(exec, argsFor);
+
+    if (res.status !== 0) {
+      const stillRegistered = verifyRegistered(mod, exec, pkgRoot);
+      if (action === 'install' ? !stillRegistered : stillRegistered) {
+        io.stderr.write(`pactive: ${action} ${host} failed (exit ${res.status})\n`);
+        if (res.stderr.trim()) io.stderr.write(`${res.stderr.trim()}\n`);
+        return 1;
+      }
+    }
+
+    if (action === 'uninstall') {
+      // Host-level residue: adapters may own resources Pactive created (e.g. the DSH profile dir).
+      if (typeof mod.cleanup === 'function') {
+        try {
+          const cleaned = mod.cleanup({ pkgRoot, env });
+          if (cleaned && cleaned.removed) io.stderr.write(`pactive: removed ${cleaned.path}\n`);
+        } catch (err) {
+          io.stderr.write(`pactive: cleanup warning: ${err?.message ?? err}\n`);
+        }
+      }
+      const stateRoot = await resolveStateRoot(env, []);
+      const residue = removeStateResidue(stateRoot);
+      if (residue.length > 0) {
+        io.stderr.write(`pactive: residue left in ${stateRoot}: ${residue.join(', ')}\n`);
+        return 1;
+      }
+    }
+
+    io.stderr.write(`pactive: ${action} ${host} ok (${pkgRoot})\n`);
+    return 0;
+  });
+}
+
+function runHost(host, userArgs, env, io) {
+  return loadAdapter(host).then((mod) => {
+    const exec = mod.resolveExec({ env });
+    const pkgRoot = resolvePkgRoot(env);
+    const argv = mod.buildArgv({ pkgRoot, userArgs });
+    io.stderr.write(`pactive: launching ${host} (${exec})\n`);
+    return new Promise((resolve) => {
+      const child = spawn(exec, argv, { stdio: 'inherit', env });
+      const forward = (sig) => {
+        if (!child.killed) child.kill(sig);
+      };
+      process.on('SIGINT', forward);
+      process.on('SIGTERM', forward);
+      child.on('error', (err) => {
+        io.stderr.write(`pactive: failed to launch ${host}: ${err.message}\n`);
+        resolve(err.code === 'ENOENT' ? 127 : 1);
+      });
+      child.on('exit', (code, signal) => {
+        process.off('SIGINT', forward);
+        process.off('SIGTERM', forward);
+        resolve(signal ? 128 + (os.constants.signals[signal] ?? 0) : (code ?? 0));
+      });
+    });
+  });
+}
+
+export async function main(argv, env = process.env, io = { stdout: process.stdout, stderr: process.stderr }) {
+  const args = argv.slice(2);
+  if (args.length === 0) {
+    usage(io.stderr);
+    return 2;
+  }
+  const [cmd, ...rest] = args;
+  switch (cmd) {
+    case '--version':
+    case '-v':
+      io.stdout.write(`${pactiveVersion()}\n`);
+      return 0;
+    case '--help':
+    case '-h':
+      // 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':
+      return { schedule: scheduleCmd, tasks: tasksCmd, cancel: cancelCmd }[cmd](rest, env, io);
+    case 'install':
+      return installCmd(rest, env, io, 'install');
+    case 'uninstall':
+      return installCmd(rest, env, io, 'uninstall');
+    default:
+      break;
+  }
+  if (!HOSTS.includes(cmd)) {
+    unknownHost(cmd, io.stderr);
+    return 2;
+  }
+  return runHost(cmd, rest, env, io);
+}
+
+// Entry guard: compare REAL paths. Installed bin shims and macOS /tmp are symlinks, so
+// `process.argv[1]` and `import.meta.url` differ textually when they point at the same file —
+// a plain string compare silently turns the CLI into a no-op (defect found 2026-11-05 via install chain).
+const isMain = (() => {
+  try {
+    const self = realpathSync(fileURLToPath(import.meta.url));
+    const argv1 = realpathSync(process.argv[1]);
+    return self === argv1;
+  } catch {
+    return false;
+  }
+})();
+if (isMain) {
+  try {
+    process.exitCode = await main(process.argv, process.env, { stdout: process.stdout, stderr: process.stderr });
+  } catch (err) {
+    const exitCode = err instanceof PactiveError ? err.exitCode : 1;
+    process.stderr.write(`pactive: ${err?.message ?? err}\n`);
+    process.exitCode = exitCode;
+  }
+}