quoxcli 0.2.0 → 0.3.1

package/lib/core/selfUpdate.js

@@ -0,0 +1,188 @@
+/**
+ * The one CLI updater (owner 2026-10-16 "we need /update", "or quox --update"): shared by /update in the
+ * conversation client and `quox update` / `quox --update` in the shell.
+ *
+ * It updates THIS quox the way it was installed, and never builds a second path where one already exists:
+ *   npm         <root> is node_modules/quoxcli        -> npm install -g quoxcli@<latest>
+ *   shared-git  the box's shared CLI tree             -> quox-cli-refresh (it refuses a dirty tree itself)
+ *   git         any other git checkout                -> git -C <root> pull --ff-only (clean and on main only)
+ *   server      a self-hosted install, at a v* tag    -> points at `quox server update` (that is its updater)
+ *   bundle      a dev-server bundle (.bundle-sha)     -> points at the server's refresh
+ * It never runs git stash, reset or checkout. Every external call is injectable (deps.run / spawn) for tests.
+ *
+ * Network: `npm view quoxcli ...` (the npm registry) and `git fetch origin main` (the tree's own remote), only
+ * when the user asks for an update. Nothing is sent but those requests.
+ */
+import { spawnSync, execFile } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { join } from 'node:path';
+import os from 'node:os';
+import { RUNNING_ROOT, findOnPath } from '../quoxon/slash/restart.js';
+import { cmpSemver } from '../server/install.js';
+import { askText } from '../quoxon/ask.js';
+
+export const NPM_PACKAGE = 'quoxcli';
+export const NOTES_MAX = 5;
+
+function defaultRun(cmd, args, { timeout = 30000 } = {}) {
+  const r = spawnSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout });
+  if (r.error) return { code: null, stdout: '', stderr: `${r.error.code || 'failed'}: ${r.error.message}` };
+  return { code: r.status, stdout: String(r.stdout || '').trim(), stderr: String(r.stderr || '').trim() };
+}
+
+/** The same, without blocking: the check runs while the conversation client keeps painting. */
+function asyncRun(cmd, args, { timeout = 30000 } = {}) {
+  return new Promise((done) => {
+    execFile(cmd, args, { encoding: 'utf8', timeout }, (err, stdout, stderr) => {
+      if (err && typeof err.code !== 'number') return done({ code: null, stdout: '', stderr: `${err.code || (err.killed ? 'timed out' : 'failed')}: ${String(stderr || err.message).trim()}` });
+      done({ code: err ? err.code : 0, stdout: String(stdout || '').trim(), stderr: String(stderr || '').trim() });
+    });
+  });
+}
+
+function withDeps(deps = {}, run = defaultRun) {
+  return {
+    run,
+    exists: existsSync,
+    readFile: (p) => readFileSync(p, 'utf8'),
+    realpath: (p) => { try { return realpathSync(p); } catch { return p; } },
+    findOnPath,
+    home: os.homedir(),
+    ...deps,
+  };
+}
+
+const gitOut = (d, dir, args, timeout = 5000) => {
+  const r = d.run('git', ['-C', dir, ...args], { timeout });
+  return r.code === 0 ? String(r.stdout || '').trim() : null;
+};
+const gitOutA = async (d, dir, args, timeout = 5000) => {
+  const r = await d.run('git', ['-C', dir, ...args], { timeout });
+  return r.code === 0 ? String(r.stdout || '').trim() : null;
+};
+const lastLine = (s) => String(s || '').trim().split('\n').filter(Boolean).pop() || '';
+
+/** How this quox was installed. -> { kind, root, version, branch?, refresh?, tag? } */
+export function detectInstall({ root = RUNNING_ROOT, env = process.env, deps = {} } = {}) {
+  const d = withDeps(deps);
+  const real = d.realpath(root);
+  let version = null;
+  try { version = JSON.parse(d.readFile(join(root, 'package.json'))).version || null; } catch { /* no package.json */ }
+  if (/[/\\]node_modules[/\\]quoxcli$/.test(real)) return { kind: 'npm', root: real, version };
+  if (d.exists(join(root, '.bundle-sha'))) return { kind: 'bundle', root: real, version };
+  const top = gitOut(d, real, ['rev-parse', '--show-toplevel']);
+  if (top) {
+    const branch = gitOut(d, top, ['rev-parse', '--abbrev-ref', 'HEAD']);
+    const refresh = d.findOnPath('quox-cli-refresh', env);
+    const shared = d.realpath(env.QUOX_CLI_DIR || join(d.home, 'quox-dashboard-cli'));
+    if (refresh && d.realpath(top) === shared) return { kind: 'shared-git', root: top, refresh, branch, version };
+    if (branch === 'HEAD') {
+      const tag = gitOut(d, top, ['describe', '--tags', '--exact-match']);
+      if (tag && /^v\d/.test(tag)) return { kind: 'server', root: top, tag, version };
+    }
+    return { kind: 'git', root: top, branch, version };
+  }
+  return { kind: 'unknown', root: real, version };
+}
+
+async function checkNpm(info, d) {
+  const cur = info.version || '0.0.0';
+  const v = await d.run('npm', ['view', NPM_PACKAGE, 'version'], { timeout: 20000 });
+  if (v.code !== 0 || !v.stdout) return { ok: false, kind: 'npm', current: cur, error: `npm view ${NPM_PACKAGE} version failed: ${lastLine(v.stderr) || `exit ${v.code}`}` };
+  const latest = lastLine(v.stdout);
+  const cmd = `npm install -g ${NPM_PACKAGE}@${latest}`;
+  const base = { ok: true, kind: 'npm', current: cur, latest, notes: [], manual: cmd };
+  const c = cmpSemver(latest, cur);
+  if (c !== null && c <= 0) return { ...base, upToDate: true, ahead: c < 0, count: 0 };
+  let count = 1;
+  const all = await d.run('npm', ['view', NPM_PACKAGE, 'versions', '--json'], { timeout: 20000 });
+  try {
+    const list = JSON.parse(all.stdout);
+    const n = (Array.isArray(list) ? list : [list]).filter((x) => cmpSemver(x, cur) === 1 && cmpSemver(x, latest) <= 0).length;
+    if (n > 0) count = n;
+  } catch { /* keep 1 */ }
+  return { ...base, upToDate: false, count, command: { cmd: 'npm', args: ['install', '-g', `${NPM_PACKAGE}@${latest}`], display: cmd } };
+}
+
+async function checkGit(info, d) {
+  const { root, kind } = info;
+  const f = await d.run('git', ['-C', root, 'fetch', 'origin', 'main', '--quiet'], { timeout: 30000 });
+  if (f.code !== 0) return { ok: false, kind, error: `git -C ${root} fetch origin main failed: ${lastLine(f.stderr) || `exit ${f.code}`}` };
+  const current = await gitOutA(d, root, ['rev-parse', '--short', 'HEAD']) || '?';
+  const latest = await gitOutA(d, root, ['rev-parse', '--short', 'origin/main']) || '?';
+  const count = Number(await gitOutA(d, root, ['rev-list', '--count', 'HEAD..origin/main']) || 0) || 0;
+  const pull = `git -C ${root} pull --ff-only`;
+  const shared = kind === 'shared-git';
+  const manual = shared ? 'quox-cli-refresh' : pull;
+  const base = { ok: true, kind, root, current, latest, count, manual };
+  if (count === 0) return { ...base, upToDate: true, notes: [] };
+  const notes = (await gitOutA(d, root, ['log', '--format=%s', '-n', String(NOTES_MAX), 'HEAD..origin/main']) || '').split('\n').filter(Boolean);
+  if (shared) {
+    return { ...base, upToDate: false, notes, scope: `This runs quox-cli-refresh, which updates quox for every session on this box (${root}).`, command: { cmd: info.refresh, args: [], display: 'quox-cli-refresh' } };
+  }
+  let refused = null;
+  if (info.branch !== 'main') refused = `${root} is on branch ${info.branch || '(unknown)'}, not main. Switch to main yourself, then update again. Nothing was changed.`;
+  else {
+    const dirty = (await gitOutA(d, root, ['status', '--porcelain', '--untracked-files=no']) || '').split('\n').filter(Boolean);
+    if (dirty.length) refused = `${root} has ${dirty.length} file${dirty.length === 1 ? '' : 's'} with uncommitted changes. Commit or move them, then update again. Nothing was changed.`;
+  }
+  return { ...base, upToDate: false, notes, refused, command: refused ? null : { cmd: 'git', args: ['-C', root, 'pull', '--ff-only'], display: pull } };
+}
+
+/**
+ * What an update would do. -> { ok, kind, current, latest, count, notes[], upToDate, command?, manual, scope?, refused?, error? }
+ * refused: this install has its own updater (or is not in a state to update): say why and the manual way.
+ */
+export async function checkUpdate(info, { deps = {} } = {}) {
+  const d = withDeps(deps, asyncRun);
+  switch (info?.kind) {
+    case 'npm': return checkNpm(info, d);
+    case 'git': case 'shared-git': return checkGit(info, d);
+    case 'server': return { ok: true, kind: 'server', current: info.tag, manual: 'quox server update', refused: `This quox is part of your self-hosted Quox install (${info.tag} at ${info.root}), so it updates with the server: run quox server update (it shows the latest release and asks first).` };
+    case 'bundle': return { ok: true, kind: 'bundle', manual: null, refused: `This quox is the dev-server bundle in ${info.root}; the Quox server refreshes it while dev mode is on. Ask your admin, or install your own copy with npm install -g ${NPM_PACKAGE}@latest.` };
+    default: return { ok: true, kind: 'unknown', manual: `npm install -g ${NPM_PACKAGE}@latest`, refused: `Could not tell how this quox was installed (${info?.root || 'unknown path'}). To install the published one: npm install -g ${NPM_PACKAGE}@latest` };
+  }
+}
+
+/** Run the update with the terminal handed over (prompts, sudo). -> { ok, code } or { ok:false, error } */
+export function runUpdate(plan, { spawn = spawnSync, env = process.env } = {}) {
+  const r = spawn(plan.command.cmd, plan.command.args, { stdio: 'inherit', env });
+  if (r.error) return { ok: false, error: `${r.error.code || 'failed'}: ${r.error.message}` };
+  const code = r.status ?? (r.signal ? 128 + (os.constants.signals[r.signal] || 0) : 1);
+  return { ok: code === 0, code };
+}
+
+const isGit = (p) => p.kind === 'git' || p.kind === 'shared-git';
+
+/** The lines shown before the ask (or the one line when there is nothing to do). */
+export function updateLines(plan) {
+  if (!plan.ok) return [`Could not check for updates: ${plan.error}`];
+  if (plan.refused && plan.kind !== 'git') return [plan.refused];
+  if (plan.upToDate) return [isGit(plan) ? `quox ${plan.current} is up to date with origin/main.` : plan.ahead ? `quox ${plan.current} is newer than the published ${plan.latest}. Nothing to update.` : `quox ${plan.current} is the latest.`];
+  const out = [];
+  const notes = plan.notes || [];
+  if (notes.length) out.push(`What's new (${isGit(plan) ? 'commits on origin/main' : 'releases'}):`, ...notes.slice(0, NOTES_MAX).map((n) => `  · ${n}`));
+  if (plan.count > notes.length && notes.length) out.push(`  · and ${plan.count - notes.length} more`);
+  if (plan.kind === 'npm') out.push(`Runs: ${plan.command.display}. Release notes show after the restart (/whatsnew).`);
+  if (plan.scope) out.push(plan.scope);
+  if (plan.refused) out.push(`quox ${plan.current} -> ${plan.latest}: ${plan.count} change${plan.count === 1 ? '' : 's'}, not updated. ${plan.refused}`);
+  return out;
+}
+
+/** "▶ quox <cur> -> <latest>: <n> changes. Update now and restart? y/N/c" (the shared ask shape). */
+export function updateAsk(plan, { restart = true } = {}) {
+  const n = plan.count;
+  return askText(`Update now${restart ? ' and restart' : ''}?`, { reason: `quox ${plan.current} -> ${plan.latest}: ${n} change${n === 1 ? '' : 's'}.` });
+}
+
+/** `quox --update [...]` is `quox update [...]` when it comes before any subcommand. */
+export function rewriteUpdateFlag(argv) {
+  const VALUE = new Set(['-p', '--profile', '-o', '--output', '--org']);
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--update') return [...argv.slice(0, i), 'update', ...argv.slice(i + 1)];
+    if (VALUE.has(a)) { i++; continue; }
+    if (!a.startsWith('-')) return argv; // a subcommand came first: its own flags are its business
+  }
+  return argv;
+}

