pactive 0.0.3-alpha.1 → 0.0.4-alpha.1

package/src/core/tick.mjs

@@ -0,0 +1,128 @@
+import { defaultAssistantId } from './assistants.mjs';
+import { reserveTrigger } from './guard.mjs';
+import { evaluateIdle } from './idle.mjs';
+import { ledger } from './lineage.mjs';
+
+/** Reasons that mean "this really was going to fire but the throttle held it back". */
+export const THROTTLE_REASONS = ['quiet', 'hourly-limit', 'global-limit', 'min-interval', 'cooldown'];
+
+/**
+ * One drive round: due tasks + one idle sweep per enabled assistant,结果落 ledger。
+ *
+ * This is the minimal closed loop before a daemon exists: `pactive tick` runs it once, so the
+ * fleet is testable unattended. A blocked task stays active (retried next tick) — losing a
+ * reminder because the guard was closed would be silent data loss.
+ *
+ * ledger events (append-only, per assistantId): `triggered` + `delivered`, or `blocked`+reason.
+ */
+export function runTick(state, now = Date.now(), options = {}) {
+  const ts = Number.isFinite(now) ? now : Date.now();
+  const ledgerFile = typeof options.ledgerFile === 'string' && options.ledgerFile ? options.ledgerFile : null;
+  const only = typeof options.assistantId === 'string' && options.assistantId !== '' ? options.assistantId : null;
+  const record = (event) => {
+    if (ledgerFile) ledger.append(ledgerFile, event);
+    return event;
+  };
+
+  const delivered = [];
+  const blocked = [];
+  const fallbackId = defaultAssistantId(state.identity?.ownerKey ?? '');
+  const table = state.assistants && typeof state.assistants === 'object' ? state.assistants : {};
+  const tasks = Array.isArray(state.tasks) ? state.tasks : [];
+
+  const queued = [];
+  const unreachable = [];
+  /**
+   * Deliver one prompt and let the receipt decide the ledger event (contract §2.2):
+   * a bound pane that only *admitted* the text is `queued`, never `delivered` (I77).
+   */
+  const deliverOne = (base) => {
+    const assistant = table[base.assistantId] ?? null;
+    const pane = assistant?.pane ?? null;
+    if (pane && typeof options.paneDeliver === 'function') {
+      const receipt = options.paneDeliver({ ...base, pane }) ?? { state: 'queued', reason: 'no-receipt' };
+      const common = { assistantId: base.assistantId, paneId: pane.paneId, agentName: pane.agentName ?? null, ...base };
+      if (receipt.state === 'accepted') {
+        return delivered.push(record({
+          event: 'delivered',
+          ...common,
+          surface: 'herdr',
+          status: receipt.status ?? null,
+        }));
+      }
+      if (receipt.state === 'unreachable') {
+        // The pane is gone: drop the binding so the next `fleet up` can rebuild it. The
+        // assistant, its tasks and its history stay (I75).
+        assistant.pane = null;
+        return unreachable.push(record({ event: 'unreachable', ...common, reason: receipt.reason ?? 'unreachable' }));
+      }
+      return queued.push(record({ event: 'queued', ...common, reason: receipt.reason ?? 'queued' }));
+    }
+    // No pane: the in-process/outbox path (unchanged), but `paneId` is always present.
+    return delivered.push(record({ event: 'delivered', paneId: null, ...base }));
+  };
+
+  // ① Due tasks (explicit user reminders): min-interval/cooldown do not apply, the user asked.
+  for (const task of tasks) {
+    if (!task || typeof task !== 'object' || task.active === false) continue;
+    if (!Number.isFinite(task.dueAt) || task.dueAt > ts) continue;
+    const assistantId = typeof task.assistantId === 'string' && task.assistantId ? task.assistantId : fallbackId;
+    if (only && assistantId !== only) continue;
+    const res = reserveTrigger(state, ts, assistantId, { ignoreEpoch: true, skipIntervalGates: true });
+    if (res.reserved) {
+      task.lastRunAt = ts;
+      if (task.kind === 'every') task.dueAt = ts + (Number.isFinite(task.everyMs) ? task.everyMs : 0);
+      else task.active = false;
+      const assistant = table[assistantId];
+      if (assistant) {
+        assistant.lastFiredAt = ts;
+        assistant.firedCount = (Number.isFinite(assistant.firedCount) ? assistant.firedCount : 0) + 1;
+      }
+      record({ event: 'triggered', assistantId, taskId: task.id, taskKind: task.kind, source: 'tick' });
+      deliverOne({
+        assistantId,
+        taskId: task.id,
+        taskKind: task.kind,
+        source: 'tick',
+        prompt: task.prompt ?? null,
+      });
+    } else {
+      blocked.push(record({ event: 'blocked', assistantId, taskId: task.id, source: 'tick', reason: res.reason }));
+    }
+  }
+
+  // ② Idle sweep: only enabled assistants, only throttle reasons are recorded (no ledger spam).
+  for (const [assistantId, assistant] of Object.entries(table)) {
+    if (!assistant || assistant.enabled !== true) continue;
+    if (only && assistantId !== only) continue;
+    const result = evaluateIdle(state, ts, {}, assistantId);
+    if (result.idle) {
+      const res = reserveTrigger(state, ts, assistantId);
+      if (res.reserved) {
+        assistant.lastFiredAt = ts;
+        assistant.firedCount = (Number.isFinite(assistant.firedCount) ? assistant.firedCount : 0) + 1;
+        record({ event: 'triggered', assistantId, source: 'tick', reason: 'idle' });
+        deliverOne({ assistantId, source: 'tick', reason: 'idle' });
+      } else {
+        blocked.push(record({ event: 'blocked', assistantId, source: 'tick', reason: res.reason }));
+      }
+    } else if (THROTTLE_REASONS.includes(result.reason)) {
+      blocked.push(record({ event: 'blocked', assistantId, source: 'tick', reason: result.reason }));
+    }
+  }
+
+  return {
+    now: ts,
+    assistantId: only,
+    assistants: Object.keys(table).length,
+    delivered: delivered.length,
+    blocked: blocked.length,
+    queued: queued.length,
+    unreachable: unreachable.length,
+    deliveries: delivered,
+    queued_events: queued,
+    unreachable_events: unreachable,
+    blocks: blocked,
+    pending: tasks.filter((t) => t && t.active !== false).length,
+  };
+}

