quoxcli 0.0.0-stage → 0.2.0

package/lib/core/output.js

@@ -0,0 +1,239 @@
+/**
+ * Output formatter for QuoxCLI
+ *
+ * All commands pass results through this module.
+ * Supports: table, json, csv, quiet output modes.
+ */
+
+import chalk from 'chalk';
+import Table from 'cli-table3';
+
+/**
+ * Format and print tabular data
+ *
+ * @param {Object} result - { columns, headers, rows } or array of objects
+ * @param {Object} options - { format, title, emptyMessage }
+ */
+export function formatOutput(result, options = {}) {
+  const format = options.format || getOutputFormat();
+  const rows = result.rows || result;
+  const columns = result.columns || (rows.length > 0 ? Object.keys(rows[0]) : []);
+  const headers = result.headers || columns;
+
+  // options.raw: the untransformed API records behind the display rows.
+  // --json exists for scripting, and scripts want DATA keys (name, state,
+  // holder_session), not the humanised table cells (NAME, HOLDER, "2d") the
+  // display rows carry -- `quox --json slot list` emitting NAME/STATE bit a
+  // live harness on 2026-08-20. Table/csv/quiet still render the display
+  // rows; json prefers raw when the caller provides it.
+  if (!Array.isArray(rows) || rows.length === 0) {
+    if (format === 'json') {
+      console.log(JSON.stringify(Array.isArray(options.raw) ? options.raw : []));
+    } else if (format === 'csv') {
+      console.log(headers.join(','));
+    } else if (format !== 'quiet') {
+      console.log(chalk.dim(options.emptyMessage || 'No results.'));
+    }
+    return;
+  }
+
+  switch (format) {
+    case 'json':
+      console.log(JSON.stringify(Array.isArray(options.raw) ? options.raw : rows, null, 2));
+      break;
+    case 'csv':
+      formatCsv(rows, columns, headers);
+      break;
+    case 'quiet':
+      formatQuiet(rows, columns);
+      break;
+    default:
+      formatTable(rows, columns, headers, options);
+  }
+}
+
+/**
+ * Format and print a single object (detail view)
+ */
+export function formatDetail(obj, options = {}) {
+  const format = options.format || getOutputFormat();
+
+  if (format === 'json') {
+    console.log(JSON.stringify(obj, null, 2));
+    return;
+  }
+
+  if (format === 'quiet') {
+    console.log(obj.id || obj.name || '');
+    return;
+  }
+
+  // Key-value display
+  const fields = options.fields || Object.keys(obj);
+  const labels = options.labels || {};
+
+  if (options.title) {
+    console.log(chalk.bold(options.title));
+    console.log(chalk.dim('─'.repeat(Math.min(options.title.length + 10, 60))));
+  }
+
+  const maxLabel = Math.max(...fields.map(f => (labels[f] || f).length));
+
+  for (const field of fields) {
+    const label = (labels[field] || field).padEnd(maxLabel + 2);
+    const raw = obj[field];
+    if (raw !== null && typeof raw === 'object') {
+      console.log(`  ${chalk.dim(label)}${formatNestedValue(raw)}`);
+    } else {
+      const value = formatValue(raw);
+      console.log(`  ${chalk.dim(label)} ${value}`);
+    }
+  }
+}
+
+/**
+ * Recursively render a nested object/array value for formatDetail, instead
+ * of falling through to formatValue's String(value) -> "[object Object]".
+ * Kept local to formatDetail (not folded into formatValue) so formatTable /
+ * formatCsv output is unchanged.
+ */
+function formatNestedValue(value, indent = 4) {
+  if (value == null) return ` ${chalk.dim('-')}`;
+
+  if (Array.isArray(value)) {
+    if (value.length === 0) return ` ${chalk.dim('[]')}`;
+    const allPrimitive = value.every(v => v === null || typeof v !== 'object');
+    if (allPrimitive) return ` ${value.map(v => formatValue(v)).join(', ')}`;
+    return '\n' + value
+      .map(v => `${' '.repeat(indent)}- ${typeof v === 'object' && v !== null ? formatNestedValue(v, indent + 2).trimStart() : formatValue(v)}`)
+      .join('\n');
+  }
+
+  const keys = Object.keys(value);
+  if (keys.length === 0) return ` ${chalk.dim('{}')}`;
+  return '\n' + keys
+    .map(k => {
+      const v = value[k];
+      if (v !== null && typeof v === 'object') {
+        return `${' '.repeat(indent)}${chalk.dim(k + ':')}${formatNestedValue(v, indent + 2)}`;
+      }
+      return `${' '.repeat(indent)}${chalk.dim(k + ':')} ${formatValue(v)}`;
+    })
+    .join('\n');
+}
+
+/**
+ * Print a success message
+ */
+export function printSuccess(message) {
+  const format = getOutputFormat();
+  if (format === 'json') {
+    console.log(JSON.stringify({ success: true, message }));
+  } else if (format !== 'quiet') {
+    console.log(chalk.green(message));
+  }
+}
+
+/**
+ * Print a warning message
+ */
+export function printWarning(message) {
+  if (getOutputFormat() !== 'quiet') {
+    console.error(chalk.yellow(message));
+  }
+}
+
+/**
+ * Print info message (suppressed in quiet/json mode)
+ */
+export function printInfo(message) {
+  const format = getOutputFormat();
+  if (format !== 'quiet' && format !== 'json') {
+    console.log(chalk.dim(message));
+  }
+}
+
+// -- Internal helpers --
+
+function formatTable(rows, columns, headers, options) {
+  const table = new Table({
+    head: headers.map(h => chalk.bold(h)),
+    style: { head: [], border: [] },
+    chars: {
+      'top': '', 'top-mid': '', 'top-left': '', 'top-right': '',
+      'bottom': '', 'bottom-mid': '', 'bottom-left': '', 'bottom-right': '',
+      'left': '', 'left-mid': '', 'mid': '', 'mid-mid': '',
+      'right': '', 'right-mid': '', 'middle': '  ',
+    },
+  });
+
+  for (const row of rows) {
+    table.push(columns.map(col => formatValue(row[col])));
+  }
+
+  console.log(table.toString());
+
+  // Show count
+  if (rows.length > 10) {
+    console.log(chalk.dim(`\n${rows.length} items`));
+  }
+}
+
+function formatCsv(rows, columns, headers) {
+  console.log(headers.map(csvEscape).join(','));
+  for (const row of rows) {
+    console.log(columns.map(col => csvEscape(row[col])).join(','));
+  }
+}
+
+function formatQuiet(rows, columns) {
+  // Print first column (usually ID) of each row
+  const idCol = columns[0];
+  for (const row of rows) {
+    console.log(row[idCol] ?? '');
+  }
+}
+
+function csvEscape(value) {
+  const str = String(value ?? '');
+  if (str.includes(',') || str.includes('"') || str.includes('\n')) {
+    return `"${str.replace(/"/g, '""')}"`;
+  }
+  return str;
+}
+
+function formatValue(value) {
+  if (value == null) return chalk.dim('-');
+  if (typeof value === 'boolean') return value ? chalk.green('yes') : chalk.dim('no');
+
+  const str = String(value);
+
+  // Color status values
+  const lower = str.toLowerCase();
+  if (['active', 'healthy', 'operational', 'approved', 'online', 'success'].includes(lower)) {
+    return chalk.green(str);
+  }
+  if (['degraded', 'warning', 'pending', 'in_progress', 'draft', 'stale'].includes(lower)) {
+    return chalk.yellow(str);
+  }
+  if (['error', 'down', 'failed', 'rejected', 'retired', 'offline', 'suspended', 'dead'].includes(lower)) {
+    return chalk.red(str);
+  }
+
+  // Truncate long values in table mode
+  if (str.length > 60) return str.slice(0, 57) + '...';
+
+  return str;
+}
+
+export function getOutputFormat() {
+  if (process.argv.includes('--json')) return 'json';
+  if (process.argv.includes('-q') || process.argv.includes('--quiet')) return 'quiet';
+
+  const idx = process.argv.indexOf('-o');
+  if (idx !== -1 && process.argv[idx + 1]) return process.argv[idx + 1];
+  const idx2 = process.argv.indexOf('--output');
+  if (idx2 !== -1 && process.argv[idx2 + 1]) return process.argv[idx2 + 1];
+
+  return 'table';
+}