package/lib/core/sessionsOverview.js

@@ -107,6 +107,70 @@ export function overviewLines(index, { now = Date.now(), localHost = null, all =
   return out;
 }
 
+/**
+ * SESSIONS (owner 2026-10-15): the quox conversation client's bare `/sessions`.
+ * Human first: every row leads with the session NAME and WHERE it runs, then
+ * how long it has been up and when it was last active. Ids and attach commands
+ * only appear with `refs` (one dim line under each row). Sections by what the
+ * thing is (terminal sessions, slots, work, chats), newest activity first.
+ * A row with no host says "host unknown"; nothing is guessed.
+ * -> [{ text, tone, state? }]
+ */
+const SECTIONS = [
+  { title: 'Terminal sessions', test: (r) => r.kind === 'tmux' },
+  { title: 'Slots', test: (r) => r.kind === 'slot' },
+  { title: 'Work', test: (r) => r.kind !== 'tmux' && r.kind !== 'slot' && r.kind !== 'conversation' },
+  { title: 'Chats', test: (r) => r.kind === 'conversation' },
+];
+
+function whereLabel(r, localHost) {
+  if (r.kind === 'conversation') return 'on the Quox server';
+  if (!r.host) return 'host unknown';
+  return localHost && r.host === localHost ? `on ${r.host} (this machine)` : `on ${r.host}`;
+}
+
+function sessionName(r) {
+  if (r.kind === 'slot') return r.holder_session || r.name || '(unnamed slot)';
+  return r.name || '(unnamed)';
+}
+
+export function humanSessionLines(index, { now = Date.now(), localHost = null, all = false, refs = false, names = {} } = {}) {
+  const prepared = prepareIndex(index, { all, names });
+  const rows = prepared.groups.flatMap((g) => g.rows).sort((a, b) => timeOf(b) - timeOf(a));
+  const counts = index.counts || {};
+  const ago = (v) => { const t = Date.parse(v); return Number.isFinite(t) ? formatAge((now - t) / 1000) : null; };
+  const out = [
+    { text: stripAnsi(line('quox', 'sessions', { result: `${counts.total || 0} live` })), tone: 'accent' },
+    { text: `${counts.working || 0} working · ${counts.waiting || 0} waiting · ${counts.resting || 0} resting · ${counts.failing || 0} failing`, tone: 'dim' },
+  ];
+  if (!rows.length) out.push({ text: 'No live sessions in this org.', tone: 'dim' });
+  for (const sec of SECTIONS) {
+    const rs = rows.filter(sec.test);
+    if (!rs.length) continue;
+    out.push({ text: `${sec.title} (${rs.length})`, tone: 'accent' });
+    for (const r of rs) {
+      const bits = [whereLabel(r, localHost)];
+      if (r.kind === 'slot' && r.holder_session && r.name && r.name !== r.holder_session) bits.push(`holds slot ${r.name}`);
+      const up = r.started_at ? ago(r.started_at) : null;
+      if (up) bits.push(`up ${up}`);
+      const act = ago(r.last_active);
+      bits.push(act ? `active ${act} ago` : 'no activity recorded');
+      const who = [r.agent ? `agent ${r.agent}` : null, r.kind === 'tmux' && r.slot ? `slot ${r.slot}` : null, r.backend || null].filter(Boolean);
+      if (who.length) bits.push(who.join(', '));
+      if (r.unread) bits.push(`${r.unread} unread`);
+      if (r.turns) bits.push(`${r.turns} turn${r.turns === 1 ? '' : 's'}`);
+      if (r.state_reason && r.state === 'failing') bits.push(r.state_reason);
+      out.push({ text: `  ${GLYPH[r.state] || '?'} ${sessionName(r)}  ${bits.join(' · ')}`, tone: TONE[r.state] || 'dim', state: r.state });
+      if (refs) out.push({ text: `      ${[r.attach_hint || null, r.id ? `id ${r.id}` : null].filter(Boolean).join(' · ')}`, tone: 'dim' });
+    }
+  }
+  if (prepared.hiddenConversations > 0) out.push({ text: `  +${prepared.hiddenConversations} older chats (last 24 h) · /sessions all`, tone: 'dim' });
+  const bad = (index.sources || []).filter((s) => s.state !== 'connected');
+  if (bad.length) out.push({ text: `could not read: ${bad.map((s) => `${s.id} (${s.state}${s.note ? `: ${s.note}` : ''})`).join(' · ')}`, tone: 'dim' });
+  if (!refs && rows.length) out.push({ text: '/sessions refs adds ids and attach commands · /sessions all includes every chat', tone: 'dim' });
+  return out;
+}
+
 export function renderOverview(index, { now = Date.now(), localHost = osHostname(), color = false, all = false, names = {} } = {}) {
   return overviewLines(index, { now, localHost, all, names }).map((l) => {
     if (!color) return l.text;

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' };