package/src/hosts/herdr/fleet-view.mjs

@@ -0,0 +1,31 @@
+// The fleet view shared by every tool surface (MCP / Pi / DSH) and the CLI.
+//
+// It is a thin join: the *binding* comes from pactive state (I76), the *status* comes from herdr
+// (`agent list`). When herdr cannot be asked, the status is `null` → rendered as "unobserved";
+// it is never guessed (I78).
+import * as herdr from './index.mjs';
+
+/** herdr `agent list` → `{available, ok, reason, map: agentName → agent_status}`. */
+export function herdrStatus(env = process.env) {
+  const probe = herdr.available({ env });
+  const map = new Map();
+  if (!probe.ok) return { available: false, ok: false, reason: probe.reason, map };
+  const listed = herdr.list({ env });
+  if (listed.ok) for (const agent of listed.agents) if (agent.agentName) map.set(agent.agentName, agent.status);
+  return { available: true, ok: listed.ok, reason: listed.ok ? null : listed.reason, map };
+}
+
+/** `{ok, count, herdr, rows}` — one row per assistant: identity ↔ pane ↔ status ↔ last delivery. */
+export function fleetPayload(core, state, paths, env = process.env) {
+  const status = herdrStatus(env);
+  const rows = core.fleet.view(state, {
+    ledgerFile: paths.ledgerFile,
+    statusOf: (pane) => (pane.agentName ? status.map.get(pane.agentName) ?? null : null),
+  });
+  return {
+    ok: true,
+    count: rows.length,
+    herdr: { available: status.available, reason: status.reason },
+    rows,
+  };
+}

