quoxcli 0.2.0 → 0.4.0

package/lib/core/slotKeeper.js

@@ -13,9 +13,10 @@
  * environmental (clock, sleep, probe, signals, fs dir) is injected.
  */
 
+import { decideWake, wakeText, draftLines, promptBoxState, isWakeLine, wakeQueued, WAKE_SETTLE_MS } from './slotWake.js';
 import {
   openSync, closeSync, writeSync, readFileSync, unlinkSync, appendFileSync,
-  statSync, writeFileSync, mkdirSync,
+  statSync, writeFileSync, mkdirSync, chmodSync,
 } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
@@ -32,6 +33,8 @@ export const BACKOFF_CAP_MS = 5 * 60 * 1000;
 // long outage beats letting the hold lapse (the collector revives a stale
 // slot for its own holder on the next successful heartbeat).
 export const MAX_FAILS = 24;
+// #893: consecutive re-leases allowed without a good heartbeat in between.
+export const MAX_REACQUIRES = 3;
 export const MAX_AUTH_FAILS = 3;
 export const LOG_MAX_BYTES = 256 * 1024;
 // QUOX-CLAUDE-3: the control queue is polled far more often than the 5-min
@@ -43,6 +46,18 @@ export const CONTROL_POLL_MS = 20 * 1000;
 export const CONTROL_BACKOFF_CAP_TICKS = 15;
 export const BUSY_WINDOW_MS = 60 * 1000;
 export const NO_TMUX_RESULT = 'session not under tmux; start it with quox claude';