package/lib/core/prodEnv.js

@@ -0,0 +1,7 @@
+/**
+ * Imported FIRST by the shipped bins (bin/quox.js, bin/quoxon.js), before anything that loads React: ES modules
+ * evaluate in import order, and React picks its build from NODE_ENV when it is first loaded. The development
+ * build roughly doubles CPU per animation frame (measured: ~51% vs 12-30% at 12 fps, 100x40). An explicit
+ * NODE_ENV (a developer's, or a test runner's) is always kept.
+ */
+if (!process.env.NODE_ENV) process.env.NODE_ENV = 'production';

package/lib/core/quoxglyph.js

@@ -0,0 +1,158 @@
+/**
+ * @quox/glyph — the canonical JS implementation of the QuoxGlyph terminal
+ * output language (DEVSUITE-GLYPH). Spec: quox-skills
+ * quoxify/references/quoxglyph-spec.md. This package IS the spec's constants:
+ * ports must consume it (or test against it), never re-type the values.
+ *
+ * Grammar:  <icon> NAME │ <verb object> │ <result> · <duration> [status]
+ * Colour:   truecolor, degrades to plain when !isTTY or NO_COLOR.
+ *           Brand gradient #38bdf8 -> #a855f7; rainbow RESERVED for completed.
+ */
+
+export const GRAD = [[56, 189, 248], [168, 85, 247]];
+export const RAINBOW = [
+  [255, 59, 48], [255, 149, 0], [255, 204, 0], [52, 199, 89],
+  [0, 199, 190], [10, 132, 255], [94, 92, 230], [191, 90, 242]
+];
+export const STATUS = {
+  ok: { glyph: '✔', rgb: [48, 209, 88] },
+  fail: { glyph: '✖', rgb: [255, 69, 58] },
+  busy: { glyph: '◐', rgb: [56, 189, 248] },
+  warn: { glyph: '⚠', rgb: [255, 214, 10] },
+  block: { glyph: '⛔', rgb: null }
+};
+export const ICONS = {
+  repobrain: '🧠 REPOBRAIN', clarify: '🔍 CLARIFY', qlarity: '🔍 QLARITY',
+  quoxplan: '🧭 QUOXPLAN', doneengine: '🏁 DONEENGINE', quoxbuild: '🔨 QUOXBUILD',
+  quoxsignal: '📡 QUOXSIGNAL', bastion: '🛰️ BASTION', precompact: '🧿 PRECOMPACT',
+  brain2: '🌌 QORTEX',
+  watchtower: '📨 WATCHTOWER', metron: '⏳ METRON',
+  quoxseo: '📈 QUOXSEO', reach: '💥 REACH', vulcan: '🌋 VULCAN',
+  quoxvoice: '📞 QUOXVOICE', quoxsecurity: '🛡️ QUOXSECURITY', quoxpert: '🎓 QUOXPERT',
+  quoxslots: '📍 QUOXSLOTS',
+  quox: 'Ⓠ QUOX'
+};
+export const BUDGETS = { VERB_MAX: 48, RESULT_MAX: 40, LINE_MAX: 120, TREE_MAX: 6, TABLE_MAX: 6 };
+export const PUA_Q = ''; // real horned Q, served by QuoxSymbols font
+
+const R = '\x1b[0m', DIM = '\x1b[2m', BOLD = '\x1b[1m';
+const fg = ([r, g, b]) => `\x1b[38;2;${r};${g};${b}m`;
+
+let forced = null;
+/** Force colour on/off (null = auto: isTTY && !NO_COLOR). */
+export function setColor(v) { forced = v; }
+function on() {
+  if (forced !== null) return forced;
+  const env = process.env.QUOX_COLOR;
+  if (env === '0') return false;
+  if (env === '1' || env === '2') return true;
+  return Boolean(process.stdout && process.stdout.isTTY) && !process.env.NO_COLOR;
+}
+
+function iconFor(surface) {
+  let name = ICONS[surface] || `Ⓠ ${String(surface).toUpperCase()}`;
+  if (process.env.QUOX_BRAND_FONT === '1') name = name.replace('Ⓠ', PUA_Q);
+  return name;
+}
+
+/** "<icon> NAME" with NAME painted in the brand gradient, bold, so a Quox
+ *  line stands out in tool output (owner 2026-10-05). Plain when colour is off. */
+export function brandName(label, col = on()) {
+  if (!col) return label;
+  const i = label.indexOf(' ');
+  const icon = i > 0 ? label.slice(0, i) : '';
+  const chars = [...(i > 0 ? label.slice(i + 1) : label)];
+  const last = Math.max(chars.length - 1, 1);
+  const painted = chars.map((c, k) => fg(GRAD[0].map((v, j) => Math.round(v + (GRAD[1][j] - v) * k / last))) + c).join('');
+  return `${icon ? icon + ' ' : ''}${BOLD}${painted}${R}`;
+}
+
+const trunc = (s, max) => ([...s].length > max ? [...s].slice(0, max - 1).join('') + '…' : s);
+
+/** The grammar event line. opts: {result, ms, status} */
+export function line(surface, verb, opts = {}) {
+  const col = on();
+  const name = brandName(iconFor(surface), col);
+  const sep = col ? `${DIM}│${R}` : '│';
+  let tail = opts.result ? trunc(opts.result, BUDGETS.RESULT_MAX) : '';
+  if (opts.ms !== undefined) {
+    const d = col ? `${DIM}${opts.ms}ms${R}` : `${opts.ms}ms`;
+    tail = tail ? `${tail} ${col ? DIM + '·' + R : '·'} ${d}` : d;
+  }
+  const s = opts.status && STATUS[opts.status];
+  if (s) tail += ' ' + (col && s.rgb ? `${fg(s.rgb)}${s.glyph}${R}` : s.glyph);
+  const v = trunc(verb, BUDGETS.VERB_MAX);
+  return tail ? `${name} ${sep} ${v} ${sep} ${tail}` : `${name} ${sep} ${v}`;
+}
+
+/** Gradient progress meter: ▰▰▰▱ done/total (or pct when total omitted). */
+export function meter(done, total, width = 8) {
+  const col = on();
+  const pct = total === undefined || total === null;
+  const ratio = pct ? Math.min(100, Math.max(0, done)) / 100 : (total > 0 ? done / total : 0);
+  const filled = Math.round(ratio * width);
+  const last = Math.max(1, width - 1);
+  let bar = '';
+  for (let i = 0; i < filled; i++) {
+    if (col) {
+      const t = i / last;
+      bar += fg(GRAD[0].map((v, k) => Math.round(v + (GRAD[1][k] - v) * t)));
+    }
+    bar += '▰';
+  }
+  if (col && filled) bar += R;
+  bar += (col ? DIM : '') + '▱'.repeat(Math.max(0, width - filled)) + (col ? R : '');
+  return pct ? `${bar} ${done}%` : `${bar} ${done}/${total}`;
+}
+
+/** Rainbow text. RESERVED for the `completed` lifecycle event. */
+export function celebrate(text) {
+  if (!on()) return text;
+  const chars = [...text];
+  const last = Math.max(1, chars.length - 1);
+  return chars.map((ch, i) => {
+    const t = (i / last) * (RAINBOW.length - 1);
+    const seg = Math.min(RAINBOW.length - 2, Math.floor(t));
+    const local = t - seg;
+    return fg(RAINBOW[seg].map((v, k) => Math.round(v + (RAINBOW[seg + 1][k] - v) * local))) + ch;
+  }).join('') + R;
+}
+
+/** WARD receipt footer. */
+export function receipt(hash, ts) {
+  const col = on();
+  const chain = col ? `${fg([168, 85, 247])}⛓${R}` : '⛓';
+  const label = col ? `${DIM}ward:${R}` : 'ward:';
+  const t = ts ? (col ? ` ${DIM}· witnessed ${ts}${R}` : ` · witnessed ${ts}`) : '';
+  return `${chain} ${label}${String(hash).slice(0, 12)}${t}`;
+}
+
+/**
+ * Lifecycle events (spec section 4b): the contract every product emits.
+ * Each returns a rendered line; the caller prints it.
+ */
+export const events = {
+  created: (surface, thing, id) => line(surface, `${thing} created`, { result: id, status: 'ok' }),
+  updated: (surface, thing, id, delta) =>
+    line(surface, `${thing} updated`, { result: delta ? `${id} ${delta}` : id, status: 'ok' }),
+  progressed: (surface, step, id, done, total) =>
+    line(surface, step, { result: `${id} ${meter(done, total)}` }),
+  completed: (surface, thing, text) => line(surface, thing, { result: celebrate(text) }),
+  assigned: (surface, thing, holder) => line(surface, `${thing} assigned`, { result: holder, status: 'busy' }),
+  released: (surface, thing, id) => line(surface, `${thing} released`, { result: id, status: 'ok' }),
+  failed: (surface, thing, why) => line(surface, `${thing} failed`, { result: why, status: 'fail' }),
+  warned: (surface, thing, risk) => line(surface, thing, { result: risk, status: 'warn' })
+};
+
+// ---- quoxcli integration (not part of the @quox/glyph copy above) ----
+// VENDORED from quox-plugin-sdk packages/quox-glyph/index.js until the
+// owner-gated npm publish lands; the lockstep test in quoxglyph.test.js
+// fails if this copy drifts from the package.
+import { getOutputFormat } from './output.js';
+
+/** Print a rendered glyph line, respecting --output json/quiet. */
+export function printEvent(rendered) {
+  const format = getOutputFormat();
+  if (format === 'json' || format === 'quiet') return;
+  console.log(`  ${rendered}`);
+}