package/src/hosts/herdr/index.mjs

@@ -0,0 +1,429 @@
+// Herdr host adapter (contract §2.1 / §2.2, I74–I79).
+//
+// Herdr is *not* a host we re-implement: it is the multiplexer we reuse. Nothing here creates a
+// PTY, a tab layout or a renderer (I74) — every call is a `herdr` CLI invocation whose argv we
+// only assemble, and every result is read back from herdr's own JSON envelope.
+//
+// Three rules this file exists to enforce:
+//   • I78 — herdr absent is an explicit refusal with a concrete reason, never a silent fake start.
+//   • I77 — delivery is judged on the *agent* surface (`agent prompt` + `agent get` state), never
+//           on screen text (`pane read | grep` is not evidence).
+//   • I79 — an assistant owns at most one live pane; `spawn` reuses an existing binding.
+import crypto from 'node:crypto';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+import { makeResolver } from '../shared/index.mjs';
+
+export const host = 'herdr';
+export const MODE = 'multiplexer';
+export const MIN_VERSION = '0.9';
+
+/** `herdr agent start --kind` values this adapter knows how to launch (§2.1). */
+export const AGENT_KINDS = {
+  pi: 'pi',
+  claude: 'claude',
+  codex: 'codex',
+  gemini: 'gemini',
+  cursor: 'cursor',
+  opencode: 'opencode',
+  qwen: 'qwen',
+  kimi: 'kimi',
+};
+
+/** Hosts herdr cannot recognise as an agent → degraded to `pane run` + a pane-only binding (I77). */
+export const PANE_ONLY_HOSTS = ['opcteam', 'dsh'];
+
+/** Placeholder for the pane id that only exists after the split/tab step has run. */
+export const PANE_TOKEN = '<pane_id>';
+
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..');
+
+/** `PACTIVE_HERDR_BIN` → PATH `herdr`; throws HostMissingError (exit 127) like every other host. */
+export const resolveExec = makeResolver(host, 'herdr');
+
+const DEFAULT_TIMEOUT_MS = 120000;
+/** Grace on top of herdr's own `--timeout` so herdr's verdict wins over the process kill. */
+const PROCESS_GRACE_MS = 5000;
+
+function timeoutFrom(env) {
+  const raw = Number(env?.PACTIVE_HERDR_TIMEOUT_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_TIMEOUT_MS;
+}
+
+function parseEnvelope(text) {
+  const trimmed = String(text ?? '').trim();
+  if (trimmed === '') return null;
+  try {
+    const parsed = JSON.parse(trimmed);
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/** I30: a child process must not inherit credential-shaped env (`*_API_KEY`, `*_TOKEN`, …). */
+const CREDENTIAL_ENV = /(^|_)(API_?KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIALS?|PRIVATE_?KEY)($|_)/i;
+
+export function childEnv(env = process.env) {
+  const out = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (!CREDENTIAL_ENV.test(key)) out[key] = value;
+  }
+  return out;
+}
+
+/**
+ * Run one herdr CLI call. Success/failure comes from the exit status; the payload (or the error
+ * code herdr itself reports) is read from the JSON envelope it prints.
+ */
+export function run(exec, argv, ctx = {}) {
+  const env = childEnv(ctx.env ?? process.env);
+  const res = spawnSync(exec, argv, {
+    encoding: 'utf8',
+    env,
+    timeout: ctx.timeoutMs ?? timeoutFrom(env),
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  const ok = res.status === 0;
+  const envelope = parseEnvelope(ok ? res.stdout : res.stderr) ?? parseEnvelope(res.stdout);
+  return {
+    ok,
+    code: res.status ?? 1,
+    argv,
+    result: envelope && envelope.result && typeof envelope.result === 'object' ? envelope.result : null,
+    error: envelope && envelope.error && typeof envelope.error === 'object' ? envelope.error : null,
+    reason: envelope?.error?.code ?? null,
+    stderr: String(res.stderr ?? '').trim(),
+    stdout: String(res.stdout ?? '').trim(),
+  };
+}
+
+/** I78: two independent preconditions, each with its own concrete reason. */
+export function available(ctx = {}) {
+  const env = ctx.env ?? process.env;
+  const reasons = [];
+  if (env.HERDR_ENV !== '1') {
+    reasons.push({
+      code: 'HERDR_ENV_MISSING',
+      reason: `HERDR_ENV is not 1 (got ${env.HERDR_ENV === undefined ? 'unset' : JSON.stringify(env.HERDR_ENV)}) — pactive is not running inside a herdr pane`,
+    });
+  }
+  let exec = null;
+  try {
+    exec = resolveExec({ env });
+  } catch (err) {
+    reasons.push({ code: err.code ?? 'HERDR_BIN_MISSING', reason: err.message });
+  }
+  const ok = reasons.length === 0;
+  return {
+    ok,
+    exec,
+    reasons,
+    reason: ok ? null : reasons.map((r) => r.reason).join('; '),
+    hint: 'daemon + outbox 仍可投递（pactive tick / pactive schedule 不依赖 herdr）',
+  };
+}
+
+/**
+ * Agent names must match `[a-z][a-z0-9_-]{0,31}` — a Chinese assistant name is not a valid agent
+ * name. The digest covers the *whole* assistantId: hashing only the `#owner` half would give every
+ * assistant of one owner the same pane name (two assistants → one agent, I79).
+ */
+export function agentNameFor(assistantId) {
+  const digest = crypto.createHash('sha256').update(String(assistantId ?? '')).digest('hex').slice(0, 12);
+  return `pactive-${digest}`;
+}
+
+export function kindFor(hostKind) {
+  return AGENT_KINDS[hostKind] ?? null;
+}
+
+export function isPaneOnly(hostKind) {
+  return PANE_ONLY_HOSTS.includes(hostKind) || kindFor(hostKind) === null;
+}
+
+function shellQuote(text) {
+  return /^[A-Za-z0-9_./:@%+=-]+$/.test(text) ? text : `'${String(text).replace(/'/g, `'\\''`)}'`;
+}
+
+/** The degraded launch command for a host herdr has no agent kind for (§2.1 last paragraph). */
+export function launchCommand(hostKind) {
+  return `${shellQuote(process.execPath)} ${shellQuote(path.join(PKG_ROOT, 'bin', 'pactive.mjs'))} ${hostKind}`;
+}
+
+/**
+ * The exact herdr argv `spawn` would run — this *is* the `--dry-run` output (zero side effects).
+ * A step marked `usesPaneId` gets PANE_TOKEN replaced with the real pane id at execution time.
+ */
+export function planSpawn(spec = {}) {
+  const assistantId = spec.assistantId ?? '';
+  const hostKind = spec.host ?? 'pi';
+  const cwd = spec.cwd ?? process.cwd();
+  const tab = spec.tab ?? null;
+  const direction = spec.direction === 'down' ? 'down' : 'right';
+  const agentName = agentNameFor(assistantId);
+  const kind = kindFor(hostKind);
+  const steps = [{ argv: null, usesPaneId: false }];
+
+  if (tab) {
+    steps[0].argv = ['tab', 'create', '--cwd', cwd, '--label', String(tab)];
+  } else {
+    steps[0].argv = ['pane', 'split', '--current', '--direction', direction, '--cwd', cwd, '--no-focus'];
+  }
+  steps.push({
+    argv: kind
+      ? ['agent', 'start', agentName, '--kind', kind, '--pane', PANE_TOKEN]
+      : ['pane', 'run', PANE_TOKEN, launchCommand(hostKind)],
+    usesPaneId: true,
+  });
+  return { assistantId, host: hostKind, agentName, kind, surface: kind ? 'agent' : 'pane', tab, cwd, steps };
+}
+
+function paneIdFrom(step) {
+  const result = step.result ?? {};
+  return (
+    result.pane?.pane_id ?? result.root_pane?.pane_id ?? result.pane_id ?? null
+  );
+}
+
+/**
+ * Create the pane and start the agent/pane command. Idempotency (I79) lives one level up in
+ * `fleet up`: an assistant that already has a live binding never reaches this function.
+ */
+export function spawn(spec = {}, ctx = {}) {
+  const probe = available(ctx);
+  if (!probe.ok) return { ok: false, state: 'unreachable', reason: probe.reason, reasons: probe.reasons };
+  const env = ctx.env ?? process.env;
+  const plan = planSpawn(spec);
+  const commands = [];
+
+  const first = run(probe.exec, plan.steps[0].argv, { env, timeoutMs: ctx.timeoutMs });
+  commands.push({ argv: plan.steps[0].argv, ok: first.ok, code: first.code, reason: first.reason });
+  if (!first.ok) {
+    return { ok: false, state: 'error', reason: first.reason ?? first.stderr ?? 'pane-create-failed', plan, commands };
+  }
+  const paneId = paneIdFrom(first);
+  if (!paneId) {
+    return { ok: false, state: 'error', reason: 'pane-id-missing', plan, commands };
+  }
+  const tabId = first.result?.tab?.tab_id ?? first.result?.pane?.tab_id ?? null;
+
+  const argv = plan.steps[1].argv.map((part) => (part === PANE_TOKEN ? paneId : part));
+  const second = run(probe.exec, argv, { env, timeoutMs: ctx.timeoutMs });
+  commands.push({ argv, ok: second.ok, code: second.code, reason: second.reason });
+  if (!second.ok && second.reason === 'agent_name_taken') {
+    // The name is already live: a previous run left the agent running, or the state lost the
+    // binding. Reuse that pane instead of failing (I79: one assistant, one pane — never two).
+    const adopted = getAgent(plan.agentName, { env });
+    if (adopted.ok && adopted.paneId) {
+      run(probe.exec, ['pane', 'close', paneId], { env, timeoutMs: ctx.timeoutMs });
+      return {
+        ok: true,
+        state: 'adopted',
+        plan,
+        commands,
+        binding: {
+          paneId: adopted.paneId,
+          agentName: plan.agentName,
+          host: plan.host,
+          surface: 'agent',
+          tabId: null,
+          boundAt: Date.now(),
+        },
+      };
+    }
+  }
+  if (!second.ok) {
+    // The pane exists but carries no agent: close it again so a failed start leaves no orphan pane.
+    run(probe.exec, ['pane', 'close', paneId], { env, timeoutMs: ctx.timeoutMs });
+    return {
+      ok: false,
+      state: 'error',
+      reason: second.reason ?? second.stderr ?? 'agent-start-failed',
+      paneId,
+      plan,
+      commands,
+    };
+  }
+
+  return {
+    ok: true,
+    state: 'bound',
+    plan,
+    commands,
+    binding: {
+      paneId,
+      agentName: plan.surface === 'agent' ? plan.agentName : null,
+      host: plan.host,
+      surface: plan.surface,
+      tabId,
+      boundAt: Date.now(),
+    },
+  };
+}
+
+/** `herdr agent list` → `[{paneId, agentName, status, cwd}]` (I76: 1:1 with `fleet ls`). */
+export function list(ctx = {}) {
+  const probe = available(ctx);
+  if (!probe.ok) return { ok: false, agents: [], reason: probe.reason };
+  const res = run(probe.exec, ['agent', 'list'], { env: ctx.env ?? process.env });
+  if (!res.ok) return { ok: false, agents: [], reason: res.reason ?? res.stderr ?? 'agent-list-failed' };
+  const agents = Array.isArray(res.result?.agents) ? res.result.agents : [];
+  return {
+    ok: true,
+    agents: agents
+      .filter((a) => a && typeof a === 'object')
+      .map((a) => ({
+        paneId: a.pane_id ?? null,
+        agentName: typeof a.name === 'string' && a.name !== '' ? a.name : null,
+        status: a.agent_status ?? 'unknown',
+        cwd: a.cwd ?? null,
+      })),
+  };
+}
+
+/** One agent's live state (`agent get`) — the observation channel of §2.2/I77. */
+export function getAgent(target, ctx = {}) {
+  const probe = available(ctx);
+  if (!probe.ok) return { ok: false, state: 'unreachable', reason: probe.reason };
+  const res = run(probe.exec, ['agent', 'get', target], { env: ctx.env ?? process.env });
+  if (!res.ok) {
+    const gone = res.reason === 'agent_not_found' || res.reason === 'pane_not_found';
+    return { ok: false, state: gone ? 'unreachable' : 'error', reason: res.reason ?? res.stderr ?? 'agent-get-failed' };
+  }
+  const agent = res.result?.agent ?? res.result ?? {};
+  return {
+    ok: true,
+    state: 'observed',
+    status: agent.agent_status ?? 'unknown',
+    paneId: agent.pane_id ?? null,
+    cwd: agent.cwd ?? null,
+  };
+}
+
+/** A pane still exists? (`pane get`) */
+export function paneAlive(paneId, ctx = {}) {
+  const probe = available(ctx);
+  if (!probe.ok) return { ok: false, alive: null, reason: probe.reason };
+  const res = run(probe.exec, ['pane', 'get', paneId], { env: ctx.env ?? process.env });
+  if (res.ok) return { ok: true, alive: true };
+  if (res.reason === 'pane_not_found') return { ok: true, alive: false, reason: 'pane_not_found' };
+  return { ok: false, alive: null, reason: res.reason ?? res.stderr ?? 'pane-get-failed' };
+}
+
+const UNREACHABLE_REASONS = new Set(['agent_not_found', 'pane_not_found', 'agent_exited', 'pane_closed']);
+
+/**
+ * Deliver one prompt (§2.2).
+ *
+ * `delivered` needs BOTH: the command returned ok AND `agent get` reported `working|blocked`
+ * (herdr's own states — we do not invent a vocabulary). Anything weaker is `queued` and says so;
+ * a vanished pane/agent is `unreachable` so the caller can drop the binding.
+ */
+export function deliver(spec = {}, ctx = {}) {
+  const env = ctx.env ?? process.env;
+  const probe = available(ctx);
+  if (!probe.ok) return { ok: false, state: 'unreachable', reason: probe.reason, at: Date.now() };
+
+  const text = String(spec.text ?? '');
+
+  // Degraded pane surface: `pane run` only acknowledges *admission*. There is no agent state to
+  // observe, so we must not call it delivered (I77) — the caller falls back to the outbox.
+  if (!spec.agentName) {
+    if (!spec.paneId) return { ok: false, state: 'unreachable', reason: 'no-agent-and-no-pane', at: Date.now() };
+    const alive = paneAlive(spec.paneId, { env });
+    if (alive.alive === false) return { ok: false, state: 'unreachable', reason: 'pane_not_found', paneId: spec.paneId, at: Date.now() };
+    const res = run(probe.exec, ['pane', 'run', spec.paneId, text], { env, timeoutMs: ctx.timeoutMs });
+    if (!res.ok) {
+      const state5 = UNREACHABLE_REASONS.has(res.reason) ? 'unreachable' : 'queued';
+      return { ok: false, state: state5, reason: res.reason ?? res.stderr ?? 'pane-run-failed', paneId: spec.paneId, at: Date.now() };
+    }
+    return {
+      ok: false,
+      state: 'queued',
+      reason: 'pane-surface-unobservable',
+      paneId: spec.paneId,
+      admitted: true,
+      at: Date.now(),
+    };
+  }
+
+  const before = getAgent(spec.agentName, { env });
+  if (before.state === 'unreachable') {
+    return { ok: false, state: 'unreachable', reason: before.reason, agentName: spec.agentName, at: Date.now() };
+  }
+
+  // Real herdr rejects `--timeout` without `--wait` ("--timeout requires --wait"), and `--wait`
+  // *is* the activity gate we need: it returns `agent_prompt_stalled` unless herdr itself observed
+  // `working`/`blocked` within 5s (§2.2: use herdr's semantics, do not invent our own).
+  const timeoutMs = Number.isFinite(spec.timeoutMs) && spec.timeoutMs > 0 ? spec.timeoutMs : timeoutFrom(env);
+  const sent = run(
+    probe.exec,
+    ['agent', 'prompt', spec.agentName, text, '--wait', '--timeout', String(timeoutMs)],
+    { env, timeoutMs: timeoutMs + PROCESS_GRACE_MS },
+  );
+  const after = getAgent(spec.agentName, { env });
+
+  if (sent.ok) {
+    return {
+      ok: true,
+      state: 'accepted',
+      reason: after.status === 'blocked' ? 'agent-blocked' : 'agent-activity-observed',
+      status: after.status ?? null,
+      agentName: spec.agentName,
+      paneId: after.paneId ?? spec.paneId ?? null,
+      at: Date.now(),
+    };
+  }
+  // `timeout` is the ambiguous verdict (herdr: "a timeout does not prove the prompt was never
+  // delivered") — say so instead of pretending either way.
+  const ambiguous = sent.reason === 'timeout';
+  return {
+    ok: false,
+    state: UNREACHABLE_REASONS.has(sent.reason) ? 'unreachable' : 'queued',
+    reason: sent.reason ?? sent.stderr ?? 'agent-prompt-failed',
+    ambiguous,
+    status: after.status ?? null,
+    agentName: spec.agentName,
+    at: Date.now(),
+  };
+}
+
+/** Close the pane (`pane close`); an already-closed pane counts as done (idempotent). */
+export function close(paneId, ctx = {}) {
+  const probe = available(ctx);
+  if (!probe.ok) return { ok: false, state: 'unreachable', reason: probe.reason, paneId };
+  const res = run(probe.exec, ['pane', 'close', paneId], { env: ctx.env ?? process.env });
+  if (res.ok) return { ok: true, state: 'closed', paneId, at: Date.now() };
+  if (res.reason === 'pane_not_found') return { ok: true, state: 'already-closed', paneId, at: Date.now() };
+  return { ok: false, state: 'error', reason: res.reason ?? res.stderr ?? 'pane-close-failed', paneId, at: Date.now() };
+}
+
+/** Focus the assistant's pane (agent surface only; a bare pane has no focus API). */
+export function focus(binding, ctx = {}) {
+  const probe = available(ctx);
+  if (!probe.ok) return { ok: false, state: 'unreachable', reason: probe.reason };
+  if (!binding?.agentName) {
+    return { ok: false, state: 'rejected', reason: 'pane-surface-has-no-focus-api', paneId: binding?.paneId ?? null };
+  }
+  const res = run(probe.exec, ['agent', 'focus', binding.agentName], { env: ctx.env ?? process.env });
+  if (!res.ok) return { ok: false, state: 'error', reason: res.reason ?? res.stderr ?? 'agent-focus-failed' };
+  return { ok: true, state: 'focused', paneId: binding.paneId ?? null, agentName: binding.agentName };
+}
+
+/** The launch plan shape the other hosts expose, so `doctor`/`--print-plan` stay uniform. */
+export function plan(ctx = {}) {
+  const probe = available(ctx);
+  return {
+    host,
+    version: MIN_VERSION,
+    mode: MODE,
+    exec: probe.exec,
+    available: probe.ok,
+    reasons: probe.reasons,
+    agentKinds: Object.keys(AGENT_KINDS),
+    paneOnlyHosts: PANE_ONLY_HOSTS,
+  };
+}