quoxcli 0.2.0 → 0.3.1

package/lib/core/slotWake.js

@@ -0,0 +1,120 @@
+/**
+ * POKE-WAKE (owner 2026-10-15: "/poke cli-site ... not listening right now ... this delay not ideal").
+ *
+ * A page is a slot message; an idle Claude Code session only reads slot mail when a turn starts
+ * (the UserPromptSubmit slot-inbox hook). Nothing starts a turn in an idle session except input.
+ * So `wake` is a slot CONTROL command (server-gated to a human org admin, never an agent) that the
+ * session's own keeper runs: it types ONE FIXED LINE into the session's tmux pane, and only when
+ * the pane is still and its prompt box is empty. The page text is never typed; the session reads
+ * it through the normal slot path. Pure decisions live here; the keeper does the I/O.
+ */
+
+export const WAKE_TTL_MS = 10 * 60 * 1000; // a busy session is retried each control tick for this long
+export const WAKE_COALESCE_MS = 60 * 1000; // repeat pokes inside this window do not type again
+export const WAKE_SETTLE_MS = 2000; // two pane samples this far apart: any change = busy or a human typing
+
+const SLOT_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
+// A box rule; the TOP one may carry the session title ("──── QUOXON ─", seen live 2026-10-15).
+const RULE_RE = /^\s*─{8,}(?:.*─)?\s*$/;
+const PROMPT_RE = /^\s*❯(?:[\s ]|$)/;
+// FORCE-WAKE: captures are escape-aware (`capture-pane -e`). Claude Code draws its empty-box suggestion FAINT
+// (ESC[2m) straight after the prompt; plain capture read it as a draft (proven live, v2.1.288, 2026-10-16).
+const ANSI_RE = /\x1b\[[0-9;?]*[A-Za-z]/g;
+const PLACEHOLDER_RE = /❯[\s ]*(?:\x1b\[(?!2m)[0-9;]*m)*\x1b\[2m/;
+const UNCAPTURABLE_RE = /\[(?:Pasted text|Image)\b/;
+const plain = (line) => line.replace(ANSI_RE, '');
+
+/** The only text a wake ever types. Names the slot, never carries the page. */
+export function wakeText(slot) {
+  if (typeof slot !== 'string' || !SLOT_RE.test(slot)) throw new Error(`not a slot name: ${JSON.stringify(slot)}`);
+  return `[quox slot wake] a page is waiting on slot ${slot}: read it with \`quox slot read ${slot}\` and answer there with \`quox slot say ${slot}\`.`;
+}
+
+const flat = (s) => String(s).replace(/\s+/g, '');
+/** WAKE-REAL: do these box lines (draftLines) hold exactly this slot's wake line, as Claude Code wrapped it? */
+export function isWakeLine(lines, slot) {
+  if (!Array.isArray(lines) || !lines.length || !SLOT_RE.test(String(slot || ''))) return false;
+  return flat(lines.join('')) === flat(wakeText(slot));
+}
+
+// WAKE-REAL: what Claude Code (v2.1.288, seen live 2026-10-17) shows while a submitted line waits for a running
+// turn: the line above the box with "ctrl+x ctrl+s to send now", and "Press up to edit queued messages" in it.
+const QUEUED_RE = /Press up to edit queued|ctrl\+x ctrl\+s to send now/;
+/** Did the last submit land in Claude Code's queue (session mid-turn) rather than start a turn? */
+export function wakeQueued(text) {
+  return typeof text === 'string' && QUEUED_RE.test(aboveFooter(text).split('\n').map(plain).join('\n'));
+}
+
+/**
+ * The state of the LAST Claude Code prompt box on screen: 'empty', 'draft' (typing would send a
+ * human's unsent text) or 'unknown' (no box: a dialog, menu or pager; never treated as empty).
+ */
+export function promptBoxState(text) {
+  const lines = draftLines(text);
+  if (lines === null) return 'unknown';
+  return lines.join('\n').replace(/\u00a0/g, ' ').trim() ? 'draft' : 'empty';
+}
+
+/**
+ * FORCE-WAKE: the last prompt box's draft as rendered, one entry per visual line (plain text, prompt
+ * stripped, trailing spaces dropped); [] for an empty box (or the faint placeholder); null for no box.
+ */
+export function draftLines(text) {
+  if (typeof text !== 'string' || !text) return null;
+  const raw = text.split('\n');
+  const lines = raw.map(plain);
+  for (let i = lines.length - 1; i > 0; i -= 1) {
+    if (!PROMPT_RE.test(lines[i]) || !RULE_RE.test(lines[i - 1])) continue;
+    if (PLACEHOLDER_RE.test(raw[i])) return [];
+    const body = [lines[i].replace(PROMPT_RE, '')];
+    for (let j = i + 1; j < lines.length && !RULE_RE.test(lines[j]); j += 1) body.push(lines[j]);
+    const out = body.map((l) => l.replace(/\u00a0/g, ' ').replace(/\s+$/, ''));
+    while (out.length && !out[out.length - 1]) out.pop();
+    return out.join('').trim() ? out : [];
+  }
+  return null;
+}
+
+/** The screen down to the last prompt box's closing rule: the footer below it ticks (shell counts,
+ * agent timers) on an idle session, so it must not count as activity. No box = the whole screen. */
+export function aboveFooter(text) {
+  if (typeof text !== 'string') return text;
+  const raw = text.split('\n');
+  const lines = raw.map(plain);
+  for (let i = lines.length - 1; i > 0; i -= 1) {
+    if (!PROMPT_RE.test(lines[i]) || !RULE_RE.test(lines[i - 1])) continue;
+    let j = i + 1;
+    while (j < lines.length && !RULE_RE.test(lines[j])) j += 1;
+    return raw.slice(0, Math.min(j + 1, raw.length)).join('\n');
+  }
+  return text;
+}
+
+/**
+ * One wake attempt. before/after are two pane captures WAKE_SETTLE_MS apart (null = unreadable).
+ * force (FORCE-WAKE, human-requested rows only): a draft yields { action: 'force' } instead of a refusal.
+ * Returns { action: 'type' } | { action: 'force' } | { action: 'submit' } (our own stranded wake line) | { action: 'wait', reason } (leave the request pending) |
+ * { action: 'done' | 'fail', result }.
+ */
+export function decideWake({ slot, before, after, firstSeenAt, nowMs, lastWokeAt = null, force = false }) {
+  if (typeof before !== 'string' || typeof after !== 'string') return { action: 'fail', result: 'could not read the session pane' };
+  if (lastWokeAt != null && nowMs - lastWokeAt < WAKE_COALESCE_MS) return { action: 'done', result: `already woken ${Math.round((nowMs - lastWokeAt) / 1000)}s ago` };
+  const expired = nowMs - firstSeenAt > WAKE_TTL_MS;
+  if (aboveFooter(before) !== aboveFooter(after)) {
+    return expired ? { action: 'fail', result: `session still busy and the wake request is ${Math.floor((nowMs - firstSeenAt) / 60000)}m old (limit ${WAKE_TTL_MS / 60000}m); the page on ${slot} shows at its next prompt` } : { action: 'wait', reason: 'busy' };
+  }
+  const box = promptBoxState(after);
+  // WAKE-REAL: the box holds OUR wake line, typed earlier but never submitted (Claude Code dropped its Enter;
+  // QUOXON 2026-10-17 00:36:41, proven by sha c8d63692). It is not a human draft: submit it, never set it aside.
+  if (box === 'draft' && isWakeLine(draftLines(after), slot)) return { action: 'submit' };
+  if (box === 'draft' && force) {
+    // FORCE-WAKE: a human wake sets the draft aside and puts it back unsent; only if it can be put back exactly.
+    if (UNCAPTURABLE_RE.test(draftLines(after).join('\n'))) return { action: 'fail', result: 'not woken: the draft holds a collapsed pasted block or image, which cannot be set aside and put back exactly; the page shows at its next prompt' };
+    return { action: 'force' };
+  }
+  if (box === 'draft') return { action: 'fail', result: 'not woken: an unsent draft is in the prompt box (typing would send it); the page shows at its next prompt' };
+  if (box === 'unknown') {
+    return expired ? { action: 'fail', result: `no empty prompt and the wake request is ${Math.floor((nowMs - firstSeenAt) / 60000)}m old (a dialog or menu is open); the page shows at its next prompt` } : { action: 'wait', reason: 'no prompt box' };
+  }
+  return { action: 'type' };
+}

package/lib/core/supervisorEngine.js

@@ -278,18 +278,24 @@ export async function attemptSlotClaim({
         return { claimed: false, reason: 'error', error: err };
       }
       claimState.held = false;
+      claimState.lapsed = true;
     }
   }
   try {
+    const wasHeld = !!(claimState && claimState.everHeld);
     const res = await checkoutSlot();
-    if (claimState) { claimState.held = true; claimState.claimedAt = now(); }
+    if (claimState) { claimState.held = true; claimState.everHeld = true; claimState.claimedAt = now(); }
     const refreshed = !!(res && res.refreshed);
+    // GRIPE-797: log state transitions only. A periodic safety re-checkout
+    // of a hold this process already had is a renewal, not a new claim.
+    if (wasHeld && claimState && !claimState.lapsed) return { claimed: true, refreshed: true };
+    if (claimState) claimState.lapsed = false;
     log('info', refreshed
       ? `slot ${slot}: already held by this resident, refreshed.`
       : `slot ${slot}: claimed (was free), now present.`);
     return refreshed ? { claimed: true, refreshed } : { claimed: true };
   } catch (err) {
-    if (claimState) claimState.held = false;
+    if (claimState) { claimState.held = false; claimState.lapsed = true; }
     if (err && err.status === 409) {
       const holder = err.detail?.holder_session || null;
       if (holder && holder !== selfIdentity) {
@@ -479,6 +485,40 @@ export function detectTurnError(result) {
   return { type, message, category, signature };
 }
 
+/**
+ * GRIPE-797: an expired provider login (claude "Failed to authenticate:
+ * OAuth session expired and could not be refreshed", codex "not logged in"
+ * or a 401) is NOT a generic provider error: the fix is a human running a
+ * login command on this host. Returns {provider, command} or null.
+ */
+export function detectAuthExpiry(result) {
+  if (!result || result.timedOut || result.error) return null;
+  // Only a FAILED turn can be an expiry: a successful reply that merely
+  // talks about logins or 401s is a reply, never an alert.
+  if (!detectTurnError(result)) return null;
+  const parts = [result.text, result.stdout, result.stderr];
+  const raw = result.raw;
+  if (raw && typeof raw === 'object') {
+    parts.push(raw.result, raw.message, raw.error && (raw.error.message || raw.error));
+  }
+  const blob = parts.filter((x) => typeof x === 'string').join('\n');
+  if (!blob) return null;
+  if (/failed to authenticate|oauth session expired|could not be refreshed|invalid authentication credentials|please run \/login/i.test(blob)) {
+    return { provider: 'claude', command: 'claude /login' };
+  }
+  if (/not logged in|codex login|401 unauthorized|\b401\b[^\n]{0,40}(unauthorized|authentication)|token (has )?expired/i.test(blob)) {
+    const claudeish = /claude/i.test(blob) && !/codex/i.test(blob);
+    return claudeish ? { provider: 'claude', command: 'claude /login' } : { provider: 'codex', command: 'codex login' };
+  }
+  return null;
+}
+
+export function buildAuthExpiryNoticeText(hostId, auth) {
+  const cmd = auth && auth.provider === 'codex' ? 'codex login' : 'claude /login';
+  const alt = auth && auth.provider === 'codex' ? '(or `claude /login`)' : '(or `codex login`)';
+  return `My login on ${hostId} has expired; run \`${cmd}\` ${alt} on ${hostId}.`;
+}
+
 /**
  * One short, plain-language, single-sentence notice: no stack, no JSON, no
  * raw provider payload. This is the ONE honest signal an operator gets per
@@ -644,6 +684,7 @@ export async function runPollOnce({
   claimState = null,
   postHeartbeat = null,
   postTurnReceipt = null,
+  alertOwner = null,
   state,
   log = () => {},
   now = () => Date.now(),
@@ -786,6 +827,29 @@ export async function runPollOnce({
     // resident's own reply. Log the full error, record it in state for
     // `status` to surface, and post at most one short plain-language
     // notice per distinct error signature per hour.
+    const authExpiry = detectAuthExpiry(result);
+    if (authExpiry) {
+      log('error', `turn auth expiry for message ${message.id}: provider=${authExpiry.provider} (login expired; never posted raw)`);
+      await receipt({ outcome: 'error', message_id: message.id, message_from: message.from, duration_ms: durationMs, error_note: `auth_expired: ${authExpiry.provider}` });
+      const noticeText = buildAuthExpiryNoticeText(hostId, authExpiry);
+      nextState = {
+        ...nextState,
+        last_turn_error: { type: 'auth_expired', message: noticeText, category: 'auth expiry', signature: `auth_expired:${authExpiry.provider}`, at: new Date(now()).toISOString() },
+      };
+      // ONE slot reply + ONE owner alert per expiry episode; the flag is
+      // cleared only by a successful reply below.
+      if (!nextState.auth_expiry_alerted_at) {
+        await postReply(noticeText);
+        if (alertOwner) {
+          try { await alertOwner(noticeText); } catch (err) { log('warn', `auth-expiry owner alert failed: ${err.message}`); }
+        }
+        nextState = { ...nextState, auth_expiry_alerted_at: new Date(now()).toISOString() };
+        log('warn', `posted auth-expiry notice and owner alert (once per episode): ${noticeText}`);
+      } else {
+        log('warn', 'auth-expiry notice suppressed (already alerted this episode; clears on next successful turn).');
+      }
+      continue;
+    }
     const turnError = detectTurnError(result);
     if (turnError) {
       log('error', `turn error for message ${message.id}: type=${turnError.type} message=${turnError.message} (never posted to the channel)`);
@@ -813,6 +877,11 @@ export async function runPollOnce({
       continue;
     }
 
+    if (nextState.auth_expiry_alerted_at) {
+      const { auth_expiry_alerted_at: _cleared, ...rest } = nextState;
+      nextState = rest;
+      log('info', 'auth recovered: successful turn, auth-expiry alert re-armed.');
+    }
     await postReply(replyText);
     log('info', `replied to ${message.id} (${replyText.length} chars, session_id=${result.session_id || 'n/a'}, cost_usd=${result.total_cost_usd ?? 'n/a'})`);
     await receipt({

package/lib/core/version.js

@@ -18,7 +18,7 @@ import { execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';
 
-export const BASE_VERSION = '0.2.0';
+export const BASE_VERSION = '0.3.1';
 
 // The CLI source root (…/cli). version.js lives at cli/lib/core/, so two
 // levels up is the tree whose HEAD identifies the running build.

package/lib/core/vm.js

@@ -0,0 +1,361 @@
+/**
+ * Shared engine behind `quox vm` and the QUOXON `/vm` command: drives the
+ * HYPERION (agent id atlas) Proxmox tools through the governed tool route
+ * (POST /api/v1/tools/execute). Pure functions over an injected `exec(tool, input)`
+ * so the CLI group and the TUI share one implementation and one set of tests.
+ *
+ * Tool names/inputs are the contract with the server side:
+ *   proxmox_vms, proxmox_containers, proxmox_vm_resources, proxmox_vm_action,
+ *   proxmox_vm_snapshot, proxmox_vm_resolve {name|vmid}, proxmox_pool_status,
+ *   proxmox_pool_lease, proxmox_pool_release, proxmox_pool_configure,
+ *   proxmox_node_power, proxmox_rehearse {vmid, node, command, checks?, keep_twin?} (starts, returns {rehearsal_id, state:'running'}),
+ *   proxmox_rehearsal_status {rehearsal_id}.
+ */
+
+import os from 'node:os';
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+export const VM_ACTIONS = ['start', 'stop', 'reboot', 'shutdown'];
+export const NODE_ACTIONS = ['reboot', 'shutdown'];
+
+/** A write was held for a human. Callers print the hint and never re-submit. */
+export class VmPendingError extends Error {
+  constructor(tool, data) {
+    super(`${tool} is awaiting approval`);
+    this.name = 'VmPendingError';
+    this.tool = tool;
+    this.approvalId = data?.approvalId || data?.approval_id || data?._approval?.id || null;
+    this.inboxItemId = data?.inbox_item_id || null;
+    this.rehearsalId = data?.rehearsal_id || null;
+  }
+}
+
+export function pendingHint(e) {
+  const id = e.approvalId || e.inboxItemId;
+  if (!id) return `${e.tool} is awaiting approval. Check: quox approvals`;
+  return `${e.tool} is awaiting approval (approval id ${id}). After a human approves, run: quox approvals result ${id}`;
+}
+
+/**
+ * DEVFLEET-READ: HYPERION (atlas) is granted ONE read tool, proxmox_read, not the per-view read
+ * tools. Callers keep using the old names; the wire call is proxmox_read with the matching view.
+ * Writes (proxmox_vm_action, _snapshot, _rehearse, _vm_doctor, pool lease/release/config) pass through.
+ */
+export const PROXMOX_READ_VIEW_OF = {
+  proxmox_vms: 'vms', proxmox_containers: 'containers', proxmox_cluster_status: 'cluster',
+  proxmox_ha_status: 'ha', proxmox_templates_list: 'templates', proxmox_storage: 'storage',
+  proxmox_node_resources: 'node', proxmox_vm_resources: 'vm', proxmox_snapshots_list: 'snapshots',
+  proxmox_backup_status: 'backups', proxmox_vm_resolve: 'resolve', proxmox_pool_status: 'pool',
+  proxmox_rehearsal_status: 'rehearsal', proxmox_doctor_report: 'doctor_report',
+};
+
+// Tools that fan out many Proxmox reads server-side and outlive the client's 30s default.
+// VM Doctor runs 12 reads in parallel; over Bastion pvesh on a slow node that is ~30s.
+export const SLOW_TOOL_TIMEOUT_MS = { proxmox_vm_doctor: 120000, proxmox_snapshots_list: 90000 };
+
+/** Build an exec(tool, input) over an API client. Throws VmPendingError on a held call. */
+export function makeExec({ client, orgId }) {
+  return async function exec(tool, input = {}) {
+    const ep = resolveEndpoint('v1.tools.execute');
+    // HYPERION (atlas) owns these tools; without agent_id the call lands on the
+    // orchestrator, which is not granted them. An attach token's agent claim still wins server-side.
+    const view = PROXMOX_READ_VIEW_OF[tool];
+    const body = view ? { tool_name: 'proxmox_read', input: { view, ...input }, agent_id: 'atlas' } : { tool_name: tool, input, agent_id: 'atlas' };
+    if (orgId) body.org_id = orgId;
+    const timeout = SLOW_TOOL_TIMEOUT_MS[tool];
+    let data = await client.post(ep.path, { service: ep.service, body, ...(timeout ? { timeout } : {}) });
+    // The caller's own token identity wins over agent_id server-side (e.g. an attached session runs
+    // as itself, which holds the legacy reads like proxmox_vms but not proxmox_read). When proxmox_read
+    // is not granted to that identity, retry once with the legacy per-view tool it does hold.
+    if (view && data && data.success === false && /not granted/i.test(String(data.error || ''))) {
+      const legacy = { tool_name: tool, input, agent_id: 'atlas' };
+      if (orgId) legacy.org_id = orgId;
+      data = await client.post(ep.path, { service: ep.service, body: legacy });
+    }
+    if (data && data.pending) throw new VmPendingError(tool, data);
+    if (data && data.success === false) {
+      const err = new Error(`${tool} via POST ${ep.path} returned success:false: ${data.error || 'unknown error'}`);
+      err.toolError = data.error || 'unknown error';
+      err.tool = tool;
+      throw err;
+    }
+    return data;
+  };
+}
+
+/** The tool's payload, whatever envelope it came wrapped in. */
+export function payloadOf(data) {
+  let p = data;
+  if (p && typeof p === 'object' && !Array.isArray(p)) {
+    for (const k of ['result', 'output', 'data']) {
+      if (p[k] !== undefined && p[k] !== null) { p = p[k]; break; }
+    }
+  }
+  if (typeof p === 'string') { try { return JSON.parse(p); } catch { return p; } }
+  return p;
+}
+
+function arrayOf(p, ...keys) {
+  if (Array.isArray(p)) return p;
+  for (const k of [...keys, 'items', 'results', 'resources']) if (Array.isArray(p?.[k])) return p[k];
+  return [];
+}
+
+const normVm = (v, fallbackType) => ({
+  vmid: Number(v.vmid ?? v.id),
+  name: v.name ?? v.hostname ?? '',
+  node: v.node ?? null,
+  type: v.type === 'lxc' || v.type === 'qemu' ? v.type : (fallbackType || 'qemu'),
+  status: v.status ?? v.state ?? '',
+  raw: v,
+});
+
+const isUnknownTool = (e) => e?.status === 404
+  || /unknown tool|tool .*not (found|available|registered)|no such tool|unsupported tool|not implemented/i.test(e?.toolError || e?.message || '');
+
+export async function listVms(exec, { node, type } = {}) {
+  if (type && !['qemu', 'lxc'].includes(type)) throw new Error('--type must be qemu or lxc');
+  const out = [];
+  if (type !== 'lxc') {
+    const p = payloadOf(await exec('proxmox_vms', node ? { node } : {}));
+    for (const v of arrayOf(p, 'vms')) out.push(normVm(v, 'qemu'));
+  }
+  if (type === 'lxc') {
+    const p = payloadOf(await exec('proxmox_containers', node ? { node } : {}));
+    for (const v of arrayOf(p, 'containers', 'lxc')) out.push(normVm(v, 'lxc'));
+  }
+  return node ? out.filter((v) => !v.node || v.node === node) : out;
+}
+
+/**
+ * name|vmid -> { vmid, node, type, name }. Tool proxmox_vm_resolve first; if the server
+ * does not know it, fall back to client-side exact match over proxmox_vms + proxmox_containers.
+ * Ambiguity is an error listing candidates; never a guess.
+ */
+export async function resolveTarget(exec, target) {
+  const t = String(target ?? '').trim();
+  if (!t) throw new Error('a VM name or vmid is required');
+  const numeric = /^\d+$/.test(t);
+  const input = numeric ? { vmid: Number(t) } : { name: t };
+  let matches = null;
+  try {
+    const p = payloadOf(await exec('proxmox_vm_resolve', input));
+    const list = Array.isArray(p) ? p : (p?.matches || p?.candidates || (p && (p.vmid !== undefined || p.id !== undefined) ? [p] : []));
+    matches = list.map((v) => normVm(v));
+    if (!matches.length) throw new Error(`no VM matches "${t}" (proxmox_vm_resolve)`);
+  } catch (e) {
+    if (e instanceof VmPendingError || !isUnknownTool(e)) throw e;
+    matches = null;
+  }
+  if (matches === null) {
+    const all = await listVms(exec, {});
+    try { all.push(...await listVms(exec, { type: 'lxc' })); } catch (e) { if (e instanceof VmPendingError) throw e; /* containers are optional */ }
+    matches = all.filter((v) => (numeric ? v.vmid === Number(t) : v.name === t));
+    if (!matches.length) throw new Error(`no VM matches "${t}" (checked proxmox_vms and proxmox_containers; exact name match only)`);
+  }
+  if (matches.length > 1) {
+    const lines = matches.map((v) => `  ${v.vmid}  ${v.name}  ${v.node || '?'}  ${v.type}`).join('\n');
+    throw new Error(`"${t}" is ambiguous, ${matches.length} candidates (use the vmid):\n${lines}`);
+  }
+  const m = matches[0];
+  if (!m.node) throw new Error(`could not determine the node for "${t}" (vmid ${m.vmid})`);
+  return { vmid: m.vmid, node: m.node, type: m.type, name: m.name };
+}
+
+const withReason = (input, reason) => (reason ? { ...input, _reason: reason } : input);
+
+export async function vmInfo(exec, target) {
+  const vm = await resolveTarget(exec, target);
+  const data = await exec('proxmox_vm_resources', { vmid: vm.vmid, node: vm.node, type: vm.type });
+  return { vm, resources: payloadOf(data) };
+}
+
+export async function vmAction(exec, action, target, { reason } = {}) {
+  if (!VM_ACTIONS.includes(action)) throw new Error(`action must be one of ${VM_ACTIONS.join(', ')}`);
+  const vm = await resolveTarget(exec, target);
+  const data = await exec('proxmox_vm_action', withReason({ vmid: vm.vmid, node: vm.node, action, type: vm.type }, reason));
+  return { vm, result: payloadOf(data) };
+}
+
+export async function vmSnapshot(exec, target, { name, reason } = {}) {
+  const vm = await resolveTarget(exec, target);
+  // proxmox_vm_snapshot requires snapname (Proxmox: letter first, then [A-Za-z0-9_-]).
+  const snapname = name || `quox-${new Date().toISOString().replace(/[-:]/g, '').replace('T', '-').slice(0, 15)}`;
+  if (!/^[A-Za-z][A-Za-z0-9_-]{0,39}$/.test(snapname)) throw new Error('snapshot name must start with a letter and use only letters, digits, _ or -');
+  const input = { vmid: vm.vmid, node: vm.node, snapname };
+  const data = await exec('proxmox_vm_snapshot', withReason(input, reason));
+  return { vm, result: payloadOf(data) };
+}
+
+/**
+ * `url:http://127.0.0.1:8080/health` | `unit:nginx` | `cmd:test -f /etc/x` -> a proxmox_rehearse check.
+ * Only the shape is checked here; the server validates the characters strictly.
+ */
+export function parseCheck(spec) {
+  const m = /^(url|unit|cmd):(.+)$/.exec(String(spec ?? '').trim());
+  if (!m) throw new Error(`--check must look like url:http://127.0.0.1:PORT/path, unit:NAME or cmd:COMMAND (got "${spec}")`);
+  if (m[1] === 'url') return { type: 'url', url: m[2] };
+  if (m[1] === 'unit') return { type: 'unit', name: m[2] };
+  return { type: 'cmd', run: m[2] };
+}
+
+/** Start a rehearsal on a network-isolated twin of the VM (HYPERION proxmox_rehearse). Returns at once; the run takes minutes (a full disk copy). */
+export async function vmRehearse(exec, target, command, { checks = [], keepTwin = false } = {}) {
+  const c = String(command ?? '').trim();
+  if (!c) throw new Error('a command is required after --');
+  if (c.includes("'")) throw new Error('the command may not contain single quotes (it runs inside bash -c, use double quotes)');
+  const vm = await resolveTarget(exec, target);
+  const input = { vmid: vm.vmid, node: vm.node, command: c };
+  if (checks.length) input.checks = checks.map(parseCheck);
+  if (keepTwin) input.keep_twin = true;
+  let data;
+  try { data = await exec('proxmox_rehearse', input); } catch (e) {
+    // The rehearsal needs ONE human approval (the card lists every host command). The proposal exists and
+    // the run starts by itself once approved, so hand back the id instead of failing.
+    if (e instanceof VmPendingError && e.rehearsalId) {
+      return { vm, result: { rehearsal_id: e.rehearsalId, state: 'awaiting_approval', approval_id: e.approvalId, inbox_item_id: e.inboxItemId, hint: pendingHint(e) } };
+    }
+    throw e;
+  }
+  return { vm, result: payloadOf(data) };
+}
+
+export const REHEARSAL_POLL_MS = 10000;
+export const REHEARSAL_TIMEOUT_MS = 50 * 60 * 1000;
+
+/** Poll proxmox_rehearsal_status until the rehearsal is done (awaiting_approval and running both keep waiting). Throws on timeout (the id stays valid for a later look). */
+export async function waitRehearsal(exec, rehearsalId, { intervalMs = REHEARSAL_POLL_MS, timeoutMs = REHEARSAL_TIMEOUT_MS, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), onTick } = {}) {
+  if (!/^RH_[0-9A-F]{16}$/.test(String(rehearsalId || ''))) throw new Error('the server did not return a rehearsal id');
+  const t0 = Date.now();
+  for (;;) {
+    const rec = payloadOf(await exec('proxmox_rehearsal_status', { rehearsal_id: rehearsalId }));
+    const r = rec?.rehearsal || rec;
+    if (r && r.state === 'done') return r;
+    if (Date.now() - t0 > timeoutMs) throw new Error(`rehearsal ${rehearsalId} is still running after ${Math.round(timeoutMs / 60000)} minutes; check later with the proxmox_rehearsal_status tool`);
+    if (onTick) onTick(r);
+    await sleep(intervalMs);
+  }
+}
+
+/** Human REST surface for the pool. */
+export function makePoolRest({ client }) {
+  const call = (name, params, body, timeout) => {
+    const ep = resolveEndpoint(name, params);
+    const m = ep.method.toLowerCase();
+    const t = timeout ? { timeout } : {};
+    return m === 'get' ? client.get(ep.path, { service: ep.service, ...t }) : client[m](ep.path, { service: ep.service, body: body || {}, ...t });
+  };
+  return {
+    status: () => call('v1.proxmox.pool'),
+    configure: (body) => call('v1.proxmox.pool.config.put', {}, body),
+    // A warm lease probes ssh, installs the key and refreshes the IP; a slow auth service stretches that past 30s.
+    lease: (body) => call('v1.proxmox.pool.lease', {}, body, 180000),
+    release: (vmid) => call('v1.proxmox.pool.release', { vmid }),
+  };
+}
+
+export async function poolStatus(rest) {
+  return rest.status();
+}
+
+export function defaultLessee(env = process.env) {
+  return env.QUOX_SESSION || os.hostname();
+}
+
+/** --pubkey-file, else ~/.ssh/id_ed25519.pub when present, else a clear error. Reads the PUBLIC key only. */
+export function readPubkey(file, { home = os.homedir() } = {}) {
+  const f = file || path.join(home, '.ssh', 'id_ed25519.pub');
+  if (!file && !fs.existsSync(f)) throw new Error('no ssh public key: pass --pubkey-file <path> (default ~/.ssh/id_ed25519.pub was not found)');
+  let txt;
+  try { txt = fs.readFileSync(f, 'utf8').trim(); } catch (e) { throw new Error(`cannot read public key ${f}: ${e.message}`); }
+  if (!/^(ssh-|ecdsa-|sk-)/.test(txt)) throw new Error(`${f} does not look like an SSH public key (refusing to send it)`);
+  return txt;
+}
+
+export async function poolLease(rest, { lessee, pubkey, cores, memoryGb, diskGb, ttlH, purpose, avx, node } = {}) {
+  const input = { lessee: lessee || defaultLessee(), ssh_pubkey: pubkey };
+  if (cores != null) input.cores = Number(cores);
+  if (memoryGb != null) input.memory_gb = Number(memoryGb);
+  if (diskGb != null) input.disk_gb = Number(diskGb);
+  if (ttlH != null) input.ttl_h = Number(ttlH);
+  if (purpose) input.purpose = purpose;
+  if (avx) input.require_avx2 = true;   // set when only some nodes have AVX2; the server errors if no lane can take it
+  if (node) input.node = node;
+  return rest.lease(input);   // 201 {lease} when a warm VM fits, 202 {vmid,state:'building'} when built to order
+}
+
+/** Host key lines for a returned lease: the fingerprint to compare, and a ready known_hosts line. Never invents a key. */
+export function poolHostKeyLines(p) {
+  const l = p && p.lease;
+  if (!l || typeof l !== 'object') return [];
+  if (l.host_key_line && l.host_key_fingerprint) {
+    return [`Host key ${l.host_key_fingerprint}`, 'known_hosts line:', `${l.ip} ${l.host_key_line}`];
+  }
+  return [`host key not read: ${l.host_key_error || 'the server returned none'}`];
+}
+
+export async function poolDone(rest, vmid) {
+  if (!/^\d+$/.test(String(vmid ?? ''))) throw new Error('vmid must be a number');
+  return rest.release(Number(vmid));
+}
+
+export async function poolConfig(rest, input = {}) {
+  return rest.configure(input);
+}
+
+export async function nodePower(exec, action, node, { reason } = {}) {
+  if (!NODE_ACTIONS.includes(action)) throw new Error(`node action must be one of ${NODE_ACTIONS.join(', ')}`);
+  if (!node) throw new Error('a node name is required');
+  // The proxmox_node_power tool is not built yet. Fail loudly instead of calling a missing tool.
+  void exec; void reason;
+  throw new Error('node power (reboot, shutdown) is not built yet; there is no proxmox_node_power tool');
+}
+
+/** Plain-text lines for a VM list. */
+export function vmListLines(vms) {
+  if (!vms.length) return ['No VMs found.'];
+  return vms.map((v) => `${String(v.vmid).padEnd(6)} ${String(v.name).padEnd(28)} ${String(v.node || '?').padEnd(8)} ${String(v.type).padEnd(5)} ${v.status}`);
+}
+
+export function textOf(p) {
+  if (p === undefined || p === null) return 'done';
+  return typeof p === 'string' ? p : JSON.stringify(p, null, 2);
+}
+
+/**
+ * VM Doctor (DEVFLEET-DOCTOR): read-only diagnosis. The server resolves the name or vmid itself
+ * (proxmox_vm_doctor), so the target goes straight through. -> the report object.
+ */
+export async function vmDoctor(exec, target) {
+  const t = String(target ?? '').trim();
+  if (!t) throw new Error('a VM name or vmid is required');
+  const p = payloadOf(await exec('proxmox_vm_doctor', { target: t }));
+  if (!p || typeof p !== 'object' || !Array.isArray(p.findings)) throw new Error('proxmox_vm_doctor returned no report');
+  return p;
+}
+
+const SEV_LABEL = { critical: 'CRITICAL', warning: 'WARNING', info: 'INFO' };
+const showVal = (v) => (typeof v === 'number' ? String(Math.round(v * 1000) / 1000) : String(v));
+
+/** Human lines for a doctor report: verdict, each finding (cause / evidence / fix), then gaps. */
+export function doctorLines(report) {
+  const vm = report.vm || {};
+  const lines = [`VERDICT  ${String(report.verdict || 'unknown').toUpperCase()}  ${vm.name || vm.vmid} (vmid ${vm.vmid} on ${vm.node}, ${vm.status || 'unknown'})`];
+  if (!report.findings.length) lines.push('No problems found in what could be read.');
+  for (const f of report.findings) {
+    lines.push('', `${SEV_LABEL[f.severity] || String(f.severity).toUpperCase()}  ${f.title}: ${f.cause}`);
+    for (const e of f.evidence || []) {
+      lines.push(`  evidence: ${e.metric} = ${showVal(e.value)} (threshold ${showVal(e.threshold)}, ${e.window}, ${e.source})`);
+    }
+    lines.push(`  fix: ${f.fix && f.fix.text}`);
+    if (f.fix && f.fix.action) lines.push(`  gated action: ${f.fix.action.tool} ${JSON.stringify(f.fix.action.input)} (asks for approval; not run)`);
+  }
+  if (report.gaps && report.gaps.length) {
+    lines.push('', 'Could not check:');
+    for (const g of report.gaps) lines.push(`  ${g}`);
+  }
+  if (report.report_id) lines.push('', `report ${report.report_id}`);
+  return lines;
+}