package/lib/core/residentAlarm.js

@@ -0,0 +1,282 @@
+/**
+ * Resident alarm — QUOXPERTICUS-REVISIT P5 "warden watchdog + loud alarm".
+ *
+ * While the warden pumps (residentPump.js) instead of answering, it also
+ * watches the resident it wards: is the tmux pane still there, has a
+ * permission dialog been stuck too long to ever clear itself, has the
+ * provider started refusing turns. Three independent conditions, each with
+ * its own escalating alert schedule (10m, 30m, then hourly) so a wedged
+ * resident is loud rather than silently absent, and each condition clears
+ * itself the moment its detector stops firing (no human-ack mechanism yet:
+ * clearing = the underlying thing is gone).
+ *
+ * Every I/O dependency (tmux session list, pane read, release/redeploy,
+ * the alert transport, the turn-receipt store, the clock) is injected, same
+ * contract as supervisorEngine.js and residentPump.js, so this runs under
+ * vitest with no real tmux host and no real Telegram bridge.
+ */
+
+import { ERROR_NOTICE_WINDOW_MS } from './supervisorEngine.js';
+
+// Gaps BETWEEN successive alerts for the SAME still-active condition:
+// immediate on first detection (see shouldSendAlarm), then +10m, then +30m,
+// then hourly forever until the condition clears.
+export const ALARM_SCHEDULE_MS = [10 * 60 * 1000, 30 * 60 * 1000, ERROR_NOTICE_WINDOW_MS];
+
+// A stuck permission dialog only becomes an alarm condition once it has sat
+// unresolved this long. Below this age it is exactly what residentPump.js
+// already logs: held input, not yet an incident.
+export const STUCK_DIALOG_ALARM_THRESHOLD_MS = 10 * 60 * 1000;
+
+// Pane-text scan patterns for a provider/credits failure. Deliberately
+// simple substring/regex matches (this is pane TEXT, not a structured
+// provider error object the way detectTurnError in supervisorEngine.js
+// parses a headless turn's JSON output) — same spirit, different signal.
+export const PROVIDER_ISSUE_PATTERNS = [
+  { pattern: 'out of usage credits', regex: /out of usage credits/i },
+  { pattern: 'usage limit', regex: /usage limit/i },
+  { pattern: 'provider error', regex: /provider error/i },
+];
+
+export function scanPaneForProviderIssue(paneText) {
+  const text = String(paneText || '');
+  for (const { pattern, regex } of PROVIDER_ISSUE_PATTERNS) {
+    if (regex.test(text)) return { matched: true, pattern };
+  }
+  return { matched: false, pattern: null };
+}
+
+export function createInitialAlarmCondition() {
+  return { active: false, first_detected_at: null, last_alerted_at: null, alert_count: 0 };
+}
+
+export function createInitialAlarmState() {
+  return {
+    pane_dead_attempted: false,
+    pane_dead_redeploy_failed: false,
+    conditions: {
+      pane_dead: createInitialAlarmCondition(),
+      stuck_dialog: createInitialAlarmCondition(),
+      provider_error: createInitialAlarmCondition(),
+    },
+  };
+}
+
+/**
+ * Advance one condition's state from a single boolean detection this pass.
+ * A detection while already active is a no-op (first_detected_at sticks to
+ * the original onset). No detection while active is a full reset: clearing
+ * a condition means the next detection is treated as a fresh onset, with
+ * its own fresh alert schedule.
+ */
+export function updateAlarmCondition(conditionState, detected, now) {
+  const current = conditionState || createInitialAlarmCondition();
+  if (detected) {
+    if (current.active) return current;
+    return { ...current, active: true, first_detected_at: now };
+  }
+  if (current.active) return createInitialAlarmCondition();
+  return current;
+}
+
+/**
+ * Whether condition `conditionState` should alert right now. The first
+ * alert for a freshly-active condition fires immediately (no delay: a dead
+ * pane or a provider outage is news the moment it is confirmed). Every
+ * alert after that waits at least the schedule's gap for however many
+ * alerts have already fired, capped at the schedule's last (hourly) entry.
+ */
+export function shouldSendAlarm(conditionState, now, schedule = ALARM_SCHEDULE_MS) {
+  if (!conditionState || !conditionState.active) return false;
+  if (conditionState.last_alerted_at == null) return true;
+  const idx = Math.min(Math.max((conditionState.alert_count || 0) - 1, 0), schedule.length - 1);
+  const gap = schedule[idx];
+  return (now - conditionState.last_alerted_at) >= gap;
+}
+
+export function recordAlarmSent(conditionState, now) {
+  return { ...conditionState, last_alerted_at: now, alert_count: (conditionState.alert_count || 0) + 1 };
+}
+
+/**
+ * Send one alarm through both transports in order, per spec: tg-send.sh
+ * first (the owner's phone), `quox slot say` second as the fallback when
+ * tg-send.sh is unavailable or fails — never silent, and the absence of the
+ * script is itself treated as "alarm-transport-unavailable", not a reason
+ * to skip the slot notice.
+ */
+export async function sendAlarm({ tgSend, postSlotNotice, text, sessionName = 'WARDEN', log = () => {} }) {
+  let tgSent = false;
+  if (tgSend) {
+    try {
+      await tgSend(sessionName, text);
+      tgSent = true;
+    } catch (err) {
+      log('warn', `alarm: tg-send.sh failed, falling back to slot say: ${err.message}`);
+    }
+  } else {
+    log('warn', 'alarm: alarm-transport-unavailable (tg-send.sh not found), falling back to slot say');
+  }
+  if (!tgSent) {
+    try {
+      await postSlotNotice(text);
+    } catch (err) {
+      log('error', `alarm: slot say fallback also failed: ${err.message}`);
+    }
+  }
+  return { tg_sent: tgSent };
+}
+
+/**
+ * Run one warden watchdog pass.
+ *
+ * Injected dependencies:
+ *   listSessions()        -> array of the host's tmux sessions ({name, ...})
+ *   readPane()             -> current pane text (only called while the pane
+ *                             is confirmed alive)
+ *   releaseSlot()           -> release the resident's slot (best-effort)
+ *   redeploy()               -> run the redeploy path (reuses `quox dev
+ *                             resident deploy`; throws on failure)
+ *   claimFallback()          -> attempt to claim the slot as this warden's
+ *                             own fallback voice (only called when redeploy
+ *                             fails); returns {claimed: bool}
+ *   postSlotNotice(text)     -> slot `say`
+ *   recordTurn(fields)       -> turn receipt (outcome/error_note only;
+ *                             NEVER a new outcome value — see
+ *                             devSupervisorTurnsStore.js OUTCOMES)
+ *   tgSend(session, text)    -> shells out to tg-send.sh; absent/failing is
+ *                             handled by sendAlarm above, never thrown here
+ *   stuckDialogSinceMs        -> residentPump.js's state.stuck_dialog_since
+ *                             for this slot (single source of truth for
+ *                             dialog detection; this module only ages it)
+ */
+export async function runWardenPass({
+  hostId,
+  slot,
+  sessionName,
+  listSessions,
+  readPane,
+  releaseSlot,
+  redeploy,
+  claimFallback,
+  postSlotNotice,
+  recordTurn,
+  tgSend,
+  stuckDialogSinceMs = null,
+  state,
+  log = () => {},
+  now = () => Date.now(),
+  schedule = ALARM_SCHEDULE_MS,
+  stuckDialogThresholdMs = STUCK_DIALOG_ALARM_THRESHOLD_MS,
+}) {
+  const base = state || createInitialAlarmState();
+  const nextState = {
+    pane_dead_attempted: base.pane_dead_attempted ?? false,
+    pane_dead_redeploy_failed: base.pane_dead_redeploy_failed ?? false,
+    conditions: {
+      pane_dead: base.conditions?.pane_dead || createInitialAlarmCondition(),
+      stuck_dialog: base.conditions?.stuck_dialog || createInitialAlarmCondition(),
+      provider_error: base.conditions?.provider_error || createInitialAlarmCondition(),
+    },
+  };
+
+  const nowMs = now();
+  const report = { pane_alive: null, redeployed: false, redeploy_error: null, fallback_claimed: false, alerts_sent: [] };
+
+  const sessions = await listSessions();
+  const paneAlive = !!(sessions || []).find((s) => s.name === sessionName);
+  report.pane_alive = paneAlive;
+
+  let paneText = null;
+
+  if (!paneAlive) {
+    if (!nextState.pane_dead_attempted) {
+      nextState.pane_dead_attempted = true;
+      log('warn', `warden: resident session ${sessionName} on ${hostId} is not present (pane dead); releasing the slot and redeploying.`);
+      try {
+        await releaseSlot();
+      } catch (err) {
+        log('warn', `warden: releasing ${slot} failed (continuing): ${err.message}`);
+      }
+      try {
+        await redeploy();
+        report.redeployed = true;
+        nextState.pane_dead_redeploy_failed = false;
+        nextState.conditions.pane_dead = createInitialAlarmCondition();
+        try {
+          await postSlotNotice(`Resident on ${hostId} lost its pane; redeployed automatically.`);
+        } catch (err) {
+          log('warn', `warden: redeploy notice failed to post: ${err.message}`);
+        }
+        try {
+          await recordTurn({ outcome: 'error', error_note: 'pane_dead_auto_redeployed' });
+        } catch (err) {
+          log('warn', `warden: redeploy receipt failed to post: ${err.message}`);
+        }
+      } catch (err) {
+        report.redeploy_error = err.message;
+        nextState.pane_dead_redeploy_failed = true;
+        log('error', `warden: redeploy failed for ${hostId}: ${err.message}`);
+        try {
+          await postSlotNotice(`Resident on ${hostId} lost its pane and automatic redeploy FAILED (${err.message}). A human should check this host.`);
+        } catch (err2) {
+          log('warn', `warden: failure notice failed to post: ${err2.message}`);
+        }
+        try {
+          const fb = await claimFallback();
+          report.fallback_claimed = !!(fb && fb.claimed);
+        } catch (err2) {
+          log('warn', `warden: fallback claim attempt failed: ${err2.message}`);
+        }
+      }
+    }
+    if (nextState.pane_dead_redeploy_failed) {
+      nextState.conditions.pane_dead = updateAlarmCondition(nextState.conditions.pane_dead, true, nowMs);
+    }
+  } else {
+    if (nextState.pane_dead_attempted || nextState.conditions.pane_dead.active) {
+      log('info', `warden: resident session ${sessionName} on ${hostId} is present again; pane-dead condition cleared.`);
+    }
+    nextState.pane_dead_attempted = false;
+    nextState.pane_dead_redeploy_failed = false;
+    nextState.conditions.pane_dead = updateAlarmCondition(nextState.conditions.pane_dead, false, nowMs);
+
+    try {
+      paneText = await readPane();
+    } catch (err) {
+      log('warn', `warden: pane read failed on ${hostId} (skipping provider-error scan this pass): ${err.message}`);
+    }
+  }
+
+  // Stuck dialog: this module never detects the dialog itself, it only ages
+  // what residentPump.js already found (single source of truth).
+  const dialogStuck = stuckDialogSinceMs != null && (nowMs - stuckDialogSinceMs) >= stuckDialogThresholdMs;
+  nextState.conditions.stuck_dialog = updateAlarmCondition(nextState.conditions.stuck_dialog, dialogStuck, nowMs);
+
+  if (paneText != null) {
+    const scan = scanPaneForProviderIssue(paneText);
+    nextState.conditions.provider_error = updateAlarmCondition(nextState.conditions.provider_error, scan.matched, nowMs);
+  }
+
+  const conditionAlerts = [
+    ['pane_dead', `Resident on ${hostId}: pane is dead and automatic redeploy failed. A human should check this host.`],
+    ['stuck_dialog', `Resident on ${hostId}: a permission dialog has been stuck for over ${Math.round(stuckDialogThresholdMs / 60000)} minutes and will never resolve itself; a human must approve or cancel it.`],
+    ['provider_error', `Resident on ${hostId}: a provider/credits error was detected in its pane. A human should check its account/billing status.`],
+  ];
+
+  for (const [key, message] of conditionAlerts) {
+    const condition = nextState.conditions[key];
+    if (shouldSendAlarm(condition, nowMs, schedule)) {
+      const sendResult = await sendAlarm({ tgSend, postSlotNotice, text: message, sessionName: `WARDEN-${hostId}`, log });
+      nextState.conditions[key] = recordAlarmSent(condition, nowMs);
+      try {
+        await recordTurn({ outcome: 'error', error_note: `alarm_${key}` });
+      } catch (err) {
+        log('warn', `warden: alarm receipt failed for ${key}: ${err.message}`);
+      }
+      report.alerts_sent.push({ condition: key, tg_sent: sendResult.tg_sent });
+    }
+  }
+
+  return { state: nextState, ...report };
+}