+// FORCE-WAKE: only a wake the server accepted from a human (an org admin via the CLI, or an allowlisted
+// Discord user) carries this provenance; anything else keeps the old refusal at a draft.
+const HUMAN_VIA = new Set(['cli', 'discord']);
+export const FORCE_STEP_MS = 400; // between a key and the capture that checks it landed
+export const FORCE_SUBMIT_WAIT_STEPS = 15; // ~6s for the wake line to leave the box before the draft goes back
+// WAKE-REAL (owner 2026-10-17 "wake just pipes text to the prompt but doesnt wake anyone"): Claude Code drops an
+// Enter that reaches it in the same read as the typed line (a loaded session reads both bursts as one paste), so
+// the line sits in the box unsent. Proven live: QUOXON's 00:36:41 wake stayed unsent 3.5 min. The keeper lets
+// the line land before Enter, then re-presses Enter only while the box still holds exactly its own line.
+export const WAKE_LAND_STEPS = 10; // ~4s for the typed line to show in the box
+export const WAKE_ENTER_TRIES = 4; // Enters sent at most (each only while the box holds only the wake line)
+export const WAKE_ENTER_WAIT_STEPS = 6; // ~2.4s for the box to clear after each Enter
 
 export function keeperDir() {
   return join(homedir(), '.quox', 'keepers');
@@ -80,12 +95,22 @@ function defaultExecFile(file, args) {
 export async function runKeeper(opts) {
   const {
     name, session, claude, heartbeat, release, forget, probe,
+    // #893: optional. Re-lease after the hold LAPSED (expired, not taken over).
+    // Must never take over; a refusal (409) means someone else holds it.
+    reacquire = null,
     sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
     rand = Math.random,
     dir = keeperDir(),
     // Remote control (all optional; absent pollControl = heartbeat-only keeper).
     pollControl, ackControl, tmuxPane = null,
     execFile = defaultExecFile,
+    // POKE-WAKE: the gap between the two pane samples a wake compares.
+    settle = (ms) => new Promise((r) => setTimeout(r, ms)),
+    // KEEPER-REEXEC: the installed build (null = unknown), how to start a successor on the new
+    // build, and how to stop a keeper on an older one. All optional; absent = old behaviour.
+    buildId = () => null,
+    reexec = null,
+    kill = (pid, sig) => process.kill(pid, sig),
     now = () => Date.now(),
     installSignals = (cleanup) => {
       const h = () => { cleanup(); process.exit(0); };
@@ -96,6 +121,8 @@ export async function runKeeper(opts) {
 
   mkdirSync(dir, { recursive: true });
   const lockPath = join(dir, `${name}.pid`);
+  const buildPath = join(dir, `${name}.build`);
+  const startBuild = buildId();
   const logPath = join(dir, `${name}.log`);
   const log = (msg) => {
     try {
@@ -119,8 +146,21 @@ export async function runKeeper(opts) {
       let other = NaN;
       try { other = parseInt(readFileSync(lockPath, 'utf-8'), 10); } catch { /* raced away */ }
       if (Number.isFinite(other) && other !== process.pid && probe.alive(other)) {
-        log(`another keeper (pid ${other}) already running; exiting`);
-        return { code: 0, reason: 'already-running' };
+        // KEEPER-REEXEC: a keeper on an older (or unrecorded) build is replaced, so checkout always
+        // leaves the slot kept by the installed code. SIGTERM drops only its lock: the hold is kept.
+        const otherBuild = (() => { try { return readFileSync(buildPath, 'utf-8').trim() || null; } catch { return null; } })();
+        if (startBuild && otherBuild !== startBuild && attempt === 0) {
+          log(`replacing keeper pid ${other} (build ${otherBuild || 'unrecorded'}) with build ${startBuild}`);
+          try { kill(other, 'SIGTERM'); } catch { /* already gone */ }
+          for (let w = 0; w < 20 && probe.alive(other); w += 1) await settle(250);
+          if (probe.alive(other)) {
+            log(`keeper pid ${other} did not exit; leaving it`);
+            return { code: 0, reason: 'already-running' };
+          }
+        } else {
+          log(`another keeper (pid ${other}) already running; exiting`);
+          return { code: 0, reason: 'already-running' };
+        }
       }
       try { unlinkSync(lockPath); } catch { /* raced away */ }
     }
@@ -136,15 +176,37 @@ export async function runKeeper(opts) {
     } catch { /* already gone */ }
   };
   installSignals(cleanup);
+  if (startBuild) { try { writeFileSync(buildPath, startBuild); } catch { /* informational */ } }
+  // KEEPER-REEXEC: checked on every control poll. Lock is removed BEFORE the successor starts so it
+  // can take it; the hold is never released (the successor heartbeats the same slot).
+  let reexecFailedFor = null;
+  const staleBuild = () => {
+    if (!startBuild || typeof reexec !== 'function') return false;
+    const nowBuild = buildId();
+    if (!nowBuild || nowBuild === startBuild) return false;
+    if (reexecFailedFor === nowBuild) return false;
+    log(`installed build ${startBuild} -> ${nowBuild}: re-exec`);
+    cleanup();
+    try { reexec(); } catch (e) {
+      // No successor: take the lock back and keep heartbeating on the old code rather than drop the hold.
+      reexecFailedFor = nowBuild;
+      try { writeFileSync(lockPath, String(process.pid)); } catch { /* best effort */ }
+      log(`re-exec failed (${e.message}); staying on build ${startBuild}`);
+      return false;
+    }
+    return true;
+  };
 
   try {
     log(`keeper started session=${session} claude=${claude?.pid}:${claude?.starttime}`);
     let fails = 0;
+    let reacquires = 0;
     let delay = KEEP_INTERVAL_MS * (1 + rand() * 0.2);
 
     // Control queue state: ids already executed (never re-run if an ack failed,
     // only re-acked), and distinct failure accounting with tick-skip backoff.
     const handled = new Map();
+    const received = new Set();
     const startedAt = now();
     let lastHeartbeatAt = null;
     // Busy/idle: only a hash of the pane is kept (pane text can hold secrets
@@ -175,8 +237,12 @@ export async function runKeeper(opts) {
         for (const row of rows) {
           let outcome = handled.get(row.id);
           if (!outcome) {
+            if (!received.has(row.id)) { received.add(row.id); log(`control ${row.command} ${row.id} received from ${row.requested_via || '?'}`); }
             outcome = await runControlCommand(row);
+            // POKE-WAKE: a wake on a busy pane stays pending server-side and is retried next tick.
+            if (outcome === null) continue;
             handled.set(row.id, outcome);
+            received.delete(row.id);
             log(`control ${row.command} ${row.id} from ${row.requested_via || '?'}: ${outcome.status} (${outcome.result})`);
           }
           await ackControl(row.id, outcome.status, outcome.result);
@@ -225,8 +291,169 @@ export async function runKeeper(opts) {
       parts.push(`keeper up ${fmtDur((now() - startedAt) / 1000)}`);
       return parts.join(', ').slice(0, 500);
     };
+    // POKE-WAKE: wake an idle session so it reads its slot page now. Types ONE fixed line (wakeText),
+    // literally (-l, no key-name parsing), only when the pane is still and the prompt box empty.
+    const wakeSeen = new Map();
+    const waitLogged = new Map();
+    let lastWokeAt = null;
+    const capture = async () => {
+      try {
+        // -e: escape-aware, so the faint empty-box placeholder is not mistaken for a draft (FORCE-WAKE).
+        const out = await execFile('tmux', ['capture-pane', '-p', '-e', '-t', tmuxPane]);
+        return typeof out === 'string' ? out : String(out?.stdout ?? '');
+      } catch { return null; }
+    };
+    const runWake = async (row) => {
+      if (!tmuxPane) return { status: 'failed', result: NO_TMUX_RESULT };
+      // The 10m budget runs from the REQUEST (server created_at), not from this keeper's first sight of
+      // it: a re-exec'd keeper continues the same budget, and an old request is not mistaken for a new one.
+      if (!wakeSeen.has(row.id)) {
+        const created = Date.parse(row.created_at || '');
+        wakeSeen.set(row.id, Number.isFinite(created) && created <= now() ? created : now());
+      }
+      const before = await capture();
+      await settle(WAKE_SETTLE_MS);
+      const after = await capture();
+      const force = HUMAN_VIA.has(row.requested_via);
+      const d = decideWake({ slot: name, before, after, firstSeenAt: wakeSeen.get(row.id), nowMs: now(), lastWokeAt, force });
+      if (d.action === 'wait') {
+        if (waitLogged.get(row.id) !== d.reason) { waitLogged.set(row.id, d.reason); log(`wake ${row.id} waiting: ${d.reason} (retrying each poll for up to 10m)`); }
+        return null;
+      }
+      wakeSeen.delete(row.id);
+      waitLogged.delete(row.id);
+      if (d.action === 'force') return forceWake(row, after);
+      if (d.action !== 'type' && d.action !== 'submit') return { status: d.action === 'done' ? 'done' : 'failed', result: d.result };
+      try {
+        if (d.action === 'submit') log(`wake ${row.id}: an earlier wake line is still unsent in the box; submitting it`);
+        const r = await submitWakeLine(row.id, { typed: d.action === 'submit' });
+        if (!r.ok) return { status: 'failed', result: `not woken: ${r.why}; the page shows at its next prompt` };
+        lastWokeAt = now();
+        return { status: 'done', result: wokeResult(r) };
+      } catch (err) {
+        return { status: 'failed', result: `tmux send-keys failed: ${err.message}` };
+      }
+    };
+    // WAKE-REAL: the two outcomes a waker is told apart: a turn started, or Claude Code queued the line mid-turn.
+    const wokeResult = (r, extra = '') => (r.queued
+      ? `queued in ${tmuxPane}${extra}: the session is mid-turn, so Claude Code holds the wake line and sends it when the turn ends; it reads slot ${name} then`
+      : `woke ${tmuxPane}${extra}: the wake line was submitted and a turn started; it is reading slot ${name} now`);
+    // WAKE-REAL: type the fixed line (unless it is already in the box), let it land, Enter, and verify it left the
+    // box. Enter is re-pressed only while the box holds exactly this slot's wake line, so nothing else is ever sent.
+    // -> { ok: true, queued } | { ok: false, why }
+    const submitWakeLine = async (id, { typed = false, clearOnFail = true } = {}) => {
+      if (!typed) {
+        await keys('-l', wakeText(name));
+        for (let k = 0; k < WAKE_LAND_STEPS; k += 1) {
+          await settle(FORCE_STEP_MS);
+          const b = draftLines(await capture());
+          if (isWakeLine(b, name) || (Array.isArray(b) && b.length)) break;
+        }
+      }
+      for (let t = 0; t < WAKE_ENTER_TRIES; t += 1) {
+        const b = draftLines(await capture());
+        if (Array.isArray(b) && b.length && !isWakeLine(b, name)) {
+          log(`wake ${id}: the box holds something other than the wake line; no Enter sent`);
+          return { ok: false, why: 'the prompt box changed while waking (someone is typing), so nothing was sent' };
+        }
+        if (t > 0 && !(Array.isArray(b) && b.length)) return { ok: true, queued: wakeQueued(await capture()) };
+        await keys('Enter');
+        if (t > 0) log(`wake ${id}: Enter was not taken; pressed it again (${t + 1} of ${WAKE_ENTER_TRIES})`);
+        for (let k = 0; k < WAKE_ENTER_WAIT_STEPS; k += 1) {
+          const screen = await capture();
+          const after = draftLines(screen);
+          if (Array.isArray(after) && !after.length) { log(`wake ${id}: wake line submitted (${t + 1} Enter${t ? 's' : ''})`); return { ok: true, queued: wakeQueued(screen) }; }
+          if (!isWakeLine(after, name)) break;
+          await settle(FORCE_STEP_MS);
+        }
+      }
+      // Still ours in the box after every try: take it back out, so it never sits there as a fake draft (not on a
+      // force: C-u would overwrite the kill ring that holds the human's draft; the next wake submits it instead).
+      if (!clearOnFail) return { ok: false, why: `Claude Code did not take Enter (${WAKE_ENTER_TRIES} tries)` };
+      for (let k = 0; k < 12 && isWakeLine(draftLines(await capture()), name); k += 1) { await keys('C-u'); await settle(FORCE_STEP_MS); }
+      log(`wake ${id}: Claude Code did not take Enter after ${WAKE_ENTER_TRIES} tries; wake line cleared`);
+      return { ok: false, why: `Claude Code did not take Enter (${WAKE_ENTER_TRIES} tries), so the wake line was cleared from the box` };
+    };
+    // FORCE-WAKE (owner 2026-10-16: "wake needs to wake"): a human wake at a draft sets the draft aside and
+    // puts it back UNSENT. Proven live on Claude Code v2.1.288: C-u kills one visual line (consecutive kills
+    // accumulate in its kill ring), the ring survives a submit, and C-y yanks it back. Every step is checked
+    // by a capture; nothing of the user's is ever followed by Enter. The draft text never goes in the log;
+    // a private copy sits in <slot>.draft until it is verified back in the box.
+    const same = (a, b) => Array.isArray(a) && Array.isArray(b) && a.join('\n') === b.join('\n');
+    const tag = (lines) => `${lines.length} line(s), ${lines.join('\n').length} chars, sha ${createHash('sha256').update(lines.join('\n')).digest('hex').slice(0, 8)}`;
+    const keys = (...k) => execFile('tmux', ['send-keys', '-t', tmuxPane, ...k]);
+    const forceWake = async (row, screen) => {
+      const draft = draftLines(screen);
+      const draftPath = join(dir, `${name}.draft`);
+      const NOT = 'not woken: ';
+      try {
+        writeFileSync(draftPath, `${draft.join('\n')}\n`, { mode: 0o600 });
+        chmodSync(draftPath, 0o600);
+      } catch (e) {
+        log(`force ${row.id}: could not save a safety copy of the draft (${e.message}); refusing`);
+        return { status: 'failed', result: `${NOT}could not save a safety copy of the draft first, so it was left untouched; the page shows at its next prompt` };
+      }
+      log(`force ${row.id}: captured draft (${tag(draft)}); safety copy ${draftPath}`);
+      // A human may be typing: the box must still hold exactly what was captured.
+      if (!same(draftLines(await capture()), draft)) {
+        log(`force ${row.id}: draft changed before clearing; refusing`);
+        try { unlinkSync(draftPath); } catch { /* best effort */ }
+        return { status: 'failed', result: `${NOT}the draft changed while setting it aside (someone is typing); left untouched` };
+      }
+      try {
+        let box = draft;
+        for (let k = 0; k < draft.length + 3 && box && box.length; k += 1) {
+          await keys('C-u');
+          await settle(FORCE_STEP_MS);
+          box = draftLines(await capture());
+        }
+        if (!box || box.length) {
+          log(`force ${row.id}: box did not clear (${box ? 'text left' : 'no box'}); yanking the draft back, nothing sent`);
+          if (box && box.length) await keys('C-u'); // finish the kill run so the yank puts back the whole draft
+          await keys('C-y');
+          await settle(FORCE_STEP_MS);
+          const back = same(draftLines(await capture()), draft);
+          log(`force ${row.id}: draft ${back ? 'restored' : `NOT verified back; safety copy kept at ${draftPath}`}`);
+          if (back) { try { unlinkSync(draftPath); } catch { /* best effort */ } }
+          return { status: 'failed', result: `${NOT}could not clear the draft safely, so it was ${back ? 'put back as it was' : `left in place (a copy is saved at ${draftPath})`}; nothing was sent` };
+        }
+        log(`force ${row.id}: cleared the prompt box (${draft.length} C-u)`);
+        const sub = await submitWakeLine(row.id, { clearOnFail: false });
+        log(`force ${row.id}: typed wake line + Enter${sub.ok ? '' : ` (${sub.why})`}`);
+        let st = sub.ok ? 'empty' : null;
+        for (let k = 0; sub.ok && k < FORCE_SUBMIT_WAIT_STEPS && st !== 'empty'; k += 1) {
+          await settle(FORCE_STEP_MS);
+          st = promptBoxState(await capture());
+        }
+        if (st !== 'empty') {
+          log(`force ${row.id}: box not free after the wake line (${st}); draft NOT restored, safety copy kept at ${draftPath}`);
+          return { status: 'failed', result: `${NOT}the wake line did not leave the prompt box; your draft is saved at ${draftPath} on that host (in the box kill ring too: Ctrl+Y)` };
+        }
+        lastWokeAt = now();
+        await keys('C-y');
+        await settle(FORCE_STEP_MS);
+        let back = draftLines(await capture());
+        if (!same(back, draft) && Array.isArray(back) && !back.length && draft.length === 1) {
+          log(`force ${row.id}: yank did not restore; typing the single-line draft back literally (no Enter)`);
+          await keys('-l', draft[0]);
+          await settle(FORCE_STEP_MS);
+          back = draftLines(await capture());
+        }
+        if (!same(back, draft)) {
+          log(`force ${row.id}: woke, but the draft is NOT verified back; safety copy kept at ${draftPath}`);
+          return { status: 'done', result: `${wokeResult(sub)}; but its draft could not be verified back in the box, a copy is saved at ${draftPath} on that host` };
+        }
+        try { unlinkSync(draftPath); } catch { /* best effort */ }
+        log(`force ${row.id}: restored draft (verified, not sent)`);
+        return { status: 'done', result: wokeResult(sub, ' (its draft was set aside and put back unsent)') };
+      } catch (err) {
+        log(`force ${row.id}: tmux failed (${err.message}); safety copy kept at ${draftPath}`);
+        return { status: 'failed', result: `tmux send-keys failed mid-wake: ${err.message}; the draft is saved at ${draftPath} on that host` };
+      }
+    };
     const runControlCommand = async (row) => {
       if (row.command === 'status') return { status: 'done', result: await statusResult() };
+      if (row.command === 'wake') return runWake(row);
       if (row.command !== 'compact') return { status: 'failed', result: `unsupported command ${row.command}` };
       if (!tmuxPane) return { status: 'failed', result: NO_TMUX_RESULT };
       try {
@@ -243,9 +470,11 @@ export async function runKeeper(opts) {
         await sleep(CONTROL_POLL_MS);
         remaining -= CONTROL_POLL_MS;
         await controlTick();
+        if (staleBuild()) return { code: 0, reason: 'reexec' };
       }
       await sleep(remaining);
       if (pollControl) await controlTick();
+      if (staleBuild()) return { code: 0, reason: 'reexec' };
 
       if (claude && !sameProcess(probe, claude.pid, claude.starttime)) {
         log(`claude session gone (pid ${claude.pid}); releasing ${name} and exiting`);
@@ -258,10 +487,26 @@ export async function runKeeper(opts) {
         lastHeartbeatAt = now();
         if (fails > 0) log(`heartbeat recovered after ${fails} failure(s)`);
         fails = 0;
+        reacquires = 0;
         log('heartbeat ok');
         delay = KEEP_INTERVAL_MS * (1 + rand() * 0.2);
       } catch (err) {
         if (isHoldLost(err)) {
+          // #893: a lease that merely EXPIRED (e.g. auth stalled past the TTL)
+          // also answers 409. Try one non-takeover re-lease per lapse, at most
+          // MAX_REACQUIRES in a row without a good heartbeat in between.
+          if (reacquire && reacquires < MAX_REACQUIRES) {
+            reacquires += 1;
+            try {
+              await reacquire();
+              log(`hold lapsed (${err.status || ''} ${err.message}); re-acquired (${reacquires}/${MAX_REACQUIRES})`);
+              fails = 0;
+              delay = 0;
+              continue;
+            } catch (re) {
+              log(`re-acquire refused: ${re.status || ''} ${re.message}`);
+            }
+          }
           log(`HOLD LOST: ${name} is no longer held by ${session}; keeper exiting`);
           try { forget(); } catch { /* best effort */ }
           return { code: 0, reason: 'hold-lost' };

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.4.0';
 
 // 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.