Skip to content

Where agent teams gather. Cross-platform team chat where AI agents are first-class teammates — with cloud or bring-your-own (Claude Code / Codex) brains.

TypeScript
256 KB
Raw Blame
/**
 * `cumora agent computer` — the BYOA daemon.
 *
 * A long-running process on the user's machine (laptop or VPS) that hosts one
 * or more of their Cumora agents, using a local engine (Claude Code / Codex / pi /
 * Grok Build / Cursor Agent / OpenCode / Gemini / Qwen / Antigravity) as each
 * agent's brain. See docs/BYOA.md.
 *
 * It talks to the Cumora server only over HTTP — no DB/Redis — so it can run
 * anywhere:
 *   - pair once:   cumora agent computer --pair <code> [--server <url>]
 *   - then run:    cumora agent computer [--server <url>]
 *
 * Per managed agent it: mints a short-lived runtime JWT, holds a wake-stream
 * SSE connection, and on each wake runs the engine in the agent's dedicated
 * home (~/.cumora/agents/<id>/). Secure adapters impose the host boundary;
 * a fixed MCP bridge sends file-IPC requests that the daemon forwards to Cumora.
 *
 * Standalone: only Node builtins + the DB-free SSE parser + engine.ts.
 */

import { execFile, spawn } from 'node:child_process'
import { createHash, randomUUID } from 'node:crypto'
import { existsSync, constants as FS_CONSTANTS, type FSWatcher, watch } from 'node:fs'
import { chmod, copyFile, lstat, mkdir, open, readdir, readFile, rename, rm, stat, truncate, writeFile } from 'node:fs/promises'
import { homedir, hostname } from 'node:os'
import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
import { promisify } from 'node:util'

const execFileP = promisify(execFile)

import { type TokenUsage, usageFromClaude } from '../cost.js'
import { GLANCE_YIELD_RULES } from '../glance-protocol.js'
import {
  composeMemoryDigest,
  conversationHeader,
  memoryIndexPathsForScope,
  uniqueProjectIds,
} from '../memory-scope.js'
import { parseSseStream, wakeStreamWasStable } from '../runtime/sse-parse.js'
import { type ProviderProfile, providerProfileEnv, providerProfileFingerprint, providerProfileMetadata, readProviderProfiles, redactProviderSecret } from './provider-profiles.js'
import { modelIdOrNull } from './model-id.js'
import { parseComputerControlEvent } from './control-event.js'
import { runEngineUpdate } from './cli-version.js'
import {
  mergeWakeBackgroundBriefs,
  parseWakeData,
  type WakeBackgroundBrief,
  wakeHasActionableInput,
} from '../runtime/wake-options.js'
import { SKYPE_EMOTICONS_GUIDE } from '../skype-emoticons.js'
import { finalizeTriage, isRateLimited, parseTriage } from '../triage-core.js'
import { type ActionSurface, actionSurfaceFor, actionSurfaceText, calendarExampleText, postingMechanicsText } from './prompt-surface.js'
import { allowUnsandboxedByoa, classifyEngineFailure, detectEnginesWithStatus, ENGINE_IDS, engineFailureOf, engineVisionCapability, type DetectedEngineSnapshot, type EngineHopReport, type EngineId, type EngineRunResult, type EngineSession, type EngineUsage, enrichDetectedEngines, evaluateRunnableEngines, getAdapter, loginCodexRuntime, runEngineDoctor, type RunnableEngineEvaluation, snapshotDetectedEngines } from './engine.js'
import { EngineSessionStore, sessionIdPreview } from './session-store.js'
import { CODEX_LOGIN_COMMAND, CODEX_MIGRATE_COMMAND, CODEX_SESSION_SCOPE, codexRuntimeHome } from './codex-runtime.js'
import { cachedCodexProvider } from './codex-provider.js'
import { migrateCodexSession, migrateCodexSessions } from './codex-session-migration.js'
import { runWithSessionRecovery } from './session-recovery.js'
import { normalizeAttachments, type AttachmentDescriptor } from '../../../../shared/attachments.js'
import { AgentAttachmentCache, attachmentImageGuidance, isImageAttachment, renderCachedAttachments, type AttachmentCacheResult } from './attachment-cache.js'

export { conversationHeader }

/** Serialize engine scans and coalesce duplicate requests. A forced refresh that
 * arrives during an ordinary scan schedules exactly one follow-up forced report,
 * so the UI acknowledgement cannot be swallowed by older work. */
export function createEngineRescanQueue(
  scan: (forceReport: boolean) => Promise<void>,
): (forceReport?: boolean) => Promise<void> {
  let inFlight: Promise<void> | null = null
  let forcedPending = false
  return (forceReport = false): Promise<void> => {
    forcedPending ||= forceReport
    if (inFlight) return inFlight
    const running = (async () => {
      let first = true
      while (first || forcedPending) {
        first = false
        const force = forcedPending
        forcedPending = false
        await scan(force)
      }
    })().finally(() => {
      if (inFlight === running) inFlight = null
    })
    inFlight = running
    return running
  }
}

const CONFIG_DIR = join(homedir(), '.cumora')
const CONFIG_PATH = join(CONFIG_DIR, 'computer.json')
const AGENTS_ROOT = join(CONFIG_DIR, 'agents')
// Per-agent, per-engine session id, persisted OUTSIDE the agent home (so the engine's
// own cwd can't clobber it). Survives a daemon restart so the next wake can
// `--resume` the SAME engine session — recovering the in-turn context an
// interrupted long task was building, instead of starting cold.
const SESSIONS_DIR = join(CONFIG_DIR, 'sessions')
// Bounded grace on a forced shutdown (SIGTERM/SIGINT): let an in-flight turn try
// to finish before we kill the engine child. The OS supervisor SIGKILLs not long
// after SIGTERM, so this is best-effort for SHORT turns; long tasks rely on the
// session-resume above. Self-update (voluntary) doesn't use this — it waits for
// idle instead (never interrupts work). Override via CUMORA_SHUTDOWN_GRACE_MS.
const SHUTDOWN_GRACE_MS = Number(process.env.CUMORA_SHUTDOWN_GRACE_MS) || 15_000
const DEFAULT_SERVER = process.env.CUMORA_SERVER_URL || 'https://api.cumora.ai'
const TOKEN_REFRESH_SKEW_MS = 5 * 60 * 1000 // refresh 5min before expiry
const AGENT_POLL_MS = 60_000
const HEARTBEAT_MS = 30_000
// How often the daemon re-scans PATH for installed engines. Deliberately much
// slower than the heartbeat: detection spawns a `which`/`where` per engine, and
// nobody installs a CLI twice a minute. The heartbeat carries the CACHED result,
// so the report costs nothing on the 30s tick.
const ENGINE_RESCAN_MS = 5 * 60 * 1000
// While an engine turn is in flight, bump the run's updated_at this often so the
// server's 10-min stale-run sweeper doesn't false-positive a legitimately long
// turn (a multi-hour Bash, a deep task) as "orphaned". 60s = 10× margin under the
// 10-min reaper; cheap (one tiny UPDATE). A long task NO LONGER hits a hidden cap.
const RUN_HEARTBEAT_MS = 60_000
// Fallback inbox drain. The wake-stream SSE can be silently severed by the
// network edge (the server writes the wake onto a half-dead socket, counts it
// delivered, and does nothing more), so a live wake can be lost until the daemon
// detects the drop and reconnects. This self-drain bounds catch-up latency
// regardless of SSE health; an empty inbox makes the turn a cheap no-op for the
// DAEMON — but not for the server: every drain is a loadInbox against Postgres,
// and at fleet scale (thousands of idle agents × one drain per 20s) that alone
// pegged Cloud SQL. So the tick stays at 20s, but a tick only drains when the
// stream is not provably alive (see fallbackPollDue): the server writes a
// `: ping` comment every 25s (wake-bus.ts), so a stream silent for three pings
// counts as dead and is polled at the old cadence AND torn down so streamLoop
// reconnects (a half-dead socket can otherwise sit "open" for many minutes);
// a stream that is demonstrably alive is trusted and only double-checked every
// INBOX_POLL_STREAM_HEALTHY_MS.
const INBOX_POLL_MS = 20_000
const INBOX_POLL_STREAM_HEALTHY_MS = 120_000
const WAKE_STREAM_STALE_MS = 75_000
// Idle-tick `avail` reassert. Every idle drain used to POST /status {avail} —
// an UPDATE + Redis publish per agent per tick that changed nothing. The server
// now no-ops an avail→avail write, but the request itself (and its resolveDevice)
// still costs; so the daemon posts avail only when the last status it sent was
// something else, and re-asserts it this often as self-healing in case the
// server-side row drifted (a failed post, a restore from backup, ...).
const AVAIL_REASSERT_MS = 10 * 60_000
// Pre-turn wake debounce. The FIRST wake from
// an idle state arms this timer; wakes arriving within the window FOLD INTO it —
// the turn snapshots ALL unread, so a burst of group messages becomes ONE big-
// engine turn instead of N. Content-blind, no classification.
//
// 500ms, not 2.5s: this delay sits on the critical path of EVERY reply, and a live
// chat measurement showed the two waits (2.53s each) costing more perceived
// latency than the coalescing saved — a room's burst still folds in at 500ms
// because the timer only starts once the first wake lands.
const WAKE_DEBOUNCE_MS = 500
// Same-turn group notice (default ON — set CUMORA_BYOA_STEER_GROUP=0
// to disable). A DIRECT ping (DM / @me / human) is ALWAYS steered into the live
// turn (see maybeSteer). With this on, plain GROUP activity arriving while busy
// ALSO gets a single CONTENT-FREE nudge ("N new message(s) in <convo> — glance
// and handle if it's yours") injected into the running turn, so the agent can
// pick it up mid-task instead of only via the post-turn coalesced
// rerun. The rerun stays as the coordination-safe BACKSTOP: if the agent handles
// the activity in-turn, the rerun's snapshot finds nothing unread and no-ops; if
// not, it still runs a clean re-glance turn. Originally shipped default-OFF
// because mid-turn group handling ran against the turn-START compose-anchor;
// that anchor is GONE — freshness is now the server-side seen-cursor (HOLD shows
// newer messages and advances the cursor), which arbitrates a mid-turn reply
// exactly like a post-wake one — so the coordination-safety objection no longer
// exists and the busy-room latency win (skip a whole wake→triage→turn cycle per
// coalesced burst) is taken by default.
const STEER_GROUP_IN_TURN = process.env.CUMORA_BYOA_STEER_GROUP !== '0'
// Throttle for the content-free group notice so a fast room can't spam the live
// session — at most one group nudge per this window (direct pings are unthrottled).
const GROUP_STEER_MIN_INTERVAL_MS = Math.max(0, Number(process.env.CUMORA_BYOA_STEER_GROUP_INTERVAL_MS ?? 8_000))
// Board-awareness: when chat is idle, check the agent's AGENDA (assigned Kanban
// cards + due calendar events) so it PROACTIVELY picks up assigned board work
// instead of only reacting to a chat push. Gated like the cloud idle scheduler:
// the agent must have been QUIET (no turn) for AGENDA_QUIET_MS — that quiet window
// is the anti-loop (after it acts, it isn't re-woken until quiet again) — and we
// check at most every AGENDA_CHECK_MS so the 20s poll doesn't hammer it.
// Tightened 3min/2min → 90s/60s: agents have NO wall-clock wakes — a judge who
// says "vote closes in 2 minutes" and goes idle can only be re-woken by a new
// message (there may be none: everyone voted), the 20s poll (no-ops once the
// inbox is acked), or THIS agenda sweep. Measured in werewolf game13: all six
// votes were in by 13:53:05 and the tally sat until a player prodded the judge
// at 13:56:53 — a 4-minute dead-air gap bounded exactly by quiet+check. 90/60
// caps "it's someone's move and nobody speaks" recovery at ~2.5min while the
// server-side agenda classifier (support-model, Cumora-subsidized — not the
// operator's quota) stays throttled by these same gates. A real fix is
// first-class agent reminders; this narrows the gap now.
const AGENDA_QUIET_MS = 90_000
const AGENDA_CHECK_MS = 60_000
const MAX_VISIBLE_ERROR_CHARS = 900
// Big-brain spawn jitter. When an SSE wake fans out to N agents on this
// computer at the same instant (e.g. a human @all in a group), N local-engine
// subprocesses would spawn in the same millisecond and slam Anthropic/OpenAI
// in lockstep — observed today as four byoa_engine_failed notices in a row
// with "Server is temporarily limiting requests · Rate limited" right after
// a counting game kicked off. Sleeping a random 0..MAX before spawning the
// big brain spreads the burst across ~1.5s so the API sees them sequentially
// instead of a stampede. Cheap (worst case: ~1.5s added to one wake's
// latency); the small-brain triage already ran first, so this only delays
// the *expensive* call we'd otherwise rate-limit-fail.
// DETERMINISTIC minimum interval between spawn starts (per-computer, applied
// to BOTH big-brain and triage paths since they share the same Anthropic/
// OpenAI account quota and the same local CLI process pool). Replaces the
// earlier RANDOM jitter approach which was probabilistic: with random
// 0-1500ms jitter, 4 simultaneous wakes could each roll a low value and
// still hit the provider in lockstep. A deterministic start-interval gate
// instead ensures each new start begins at least N ms after the previous
// one — burst rate becomes a hard 2/sec
// regardless of how many agents woke at once. Anthropic/OpenAI short-window
// burst limits are well above 2/sec so this eliminates the "Server is
// temporarily limiting requests" storms entirely without slowing the steady
// state. Override via CUMORA_BYOA_MIN_SPAWN_INTERVAL_MS.
const MIN_SPAWN_INTERVAL_MS = Math.max(0, Number(process.env.CUMORA_BYOA_MIN_SPAWN_INTERVAL_MS ?? 500))
// Per-computer cap on concurrent big-brain spawns. Without this, N agents
// woken on the same SSE fanout each go to triage + spawn in parallel and
// all hit the underlying provider (Anthropic/OpenAI) at the same wall-clock
// window — even with jitter, the user's per-account short-window burst
// limit is typically smaller than the agent count, so we observed 130
// "Server is temporarily limiting requests" hits in 17 minutes during a
// counting game with 7 agents. Serializing through this semaphore makes
// the daemon respect the provider's burst limit by construction:
// excess agents queue while the first N are in flight; queue drains naturally
// as each turn finishes. Trade-off: tail latency for late-queued agents
// while a turn is being served.
//
// DEFAULT 6 (was 2). The 2 was calibrated for the cold-spawn era — every turn
// spawned a fresh CLI process and N simultaneous spawns slammed the provider.
// Two things changed: turns now run through PERSISTENT engine sessions
// (ensureEngineSession — no per-turn process spawn to burst), and actual spawns
// are paced by the deterministic spawnPacer above. What the old default DID
// provably cause: in a broadcast room (werewolf, 7 players woken by every group
// message) the queue ran 6 deep and tail turns waited 215-359s — minutes of
// user-visible silence purely from queueing. 6 keeps a hard backstop while
// letting a whole team think in parallel. Override via CUMORA_BYOA_MAX_CONCURRENT_BIG_BRAIN.
const BIG_BRAIN_CONCURRENCY = Math.max(1, Number(process.env.CUMORA_BYOA_MAX_CONCURRENT_BIG_BRAIN ?? 6))
// Per-computer cap on concurrent SMALL-brain (triage) spawns. The same
// thundering-herd problem the big-brain sem fixes: when N agents wake on
// the same SSE fanout, each spawns its own `claude --model haiku` (or
// `codex --model gpt-5.4-mini`) for triage. Without a cap the local CLI
// processes + Anthropic/OpenAI small-model endpoint get hammered and the
// 30s TRIAGE_TIMEOUT_MS fires for the slower-queued ones, abort sends
// SIGTERM (exit 143), daemon treats abort as rate-limited and enters a
// 30s per-agent cooldown — every agent's triage stalls for 30s, no big
// brain wakes, the whole computer goes silent. Observed today: 4 agents
// `local triage RATE-LIMITED (timed out) — process exited with code 143`
// in the same second. Triage is cheaper than big brain so the default sits
// above BIG_BRAIN_CONCURRENCY. DEFAULT 8 (was 4): a 7-8 agent broadcast wake
// (werewolf, @all) queued in two waves at 4 — measured as "triage 4983-7772ms"
// where most of that was queue wait, delaying every turn behind it. 8 lets a
// full team's gate checks run in one wave; the shared spawnPacer still caps the
// provider burst rate, and the 143/timeout storm the cap exists for stays
// prevented. Override via CUMORA_BYOA_MAX_CONCURRENT_TRIAGE.
const TRIAGE_CONCURRENCY = Math.max(1, Number(process.env.CUMORA_BYOA_MAX_CONCURRENT_TRIAGE ?? 8))
// After a rate-limit hit on this agent, skip ITS turns for this long before
// retrying. Without this, a rate-limited agent re-attempts on EVERY poll +
// SSE wake, each attempt burning a wasted call on the throttled provider
// — that's where the 130 rate-limit log lines came from. A 60s cooldown
// lets the provider's short-window limit reset before we try again.
const ENGINE_BACKOFF_AFTER_RATE_LIMIT_MS = 60_000
/** Cooldown after an engine failure only the OPERATOR can clear — a signed-out
 *  CLI, an exhausted credit balance. Far longer than the rate-limit window,
 *  because retrying changes nothing until a human logs in or tops up.
 *
 *  Measured before this existed: nine computers with a signed-out Claude
 *  produced 1,988 failed turns in forty minutes — about one every twelve
 *  seconds each, forever, with no backoff and nothing telling their operator
 *  why. That is most of what a fleet-wide "97% failure rate" actually was. */
const ENGINE_BACKOFF_AFTER_OPERATOR_FIX_MS = 15 * 60_000

/** Engine failures that will recur identically until a human intervenes.
 *  Deliberately narrow: only errors whose remedy is unambiguous and whose
 *  retry has no chance of succeeding. Anything uncertain stays on the normal
 *  path and keeps retrying. */
const OPERATOR_FIX_RE = /not logged in|please run \/login|credit balance is too low|insufficient (credit|quota)|invalid api key|unauthorized/i

export function needsOperatorFix(err: string | null | undefined): boolean {
  return !!err && OPERATOR_FIX_RE.test(err)
}

/** What a finished engine turn says about trying again, in one place.
 *
 *  A turn ends on one of two paths — the chat wake, and the proactive agenda
 *  heartbeat that fires every AGENDA_CHECK_MS on its own — and both end at this
 *  same question. They used to answer it differently: the chat path put a
 *  signed-out engine to sleep for fifteen minutes, and the agenda path did not.
 *  So an agent nobody happened to be chatting with kept exactly the spin the
 *  pause exists to stop, one dead spawn a minute, indefinitely.
 *
 *  Classifying once is what keeps the two paths honest. A path can still fail to
 *  ASK — which is one grep away — but it can no longer hold a different opinion
 *  than the other about what a given failure means.
 *
 *  Order matters: a throttle that also mentions quota is a throttle. It clears
 *  itself, so it takes the short cooldown and stays out of the user's chat. */
export type TurnOutcome =
  /** Clean turn — cancel any pause this agent was under. */
  | 'ok'
  /** Provider throttle. Clears itself: short cooldown, no user-facing notice. */
  | 'rate-limited'
  /** Only a human can clear it. Long pause, and tell someone. */
  | 'operator-fix'
  /** Cause unknown. Keep retrying, and leave any existing pause alone. */
  | 'transient'

export function classifyTurnOutcome(engineError: string | null | undefined): TurnOutcome {
  if (!engineError) return 'ok'
  // Preserve normal retries for local startup failures, even when the path
  // happens to contain provider keywords such as "quota".
  if (classifyEngineFailure(engineDiagnosticProse(engineError)) === 'startup') return 'transient'
  if (isRateLimited(engineError)) return 'rate-limited'
  if (needsOperatorFix(engineError)) return 'operator-fix'
  return 'transient'
}

/** The engine backoff deadline a finished turn implies, or null to leave the
 *  current one untouched. Null is not zero: an unexplained failure must not
 *  cancel a pause an earlier, well-understood one established. */
export function backoffUntilFor(outcome: TurnOutcome, now: number): number | null {
  switch (outcome) {
    case 'ok': return 0
    case 'rate-limited': return now + ENGINE_BACKOFF_AFTER_RATE_LIMIT_MS
    case 'operator-fix': return now + ENGINE_BACKOFF_AFTER_OPERATOR_FIX_MS
    case 'transient': return null
  }
}
// Neutral cwd for LOCAL small-brain triage: no persona CLAUDE.md / skills / MCP,
// so the cerebellum completion is fast and tool-free.
const TRIAGE_DIR = join(CONFIG_DIR, 'triage')
const TRIAGE_TIMEOUT_MS = 30_000

/** Per-computer concurrency gate for big-brain spawns. acquire() resolves
 *  immediately if a slot is free; otherwise it queues FIFO and resolves
 *  when an earlier holder releases. Pure in-process — bounded queue size
 *  follows the agent count (~7 typical), no memory concern. */
class BigBrainSemaphore {
  private inFlight = 0
  private readonly waiters: Array<() => void> = []
  constructor(private readonly max: number) {}
  async acquire(): Promise<void> {
    if (this.inFlight < this.max) {
      this.inFlight += 1
      return
    }
    await new Promise<void>((resolve) => this.waiters.push(resolve))
    this.inFlight += 1
  }
  release(): void {
    this.inFlight -= 1
    const next = this.waiters.shift()
    if (next) next()
  }
  /** Diagnostic only — number of waiters currently queued. */
  get queueDepth(): number { return this.waiters.length }
}
const bigBrainSem = new BigBrainSemaphore(BIG_BRAIN_CONCURRENCY)
const triageSem = new BigBrainSemaphore(TRIAGE_CONCURRENCY)

/** Per-computer ADAPTIVE minimum interval between local-CLI spawns.
 *  Deterministic spacing (see MIN_SPAWN_INTERVAL_MS above) that
 *  auto-tunes to the user's actual Anthropic/OpenAI burst quota: starts
 *  at MIN_SPAWN_INTERVAL_MS (default 500ms), doubles on every
 *  rate-limit event (signaled via `onRateLimited()`), capped at 8s.
 *  After CONSECUTIVE_OK_BEFORE_HALVE (5) successive successes (signaled
 *  via `onOk()`), halves back toward the base — so a transient burst
 *  spike doesn't permanently slow steady-state throughput. This lets one
 *  daemon binary work across very different account tiers without env
 *  tuning, and converges to the user's actual quota in a minute or two
 *  of natural traffic. */
class AdaptivePacer {
  private next = 0
  private current: number
  private consecutiveOk = 0
  constructor(private readonly base: number, private readonly maxMs = 8000) {
    this.current = base
  }
  async gate(): Promise<void> {
    if (this.current <= 0) return
    const now = Date.now()
    const earliest = Math.max(now, this.next)
    this.next = earliest + this.current
    const wait = earliest - now
    if (wait > 0) await new Promise((r) => setTimeout(r, wait))
  }
  /** Called when a spawn after gate() ends up rate-limited. Doubles the
   *  interval (capped) and resets the success streak so we don't halve
   *  back too fast on the next OK. */
  onRateLimited(): void {
    const prev = this.current
    this.current = Math.min(this.maxMs, Math.max(this.base, this.current * 2))
    this.consecutiveOk = 0
    if (this.current !== prev) {
      console.warn(`[pacer] adapt: ${prev}ms → ${this.current}ms (rate-limited; cap ${this.maxMs}ms)`)
    }
  }
  /** Called when a spawn completes cleanly (no rate-limit). After enough
   *  in a row, decay back toward the base. */
  onOk(): void {
    if (this.current === this.base) return
    this.consecutiveOk += 1
    if (this.consecutiveOk >= 5) {
      const prev = this.current
      this.current = Math.max(this.base, Math.floor(this.current / 2))
      this.consecutiveOk = 0
      if (this.current !== prev) {
        console.log(`[pacer] adapt: ${prev}ms → ${this.current}ms (5 ok; decaying toward base ${this.base}ms)`)
      }
    }
  }
  get intervalMs(): number { return this.current }
}
const spawnPacer = new AdaptivePacer(MIN_SPAWN_INTERVAL_MS)

// ─── self-update ──────────────────────────────────────────────────────────
// Injected by esbuild at build time (agent-cli/build.mjs). Source-mode
// launchers may provide CUMORA_VERSION; otherwise development falls back to
// 0.0.0. The typeof guard keeps an undefined build constant safe at runtime.
declare const __CUMORA_VERSION__: string | undefined
export function resolveCurrentVersion(bundledVersion: string | undefined, envVersion = process.env.CUMORA_VERSION): string {
  return bundledVersion ?? (envVersion?.trim() || '0.0.0')
}
const CURRENT_VERSION = resolveCurrentVersion(
  typeof __CUMORA_VERSION__ === 'string' ? __CUMORA_VERSION__ : undefined,
)
const UPDATE_CHECK_MS = 6 * 60 * 60 * 1000 // re-check npm every 6h
// Log rotation: the service supervisor (launchd StandardOutPath / systemd) writes
// the daemon's stdout to ~/.cumora/daemon.log and NEVER rotates it — left alone it
// fills the user's disk. We cap it ourselves.
const MAX_LOG_BYTES = 20 * 1024 * 1024 // rotate when the live log passes 20MB
const LOG_ROTATE_MS = 5 * 60 * 1000 // check every 5 minutes
const SERVICE_LABEL = 'io.cumora.daemon'
/** The supervisor (`--install-service`) sets this so the daemon knows a clean
 *  exit will be auto-restarted on `cumora@latest` — only then do we self-exit
 *  to apply an update. A manually-run daemon just logs the available version. */
const SUPERVISED = process.env.CUMORA_SUPERVISED === '1'

export function windowsTaskName(home = homedir()): string {
  const userKey = createHash('sha256').update(home.toLowerCase()).digest('hex').slice(0, 12)
  return `Cumora BYOA Daemon (${userKey})`
}

/** semver-ish a > b for plain MAJOR.MINOR.PATCH (ignores pre-release tags). */
function versionGt(a: string, b: string): boolean {
  const pa = a.split('.').map((n) => parseInt(n, 10) || 0)
  const pb = b.split('.').map((n) => parseInt(n, 10) || 0)
  for (let i = 0; i < 3; i++) {
    if ((pa[i] ?? 0) > (pb[i] ?? 0)) return true
    if ((pa[i] ?? 0) < (pb[i] ?? 0)) return false
  }
  return false
}

interface DaemonConfig {
  serverUrl: string
  computerId: string
  deviceToken: string
}

interface AgentInfo {
  providerProfile?: string | null
  id: string
  name: string
  role: string | null
  systemPrompt: string | null
  engine: EngineId | null
  model: string | null
  fastModel: string | null
  nativeFastMode?: boolean
  modelCatalog?: {
    models: Array<{ id: string; label: string; vision?: 'supported' | 'unsupported' | 'unknown' }>
    defaultModel: string | null
  }
}

/** Render one attachment descriptor in the inbox digest. The daemon separately
 *  downloads authorized bytes into the Agent home. */
export function attachmentNote(
  att: { name?: string; kind?: string; mime?: string; size?: number; url?: string } | null | undefined,
): string {
  if (!att || typeof att !== 'object') return ''
  const name = typeof att.name === 'string' && att.name.trim() ? att.name.trim().slice(0, 120) : 'file'
  const type = typeof att.mime === 'string' && att.mime.trim()
    ? att.mime.trim().slice(0, 60)
    : (typeof att.kind === 'string' ? att.kind.slice(0, 20) : '')
  const size = typeof att.size === 'number' && Number.isFinite(att.size) && att.size > 0
    ? ` ${att.size >= 1024 * 1024 ? `${(att.size / 1024 / 1024).toFixed(1)}MB` : `${Math.max(1, Math.round(att.size / 1024))}KB`}`
    : ''
  const url = typeof att.url === 'string' && /^https?:\/\//.test(att.url) ? ` ${att.url}` : ''
  return `  [attachment: ${name}${type ? ` · ${type}` : ''}${size}${url}]`
}

/** Render every descriptor in canonical order. The singular helper remains for
 *  legacy callers and tests; the digest always goes through this list boundary. */
export function attachmentNotes(value: unknown): string {
  return normalizeAttachments(value).map((attachment) => attachmentNote({
    name: attachment.name,
    kind: attachment.kind,
    mime: attachment.mime,
    size: attachment.size,
  })).join('')
}

interface RuntimeCliAttachmentRead {
  messageId: string
  attachments: AttachmentDescriptor[]
}

function runtimeCliAttachmentReads(value: unknown): RuntimeCliAttachmentRead[] {
  if (!Array.isArray(value)) return []
  const reads: RuntimeCliAttachmentRead[] = []
  for (const candidate of value.slice(0, 200)) {
    if (!candidate || typeof candidate !== 'object') continue
    const record = candidate as Record<string, unknown>
    if (typeof record.messageId !== 'string' || !record.messageId) continue
    const attachments = normalizeAttachments(record.attachments)
    if (attachments.length > 0) reads.push({ messageId: record.messageId, attachments: [...attachments] })
  }
  return reads
}

/** Add the local path to each attachment object inside the CLI's JSON result.
 *  JSON output stays valid instead of receiving a trailing prose block. */
export function enrichCliJsonWithAttachmentPaths(
  text: string,
  cachedByMessage: ReadonlyMap<string, AttachmentCacheResult>,
  vision: 'supported' | 'unsupported' | 'unknown',
): string | null {
  let value: unknown
  try { value = JSON.parse(text) } catch { return null }
  const visit = (node: unknown): void => {
    if (!node || typeof node !== 'object') return
    if (Array.isArray(node)) {
      for (const item of node) visit(item)
      return
    }
    const record = node as Record<string, unknown>
    const messageId = typeof record.id === 'string' ? record.id : null
    const cached = messageId ? cachedByMessage.get(messageId) : undefined
    if (cached) {
      for (const field of ['attachments', 'attachment'] as const) {
        const raw = record[field]
        const list = Array.isArray(raw) ? raw : raw && typeof raw === 'object' ? [raw] : []
        for (const attachment of list) {
          if (!attachment || typeof attachment !== 'object') continue
          const descriptor = attachment as Record<string, unknown>
          const key = typeof descriptor.key === 'string' ? descriptor.key : null
          const file = cached.files.find((candidate) => candidate.attachment.key === key)
          if (file) {
            descriptor.localPath = file.path
            if (file.attachment.kind === 'img' || file.attachment.mime?.startsWith('image/') === true) {
              descriptor.localImageGuidance = attachmentImageGuidance(vision)
            }
            if (file.text !== undefined) {
              descriptor.localText = file.text
              descriptor.localTextTruncated = file.textTruncated === true
            }
          } else {
            const failure = cached.failures.find((candidate) => candidate.key === key)
              ?? cached.failures.find((candidate) => !candidate.key && candidate.name === descriptor.name)
            if (failure) descriptor.localError = failure.reason
          }
        }
      }
    }
    for (const child of Object.values(record)) visit(child)
  }
  visit(value)
  return JSON.stringify(value, null, 2)
}

interface RuntimeInboxResponse {
  rows?: Array<{
    id?: string
    conversation_id?: string
    conversation_kind?: string
    conversation_title?: string
    conversation_topic?: string | null
    project_id?: string | null
    project_name?: string | null
    author_name?: string
    author_kind?: string
    body?: string
    kind?: string
    /** Legacy first-entry projection for clients that predate multi-attachments. */
    attachment?: AttachmentDescriptor | null
    /** Canonically ordered message attachments. */
    attachments?: AttachmentDescriptor[]
    sequence?: number
  }>
}

// How many unread MESSAGE lines the pre-loaded wake digest may carry. It rides
// in EVERY chat turn's prompt (see chatDelta), so it stays small.
const DIGEST_MAX_MESSAGE_LINES = 40

/** Render the pre-loaded unread digest for the wake prompt within
 *  DIGEST_MAX_MESSAGE_LINES.
 *
 *  The budget is spent PER CONVERSATION rather than as one global "newest N
 *  lines" tail, because `ackSeen` marks the WHOLE snapshot read: anything the
 *  digest leaves out is marked read having never been shown, and since
 *  mark-read pins each conversation's cursor at its NEWEST message it can never
 *  resurface in a later wake. A global tail let a burst in one busy room evict —
 *  and then ack away — every message of a quieter conversation, including a
 *  human DM the agent could not even name afterwards. The cloud path avoids this
 *  by giving every conversation with unread its own window (see loadContext).
 *
 *  Whatever the budget still cannot fit is announced IN PLACE with its exact
 *  count and the command that reads it, so the engine can recover the rest
 *  instead of never learning it existed. Conversations keep first-seen order and
 *  their messages stay chronological; when everything fits, every unread line is
 *  shown, exactly as before.
 *
 *  Exported for tests — pure, no server and no engine. */
interface InboxDigestConversation {
  head: string
  msgs: string[]
  ids?: string[]
}

function inboxDigestKeepCounts(
  byConvo: Map<string, InboxDigestConversation>,
  budget: number,
): Map<string, number> {
  // Water-fill quietest-first: each conversation takes at most an even share of
  // what is LEFT, so a small conversation keeps all of its messages and the busy
  // one absorbs the slack. When the total fits, this hands every conversation
  // its full set (nothing omitted, nothing announced).
  const keep = new Map<string, number>()
  let lineBudget = budget
  let unserved = byConvo.size
  for (const [id, convo] of [...byConvo].sort((a, b) => a[1].msgs.length - b[1].msgs.length)) {
    const n = Math.min(convo.msgs.length, Math.max(0, Math.floor(lineBudget / unserved)))
    keep.set(id, n)
    lineBudget -= n
    unserved -= 1
  }
  return keep
}

/** IDs represented by the rendered digest lines. Attachment materialization
 *  uses the same water-fill decision so it downloads exactly what the engine
 *  is shown, rather than every unread row returned by /inbox. */
export function visibleInboxMessageIds(
  byConvo: Map<string, InboxDigestConversation>,
  budget = DIGEST_MAX_MESSAGE_LINES,
): Set<string> {
  const keep = inboxDigestKeepCounts(byConvo, budget)
  const visible = new Set<string>()
  for (const [id, convo] of byConvo) {
    const shown = keep.get(id) ?? 0
    for (const messageId of (convo.ids ?? []).slice(convo.msgs.length - shown)) visible.add(messageId)
  }
  return visible
}

export function renderInboxDigest(
  byConvo: Map<string, InboxDigestConversation>,
  budget = DIGEST_MAX_MESSAGE_LINES,
): string {
  if (byConvo.size === 0) return ''
  const keep = inboxDigestKeepCounts(byConvo, budget)
  const lines: string[] = []
  for (const [id, convo] of byConvo) {
    const shown = keep.get(id) ?? 0
    lines.push(convo.head)
    // Never drop unread in SILENCE — this turn is about to mark it read.
    if (convo.msgs.length > shown) {
      lines.push(`  … ${convo.msgs.length - shown} older unread message(s) not shown — \`cumora messages ${id} --tail ${convo.msgs.length}\` to read them`)
    }
    // slice(length - shown), NOT slice(-shown): slice(-0) is slice(0) and would
    // print everything for a conversation budgeted to zero.
    lines.push(...convo.msgs.slice(convo.msgs.length - shown))
  }
  return lines.join('\n')
}

interface RuntimeInboxTriageResponse {
  actionable?: boolean
  reason?: string
  promptNote?: string
  source?: string
}

/** `/inbox-triage/payload`: either a verdict the server decided without a model
 *  (hard rule / empty inbox), or the prompt for the daemon's LOCAL small brain. */
interface RuntimeTriagePayload {
  verdict?: RuntimeInboxTriageResponse
  instructions?: string
  input?: string
  /** Direction-aware fail mode: TRUE when the wake is purely agent-to-agent
   *  (no human in the unread set) → a LOCAL triage failure fails CLOSED
   *  (suppress) instead of open, so a flaky local model can't amplify a loop.
   *  Absent/false → fail open (a human is present; never leave them hanging). */
  failClosed?: boolean
}

// ─── arg parsing ────────────────────────────────────────────────────────

function parseArgs(argv: string[]): {
  pair?: string; server?: string; engine?: string; provider?: string
  installService?: boolean; uninstallService?: boolean; restart?: boolean; stop?: boolean
  status?: boolean; logs?: boolean; version?: boolean; doctor?: boolean; help?: boolean
  codexLogin?: boolean; migrateCodexSessions?: boolean
} {
  const out: ReturnType<typeof parseArgs> = {}
  for (let i = 0; i < argv.length; i++) {
    if (argv[i] === '--help' || argv[i] === '-h' || argv[i] === 'help') out.help = true
    else if (argv[i] === '--pair') out.pair = argv[++i]
    else if (argv[i].startsWith('--pair=')) out.pair = argv[i].slice('--pair='.length)
    else if (argv[i] === '--provider') out.provider = argv[++i] || ''
    else if (argv[i].startsWith('--provider=')) out.provider = argv[i].slice('--provider='.length)
    else if (argv[i] === '--server') out.server = argv[++i]
    else if (argv[i].startsWith('--server=')) out.server = argv[i].slice('--server='.length)
    else if (argv[i] === '--engine') out.engine = argv[++i]
    else if (argv[i].startsWith('--engine=')) out.engine = argv[i].slice('--engine='.length)
    else if (argv[i] === '--install-service') out.installService = true
    else if (argv[i] === '--uninstall-service') out.uninstallService = true
    else if (argv[i] === '--restart') out.restart = true
    else if (argv[i] === '--stop') out.stop = true
    else if (argv[i] === '--status') out.status = true
    else if (argv[i] === '--logs') out.logs = true
    else if (argv[i] === '--doctor' || argv[i] === 'doctor') out.doctor = true
    else if (argv[i] === '--codex-login') out.codexLogin = true
    else if (argv[i] === '--migrate-codex-sessions') out.migrateCodexSessions = true
    else if (argv[i] === '--version' || argv[i] === '-v') out.version = true
  }
  return out
}

// ─── HTTP helpers ───────────────────────────────────────────────────────

/** Wall-clock cap on every SHORT request/response call to the server (status,
 *  runs, token mint, heartbeat, agent sync).
 *
 *  Without this, a request that never answers — a half-open socket surviving a
 *  laptop sleep/network switch, a hung proxy, a pod that accepted the connection
 *  and stopped — parks the turn forever: `catch` only sees throws, never a
 *  promise that simply doesn't settle. The turn's `finally { this.busy = false }`
 *  never runs, so the agent stays permanently `busy`, every later wake collapses
 *  to `turn busy — coalescing`, and the heartbeat interval stops going out until
 *  the server marks the whole computer offline. One stalled socket takes down
 *  every agent on the machine.
 *
 *  Deliberately NOT applied to the wake-stream (an intentionally long-lived SSE
 *  connection, which has its own idle/backoff handling) or the npm version check. */
const HTTP_TIMEOUT_MS = Math.max(1_000, Number(process.env.CUMORA_HTTP_TIMEOUT_MS ?? 20_000))

async function api<T>(serverUrl: string, path: string, init: RequestInit): Promise<T> {
  const res = await fetch(`${serverUrl}${path}`, {
    ...init,
    headers: { 'Content-Type': 'application/json', ...(init.headers ?? {}) },
    signal: init.signal ?? AbortSignal.timeout(HTTP_TIMEOUT_MS),
  })
  if (!res.ok) {
    const body = await res.text().catch(() => '')
    throw new Error(`${init.method ?? 'GET'} ${path} → HTTP ${res.status} ${body.slice(0, 200)}`)
  }
  return res.json() as Promise<T>
}

/** Fire-and-forget runtime call (status / runs). Never throws — observability
 *  must never break the agent loop. The timeout is what makes that promise hold
 *  for a server that stops answering rather than refusing (see HTTP_TIMEOUT_MS):
 *  an abort throws, so it lands in the catch and the turn proceeds. */
async function runtimeBest(
  serverUrl: string, path: string, token: string, body: unknown,
): Promise<unknown> {
  try {
    const res = await fetch(`${serverUrl}/runtime${path}`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
      body: JSON.stringify(body),
      signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
    })
    return res.ok ? await res.json().catch(() => null) : null
  } catch { return null }
}

async function runtimeGet<T>(
  serverUrl: string, path: string, token: string,
): Promise<T | null> {
  try {
    const res = await fetch(`${serverUrl}/runtime${path}`, {
      method: 'GET',
      headers: { Authorization: `Bearer ${token}` },
      signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
    })
    return res.ok ? await res.json().catch(() => null) as T | null : null
  } catch { return null }
}

async function failureConversationIds(serverUrl: string, token: string, conversationId: string | null): Promise<string[]> {
  if (conversationId) return [conversationId]
  // A diagnostic lookup must not advance the agent's inbox freshness baseline.
  const inbox = await runtimeGet<RuntimeInboxResponse>(serverUrl, '/inbox?probe=1', token)
  const ids = new Set<string>()
  for (const row of inbox?.rows ?? []) {
    if (typeof row.conversation_id === 'string' && row.conversation_id) ids.add(row.conversation_id)
    if (ids.size >= 5) break
  }
  return [...ids]
}

/** Should this 20s fallback tick actually drain the inbox?
 *
 *  Yes when the wake-stream is not provably alive: never connected, or silent
 *  (no event, no `: ping`) for WAKE_STREAM_STALE_MS. Otherwise the stream is
 *  trusted to deliver wakes and the drain runs only as a slow double-check,
 *  every INBOX_POLL_STREAM_HEALTHY_MS since the last drain. `streamLastSeenAt`
 *  is null while disconnected. Exported for tests — pure. */
export function fallbackPollDue(input: {
  now: number
  streamLastSeenAt: number | null
  lastInboxDrainAt: number
  staleMs?: number
  healthyIntervalMs?: number
}): boolean {
  const staleMs = input.staleMs ?? WAKE_STREAM_STALE_MS
  const healthyIntervalMs = input.healthyIntervalMs ?? INBOX_POLL_STREAM_HEALTHY_MS
  const streamAlive = input.streamLastSeenAt !== null && input.now - input.streamLastSeenAt < staleMs
  if (!streamAlive) return true
  return input.now - input.lastInboxDrainAt >= healthyIntervalMs
}

/** Which conversation should show "<agent> is typing…" for this turn.
 *
 *  The wake's own conversation when it had one. Otherwise derive it from what is
 *  unread, because a wake frequently carries none: a poll-driven turn never does
 *  (only an SSE wake sets it, and polling is the only path left when the
 *  wake-stream is down), and a wake that lands mid-turn is coalesced through
 *  scheduleWake's busy branch, which re-kicks without a conversation.
 *
 *  `seen` is keyed by conversation_id, so the daemon already knows where the work
 *  came from. With exactly one unread conversation that's unambiguous. With
 *  several, stay silent rather than light up an arbitrary room — a wrong
 *  indicator is worse than none, and the reply itself still lands correctly.
 *
 *  Exported for tests: this decides whether a working agent looks alive or dead,
 *  and the "no indicator at all" case is the one users read as a hang. */
export function typingConversation(
  wakeConvo: string | null,
  seen: Map<string, string>,
): string | null {
  if (wakeConvo) return wakeConvo
  return seen.size === 1 ? [...seen.keys()][0] : null
}

function hashText(text: string): string {
  return createHash('sha1').update(text).digest('hex').slice(0, 12)
}

function conciseError(text: string): string {
  return text
    .replace(/\x1B\[[0-?]*[ -/]*[@-~]/g, '')
    .replace(/\r/g, '')
    .trim()
    .slice(0, MAX_VISIBLE_ERROR_CHARS)
}

// A session that has grown past the model's context window. The daemon drops the
// session on this error so the NEXT wake starts fresh — recovery is automatic.
const CONTEXT_OVERFLOW_RE = /context window|context length|context_length_exceeded|maximum context|reached its context|prompt is too long|input is too long|too many tokens/i

// A POISONED transcript: a string sliced mid-emoji left a lone UTF-16 surrogate,
// and the Anthropic API's strict JSON parser rejected the request body. Once it's
// in the persistent transcript every later turn re-sends it → wedged forever. Only
// dropping the session clears it (same recovery shape as a context overflow). We
// also scrub outgoing text (engine.ts stripLoneSurrogates) so we stop creating it.
const POISONED_BODY_RE = /no (?:low|high) surrogate|unpaired surrogate|lone surrogate|surrogate in string|request body is not valid json/i

// A STALE resume target: we passed `--resume <id>` and the engine says it has no
// such session. Dropping the id is the right recovery — the next wake starts a
// fresh session instead of re-failing against a target that no longer exists.
//
// Every branch pairs the noun with FAILURE wording. A bare mention of a session
// or conversation proves nothing: the engine's own event stream is full of them
// (see `engineDiagnosticProse`), so matching the noun alone turned every
// mid-turn engine death into a "stale resume target" and threw away the session
// id that exists to recover the interrupted turn.
const STALE_RESUME_RE = new RegExp([
  // "No conversation found with session ID: …", "no such session",
  // "No previous sessions found for this project" (gemini, when the whole
  // chats dir is gone). The trailing `s?` is load-bearing: an engine that
  // reports the miss in the PLURAL is saying the resume target is gone just as
  // plainly as the singular, and without it the daemon kept the dead id and
  // re-sent it every wake — a permanently wedged agent, not a degraded one.
  String.raw`\bno (?:such )?(?:\w+ )?(?:conversation|session|thread)s?\b`,
  // "Session not found", "conversation no longer exists", "thread has expired"
  String.raw`\b(?:conversation|session|thread)s?(?: id)?\b[^\n]{0,24}?\b(?:not found|no longer exists?|do(?:es)? not exist|doesn't exist|has expired|is expired|is invalid|is unknown)\b`,
  // "Invalid session id", "unknown conversation", "expired thread"
  String.raw`\b(?:invalid|unknown|expired|stale|malformed) (?:\w+ )?(?:conversation|session|thread)s?\b`,
  // "could not resume", "unable to resume this conversation", "failed to resume"
  String.raw`\b(?:could ?n(?:o|')?t|cannot|can't|unable to|failed to)\b[^\n]{0,24}?\bresume\b`,
  // codex app-server's own wording
  String.raw`\bthread/resume failed\b`,
].join('|'), 'i')

/** The human-readable part of an engine failure blob.
 *
 *  `failurePreview` (engine.ts) appends the tail of the engine's STDOUT to the
 *  error text, and on the Claude path that stdout is stream-json: EVERY event
 *  line carries a `"session_id"` field. Those lines are machine structure, not
 *  diagnosis, so pattern-matching them as prose is what produced the false
 *  "stale resume target" verdict on any mid-turn death. Keep an event line's
 *  error text (that IS diagnosis) and drop everything else about it. */
export function engineDiagnosticProse(err: string): string {
  const out: string[] = []
  for (const line of err.split('\n')) {
    const trimmed = line.trim()
    if (!trimmed.startsWith('{')) { out.push(line); continue }
    let ev: { is_error?: unknown; result?: unknown; error?: unknown }
    try { ev = JSON.parse(trimmed) } catch { continue }
    // `result` is prose only on a FAILED turn; on a successful one it's the
    // agent's own answer, which must never be read as an engine diagnosis.
    if (ev.is_error === true && typeof ev.result === 'string') out.push(ev.result)
    if (typeof ev.error === 'string') out.push(ev.error)
    else if (ev.error && typeof ev.error === 'object') {
      const m = (ev.error as { message?: unknown }).message
      if (typeof m === 'string') out.push(m)
    }
  }
  return out.join('\n')
}

/** True when an engine error really says the `--resume` target is gone. */
export function isStaleResumeError(err: string): boolean {
  return STALE_RESUME_RE.test(engineDiagnosticProse(err))
}

export function authFailureHint(engine: EngineId, detail: string): string {
  if (classifyEngineFailure(engineDiagnosticProse(detail)) === 'startup') {
    return 'The local engine could not start. Check the executable path and sandbox configuration on that computer, then wake the agent again.'
  }
  if (CONTEXT_OVERFLOW_RE.test(detail)) {
    return 'The agent filled up its context window. Its session has been reset automatically — just wake the agent again and it will start fresh.'
  }
  if (POISONED_BODY_RE.test(detail)) {
    return 'A malformed character (a split emoji) had poisoned the agent\'s session. It has been reset automatically — just wake the agent again.'
  }
  if (classifyEngineFailure(detail) !== 'authentication' && !/(auth|login|token|quota|credit|billing|subscription|rate limit|usage limit|api key)/i.test(detail)) {
    return 'Check the daemon terminal for details, then wake the agent again.'
  }
  if (engine === 'claude') {
    return 'Open Claude Code on that computer and sign in, refresh quota, or add credits, then wake the agent again.'
  }
  if (engine === 'codex') {
    return `Run \`${CODEX_LOGIN_COMMAND}\` on that computer to sign in to Cumora's isolated Codex runtime (or check the account quota), then wake the agent again.`
  }
  if (engine === 'grok') {
    return 'Open Grok Build on that computer and run `grok login`, or set XAI_API_KEY, then wake the agent again.'
  }
  if (engine === 'cursor') {
    return 'Open a terminal on that computer and run `cursor-agent login` (or fix its quota / API key), then wake the agent again.'
  }
  if (engine === 'opencode') {
    return 'Open a terminal on that computer and run `opencode providers login` (or fix the selected provider/model quota), then wake the agent again.'
  }
  if (engine === 'pi') {
    return 'Open pi on that computer and run `/login` for its provider (or fix the API key / quota), then wake the agent again.'
  }
  if (engine === 'gemini') {
    return 'Open Gemini CLI on that computer and run `gemini` to refresh its login, API key, or quota, then wake the agent again.'
  }
  if (engine === 'qwen') {
    return 'Open Qwen Code on that computer and run `qwen` to refresh its login, API key, or quota, then wake the agent again.'
  }
  if (engine === 'antigravity') {
    return 'Open Antigravity on that computer and run `agy` to refresh its login, model access, or quota, then wake the agent again.'
  }
  if (engine === 'zcode') {
    return 'Open ZCode on that computer and run `zcode` to refresh its login, model access, or quota, then wake the agent again.'
  }
  if (engine === 'maka') {
    return 'Open Maka on that computer and run `maka` to refresh its login, model access, or quota, then wake the agent again.'
  }
  if (engine === 'omp') {
    return 'Open a terminal on that computer and run `omp` (or `omp login`) to refresh its provider credentials, then wake the agent again.'
  }
  return 'Check the daemon terminal for details, then wake the agent again.'
}

function missingEngineMessage(): string {
  return [
    'no supported local agent engine found on PATH',
    '',
    'Secure default — install and sign in to at least one of:',
    '  - Claude Code: install the `claude` CLI, then run `claude` once to sign in',
    `  - Codex: install the \`codex\` CLI, then run \`${CODEX_LOGIN_COMMAND}\``,
    '',
    'Unsandboxed compatibility engines (explicit opt-in required):',
    '  - Grok Build: install the `grok` CLI, then run `grok login` once',
    '  - Cursor Agent: install Cursor (the `cursor-agent` CLI ships with it), then run `cursor-agent login`',
    '  - OpenCode: install the `opencode` CLI, then run `opencode providers login` once',
    '  - pi: `npm install -g --ignore-scripts @earendil-works/pi-coding-agent`, then run `pi` once and `/login` a provider',
    '  - Gemini CLI: install the `gemini` CLI, then run `gemini` once to sign in',
    '  - Qwen Code: install the `qwen` CLI, then run `qwen` once to sign in',
    '  - Antigravity: install the `agy` CLI, then run `agy` once to sign in',
    '  - ZCode: install the `zcode` CLI, then run `zcode` once to sign in',
    '    (the daemon drives it through the npm-published `zcode-acp-server` bridge via npx;',
    '     CUMORA_ZCODE_ACP_BIN pins a specific bridge copy when needed)',
    '  - Maka: install the `maka` CLI, then run `maka` once to sign in',
    '  - omp: install the `omp` CLI, then run `omp` once to sign in to a provider',
    '',
    'After that, rerun:',
    '  npx cumora@latest agent computer --pair <code>',
  ].join('\n')
}

function unsandboxedCompatibilityHint(platform: NodeJS.Platform): string {
  return platform === 'win32'
    ? [
        '  PowerShell:',
        "    $env:CUMORA_BYOA_ALLOW_UNSANDBOXED = '1'",
        '    # Then rerun your original Cumora command in this PowerShell session.',
      ].join('\n')
    : '  CUMORA_BYOA_ALLOW_UNSANDBOXED=1 npx cumora@latest agent computer ...'
}

function sandboxedEngineMessage(installed: readonly EngineId[], platform: NodeJS.Platform = process.platform): string {
  return [
    `installed engines are disabled by Cumora's secure BYOA default: ${installed.join(', ')}`,
    '',
    platform === 'win32'
      ? 'Use Codex on native Windows, or run Claude Code inside WSL2.'
      : 'Install and sign in to Claude Code or Codex.',
    'Grok, Cursor, OpenCode, pi, Gemini, Qwen, Antigravity, and native-Windows Claude currently lack',
    'a Cumora-verified fail-closed host boundary.',
    '',
    'Compatibility only (grants the model your host files, environment, and network):',
    unsandboxedCompatibilityHint(platform),
  ].join('\n')
}

function incapableEngineMessage(blocked: ReadonlyArray<{ id: EngineId; reason: string }>, platform: NodeJS.Platform = process.platform): string {
  return [
    'installed secure engines cannot enforce Cumora\'s BYOA boundary:',
    ...blocked.map(({ id, reason }) => `  - ${id}: ${reason}`),
    '',
    'Update the CLI and install any named sandbox dependencies, then retry.',
    'Compatibility only (disables this capability gate and host boundary):',
    unsandboxedCompatibilityHint(platform),
  ].join('\n')
}

function helpText(): string {
  return [
    'cumora agent computer — run your Cumora agents on THIS machine (BYOA)',
    '',
    'The daemon talks to a Cumora server over HTTP and drives a local agent',
    'engine. Claude Code and Codex are sandboxed by default. Grok Build, Cursor',
    'Agent, OpenCode, pi, Gemini, Qwen, Antigravity, and native-Windows Claude require the explicit',
    'high-risk CUMORA_BYOA_ALLOW_UNSANDBOXED=1 compatibility switch.',
    'Pair once, then the daemon runs in the background.',
    '',
    'Usage:',
    '  npx cumora@latest agent computer --pair <code> [--server <url>] [--engine <id>]',
    '  npx cumora@latest agent computer [--server <url>]',
    '',
    'Setup:',
    '  --pair <code>        pair this machine to your account (code from',
    '                       Cumora -> You -> Computers -> Add a computer)',
    '  --server <url>       Cumora server URL (default: ' + DEFAULT_SERVER + ')',
    '  --engine <id>        force an engine: ' + ENGINE_IDS.join(' | ') + '',
    '  --codex-login        sign in to Cumora\'s isolated Codex runtime',
    '  --migrate-codex-sessions  copy existing Cumora Codex threads into that runtime',
    '',
    'Background service:',
    '  --install-service    install + start the background supervisor',
    '  --uninstall-service  remove the background supervisor',
    '  --restart            restart the background service',
    '  --stop               stop the background service',
    '  --status             show pairing + service status',
    '  --logs               tail the daemon logs',
    '',
    'Diagnostics:',
    '  --doctor             check engines, PATH, login/quota',
    '  --provider <id>      with --doctor: check one local Claude provider profile',
    '  --version, -v        print the daemon version',
    '  --help, -h           show this help',
    '',
    'With no flags it starts the daemon in the foreground (must be paired first).',
  ].join('\n')
}

/** Snapshot rows for refused engines, each carrying the reason it was refused.
 *  Reported alongside the runnable ones so the card can explain an absence;
 *  they never enter the `engines` list, which is what picks an adapter. */
async function blockedSnapshotRows(
  blocked: RunnableEngineEvaluation['blocked'],
): Promise<DetectedEngineSnapshot[]> {
  const rows = await snapshotDetectedEngines(blocked.map(({ id }) => id))
  return rows.map((row) => ({
    ...row,
    blockedReason: blocked.find(({ id }) => id === row.id)?.reason,
  }))
}

/** Diagnose an explicit choice without confusing installation with permission
 * to run. Both inventories come from the same scan. */
export function validatePairingEngine(
  preferredEngine: string,
  installed: readonly EngineId[],
  evaluated: RunnableEngineEvaluation,
  platform: NodeJS.Platform = process.platform,
): void {
  if (!ENGINE_IDS.includes(preferredEngine as EngineId)) {
    throw new Error(`--engine must be one of: ${ENGINE_IDS.join(', ')} (got "${preferredEngine}")`)
  }
  const id = preferredEngine as EngineId
  if (!installed.includes(id)) {
    throw new Error(`--engine ${id} chosen, but ${id} was not found on PATH. Installed: ${installed.join(', ') || 'none'}.`)
  }
  if (!evaluated.runnable.includes(id)) {
    const blocked = evaluated.blocked.find((entry) => entry.id === id)
    throw new Error([
      `--engine ${id} chosen: ${id} is installed but cannot run under Cumora's secure BYOA default.`,
      blocked ? incapableEngineMessage([blocked], platform) : sandboxedEngineMessage([id], platform),
    ].join('\n\n'))
  }
}

/** The engines this machine can run, plus the ones it cannot and why.
 *
 *  The refusals used to stop at the console.warn below. Pairing then reported
 *  only the runnable list, so a fresh computer's card said nothing about the
 *  engine that was skipped until the first PATH rescan minutes later — which is
 *  precisely the window in which someone asks why their Claude Code is not
 *  listed. */
async function requireLocalEngine(preferredEngine?: string): Promise<RunnableEngineEvaluation> {
  const detected = await detectEnginesWithStatus()
  if (!detected.reliable) {
    throw new Error('could not scan PATH (`which` / `where` failed). Fix that, then retry pairing.')
  }
  const evaluated = await evaluateRunnableEngines(detected.engines)
  // Check the requested engine against the raw PATH inventory first. The
  // runnable list excludes installed engines refused by the security policy.
  if (preferredEngine) validatePairingEngine(preferredEngine, detected.engines, evaluated)
  if (detected.engines.length === 0) throw new Error(missingEngineMessage())
  if (evaluated.runnable.length === 0) {
    if (evaluated.blocked.length > 0) throw new Error(incapableEngineMessage(evaluated.blocked))
    throw new Error(sandboxedEngineMessage(detected.engines))
  }
  if (evaluated.blocked.length > 0) {
    console.warn(`[computer] secure engine(s) disabled: ${evaluated.blocked.map(({ id, reason }) => `${id} (${reason})`).join('; ')}`)
  }
  return evaluated
}

/** Resolve the engine a daemon can actually run from its LIVE PATH inventory. */
export function resolveAvailableEngine(
  requested: EngineId | null | undefined,
  available: readonly EngineId[],
): EngineId | null {
  return requested && available.includes(requested) ? requested : (available[0] ?? null)
}

export interface EngineInventory {
  current: EngineId[]
}

/** Hysteresis for trustworthy scans. A previously runnable engine survives a
 * transient capability probe and two consecutive PATH misses. Confirmed
 * incompatibility removes it immediately because the security floor is not a
 * liveness signal and must never be debounced. */
export class EngineInventoryStabilizer {
  private readonly missingCounts = new Map<EngineId, number>()

  constructor(private readonly missingThreshold = 3) {}

  stabilize(
    previous: readonly EngineId[],
    installed: readonly EngineId[],
    evaluated: RunnableEngineEvaluation,
  ): EngineId[] {
    const installedSet = new Set(installed)
    const runnableSet = new Set(evaluated.runnable)
    const transientSet = new Set([
      ...evaluated.temporarilyUnverifiable ?? [],
      ...evaluated.blocked.filter((entry) => entry.state === 'temporarily-unverifiable').map((entry) => entry.id),
    ])
    const incompatibleSet = new Set(evaluated.blocked
      .filter((entry) => entry.state === 'confirmed-incompatible')
      .map((entry) => entry.id))
    const next: EngineId[] = []

    for (const id of previous) {
      if (incompatibleSet.has(id)) {
        this.missingCounts.delete(id)
        continue
      }
      if (installedSet.has(id)) {
        this.missingCounts.delete(id)
        if (runnableSet.has(id) || transientSet.has(id)) next.push(id)
        continue
      }
      const misses = (this.missingCounts.get(id) ?? 0) + 1
      this.missingCounts.set(id, misses)
      if (misses < this.missingThreshold) next.push(id)
    }

    for (const id of installed) {
      if (runnableSet.has(id)) {
        this.missingCounts.delete(id)
        if (!next.includes(id)) next.push(id)
      }
    }
    return next
  }
}

/** Replace the shared engine inventory after a trustworthy PATH scan. */
export function replaceEngineInventory(inventory: EngineInventory, next: readonly EngineId[]): boolean {
  const current = inventory.current
  const changed = next.length !== current.length || next.some((engine, i) => engine !== current[i])
  if (changed) inventory.current = [...next]
  return changed
}

/** A user-requested refresh must report even an unchanged snapshot so the
 * server can clear the pending request and the UI can observe completion. */
export function shouldReportEngineSnapshot(fingerprint: string, previous: string, force = false): boolean {
  return force || fingerprint !== previous
}

/**
 * Report the engine snapshot and return the fingerprint the daemon should
 * remember — which is the OLD one whenever the report did not land.
 *
 * The predicate above is `force || fingerprint !== previous`, so the remembered
 * fingerprint is a delivery watermark, not a "what did I last compute" note.
 * Advancing it before the POST resolves makes a failure indistinguishable from
 * a success: every later rescan re-derives the same fingerprint, skips the
 * report, and the machine's card stays frozen at whatever the server last saw.
 * An operator who installs the missing dependency an engine was blocked on
 * would watch the card keep saying it is missing until they either hit Rescan
 * (the only caller that passes `force`) or restart the daemon.
 *
 * Separate from the scan loop so this rule is testable without a daemon.
 */
export async function reportEngineSnapshot(
  fingerprint: string,
  previous: string,
  force: boolean,
  post: () => Promise<unknown>,
): Promise<string> {
  if (!shouldReportEngineSnapshot(fingerprint, previous, force)) return previous
  try {
    await post()
    return fingerprint
  } catch (err) {
    console.warn(
      '[computer] engine snapshot report failed; retrying on the next scan:',
      err instanceof Error ? err.message : err,
    )
    return previous
  }
}

// ─── config ─────────────────────────────────────────────────────────────

async function loadConfig(): Promise<DaemonConfig | null> {
  try { return JSON.parse(await readFile(CONFIG_PATH, 'utf8')) as DaemonConfig }
  catch { return null }
}

async function saveConfig(cfg: DaemonConfig): Promise<void> {
  await mkdir(CONFIG_DIR, { recursive: true })
  await writeFile(CONFIG_PATH, JSON.stringify(cfg, null, 2), 'utf8')
  await chmod(CONFIG_PATH, 0o600)
}

// ─── the `cumora` shim ──────────────────────────────────────────────────
//
// The engine must be able to use Cumora without also receiving a reusable JWT
// or arbitrary network access. The fixed MCP bridge calls a tiny `cumora`
// executable in a daemon-owned tools directory; that client writes argv into a
// per-agent rendezvous directory outside the model home and waits for the daemon
// to answer. The daemon alone owns the runtime token and performs the HTTP call.
//
// Files rather than a TCP/Unix socket are deliberate: every supported engine
// can keep tool subprocesses network-denied, and the protocol works on macOS,
// Linux, native Windows, and WSL without punching a hole in that boundary.
//
// Exported for tests: the output-truncation regression below is only observable
// by running the real shim text against a real pipe.
export const CUMORA_SHIM = `#!/usr/bin/env node
'use strict'
;(async () => {
  var ipc = process.env.CUMORA_AGENT_IPC_DIR
  if (!ipc) { console.error('cumora: runtime IPC not set'); process.exit(70) }
  var argv = process.argv.slice(2)
  // Shell-safe body input. A reply written inline (cumora reply id "..text..")
  // is mangled by bash BEFORE this shim runs: backticks and $(...) get run as
  // commands and collapse to empty, quotes get eaten. So --file <path> /
  // --stdin let the body come from a file (written by the editor, no shell) or
  // a pipe; we read it LOCALLY and pass it as one argument that travels as
  // JSON and is never re-parsed by a shell, so code/quotes/$ survive verbatim.
  //
  // It goes LAST, behind a POSIX \`--\`, so the server takes it literally. Spliced
  // in place it was still read as argv: a body starting with \`---\` (markdown
  // rule, front-matter fence, diff header) parsed as a FLAG and the message was
  // silently dropped, and escapes inside it were expanded a second time.
  var fs = require('fs')
  var path = require('path')
  var crypto = require('crypto')
  var body = null
  var fi = argv.indexOf('--file')
  if (fi >= 0 && argv[fi + 1] !== undefined) {
    try { body = fs.readFileSync(argv[fi + 1], 'utf8') }
    catch (e) { console.error('cumora: cannot read --file ' + argv[fi + 1]); process.exit(70) }
    argv.splice(fi, 2)
  }
  var si = argv.indexOf('--stdin')
  if (si >= 0) {
    argv.splice(si, 1)
    if (body === null) { try { body = fs.readFileSync(0, 'utf8') } catch (e) { body = '' } }
  }
  if (body !== null) argv.push('--', body)
  var id = crypto.randomUUID()
  var requests = path.join(ipc, 'requests')
  var responses = path.join(ipc, 'responses')
  var request = path.join(requests, id + '.json')
  var staged = request + '.' + process.pid + '.tmp'
  fs.writeFileSync(staged, JSON.stringify({ argv: argv }), { mode: 0o600 })
  fs.renameSync(staged, request)

  var response = path.join(responses, id + '.json')
  var deadline = Date.now() + 5 * 60 * 1000
  while (!fs.existsSync(response)) {
    if (Date.now() >= deadline) {
      try { fs.unlinkSync(request) } catch (e) {}
      console.error('cumora: daemon IPC timed out')
      process.exit(70)
    }
    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25)
  }
  var data
  try { data = JSON.parse(fs.readFileSync(response, 'utf8')) }
  finally { try { fs.unlinkSync(response) } catch (e) {} }
  if (data && typeof data.error === 'string' && data.error) console.error('cumora: ' + data.error)
  const code = typeof data.exitCode === 'number' ? data.exitCode : 0
  // Exit from the write CALLBACK, not the next statement: stdout on a PIPE is
  // ASYNC, so process.exit() kills us with the tail still buffered. The engine
  // always runs this shim with stdout piped, so a big result (cumora messages
  // --tail 30, cumora inbox --json) silently arrived truncated at the pipe
  // buffer — 64KB, or 8KB on the socketpair a stdio:'pipe' parent hands us —
  // with exit 0 and empty stderr, so nothing signalled the loss and --json
  // output simply failed to parse. Exiting IN the callback also keeps a reader
  // that closed early (| head) an exit-0 like before, instead of the unhandled
  // EPIPE crash a bare process.exitCode would produce.
  if (typeof data.text === 'string' && data.text) process.stdout.write(data.text + '\\n', () => process.exit(code))
  else process.exit(code)
})().catch((e) => { console.error('cumora:', (e && e.message) || e); process.exit(70) })
`

/** The fixed MCP bridge keeps Cumora actions outside the model's command
 * sandbox without exposing daemon credentials. Local-body flags are rejected
 * because MCP is not sandboxed; callers pass body text as an argv item instead. */
export const CUMORA_MCP_SHIM = `#!/usr/bin/env node
'use strict'
var cp = require('child_process')
var path = require('path')
var readline = require('readline')
var shim = path.join(__dirname, 'cumora')
var childEnv = {}
;['PATH', 'HOME', 'USER', 'LOGNAME', 'SHELL', 'TMPDIR', 'TMP', 'TEMP', 'LANG', 'LANGUAGE', 'TERM', 'NO_COLOR', 'SYSTEMROOT', 'COMSPEC', 'PATHEXT', 'WINDIR', 'CUMORA_AGENT_IPC_DIR', 'CUMORA_AGENT_ID'].forEach(function (name) {
  if (process.env[name] !== undefined) childEnv[name] = process.env[name]
})
function send(id, result, error) {
  var msg = { jsonrpc: '2.0', id: id }
  if (error) msg.error = { code: -32602, message: error }
  else msg.result = result
  process.stdout.write(JSON.stringify(msg) + '\\n')
}
function toolError(text) {
  return { content: [{ type: 'text', text: text }], isError: true }
}
function handle(msg) {
  if (!msg || msg.jsonrpc !== '2.0') return
  if (msg.method === 'initialize' && msg.id !== undefined) {
    send(msg.id, {
      protocolVersion: (msg.params && msg.params.protocolVersion) || '2025-06-18',
      capabilities: { tools: {} },
      serverInfo: { name: 'cumora', version: '1.0.0' },
    })
    return
  }
  if (msg.method === 'tools/list' && msg.id !== undefined) {
    send(msg.id, { tools: [{
      name: 'cli',
      description: 'Act in Cumora. Pass command-line words as argv; put message bodies directly in argv and never use local file paths.',
      inputSchema: {
        type: 'object',
        properties: { argv: { type: 'array', items: { type: 'string' }, minItems: 1, maxItems: 2000 } },
        required: ['argv'],
        additionalProperties: false,
      },
    }] })
    return
  }
  if (msg.method === 'tools/call' && msg.id !== undefined) {
    var p = msg.params || {}
    var argv = p.arguments && p.arguments.argv
    if (p.name !== 'cli' || !Array.isArray(argv) || !argv.length || argv.length > 2000 || argv.some(function (v) { return typeof v !== 'string' })) {
      send(msg.id, toolError('invalid Cumora argv'))
      return
    }
    if (argv.some(function (v) { return v === '--file' || v === '--stdin' })) {
      send(msg.id, toolError('local file/stdin flags are unavailable; pass body text directly in argv'))
      return
    }
    cp.execFile(process.execPath, [shim].concat(argv), {
      env: childEnv,
      maxBuffer: 32 * 1024 * 1024,
      windowsHide: true,
    }, function (err, stdout, stderr) {
      var text = String(stdout || '')
      if (stderr) text += (text ? '\\n' : '') + String(stderr)
      var failed = !!err
      send(msg.id, { content: [{ type: 'text', text: text.trimEnd() }], isError: failed })
    })
    return
  }
  if (msg.method === 'ping' && msg.id !== undefined) send(msg.id, {})
}
var rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity })
rl.on('line', function (line) {
  try { handle(JSON.parse(line)) }
  catch (e) { process.stderr.write('cumora-mcp: invalid JSON\\n') }
})
`

const CLI_IPC_FALLBACK_POLL_MS = 1_000
const CLI_IPC_MAX_REQUEST_BYTES = 32 * 1024 * 1024
const CLI_IPC_MAX_ARGS = 2_000

export interface RuntimeCliBrokerResult {
  text?: string
  exitCode: number
  error?: string
}

/** File-rendezvous broker used by one AgentRunner.
 *
 * Request names come from readdir(), not request content, and are claimed by an
 * atomic rename before parsing. A malformed/oversized request gets a bounded
 * error response; it can never turn into a path chosen by the model. */
export class RuntimeCliBroker {
  private timer: ReturnType<typeof setInterval> | null = null
  private watcher: FSWatcher | null = null
  private pollPromise: Promise<void> | null = null
  private rerunRequested = false
  private stopped = false
  private abortController = new AbortController()
  private readonly requestsDir: string
  private readonly responsesDir: string

  constructor(
    ipcDir: string,
    private readonly processingDir: string,
    private readonly invoke: (argv: string[], signal: AbortSignal) => Promise<RuntimeCliBrokerResult>,
  ) {
    this.requestsDir = join(ipcDir, 'requests')
    this.responsesDir = join(ipcDir, 'responses')
  }

  async start(): Promise<void> {
    // A stopped broker may be started again by a supervisor. Never clean or
    // reuse its namespace while the previous drain is still unwinding.
    if (this.pollPromise) await this.pollPromise.catch(() => {})
    this.pollPromise = null
    this.rerunRequested = false
    await mkdir(this.requestsDir, { recursive: true })
    await mkdir(this.responsesDir, { recursive: true })
    await mkdir(this.processingDir, { recursive: true })
    // Requests/responses cannot survive their daemon process: the bearer token
    // and server result they belonged to are gone. Remove only this dedicated
    // IPC namespace, never agent work files.
    await this.clearDir(this.requestsDir)
    await this.clearDir(this.responsesDir)
    await this.clearDir(this.processingDir)
    this.stopped = false
    this.abortController = new AbortController()
    // Directory notifications keep the common path event-driven even when one
    // computer hosts many agents. A slow fallback poll covers dropped watcher
    // events and filesystems where fs.watch is unavailable or unreliable.
    try {
      this.watcher = watch(this.requestsDir, { persistent: false }, () => {
        void this.poll().catch((err) => this.logPollFailure(err))
      })
      this.watcher.on('error', () => {
        this.watcher?.close()
        this.watcher = null
      })
    } catch { this.watcher = null }
    this.timer = setInterval(() => {
      void this.poll().catch((err) => this.logPollFailure(err))
    }, CLI_IPC_FALLBACK_POLL_MS)
    this.timer.unref?.()
  }

  stop(): void {
    this.stopped = true
    this.rerunRequested = false
    this.abortController.abort()
    if (this.timer) clearInterval(this.timer)
    this.timer = null
    this.watcher?.close()
    this.watcher = null
  }

  /** Immediate poll for deterministic tests; the normal runner uses the timer. */
  poll(): Promise<void> {
    if (this.stopped) return Promise.resolve()
    // Coalesce an arbitrary watcher/timer storm into one pending rerun. Every
    // caller shares the same drain promise, so an explicit await still covers a
    // request that landed after the active pass took its readdir snapshot.
    this.rerunRequested = true
    if (!this.pollPromise) {
      const drain = this.drainPolls()
      this.pollPromise = drain
      // Use both handlers instead of .finally(): ignoring the Promise returned
      // by finally() would itself create an unhandled rejection on failure.
      void drain.then(
        () => { if (this.pollPromise === drain) this.pollPromise = null },
        () => { if (this.pollPromise === drain) this.pollPromise = null },
      )
    }
    return this.pollPromise
  }

  private async drainPolls(): Promise<void> {
    while (!this.stopped && this.rerunRequested) {
      this.rerunRequested = false
      const names = await readdir(this.requestsDir).catch(() => [] as string[])
      for (const name of names) {
        if (this.stopped || this.abortController.signal.aborted) break
        if (!/^[0-9a-f-]{36}\.json$/i.test(name)) continue
        try { await this.handle(name) }
        catch (err) { this.logPollFailure(err, name) }
      }
    }
  }

  private logPollFailure(err: unknown, name?: string): void {
    console.error(
      `[runtime] CLI IPC broker${name ? ` request ${name}` : ''} failed`,
      err instanceof Error ? err.message : String(err),
    )
  }

  private async handle(name: string): Promise<void> {
    const signal = this.abortController.signal
    if (signal.aborted) return
    const source = join(this.requestsDir, name)
    // Production puts processingDir outside the model-writable Agent home.
    // Once rename succeeds, the sandbox cannot replace the claimed inode during
    // the lstat/open gap (including on Windows, where O_NOFOLLOW is unavailable).
    const claimed = join(this.processingDir, `${name}.${process.pid}.${randomUUID().slice(0, 8)}.processing`)
    try { await rename(source, claimed) } catch { return }
    const response = join(this.responsesDir, name)
    let stagedResponse: string | null = null
    let result: RuntimeCliBrokerResult
    try {
      // Never follow a model-created request symlink with the daemon's broader
      // privileges. O_NOFOLLOW is defense in depth on POSIX; the private claim
      // directory closes the check/open race on every supported platform.
      const before = await lstat(claimed)
      if (!before.isFile() || before.isSymbolicLink()) {
        throw new Error('runtime IPC request is not a regular file')
      }
      const noFollow = typeof FS_CONSTANTS.O_NOFOLLOW === 'number' ? FS_CONSTANTS.O_NOFOLLOW : 0
      const file = await open(claimed, FS_CONSTANTS.O_RDONLY | noFollow)
      let raw: string
      try {
        const info = await file.stat()
        if (!info.isFile() || info.size > CLI_IPC_MAX_REQUEST_BYTES) {
          throw new Error('runtime IPC request is too large')
        }
        raw = await file.readFile('utf8')
      }
      finally { await file.close() }
      const parsed = JSON.parse(raw) as { argv?: unknown }
      if (!Array.isArray(parsed.argv)
          || parsed.argv.length > CLI_IPC_MAX_ARGS
          || parsed.argv.some((arg) => typeof arg !== 'string')) {
        throw new Error('runtime IPC argv is invalid')
      }
      if (signal.aborted) throw new Error('runtime IPC request cancelled')
      result = await this.invoke(parsed.argv as string[], signal)
    } catch (err) {
      if (signal.aborted) {
        await rm(claimed, { force: true }).catch(() => {})
        return
      }
      result = { exitCode: 70, error: err instanceof Error ? err.message : String(err) }
    }
    try {
      if (signal.aborted) return
      // Stage in the daemon-private directory. The model can write response
      // contents only after the final atomic rename, never redirect a privileged
      // write by pre-creating a symlink at a guessed temporary name.
      stagedResponse = join(this.processingDir, `${name}.${process.pid}.${randomUUID().slice(0, 8)}.response.tmp`)
      await writeFile(stagedResponse, JSON.stringify(result), { mode: 0o600 })
      if (signal.aborted) return
      await rename(stagedResponse, response)
      stagedResponse = null
    } finally {
      if (stagedResponse) await rm(stagedResponse, { force: true }).catch(() => {})
      await rm(claimed, { force: true }).catch(() => {})
    }
  }

  private async clearDir(dir: string): Promise<void> {
    const names = await readdir(dir).catch(() => [] as string[])
    // These directories contain protocol files only. Never recurse into a
    // model-created directory/junction while cleaning stale traffic.
    await Promise.all(names.map((name) => rm(join(dir, name), { force: true }).catch(() => {})))
  }
}

/** PowerShell only resolves files on PATH through PATHEXT, so the extensionless
 *  POSIX shim needs a .cmd launcher on Windows. Keep the Node program itself in
 *  one file so both launchers exercise the exact same argument/HTTP path. */
export const CUMORA_WINDOWS_SHIM = '@echo off\r\nnode "%~dp0cumora" %*\r\n'

export function prependAgentBinToPath(binDir: string, currentPath = process.env.PATH ?? ''): string {
  return currentPath ? `${binDir}${delimiter}${currentPath}` : binDir
}

/** Secure adapters must resolve their own binary from the operator's original
 * PATH. The agent home is model-writable, so prepending <home>/bin would let a
 * model plant `claude`/`codex` and escape before the next sandbox starts. */
export function engineProcessPath(
  binDir: string,
  currentPath = process.env.PATH ?? '',
  unsandboxed = allowUnsandboxedByoa(),
): string {
  if (unsandboxed) return prependAgentBinToPath(binDir, currentPath)
  const writableHome = resolve(dirname(binDir))
  return currentPath
    .split(delimiter)
    // Empty and relative PATH entries resolve against the engine cwd — its
    // model-writable home — and are therefore engine-shadow paths too.
    .filter((entry) => {
      if (!entry || !isAbsolute(entry)) return false
      const fromHome = relative(writableHome, resolve(entry))
      return isAbsolute(fromHome) || fromHome === '..' || fromHome.startsWith(`..${sep}`)
    })
    .join(delimiter)
}

async function writeShimFile(path: string, data: string, mode: number): Promise<void> {
  const staged = join(dirname(path), `.cumora-shim-${process.pid}-${randomUUID()}.tmp`)
  await writeFile(staged, data, { encoding: 'utf8', mode, flag: 'wx' })
  try {
    await chmod(staged, mode)
    try { await rename(staged, path) }
    catch (err) {
      if (process.platform !== 'win32'
          || !['EEXIST', 'EPERM'].includes((err as NodeJS.ErrnoException).code ?? '')) throw err
      await rm(path, { force: true })
      await rename(staged, path)
    }
  } finally {
    await rm(staged, { force: true }).catch(() => {})
  }
}

export async function writeShim(
  binDir: string,
  platform: NodeJS.Platform = process.platform,
): Promise<void> {
  try {
    const info = await lstat(binDir)
    if (!info.isDirectory() || info.isSymbolicLink()) {
      throw new Error(`secure BYOA refuses linked shim directory: ${binDir}`)
    }
  } catch (err) {
    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err
    await mkdir(binDir, { recursive: true })
    const created = await lstat(binDir)
    if (!created.isDirectory() || created.isSymbolicLink()) {
      throw new Error(`secure BYOA could not create a trusted shim directory: ${binDir}`)
    }
  }
  await writeShimFile(join(binDir, 'cumora'), CUMORA_SHIM, 0o755)
  await writeShimFile(join(binDir, 'cumora-mcp'), CUMORA_MCP_SHIM, 0o755)
  if (platform === 'win32') {
    await writeShimFile(join(binDir, 'cumora.cmd'), CUMORA_WINDOWS_SHIM, 0o600)
  }
}

// ─── pairing ────────────────────────────────────────────────────────────

/** A human-friendly machine name for the Computer. `os.hostname()` is
 *  unreliable on macOS — when the BSD HostName is unset (the default) it
 *  returns "localhost", not the machine's real name. So on macOS prefer the
 *  OS's friendly ComputerName ("MacBook Air"), then LocalHostName; elsewhere
 *  `os.hostname()` is fine. */
async function detectHostName(): Promise<string> {
  const base = hostname()
  if (base && base.toLowerCase() !== 'localhost') return base
  if (process.platform === 'darwin') {
    for (const key of ['ComputerName', 'LocalHostName']) {
      try {
        const { stdout } = await execFileP('scutil', ['--get', key])
        const name = stdout.trim()
        if (name) return name
      } catch { /* scutil missing / key unset — try the next */ }
    }
  }
  return base || 'My computer'
}

async function doPair(code: string, serverUrl: string, preferredEngine?: string): Promise<void> {
  const evaluated = await requireLocalEngine(preferredEngine)
  const runnable = evaluated.runnable
  // The chosen engine becomes this computer's DEFAULT — it's sent first in the
  // engines list, which the server stores as available_engines[0] and uses as
  // the engine for the starter team and any agent assigned here without an
  // explicit override. (No separate column needed: "first = default".)
  let engines = [...runnable]
  if (preferredEngine) {
    engines = [preferredEngine as EngineId, ...runnable.filter((e) => e !== preferredEngine)]
  }
  const blockedIds = evaluated.blocked.map(({ id }) => id)
  const snapshot = [
    ...await snapshotDetectedEngines(engines),
    ...await blockedSnapshotRows(evaluated.blocked),
  ]
  const paired = await api<{ computerId: string; deviceToken: string }>(
    serverUrl, '/api/computers/pair',
    { method: 'POST', body: JSON.stringify({
      code, hostName: await detectHostName(), engines, detected: snapshot,
      blocked: blockedIds, version: CURRENT_VERSION, supervised: SUPERVISED,
    }) },
  )
  await saveConfig({ serverUrl, computerId: paired.computerId, deviceToken: paired.deviceToken })
  console.log(`[computer] paired as ${paired.computerId} (default engine: ${engines[0] ?? 'none'}; available: ${engines.join(', ') || 'none'}) — starting…`)
}

// ─── per-agent runner ───────────────────────────────────────────────────

/** Buffered per-hop trajectory reporter. The engine sessions (ClaudeSession /
 *  CodexSession) fire `onHopUsage` for every assistant message / turn-completed
 *  event; this collects them and POSTs in batches so the universal llm_calls
 *  ledger sees BYOA trajectory at the same granularity it sees cloud, without
 *  paying a round-trip per hop.
 *
 *  Discipline:
 *    - Fire-and-forget. A network blip on the report MUST NEVER affect the
 *      engine turn that produced it.
 *    - Bounded queue (MAX_BUFFER) so a hard server outage can't blow memory on
 *      a long-running daemon — old hops are dropped first with a warn log.
 *    - Auto-flush on every WINDOW_MS tick AND when buffer hits FLUSH_AT.
 *    - flush() can be awaited at "natural pauses" (turn end) to push the tail
 *      promptly without waiting for the timer. */
type ByoaSource = `byoa-${EngineId}`

function byoaSourceOf(id: EngineId): ByoaSource {
  return `byoa-${id}`
}

interface PendingHop {
  source: ByoaSource
  purpose: 'agent-turn' | 'inbox-triage' | 'compaction' | 'completion-verify' | 'steer-summary' | 'agenda' | 'synthetic-wake-gate'
  runId: string | null
  conversationId: string | null
  model: string
  usage?: TokenUsage | null
  latencyMs: number
  status: 'ok' | 'rate_limited' | 'timeout' | 'failed'
  error?: string | null
  extras?: Record<string, unknown>
}

class HopReporter {
  private buf: PendingHop[] = []
  private timer: ReturnType<typeof setTimeout> | null = null
  private stopped = false
  private readonly WINDOW_MS = 250
  private readonly FLUSH_AT = 10
  private readonly MAX_BUFFER = 500
  constructor(
    private readonly serverUrl: string,
    private readonly getToken: () => Promise<string>,
  ) {}

  push(hop: PendingHop): void {
    if (this.stopped) return
    if (this.buf.length >= this.MAX_BUFFER) {
      // Drop the OLDEST entry — newer hops are more interesting + the bound
      // protects the process from a hung server. We log once per overflow
      // window so the log isn't a flood.
      const dropped = this.buf.shift()
      if (dropped) console.warn(`[hop-reporter] buffer overflow — dropped oldest hop (${dropped.purpose}, ${dropped.model})`)
    }
    this.buf.push(hop)
    if (this.buf.length >= this.FLUSH_AT) { void this.flush(); return }
    if (!this.timer) this.timer = setTimeout(() => { this.timer = null; void this.flush() }, this.WINDOW_MS)
  }

  /** Send everything queued right now. Idempotent + reentrant-safe — drains
   *  the snapshot, leaves new pushes for the next flush. Resolves after the
   *  HTTP attempt (or instantly if nothing to send). */
  async flush(): Promise<void> {
    if (this.timer) { clearTimeout(this.timer); this.timer = null }
    if (this.buf.length === 0) return
    // Snapshot + clear; new pushes during the await go to a fresh buffer.
    const batch = this.buf
    this.buf = []
    // Codex + Claude batches might intermix (the same reporter is used across
    // session lifetimes), so split by source — the server endpoint takes one
    // source per call (the row's `source` column is set from it).
    const byHourceSource = new Map<ByoaSource, PendingHop[]>()
    for (const h of batch) {
      const arr = byHourceSource.get(h.source) ?? []
      arr.push(h); byHourceSource.set(h.source, arr)
    }
    let token: string
    try { token = await this.getToken() } catch { /* token unavailable — drop, daemon recovers */ return }
    await Promise.all([...byHourceSource.entries()].map(([source, hops]) =>
      // daemonVersion lets the operator correlate spend / cache patterns with
      // an agent-cli release in the Observability dashboard. One version per
      // batch — daemons never upgrade mid-batch, so every hop in this group
      // shares it on the server side.
      runtimeBest(this.serverUrl, '/llm-calls', token, { source, hops, daemonVersion: CURRENT_VERSION }),
    ))
  }

  stop(): void {
    this.stopped = true
    if (this.timer) { clearTimeout(this.timer); this.timer = null }
    // Final flush — best-effort, fire-and-forget.
    void this.flush()
  }
}

/** CUMORA_ENGINE_MODEL value meaning "impose no model at all — use whatever
 *  the local CLI is already configured for". */
const ENGINE_MODEL_LOCAL = 'local'

/** The model the LOCAL engine should run this agent's turns on.
 *
 *  BYOA wakes omit `--model` by default so the CLI/account uses its own
 *  default. (Secure Codex deliberately ignores user config.) The daemon
 *  discovery list leaves `agent.model` unset; `CUMORA_ENGINE_MODEL=local`
 *  is the same no-pin path. A concrete `CUMORA_ENGINE_MODEL` still overrides.
 *
 *  Exported for tests. */
export function resolveEngineModel(
  configured: string | null | undefined,
  override: string | undefined,
): string | null {
  const o = override?.trim()
  if (!o) return modelIdOrNull(configured)
  if (o.toLowerCase() === ENGINE_MODEL_LOCAL) return null
  return modelIdOrNull(o)
}

/** The same knob governs the small-brain pin. `local` has to impose NOTHING:
 *  otherwise ANTHROPIC_SMALL_FAST_MODEL would still name a model the custom
 *  provider lacks, and the CLI's own quick calls would fail instead of the turn.
 *  A concrete override only replaces the big-brain pin, so fast_model is left
 *  alone there. */
export function resolveEngineFastModel(
  configured: string | null | undefined,
  override: string | undefined,
): string | null {
  return override?.trim().toLowerCase() === ENGINE_MODEL_LOCAL ? null : modelIdOrNull(configured)
}

/** Resolve the actual classifier model. A member-specific small brain is more
 * precise than the legacy computer-wide knob; `local` can still suppress the
 * member pin through resolveEngineFastModel(). Exported for regression tests. */
export function resolveTriageModel(
  configured: string | null | undefined,
  computerDefault: string | undefined,
  engineOverride: string | undefined,
): string | undefined {
  return resolveEngineFastModel(configured, engineOverride)?.trim() || computerDefault?.trim() || undefined
}

export class AgentRunner {
  /** Aborted once in stop(). Handed to every one-shot `adapter.run(...)` so the
   *  engine child dies with its runner, the way the persistent session already
   *  does. Without it those children were orphaned: they keep the `cumora` IPC
   *  shim on PATH, so they go on posting AS the agent
   *  while the replacement runner independently answers the same messages. */
  private readonly teardown = new AbortController()
  private token = ''
  private tokenExpiresAt = 0
  private home: string
  private binDir: string
  private trustedCliDir: string
  private ipcDir: string
  private readonly engine: EngineId
  private readonly sessionStore: EngineSessionStore
  private busy = false
  private pendingRerun = false
  // Triage-trouble backoff: when the small-brain triage is rate-limited OR
  // fails (fail-open), we skip whole turns until this time, doubling each
  // consecutive hit — so a broken/throttled triage can't be hammered every poll
  // and (critically) can never escalate to the expensive big brain.
  private triageBackoffUntil = 0
  private triageTroubleStreak = 0
  // Big-brain rate-limit cooldown: when the LAST attempt got
  // "Server is temporarily limiting requests" from the provider, do not
  // attempt another big-brain call from THIS agent until the cooldown
  // expires. Without this, we'd re-attempt on every poll + SSE wake (each
  // burning a real call against the same throttle that just rejected us)
  // and the loop is visible to the user as 100+ rate-limit log lines and
  // 30-65s end-to-end latency per turn. A signed-out engine earns the same
  // treatment for longer, since retrying it cannot succeed at all. Assigned
  // only by applyTurnBackoff(), from the outcome BOTH turn paths classify.
  private engineBackoffUntil = 0
  /** Why this agent is paused, for the skip log. A fifteen-minute operator
   *  pause used to print as a rate-limit cooldown, which sends whoever is
   *  reading the daemon log looking for a throttle that was never there. */
  private engineBackoffWhy = 'rate limit'
  private stopped = false
  private lastWakeConvo: string | null = null
  /** Synthetic work delivered with a wake has no durable chat row. Preserve it
   *  across debounce/coalescing so a brief-only Kanban assignment can drive the
   *  next turn instead of falling into the empty-inbox cost gate. */
  private pendingBackgroundBrief: WakeBackgroundBrief | null = null
  /** Pre-turn debounce timer (see WAKE_DEBOUNCE_MS). Non-null = a turn is already
   *  scheduled to start shortly; further wakes fold into it instead of stacking. */
  private wakeDebounceTimer: ReturnType<typeof setTimeout> | null = null
  /** The engine session id to `--resume` next wake, so the agent keeps
   *  continuous context (its place in a running task) instead of waking cold
   *  on a frozen inbox snapshot. Captured from each run's stream-json output;
   *  cleared if a resume fails so the next wake starts a clean session. */
  private sessionId: string | null = null
  /** Set when the persistent engine process proved unusable on this machine, so
   *  the runner stops trying it and stays on the one-shot path. Without this a
   *  process that starts and then fails every turn fails every turn forever;
   *  with it, the worst case is exactly the pre-persistent behaviour. */
  private persistentUnusable = false
  /** The long-lived engine process (persistent stream-json for claude, app-server
   *  thread for codex), created lazily and reused across wakes so turns 2..N skip
   *  the cold start. Null = not yet started, dead (respawn next turn), or this
   *  engine/config has no persistent mode (a custom args override). */
  private engineSession: EngineSession | null = null
  /** The currently awaited engine operation (persistent send or one-shot run).
   * Runner replacement aborts/stops it and awaits this barrier before the next
   * runner rewrites persona or standing-prompt files. */
  private activeEngineRun: Promise<EngineRunResult> | null = null
  private activeTriage: Promise<unknown> | null = null
  /** When the last engine turn (chat OR agenda) finished — the "quiet" anchor for
   *  agenda wakes, and the throttle for how often we check the board. */
  private lastTurnEndedAt = 0
  private lastAgendaCheckAt = 0
  /** Same-turn steering state: a guard against concurrent steer checks, and the
   *  last direct-message id we steered (so repeated wakes for it don't re-inject). */
  private sideSteering = false
  private lastSteeredMsgId: string | null = null
  /** Content-free group-notice state (opt-in, see STEER_GROUP_IN_TURN): the last
   *  group msg id we nudged about + when, so a fast room can't re-inject on every
   *  message (throttled by GROUP_STEER_MIN_INTERVAL_MS). */
  private lastGroupSteeredMsgId: string | null = null
  private lastGroupSteerAt = 0
  private pollTimer: ReturnType<typeof setInterval> | undefined
  /** Wake-stream liveness for fallbackPollDue: when the stream last showed
   *  signs of life (connect, any event, any `: ping`); null while disconnected. */
  private streamLastSeenAt: number | null = null
  /** Aborts the current wake-stream fetch, so a stream that has gone silent can
   *  be torn down and reconnected instead of waiting for TCP to notice. */
  private streamAbort: AbortController | null = null
  /** Last successful inbox check; 0 means a retry is due. */
  private lastInboxDrainAt = 0
  /** The last status POST that succeeded, and when — see AVAIL_REASSERT_MS. */
  private lastPostedStatus: string | null = null
  private lastPostedStatusAt = 0
  private readonly adapter
  /** Per-agent attachment cache. A long-lived instance lets cleanup protect
   * paths used by the current turn and reap them when the runner stops. */
  private readonly attachmentCache: AgentAttachmentCache
  /** Privileged local broker: the engine sees only its IPC directory, while the
   *  daemon keeps the short-lived runtime JWT in memory. */
  private cliBroker: RuntimeCliBroker | null = null
  /** Buffered ledger reporter — collects per-hop usage from the engine and
   *  POSTs to /runtime/llm-calls so the universal llm_calls ledger sees BYOA
   *  trajectory. Created lazily on first use. */
  private hopReporter: HopReporter | null = null
  /** runId of the run row currently in flight (chat or agenda). Hops emitted
   *  during this turn carry it so the ledger can link them back to the run.
   *  Cleared at turn end. */
  private currentRunId: string | null = null

  constructor(
    private readonly cfg: DaemonConfig,
    private readonly agent: AgentInfo,
    engine: EngineId,
    private readonly provider?: ProviderProfile,
  ) {
    this.engine = engine
    this.home = join(AGENTS_ROOT, agent.id)
    this.binDir = join(this.home, 'bin')
    // The fixed MCP server runs outside the model sandbox. Its source and the
    // sibling IPC shim therefore live outside the model-writable Agent home.
    this.trustedCliDir = join(CONFIG_DIR, '.runtime-cli-tools', this.agent.id)
    // Keep even the IPC parent outside the model-writable home. Secure Codex is
    // granted only the two leaf request/response directories; Claude reaches
    // them through the fixed MCP bridge, not a model-controlled shell.
    this.ipcDir = join(CONFIG_DIR, '.runtime-cli-ipc', this.agent.id)
    this.attachmentCache = new AgentAttachmentCache(
      this.home,
      this.cfg.serverUrl,
      () => this.ensureToken(),
    )
    // The profile is a third dimension of session identity alongside agent and
    // engine: a different endpoint/account owns a different transcript, so its
    // session id must never be offered to another profile's provider.
    this.sessionStore = new EngineSessionStore(SESSIONS_DIR, agent.id, engine,
      engine === 'codex' ? CODEX_SESSION_SCOPE : providerProfileFingerprint(provider) || undefined)
    this.adapter = getAdapter(engine)
  }

  private get reporter(): HopReporter {
    if (!this.hopReporter) {
      this.hopReporter = new HopReporter(this.cfg.serverUrl, async () => this.ensureToken())
    }
    return this.hopReporter
  }

  /** Map every adapter's raw EngineUsage → universal TokenUsage. Adapters
   *  normalize their native counters into this Claude-shaped interface, so a
   *  single ledger path covers every BYOA engine. */
  private hopUsageOf(u: EngineUsage): TokenUsage {
    return usageFromClaude(u as unknown as Record<string, unknown>)
  }

  /** Called by engine sessions/stream trackers for every provider hop. Pushes
   *  one PendingHop into the batched
   *  reporter; never throws. The engine's optional enrichment hints
   *  (hopIndex/toolUses/textChars) ride along in `extras` — these are exactly
   *  the columns the operator needs to ANSWER "why was this hop expensive?"
   *  without having to pull the prompt body back. */
  private onEngineHop(report: EngineHopReport, purpose: PendingHop['purpose']): void {
    try {
      const extras: Record<string, unknown> = {}
      if (typeof report.hopIndex === 'number') extras.hopIndex = report.hopIndex
      if (typeof report.toolUses === 'number') extras.toolUses = report.toolUses
      if (typeof report.textChars === 'number') extras.textChars = report.textChars
      this.reporter.push({
        source: byoaSourceOf(this.adapter.id),
        purpose,
        runId: this.currentRunId,
        conversationId: this.lastWakeConvo,
        model: report.model,
        usage: report.usage ? this.hopUsageOf(report.usage) : undefined,
        latencyMs: report.latencyMs ?? 0,
        status: 'ok',
        extras: Object.keys(extras).length ? extras : undefined,
      })
    } catch (err) {
      console.warn(`[computer] ${this.agent.id} hop report dropped:`, err instanceof Error ? err.message : err)
    }
  }

  /** Is a turn currently in flight? (Used by the supervisor loop to avoid
   *  restarting/auto-updating mid-turn.) */
  get isBusy(): boolean { return this.busy }

  /** Update the engine session id AND persist it to disk, so a daemon restart can
   *  `--resume` the same session and recover the interrupted turn's context. */
  private setSessionId(id: string | null): void {
    if (id === this.sessionId) return
    const previous = this.sessionId
    this.sessionId = id
    void this.sessionStore.save(id)
    if (id) console.log(`[computer] ${this.agent.id} saved ${this.engine} session ${sessionIdPreview(id)}`)
    else if (previous) console.log(`[computer] ${this.agent.id} cleared ${this.engine} session ${sessionIdPreview(previous)}`)
  }

  /** Defense in depth: the store and adapter are both fixed at construction.
   * Refuse resume if a future refactor ever lets those bindings diverge. */
  private resumeSessionId(): string | null {
    if (this.engine === this.adapter.id && this.sessionStore.engine === this.engine) return this.sessionId
    console.error(`[computer] ${this.agent.id} refused cross-engine resume: store=${this.sessionStore.engine}, runner=${this.engine}, adapter=${this.adapter.id}`)
    return null
  }

  /** True when an engine error means the session is unusable and the NEXT wake
   *  must start FRESH (no --resume). Two cases:
   *   1. CONTEXT-WINDOW OVERFLOW — the persistent/resumed session has grown past
   *      the model's window. Carrying it forward (--resume) just re-overflows on
   *      every wake, so the agent stays wedged ("wake again" never helps) until
   *      we drop it. This is hadResume-independent: even a single resumed session
   *      that's now too big must be abandoned.
   *   2. STALE / MISSING resume target — we tried to --resume a session the
   *      engine no longer has. Only meaningful when we actually passed one, and
   *      only when the engine SAYS SO: a mid-turn crash (OOM, sleep, provider
   *      hangup) leaves a resumable session, so it must NOT reset — that would
   *      discard the context the interrupted turn was building. */
  private mustResetSession(err: string, hadResume: boolean): boolean {
    if (this.isContextOverflow(err)) return true
    if (this.isPoisonedTranscript(err)) return true
    if (hadResume && isStaleResumeError(err)) return true
    return false
  }

  private isContextOverflow(err: string): boolean {
    return CONTEXT_OVERFLOW_RE.test(err)
  }

  private isPoisonedTranscript(err: string): boolean {
    return POISONED_BODY_RE.test(err)
  }

  /** Human-readable reason for a forced session reset (just for the log). */
  private resetReason(err: string): string {
    if (this.isContextOverflow(err)) return 'engine hit its context-window limit'
    if (this.isPoisonedTranscript(err)) return 'transcript poisoned by a malformed character (split emoji / lone surrogate)'
    return 'engine session problem'
  }

  /** Drop the session id AND tear down any persistent engine process so the next
   *  wake spawns a genuinely clean session (no --resume of the bad context). */
  private async resetEngineSession(reason: string): Promise<void> {
    console.warn(`[computer] ${this.agent.id} ${reason} — starting a FRESH engine session next wake`)
    this.setSessionId(null)
    await this.engineSession?.stop({ force: true })
    this.engineSession = null
  }

  private async trackEngineRun(run: Promise<EngineRunResult>): Promise<EngineRunResult> {
    this.activeEngineRun = run
    try { return await run }
    finally { if (this.activeEngineRun === run) this.activeEngineRun = null }
  }

  /** Execute exactly one engine attempt. Session capture and the persistent to
   * one-shot transport fallback live here so chat and agenda cannot drift. */
  private async runEngineAttempt(
    delta: string,
    resumeSessionId: string | null,
    localImages: readonly string[] = [],
  ): Promise<EngineRunResult> {
    const session = this.ensureEngineSession(resumeSessionId)
    const prompt = this.turnPrompt(session, delta)
    const nativeImages = this.nativeImagePaths(localImages)
    let result: EngineRunResult
    if (session) {
      const capture = setInterval(() => { if (session.sessionId) this.setSessionId(session.sessionId) }, 2000)
      capture.unref?.()
      try {
        result = await this.trackEngineRun(session.send(prompt, nativeImages))
      } finally {
        clearInterval(capture)
      }
      if (session.sessionId) this.setSessionId(session.sessionId)
      if (!session.alive) this.engineSession = null
      const persistentFailure = engineFailureOf(result, !!resumeSessionId)
      if (persistentFailure && !result.failure) result.failure = persistentFailure
      // A dead persistent transport that never reached the model is safe to
      // retry one-shot. Preserve the same resume target for continuity.
      if (result.error && !result.usage && !session.alive && persistentFailure?.kind !== 'resume-not-found') {
        this.persistentUnusable = true
        this.engineSession = null
        this.logEngineLine(`[engine] persistent session failed to produce a turn (${result.error.slice(0, 160)}) — falling back to one-shot for the rest of this process`)
        result = await this.trackEngineRun(this.adapter.run({
          home: this.home,
          prompt: this.turnPrompt(null, delta),
          env: this.engineEnv(),
          model: this.engineModel(),
          fastModel: this.engineFastModel(),
          nativeFastMode: this.agent.nativeFastMode ?? false,
          resumeSessionId,
          vision: this.visionCapability(),
          localImages: nativeImages,
          onLog: (line) => this.logEngineLine(line),
          onHopUsage: (r) => this.onEngineHop(r, 'agent-turn'),
          signal: this.teardown.signal,
        }))
      }
    } else {
      result = await this.trackEngineRun(this.adapter.run({
        home: this.home,
        prompt,
        env: this.engineEnv(),
        model: this.engineModel(),
        fastModel: this.engineFastModel(),
        nativeFastMode: this.agent.nativeFastMode ?? false,
        resumeSessionId,
        vision: this.visionCapability(),
        localImages: nativeImages,
        onLog: (line) => this.logEngineLine(line),
        onHopUsage: (r) => this.onEngineHop(r, 'agent-turn'),
        signal: this.teardown.signal,
      }))
    }
    if (result.sessionId) this.setSessionId(result.sessionId)
    return result
  }

  /** A missing resume target proves the model never began the requested turn,
   * so one fresh retry is safe. Every other failure returns immediately to
   * avoid duplicating tool side effects after an ambiguous crash or timeout. */
  private async runWithSessionRecovery(
    delta: string,
    localImages: readonly string[] = [],
  ): Promise<EngineRunResult> {
    const resumeSessionId = this.resumeSessionId()
    return runWithSessionRecovery({
      resumeSessionId,
      run: (resume) => this.runEngineAttempt(delta, resume, localImages),
      reset: () => this.resetEngineSession(`${this.engine} resume target ${sessionIdPreview(resumeSessionId ?? '')} does not exist`),
      onFreshRetry: () => console.warn(`[computer] ${this.agent.id} retrying turn once with a fresh ${this.engine} session`),
    })
  }

  private async loadSessionId(): Promise<void> {
    await this.sessionStore.quarantineLegacy()
    const s = await this.sessionStore.load()
    if (s) {
      this.sessionId = s
      console.log(`[computer] ${this.agent.id} restored ${this.engine} session ${sessionIdPreview(s)} from disk — will --resume (continuity across restart)`)
    }
  }

  async start(): Promise<void> {
    await this.adapter.seedHome(this.home, { id: this.agent.id, name: this.agent.name, role: this.agent.role, systemPrompt: this.agent.systemPrompt })
    if (allowUnsandboxedByoa()) await writeShim(this.binDir)
    await writeShim(this.trustedCliDir)
    // Versions before the broker stored a live bearer token beside the shim.
    // Remove it before any new engine process can inspect the old home.
    try {
      const bin = await lstat(this.binDir)
      if (!bin.isDirectory() || bin.isSymbolicLink()) {
        throw new Error(`secure BYOA refuses linked legacy shim directory: ${this.binDir}`)
      }
      await rm(join(this.binDir, '.runtime-token'), { force: true })
    } catch (err) {
      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err
    }
    this.cliBroker = new RuntimeCliBroker(
      this.ipcDir,
      join(CONFIG_DIR, '.runtime-cli-broker', this.agent.id),
      (argv, signal) => this.invokeRuntimeCli(argv, signal),
    )
    await this.cliBroker.start()
    await this.loadSessionId()
    void this.streamLoop()
    // SSE-independent safety net (see INBOX_POLL_MS): tick every 20s, but only
    // drain when the wake-stream can't be trusted (or the slow double-check is
    // due), so a fleet of idle agents stops hammering /inbox in lockstep. Skip
    // while busy so it never piles on the live turn.
    this.pollTimer = setInterval(() => {
      if (this.busy || this.stopped) return
      const now = Date.now()
      // A connected stream that has missed three pings is half-dead: tear it
      // down so streamLoop reconnects (and its reconnect-catchup drains).
      if (this.streamLastSeenAt !== null && now - this.streamLastSeenAt >= WAKE_STREAM_STALE_MS && this.streamAbort) {
        console.warn(`[computer] ${this.agent.id} wake-stream silent for ${Math.round((now - this.streamLastSeenAt) / 1000)}s — reconnecting`)
        this.streamAbort.abort()
      }
      if (fallbackPollDue({ now, streamLastSeenAt: this.streamLastSeenAt, lastInboxDrainAt: this.lastInboxDrainAt })) {
        this.scheduleWake('poll')
      }
    }, INBOX_POLL_MS)
  }

  /** POST /status, skipping an idle `avail` the server already holds. Any other
   *  status (thinking, resting…) always posts, and the avail right after it
   *  posts too — only avail-after-avail is elided, and even that is re-asserted
   *  every AVAIL_REASSERT_MS. A failed post is not remembered, so the next tick
   *  retries it. */
  private async postStatus(token: string, status: 'avail' | 'thinking'): Promise<void> {
    const now = Date.now()
    if (status === 'avail' && this.lastPostedStatus === 'avail' && now - this.lastPostedStatusAt < AVAIL_REASSERT_MS) return
    const ok = await runtimeBest(this.cfg.serverUrl, '/status', token, { status })
    if (ok) { this.lastPostedStatus = status; this.lastPostedStatusAt = now }
    else this.lastPostedStatus = null
  }

  /** Phase 1 of shutdown: stop accepting NEW wakes/turns, but leave any in-flight
   *  turn (and its engine child) running so a brief drain can let it finish. */
  beginStop(): void {
    this.stopped = true
    if (this.pollTimer) { clearInterval(this.pollTimer); this.pollTimer = undefined }
    this.streamAbort?.abort()
    if (this.wakeDebounceTimer) { clearTimeout(this.wakeDebounceTimer); this.wakeDebounceTimer = null }
  }

  async stop(options: { forceEngine?: boolean; purgeAttachments?: boolean } = {}): Promise<void> {
    this.beginStop()
    const session = this.engineSession
    this.engineSession = null
    this.cliBroker?.stop()
    this.cliBroker = null
    // Kill a one-shot engine child too. sync() tears a runner down on any
    // config change (engine/model/persona) or unassign while the daemon keeps
    // running, which is exactly where an orphan does damage: it would still be
    // acting with the OLD persona the operator just replaced.
    this.teardown.abort()
    // Drain any hops queued at shutdown so the ledger doesn't lose the tail
    // (e.g. the agent was mid-turn when the daemon restarts for an update).
    this.hopReporter?.stop()
    this.hopReporter = null
    await Promise.allSettled([
      session?.stop({ force: options.forceEngine }) ?? Promise.resolve(),
      this.activeEngineRun ?? Promise.resolve(),
      this.activeTriage ?? Promise.resolve(),
    ])
    await this.attachmentCache.dispose({ purge: options.purgeAttachments === true }).catch((error) => {
      console.warn(`[computer] ${this.agent.id} attachment cache cleanup failed`, error)
    })
    await this.sessionStore.flush()
  }

  /** Does this runner's live config still match the latest server state? The
   *  engine + model + persona are captured at construction (the adapter is
   *  fixed, and seedHome runs once in start()), so when any of them changes in
   *  Cumora, sync() must tear this runner down and build a fresh one — otherwise
   *  e.g. a Claude→Codex switch wouldn't take effect until a daemon restart. */
  configMatches(agent: AgentInfo, engine: EngineId, provider?: ProviderProfile): boolean {
    return this.adapter.id === engine
      && providerProfileFingerprint(this.provider) === providerProfileFingerprint(provider)
      && this.agent.name === agent.name
      && this.agent.role === agent.role
      && this.agent.systemPrompt === agent.systemPrompt
      && this.agent.model === agent.model
      && this.agent.fastModel === agent.fastModel
      && (this.agent.nativeFastMode ?? false) === (agent.nativeFastMode ?? false)
  }

  private async ensureToken(signal?: AbortSignal): Promise<string> {
    if (this.token && Date.now() < this.tokenExpiresAt - TOKEN_REFRESH_SKEW_MS) return this.token
    const minted = await api<{ token: string; expiresInSeconds: number }>(
      this.cfg.serverUrl, `/api/agents/${this.agent.id}/runtime-token`,
      { method: 'POST', headers: { Authorization: `Bearer ${this.cfg.deviceToken}` }, body: JSON.stringify({ providerProfile: this.agent.providerProfile ?? null }), signal },
    )
    this.token = minted.token
    this.tokenExpiresAt = Date.now() + minted.expiresInSeconds * 1000
    return this.token
  }

  private invalidateToken(token: string): void {
    // Do not erase a newer token if an older in-flight request finishes late.
    if (this.token !== token) return
    this.token = ''
    this.tokenExpiresAt = 0
  }

  /** Execute one shim request outside the model's sandbox. The broker accepts
   *  only argv strings; identity, URL, Authorization, redirects, and token
   *  refresh remain daemon-owned and cannot be changed by the model. */
  private async invokeRuntimeCli(argv: string[], lifecycleSignal: AbortSignal): Promise<RuntimeCliBrokerResult> {
    const requestAbort = new AbortController()
    const timeout = setTimeout(() => requestAbort.abort(), HTTP_TIMEOUT_MS)
    const onLifecycleAbort = () => requestAbort.abort()
    if (lifecycleSignal.aborted) requestAbort.abort()
    else lifecycleSignal.addEventListener('abort', onLifecycleAbort, { once: true })
    try {
      const token = await this.ensureToken(requestAbort.signal)
      if (requestAbort.signal.aborted) return { exitCode: 70, error: 'runtime IPC request cancelled' }
      const res = await fetch(`${this.cfg.serverUrl}/runtime/cli`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
        body: JSON.stringify({ argv }),
        signal: requestAbort.signal,
      })
      if (!res.ok) {
        if (res.status === 401 || res.status === 403) this.invalidateToken(token)
        const body = await res.text().catch(() => '')
        return { exitCode: 70, error: `HTTP ${res.status} ${body.slice(0, 200)}`.trim() }
      }
      const data = await res.json() as { text?: unknown; exitCode?: unknown; attachmentReads?: unknown }
      let text = typeof data.text === 'string' ? data.text : ''
      const reads = runtimeCliAttachmentReads(data.attachmentReads)
      const cachedByMessage = new Map<string, AttachmentCacheResult>()
      if (reads.length > 0) {
        for (const read of reads) {
          cachedByMessage.set(read.messageId, await this.attachmentCache.materialize(read.messageId, read.attachments))
        }
        const trimmed = text.trimStart()
        const enriched = trimmed.startsWith('{') || trimmed.startsWith('[')
          ? enrichCliJsonWithAttachmentPaths(text, cachedByMessage, this.visionCapability())
          : null
        if (enriched !== null) {
          text = enriched
        } else if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
          console.warn(`[computer] ${this.agent.id} CLI returned unparseable JSON with attachments`)
        } else {
          const blocks = [...cachedByMessage.entries()]
            .map(([messageId, cached]) =>
              `Message ${messageId}:\n${renderCachedAttachments(cached, this.visionCapability())}`)
            .filter((block) => block.trim().length > 0)
          if (blocks.length > 0) text += `\n\nAttachment files cached in your Agent home:\n${blocks.join('\n\n')}`
        }
      }
      return {
        text,
        exitCode: typeof data.exitCode === 'number' ? data.exitCode : 0,
      }
    } catch (err) {
      return { exitCode: 70, error: err instanceof Error ? err.message : String(err) }
    } finally {
      clearTimeout(timeout)
      lifecycleSignal.removeEventListener('abort', onLifecycleAbort)
    }
  }

  /** Env handed to the engine subprocess. Secure mode preserves the operator's
   *  original PATH so model-writable <home>/bin cannot shadow the engine binary;
   *  compatibility mode alone exposes its legacy CLI shim there. No server URL
   *  or bearer token crosses the model-process boundary. */
  /** Big-brain model for the local engine, after the CUMORA_ENGINE_MODEL escape. */
  private engineModel(): string | null {
    if (this.provider) return this.agent.model || this.provider.model
    return resolveEngineModel(this.agent.model, process.env.CUMORA_ENGINE_MODEL)
  }

  /** Small/fast-brain model for the local engine, after the same escape. */
  private engineFastModel(): string | null {
    if (this.provider) return this.agent.fastModel || this.provider.fastModel
    return resolveEngineFastModel(this.agent.fastModel, process.env.CUMORA_ENGINE_MODEL)
  }

  /** Per-agent small brain wins over the computer-wide compatibility knob.
   * This makes participants.fast_model real for every adapter whose classify()
   * already accepts a model, while preserving CUMORA_TRIAGE_MODEL as a fallback
   * for old deployments and engines left on their default. */
  private triageModelPin(): string | undefined {
    if (this.provider) return this.agent.fastModel || this.provider.fastModel
    return resolveTriageModel(this.agent.fastModel, process.env.CUMORA_TRIAGE_MODEL, process.env.CUMORA_ENGINE_MODEL)
  }

  private engineEnv(): NodeJS.ProcessEnv {
    const env = {
      ...process.env,
      PATH: engineProcessPath(this.binDir),
      CUMORA_AGENT_IPC_DIR: this.ipcDir,
      CUMORA_AGENT_MCP_SHIM: join(this.trustedCliDir, 'cumora-mcp'),
      CUMORA_AGENT_ID: this.agent.id,
    }
    return this.provider ? providerProfileEnv(env, this.provider) : env
  }

  /** The long-lived engine process for this agent (persistent stream-json),
   *  created lazily and reused across wakes so turns 2..N skip the cold start.
   *  Returns null if the engine has no persistent mode (Cursor/OpenCode, Codex
   *  fallback, or custom args) — the caller then uses one-shot run(). If the
   *  prior process has died it respawns, resuming this.sessionId so context
   *  carries across the restart. */
  private ensureEngineSession(resumeSessionId = this.resumeSessionId()): EngineSession | null {
    if (this.stopped) return null
    if (!this.adapter.startSession) return null
    if (this.persistentUnusable) return null
    if (this.engineSession?.alive) return this.engineSession
    this.engineSession = this.adapter.startSession({
      home: this.home,
      env: this.engineEnv(),
      model: this.engineModel(),
      fastModel: this.engineFastModel(),
      nativeFastMode: this.agent.nativeFastMode ?? false,
      resumeSessionId,
      standingPrompt: this.standingPrompt(),
      vision: this.visionCapability(),
      onLog: (line) => this.logEngineLine(line),
      // Trajectory hook — every assistant hop (Claude) / turn-completed (Codex)
      // shows up here and gets batched to the universal ledger. Purpose is
      // 'agent-turn' for ALL session-issued hops; triage / agenda / etc. ride
      // their own purpose-tagged paths (see recordTriageUsage etc.).
      onHopUsage: (r) => this.onEngineHop(r, 'agent-turn'),
    })
    if (this.engineSession) {
      console.log(`[computer] ${this.agent.id} engine session ${this.sessionId ? `respawned (resume ${this.sessionId.slice(0, 8)})` : 'spawned fresh'} — persistent, no per-wake cold start`)
    }
    return this.engineSession
  }

  /** Enter, or clear, this agent's engine pause for a finished turn. Both turn
   *  paths call this and nothing else assigns engineBackoffUntil, so the chat
   *  wake and the agenda heartbeat cannot drift apart again. */
  private applyTurnBackoff(outcome: TurnOutcome): void {
    const until = backoffUntilFor(outcome, Date.now())
    if (until === null) return
    this.engineBackoffUntil = until
    this.engineBackoffWhy = outcome === 'operator-fix' ? 'operator action needed' : 'rate limit'
  }

  private visibleEngineError(exitCode: number, detail?: string): string {
    const raw = conciseError(redactProviderSecret(detail || `process exited with code ${exitCode}`, this.provider))
    const redacted = raw
      .split(this.home).join('<agent home>')
      .split(homedir()).join('~')
    return `local ${this.adapter.id} failed (exit ${exitCode}): ${redacted}`
  }

  /** Keep a long engine turn alive: bump the run's updated_at every RUN_HEARTBEAT_MS
   *  so the server's 10-min stale-run sweeper doesn't reap a legitimately long turn
   *  as "orphaned". Fires once immediately, then on an interval. Returns a stop fn
   *  for the turn's finally block. No-op (and no timer) when there's no run id. */
  private beatRun(token: string, runId: string | undefined): () => void {
    if (!runId) return () => { /* nothing to heartbeat */ }
    const beat = (): void => { void runtimeBest(this.cfg.serverUrl, `/runs/${runId}/heartbeat`, token, {}) }
    beat()
    const timer = setInterval(beat, RUN_HEARTBEAT_MS)
    return () => clearInterval(timer)
  }

  private async publishEngineFailure(args: {
    token: string
    runId?: string
    conversationId: string | null
    error: string
    exitCode: number
  }): Promise<void> {
    if (args.runId) {
      await runtimeBest(this.cfg.serverUrl, '/events', args.token, {
        runId: args.runId,
        kind: 'engine.failed',
        level: 'error',
        title: `${this.adapter.id} exited ${args.exitCode}`,
        data: { error: args.error },
        stage: 'failed',
      })
    }
    const hint = authFailureHint(this.adapter.id, args.error)
    const conversationIds = await failureConversationIds(this.cfg.serverUrl, args.token, args.conversationId)
    await Promise.all(conversationIds.map((conversationId) => runtimeBest(this.cfg.serverUrl, '/notices', args.token, {
      conversationId,
      agentId: this.agent.id,
      noticeKind: 'byoa_engine_failed',
      text: `${this.agent.name} could not run on local ${this.adapter.id}: ${args.error}\n${hint}`,
      dedupeKey: `byoa_engine_failed:${this.agent.id}:${conversationId}:${hashText(args.error)}`,
      dedupeTtlSec: 900,
    })))
  }

  /** Preload global + current-project memory indexes. Existing
   *  `memory/MEMORY.md` stays GLOBAL; project work lives under
   *  `memory/projects/<id>/MEMORY.md`. A no-project wake injects global
   *  only — same contract as cloud `loadMemory`. */
  private async memoryDigest(projectIds: readonly string[] = []): Promise<string> {
    const parts: Array<{ label: string; body: string }> = []
    for (const rel of memoryIndexPathsForScope(projectIds)) {
      try {
        const txt = (await readFile(join(this.home, rel), 'utf8')).trim()
        if (txt) parts.push({ label: rel, body: txt })
      } catch { /* missing index is fine */ }
    }
    return composeMemoryDigest(parts)
  }

  /** Triage the inbox on the LOCAL small brain. The whole point of BYOA is that
   *  judgment runs on the operator's OWN machine — so the cerebellum is the
   *  engine's cheap fast model (Claude Haiku), NOT a cloud call. The server only
   *  builds the prompt (it has the DB for inbox+context); inference is 100%
   *  local: no network model hop, no sub2api quota (429/503), no big brain. */
  private async inboxTriage(token: string): Promise<RuntimeInboxTriageResponse | null> {
    const payload = await runtimeGet<RuntimeTriagePayload>(this.cfg.serverUrl, '/inbox-triage/payload', token)
    if (!payload) return null
    if (payload.verdict) return payload.verdict // hard rule / empty inbox — no model needed
    if (!payload.instructions || !payload.input) return null
    // No per-engine "skip triage" escape hatch. It looked like a win (dodge one
    // cold CLI spawn per wake) but triage is NOT on the reply critical path:
    // triage-core answers human DMs/groups deterministically without a model,
    // and the small brain runs on the local cheap model. The escape hatch only
    // made one engine judge its own inbox instead of using the shared gate.

    // Triage concurrency gate + deterministic spawn pacer. Pacer is shared
    // with the big-brain path (same Anthropic/OpenAI account quota, same
    // local CLI process pool) — every spawn waits its turn so the provider
    // never sees a burst of N simultaneous starts. See SpawnPacer doc.
    await triageSem.acquire()
    await spawnPacer.gate()
    const controller = new AbortController()
    const timer = setTimeout(() => controller.abort(), TRIAGE_TIMEOUT_MS)
    const onStop = () => controller.abort(this.teardown.signal.reason)
    this.teardown.signal.addEventListener('abort', onStop, { once: true })
    let res: { text: string; error?: string; usage?: EngineUsage; model?: string | null }
    try {
      await mkdir(TRIAGE_DIR, { recursive: true })
      this.teardown.signal.throwIfAborted()
      const pending = this.adapter.classify({
        cwd: TRIAGE_DIR,
        prompt: `${payload.instructions}\n\n${payload.input}`,
        env: this.engineEnv(),
        // Agent-specific small brain first; computer-wide override second; then
        // the adapter chooses its own cheap/default model.
        model: this.triageModelPin(),
        signal: controller.signal,
      })
      this.activeTriage = pending
      res = await pending
    } catch (err) {
      res = { text: '', error: err instanceof Error ? err.message : String(err) }
    } finally {
      clearTimeout(timer)
      triageSem.release()
      this.activeTriage = null
      this.teardown.signal.removeEventListener('abort', onStop)
    }

    res.text = redactProviderSecret(res.text, this.provider)
    if (res.error) res.error = redactProviderSecret(res.error, this.provider)
    if (res.error || !res.text.trim()) {
      const errText = res.error ?? 'no output'
      // CRITICAL: a rate-limited small model must NOT fail-open. Fail-open wakes
      // the expensive big brain to "decide" — which on a 429/quota/overload just
      // burns more of the user's quota and trips the big brain's own limit too
      // (the runaway that drained accounts). Fail CLOSED: skip, don't wake the
      // engine, don't ack — the caller backs off and retries when the limit lifts.
      // A TIMEOUT counts too: a triage that runs past the ceiling is almost always
      // the engine retrying a throttled provider, so treat it as a back-off signal
      // rather than fail-open into the big brain.
      if (controller.signal.aborted || isRateLimited(errText)) {
        console.warn(`[computer] ${this.agent.id} local triage RATE-LIMITED${controller.signal.aborted ? ' (timed out)' : ''} — backing off, NOT waking the big brain: ${errText.slice(0, 160)}`)
        return {
          actionable: false,
          reason: `triage rate-limited (${errText.slice(0, 120)}); backing off`,
          promptNote: '',
          source: 'rate-limited',
        }
      }
      if (payload.failClosed) {
        // Purely agent-to-agent wake: a flaky local model must NOT fail open, or
        // every triage error wakes the big brain and amplifies the very loop the
        // gate exists to stop. A missed agent↔agent reply is cheap and self-heals
        // on the next real event.
        console.warn(`[computer] ${this.agent.id} local triage failed: ${errText.slice(0, 200)} — fail CLOSED (agent-only, no human waiting)`)
        return {
          actionable: false,
          reason: `local triage failed (${errText.slice(0, 120)}); fail closed (agent-only)`,
          promptNote: '',
          source: 'fail-closed',
        }
      }
      console.warn(`[computer] ${this.agent.id} local triage failed: ${errText.slice(0, 200)} — fail open`)
      return {
        actionable: true,
        reason: `local triage failed (${errText.slice(0, 120)}); fail open`,
        promptNote:
          'Local small-brain triage failed; read the inbox/context yourself and respond only if a human needs you. ' +
          'Do not silently ack unread human messages unless the thread clearly shows they are irrelevant or already handled.',
        source: 'fail-open',
      }
    }
    const parsed = parseTriage(res.text)
    // A valid "don't reply" verdict (actionable:false) legitimately has no
    // promptNote — accept it so the gate actually gates. Only a verdict we
    // couldn't even recover `actionable` from (parsed === null) fails open.
    if (parsed) {
      const verdict = finalizeTriage(parsed, 'support-model-local')
      // Record the gate's cache-aware cost (fire-and-forget). A BYOA triage runs
      // LOCAL + cold-session — its input is uncached, the cost this ledger exists
      // to weigh. usage is present for Claude, Cursor, and OpenCode; absent for
      // the current Codex/Grok one-shot classifiers.
      void this.recordTriageUsage(token, verdict.actionable, verdict.reason, res.usage, res.model)
      return verdict
    }
    if (payload.failClosed) {
      console.warn(`[computer] ${this.agent.id} local triage unparseable: ${res.text.slice(0, 200)} — fail CLOSED (agent-only, no human waiting)`)
      return {
        actionable: false,
        reason: 'local triage produced no usable verdict; fail closed (agent-only)',
        promptNote: '',
        source: 'fail-closed',
      }
    }
    console.warn(`[computer] ${this.agent.id} local triage unparseable: ${res.text.slice(0, 200)} — fail open`)
    return {
      actionable: true,
      reason: 'local triage produced no usable verdict; fail open',
      promptNote: 'Local small-brain triage gave no clear verdict; read the inbox/context yourself and respond only if a human needs you.',
      source: 'fail-open',
    }
  }

  /** Triage model id for pricing, honoring the agent pin then CUMORA_TRIAGE_MODEL. Cursor,
   *  OpenCode, pi and Antigravity have no universal cheap alias, so a reported/pinned stream
   *  model wins and the agent model is only a fallback. */
  private triageModel(): string {
    const pinned = this.triageModelPin()
    if (pinned) return pinned
    if (this.adapter.id === 'claude') return 'haiku'
    if (this.adapter.id === 'grok') return 'grok-4.5'
    if (this.adapter.id === 'codex') {
      const provider = cachedCodexProvider(this.engineEnv())
      return provider?.prefersLocalDefault ? provider.defaultModel ?? '<codex-default>' : 'gpt-5.4-mini'
    }
    if (this.adapter.id === 'gemini') return 'gemini-2.5-flash-lite'
    if (this.adapter.id === 'qwen') return 'qwen3-coder-flash'
    if (this.adapter.id === 'opencode') return this.agent.model ?? '<opencode-default>'
    if (this.adapter.id === 'pi') return this.agent.model ?? '<pi-default>'
    if (this.adapter.id === 'antigravity') return this.agent.model ?? 'gemini-3.8-flash-high'
    if (this.adapter.id === 'zcode') return this.agent.model ?? '<zcode-default>'
    if (this.adapter.id === 'maka') return '<maka-default>'
    if (this.adapter.id === 'omp') return this.agent.model ?? '<omp-default>'
    if (this.adapter.id === 'cursor') return this.agent.model ?? '<cursor-default>'
    return this.agent.model ?? '<cursor-default>'
  }

  /** Post one local-triage record to the cost ledger. Best-effort. */
  private async recordTriageUsage(token: string, actionable: boolean, reason: string, usage?: EngineUsage, model?: string | null): Promise<void> {
    await runtimeBest(this.cfg.serverUrl, '/triage', token, {
      source: `byoa-${this.adapter.id}`,
      model: model || this.triageModel(),
      actionable,
      reason,
      usage: usage ? usageFromClaude(usage) : null,
      // Mirror the hop reporter — every BYOA-emitted row in llm_calls carries
      // the daemon version that produced it.
      daemonVersion: CURRENT_VERSION,
    })
  }

  /** Snapshot the unread inbox: the {conversationId → latest unread message id}
   *  cursor map (for `ackSeen`), AND a human-readable digest of the unread
   *  messages to PRE-LOAD into the wake prompt. Pre-loading is what the cloud
   *  agent already does (it builds the turn input from the inbox), so the BYOA
   *  engine can read the room and reply WITHOUT first spending `cumora inbox` +
   *  `cumora messages` round-trips — each of those is an extra opus hop, and
   *  cutting them is most of the per-turn latency.
   *  Captured BEFORE the engine runs so `ackSeen` advances exactly what THIS
   *  turn saw; messages that land mid-turn keep a higher id, stay unread, and
   *  drive the coalesced rerun. */
  /** Parse a system row's wire payload as a due calendar alarm (the JSON the
   *  server's calendar dispatcher writes). Wire-format read, not content
   *  classification. Null = not a calendar dispatch. */
  private parseAlarmPayload(raw: string): { assigneeId?: string; title?: string; agentPrompt?: string } | null {
    try {
      const p = JSON.parse(raw) as { kind?: unknown; assigneeId?: unknown; title?: unknown; agentPrompt?: unknown }
      if (p?.kind !== 'calendar_event') return null
      return {
        assigneeId: typeof p.assigneeId === 'string' ? p.assigneeId : undefined,
        title: typeof p.title === 'string' ? p.title : undefined,
        agentPrompt: typeof p.agentPrompt === 'string' ? p.agentPrompt : undefined,
      }
    } catch { return null }
  }

  private async snapshotUnread(token: string): Promise<{ seen: Map<string, string>; digest: string; hasReal: boolean; projectIds: string[]; imagePaths: string[] }> {
    const inbox = await runtimeGet<RuntimeInboxResponse>(this.cfg.serverUrl, '/inbox', token)
    this.lastInboxDrainAt = inbox ? Date.now() : 0
    if (!inbox) throw new Error('inbox fetch failed')
    const seen = new Map<string, string>()
    // Unread grouped BY CONVERSATION (first-seen order), each with the header
    // (title + topic) the cloud agent's context also carries — so a BYOA agent
    // always sees what the group is FOR (its topic), not just the messages.
    // Grouped rather than one flat line list because the digest has a LINE
    // BUDGET, and spending it per conversation is what stops a busy room from
    // evicting — and `ackSeen` then burying — a quiet one. See renderInboxDigest.
    const byConvo = new Map<string, InboxDigestConversation>()
    // `hasReal` = is ANY unread a genuine human/agent message (not a system
    // relay/status/membership notice)? The cost gate in runTurn uses this to
    // refuse to spend ANY model on a system-only (or empty) inbox.
    let hasReal = false
    // rows are ordered created_at ASC, so the last row per conversation is its
    // newest unread message — exactly the cursor we want to advance to.
    for (const row of inbox?.rows ?? []) {
      if (typeof row.conversation_id !== 'string' || !row.conversation_id) continue
      if (typeof row.id === 'string' && row.id) seen.set(row.conversation_id, row.id)
      // A due CALENDAR dispatch is a SELF-SCHEDULED ALARM, not system noise —
      // it must count as real or a BYOA agent's own alarm can never wake its
      // engine (the cloud path special-cases these system rows the same way).
      const alarm = row.kind === 'system' && typeof row.body === 'string' ? this.parseAlarmPayload(row.body) : null
      if (row.kind !== 'system' || (alarm && (!alarm.assigneeId || alarm.assigneeId === this.agent.id))) hasReal = true
      let convo = byConvo.get(row.conversation_id)
      if (!convo) {
        const head = conversationHeader({
          conversation_id: row.conversation_id,
          conversation_kind: row.conversation_kind,
          conversation_title: row.conversation_title,
          conversation_topic: row.conversation_topic,
          project_name: row.project_name,
        })
        convo = { head, msgs: [], ids: [] }
        byConvo.set(row.conversation_id, convo)
      }
      const author = row.author_name ?? 'someone'
      const who = row.author_kind ? `${author} (${row.author_kind})` : author
      // Render a due calendar alarm readably (title — prompt) so the engine
      // knows WHY it woke; other system rows stay redacted as before.
      const body = (row.kind === 'system'
        ? (alarm ? `[calendar:due] ${[alarm.title, alarm.agentPrompt].filter(Boolean).join(' — ') || 'scheduled alarm fired'}` : '[system]')
        : (row.body ?? '')).replace(/\s+/g, ' ').slice(0, 600)
      // Keep the message id + convo id on each line (like the cloud agent's
      // context) so the engine can QUOTE the exact message: `cumora reply
      // <convo> '<body>' --quote <message_id>`.
      convo.msgs.push(`  [${row.id}] ${row.conversation_id}  ${who}: ${body}${attachmentNotes(row.attachments ?? row.attachment)}`)
      if (row.id) convo.ids?.push(row.id)
    }
    const attachmentBlocks: string[] = []
    const imagePaths: string[] = []
    const visibleMessageIds = visibleInboxMessageIds(byConvo)
    for (const row of inbox.rows ?? []) {
      if (!row.id || !visibleMessageIds.has(row.id)) continue
      const descriptors = normalizeAttachments(row.attachments ?? row.attachment)
      if (descriptors.length === 0) continue
      const cached = await this.attachmentCache.materialize(row.id, descriptors)
      for (const file of cached.files) {
        if (isImageAttachment(file.attachment)) imagePaths.push(file.path)
      }
      const block = renderCachedAttachments(cached, this.visionCapability())
      if (block) attachmentBlocks.push(`Message ${row.id}:\n${block}`)
    }
    const projectIds = uniqueProjectIds(
      (inbox?.rows ?? []).map((r) => (typeof r.project_id === 'string' ? r.project_id : null)),
    )
    const digest = renderInboxDigest(byConvo)
    return {
      seen,
      digest: `${digest}${attachmentBlocks.length ? `\n\nAttachment files cached in your Agent home:\n${attachmentBlocks.join('\n\n')}` : ''}`,
      hasReal,
      projectIds,
      imagePaths: [...new Set(imagePaths)],
    }
  }

  private visionCapability(): 'supported' | 'unsupported' | 'unknown' {
    return engineVisionCapability(this.agent.modelCatalog, this.engineModel())
  }

  /** Only Codex has a verified native path-input contract in this daemon. Keep
   * the capability gate here so an unknown or non-visual model still receives
   * the textual path and honest guidance, never an unsupported image request. */
  private nativeImagePaths(paths: readonly string[]): readonly string[] {
    if (this.engine !== 'codex' || this.visionCapability() !== 'supported') return []
    return [...new Set(paths.filter((path) => path.length > 0 && isAbsolute(path)))]
  }

  /** Advance this agent's read cursor over the conversations it just saw, so a
   *  wake that ends WITHOUT a reply (small-brain said "skip", or the engine
   *  read the room and chose silence) does not re-trigger on the same messages
   *  every INBOX_POLL_MS. markConversationRead is monotonic, so this never
   *  regresses a cursor the engine already advanced further via `cumora reply`. */
  private async ackSeen(token: string, seen: Map<string, string>): Promise<void> {
    if (seen.size === 0) return
    await Promise.all([...seen].map(([conversationId, upToMessageId]) =>
      runtimeBest(this.cfg.serverUrl, '/conversation/mark-read', token, { conversationId, upToMessageId }),
    ))
  }

  /** Log an engine stream-json line, dropping the high-volume noise that
   *  floods the console without telling us anything: per-spawn SessionStart
   *  hook chatter (started/response × N hooks) and rate-limit keepalives. We
   *  keep the signal — assistant text, tool calls/results, init, errors. */
  private logEngineLine(line: string): void {
    line = redactProviderSecret(line, this.provider)
    if (line.includes('"hook_started"') || line.includes('"hook_response"') || line.includes('"rate_limit_event"')) return
    console.log(`[${this.agent.id}/${this.adapter.id}] ${line.slice(0, 500)}`)
  }

  private formatTriageNote(triage: RuntimeInboxTriageResponse | null): string {
    if (!triage) return ''
    const note = typeof triage?.promptNote === 'string' ? triage.promptNote.trim() : ''
    if (!note) return ''
    const state = triage.actionable === false ? 'not relevant' : 'relevant'
    const source = typeof triage.source === 'string' ? triage.source : 'server'
    const reason = typeof triage.reason === 'string' && triage.reason.trim()
      ? `\nReason: ${triage.reason.trim().slice(0, 500)}`
      : ''
    return `Small-brain inbox triage (${state}, ${source}): ${note}${reason}`
  }

  /** The INVARIANT operational scaffold — identical every turn. It goes into the
   *  engine's system prompt ONCE per session (Claude: `--append-system-prompt-file`)
   *  instead of being re-sent in every turn's message. THAT is what keeps the
   *  transcript small enough that the engine's NATIVE auto-compaction keeps up.
   *  Engines without a system-prompt file get this
   *  inlined into each turn instead (see the turn paths). Covers BOTH chat and
   *  agenda turns; the per-turn deltas (chatDelta / agendaDelta) carry only the
   *  dynamic bits. No game-specific rules — the engine coordinates in-turn via the
   *  shared glance-yield protocol, exactly like the cloud pod-agent. */
  /** Which calling convention this agent's turns actually have. */
  private promptSurface(): ActionSurface {
    return actionSurfaceFor(allowUnsandboxedByoa())
  }

  private standingPrompt(): string {
    // RESTORED to the 5/28T22:17Z baseline SHAPE: one minimal prompt of essential
    // mechanics, with GLANCE_YIELD_RULES and a few core sections — NOT a wall of
    // ── XXX ── sections (that's the bloat the user called out: AGENT_VOICE_RULES
    // priming, MORE CUMORA COMMANDS, HELD REPLY explainer, CONTEXT COMPACTION,
    // WORKING A BOARD CARD — none of those existed at 5/28 when coord was perfect,
    // ergo none of them are required for coord). The agent discovers other CLI
    // surface via `cumora <cmd> --help` when it needs it.
    return (
      `You are a Cumora teammate — a first-class member of this team with your own voice. ` +
      actionSurfaceText(this.promptSurface()) +
      `Read the relevant thread and respond appropriately, in your own voice — like a real teammate. ` +
      `If a human addressed the whole team, you and every peer likely woke at the same instant, so ` +
      `coordinate via the protocol below — in short: post the real next item from what's ACTUALLY been posted, ` +
      `optimistically; the server HOLDs you and shows the newer messages if a peer moved the room while you composed.\n` +
      // The shared glance-and-yield protocol — verbatim via the const so BYOA
      // coordinates identically to the cloud pod-agent.
      GLANCE_YIELD_RULES + `\n\n` +
      postingMechanicsText(this.promptSurface()) +
      `After your work is complete and your final \`cumora reply\` returns success, end the turn. ` +
      `Do NOT restate it, summarise it, or narrate what you just did. ` +
      `A progress update or a brief reply to a mid-task ping does not complete your task — continue the work. ` +
      // agy's command-safety monitor re-reviews shell operators on each call.
      `Keep each \`cumora\` call a SINGLE fully quoted command with no pipes, \`&&\`, or redirection. ` +
      `When you're answering a ` +
      `SPECIFIC message, add \`--quote <message_id>\` so your reply threads to its context. ` +
      `To address a teammate, @<their-id> (the short id in \`cumora messages\` / \`cumora participants\`), ` +
      `NOT their display name.\n\n` +
      // Skype emoticons — shared with the cloud agent so a BYOA agent is as
      // expressive, not stuck on native emoji only.
      `${SKYPE_EMOTICONS_GUIDE}\n\n` +
      `Memory: durable store under \`memory/\` (global identity, indexed by \`memory/MEMORY.md\`) ` +
      `and \`memory/projects/<projectId>/\` for unpinned work facts of the current project. ` +
      `This wake injects only global + this project's index — other projects are out of scope. ` +
      `Write project decisions/materials under \`memory/projects/<id>/\` (and a pointer in that folder's MEMORY.md); ` +
      `write identity-level facts under \`memory/\`. Pinning a memory makes it global. ` +
      `Saying "got it" does NOT persist. Chat history can be wiped by compaction; memory files remain.\n\n` +
      `Drive what you own forward — see a task through. Multi-step turns are fine; you do NOT have to ` +
      `fragment. If someone DMs you mid-task, answer briefly then keep going. The only thing to avoid ` +
      `is a pointless loop. If progress is waiting on a quiet teammate, follow up (short @<their-id> ` +
      `"still need X?") and schedule your own check-back: ` +
      calendarExampleText(this.promptSurface(), this.agent.id) +
      `Stop only when the work is truly done or it's someone else's move.\n\n` +
      `Privacy: stay inside your home directory. Never read or expose files outside it — this machine ` +
      `holds the operator's private files.`
    )
  }

  /** Per-turn CHAT delta — only the dynamic bits (the invariant HOW lives in the
   *  standing prompt). Kept small so the persistent session's transcript grows
   *  slowly and native compaction can keep up. */
  private chatDelta(memoryDigest: string, triageNote: string, inboxDigest: string, roster?: string): string {
    return (
      `You've been woken because there's new activity in your Cumora conversations, and the cerebellum triage already ` +
      `decided you should respond — your job is to DO it (write the reply / take the action), not to re-judge whether to. ` +
      `Follow your standing instructions for HOW.\n\n` +
      // A CLOCK. Without it the model has no idea what time it is (session
      // context only carries stale timestamps), so any time arithmetic —
      // most visibly `cumora calendar create --at` deadlines — silently
      // lands in the past: a werewolf judge scheduled every phase alarm ~20
      // minutes before "now" and they all fired instantly. One line, per
      // turn, always current.
      `Current time (UTC): ${new Date().toISOString()} — use this for any --at / deadline math.\n\n` +
      (triageNote ? `${triageNote}\n\n` : ``) +
      (inboxDigest
        // Pre-loaded unread (fetched for you) — mirrors how the cloud agent gets
        // its inbox in the turn input, cutting the inbox/messages hops.
        ? `Your unread messages (ALREADY FETCHED — no need to re-run \`cumora inbox\` / \`cumora messages\` to re-read ` +
          `these; but DO \`cumora glance\` before posting in a group, to catch anything posted while you compose):\n${inboxDigest}\n\n`
        : `Run \`cumora inbox\`, then \`cumora messages <conversationId> --tail 30\`, to catch up.\n\n`) +
      (memoryDigest ? `Your memory index (global \`memory/MEMORY.md\` + current project, if any):\n${memoryDigest}\n\n` : ``) +
      (roster ? `Your team right now (trust over memory — current roster; use these ids for @mentions and \`cumora dm\`):\n${roster}\n` : ``)
    ).trimEnd()
  }

  /** Per-turn delta for a deliberate manual wake carrying its own work brief.
   * Unlike a background agenda scan, this is already an actionable user/team
   * assignment and must run even when there is no unread chat row. */
  private manualBriefDelta(
    brief: WakeBackgroundBrief,
    memoryDigest: string,
    inboxDigest: string,
    roster?: string,
  ): string {
    return (
      `Current time (UTC): ${new Date().toISOString()} — use this for any --at / deadline math.\n\n` +
      `Someone just put this work on you directly. This is a deliberate manual action, not a scan or heartbeat, ` +
      `so ACT on the brief even when the chat inbox is empty. Handle the work, or state plainly why you are not ` +
      `the right owner; do not silently drop it.\n\n` +
      `Brief: ${brief.title}\n` +
      `Source: ${brief.source ?? 'manual'}\n\n` +
      `${brief.body}\n\n` +
      (inboxDigest
        ? `Unread messages that arrived with this wake (also handle anything addressed to you):\n${inboxDigest}\n\n`
        : '') +
      (memoryDigest ? `Your memory index (global \`memory/MEMORY.md\` + current project, if any):\n${memoryDigest}\n\n` : '') +
      (roster ? `Your team (use these ids for @mentions):\n${roster}\n` : '')
    ).trimEnd()
  }

  /** Per-turn AGENDA delta — dynamic bits for a proactive board-work wake; the
   *  invariant mechanics live in the standing prompt. */
  private agendaDelta(brief: string, memoryDigest: string, roster?: string): string {
    return (
      `Current time (UTC): ${new Date().toISOString()} — use this for any --at / deadline math.\n\n` +
      `You've been woken by your OWN AGENDA — Kanban cards assigned to you (or @-mentioning you), calendar slots due now, ` +
      `AND any conversation you're in that went quiet mid-flow and needs follow-up. The system already triaged that there's ` +
      `real work to progress, so ACT: pick the most timely item and move it forward; don't deliberate whether to. For a quiet ` +
      `conversation, FIRST decide if it's genuinely waiting or already CONCLUDED (wrap-ups / closing remarks / a result reached ` +
      `/ nothing pending) — if concluded, do NOT post; reviving a finished thread late is noise. Only when someone is plainly ` +
      `waiting: read the room, then send AT MOST ONE message (answer if it needs your answer; a single brief nudge otherwise) — ` +
      `never nag, never revive a finished thread. Coordinate before you commit (claim before shared work, trust card status); ` +
      `follow your standing instructions for mechanics.\n\n` +
      `${brief}\n\n` +
      (memoryDigest ? `Your memory index (global \`memory/MEMORY.md\` + current project, if any):\n${memoryDigest}\n\n` : ``) +
      (roster ? `Your team (use these ids for @mentions):\n${roster}\n` : ``)
    ).trimEnd()
  }

  /** Combine the standing scaffold with a per-turn delta. When the turn runs on a
   *  persistent session that ALREADY carries the standing prompt out-of-band
   *  (Claude's --append-system-prompt-file), we send ONLY the delta — that's the
   *  whole point. Otherwise (one-shot run, or an engine without a system-prompt
   *  file) we inline the standing prompt, preserving prior behavior. */
  private turnPrompt(session: EngineSession | null, delta: string): string {
    // If the session took the standing prompt out-of-band at spawn (Claude
    // system-prompt file / Codex developerInstructions), send ONLY the delta —
    // that's what keeps the transcript small. Otherwise inline it (one-shot path,
    // or out-of-band delivery wasn't available).
    if (session?.carriesStandingPrompt) return delta
    return `${this.standingPrompt()}\n\n════════\n\n${delta}`
  }

  /** When chat is idle, PROACTIVELY pick up assigned board work — the BYOA analog
   *  of the cloud idle scheduler's agenda heartbeat. Gated by a quiet window (the
   *  anti-loop) + a throttle so the 20s poll doesn't hammer it. Runs through the
   *  SAME persistent engine; isolated from the chat path so it can't break it. */
  private async maybeAgendaTurn(token: string): Promise<void> {
    const now = Date.now()
    if (now - this.lastTurnEndedAt < AGENDA_QUIET_MS) return
    if (now - this.lastAgendaCheckAt < AGENDA_CHECK_MS) return
    this.lastAgendaCheckAt = now
    // Same pause guard as runTurn — a throttle or a signed-out engine hit on a
    // chat turn stops the heartbeat too, because it would hit exactly the same
    // wall. Re-fires on the next AGENDA_CHECK_MS tick once the pause expires.
    // Place this BEFORE the /agenda fetch + /runs row creation so we don't
    // leak a 'running' run row that the stale-run sweeper later reaps.
    if (Date.now() < this.engineBackoffUntil) {
      const leftS = Math.round((this.engineBackoffUntil - Date.now()) / 1000)
      console.log(`[computer] ${this.agent.id} agenda skip: engine paused (${this.engineBackoffWhy}), ${leftS}s left`)
      return
    }
    const ag = await runtimeGet<{ actionable?: boolean; brief?: string; focus?: string }>(
      this.cfg.serverUrl, '/agenda', token,
    )
    if (!ag?.actionable || !ag.brief) return
    console.log(`[computer] ${this.agent.id} agenda turn START — proactive board work${ag.focus ? `: ${ag.focus.slice(0, 80)}` : ''}`)
    await this.postStatus(token, 'thinking')
    const run = (await runtimeBest(this.cfg.serverUrl, '/runs', token, {
      trigger: { source: 'byoa-agenda', engine: this.adapter.id },
    })) as { runId?: string } | null
    // Pin the per-hop ledger's `runId` for the lifetime of this turn so every
    // hop emitted by the engine is linked back to the agent_runs row. Cleared
    // in finally below alongside the heartbeat stop.
    this.currentRunId = run?.runId ?? null
    const stopRunBeat = this.beatRun(token, run?.runId)
    let exitCode = 0
    let engineError: string | null = null
    let turnUsage: EngineUsage | undefined
    let turnModel: string | null | undefined
    // Spawn jitter + concurrency gate — same reason as the chat path (see
    // runTurn): when multiple agents on this computer hit the agenda
    // heartbeat in the same tick (they often do — same poll interval, all
    // due at once), staggering AND capping concurrent spawns keeps the
    // provider's short-window burst limit from rejecting them all.
    await bigBrainSem.acquire()
    await spawnPacer.gate()
    try {
      const [memoryDigest, roster] = await Promise.all([
        this.memoryDigest(),
        runtimeGet<{ roster: string }>(this.cfg.serverUrl, '/roster', token).then((r) => r?.roster ?? '').catch(() => ''),
      ])
      this.teardown.signal.throwIfAborted()
      const result = await this.runWithSessionRecovery(this.agendaDelta(ag.brief, memoryDigest, roster))
      exitCode = result.exitCode
      turnUsage = result.usage
      turnModel = result.model
      if (result.error) engineError = this.visibleEngineError(exitCode, result.failure?.message ?? result.error)
      if (engineError && result.failure?.kind !== 'resume-not-found' && this.mustResetSession(engineError, false)) {
        await this.resetEngineSession(this.resetReason(engineError))
      }
    } catch (err) {
      exitCode = 1
      engineError = this.visibleEngineError(1, err instanceof Error ? (err.stack || err.message) : String(err))
    } finally {
      stopRunBeat()
      this.lastTurnEndedAt = Date.now()
      // Per-turn ledger drain: turn just ended, push any queued hops promptly
      // instead of waiting for the 250ms timer. Fire-and-forget — the void
      // wraps because a slow flush must not block the chat path.
      this.currentRunId = null
      void this.reporter.flush()
      await this.postStatus(token, 'avail')
      // Mirror chat path: release the concurrency slot regardless of outcome.
      bigBrainSem.release()
    }
    // Rate-limit: same as chat-turn path — suppress the user-facing notice
    // and just defer (no inbox state to keep here since agenda turns are
    // proactive; next heartbeat re-evaluates after cooldown).
    const outcome = classifyTurnOutcome(engineError)
    if (engineError && outcome !== 'rate-limited') {
      await this.publishEngineFailure({ token, runId: run?.runId, conversationId: null, error: engineError, exitCode })
    }
    if (outcome === 'rate-limited') {
      spawnPacer.onRateLimited()
      console.warn(`[computer] ${this.agent.id} agenda engine RATE-LIMITED — cooling down ${Math.round(ENGINE_BACKOFF_AFTER_RATE_LIMIT_MS / 1000)}s, pacer now ${spawnPacer.intervalMs}ms`)
    } else if (outcome === 'operator-fix') {
      // This heartbeat used to be the one path that published the notice and
      // then came straight back a minute later, and again, for as long as the
      // engine stayed signed out — fifteen dead spawns per agent inside the
      // single window the notice is deduplicated over, so the fleet burned its
      // error budget while the operator saw one message about it.
      console.warn(`[computer] ${this.agent.id} agenda engine needs operator action — pausing ${Math.round(ENGINE_BACKOFF_AFTER_OPERATOR_FIX_MS / 60000)}min: ${engineError?.slice(0, 160)}`)
    } else if (outcome === 'ok') {
      spawnPacer.onOk()
    }
    this.applyTurnBackoff(outcome)
    // Finalize the run — WITHOUT this the row stays 'running' and the 10-min
    // stale-run sweeper reaps EVERY agenda turn as "orphaned" (the bug behind the
    // recurring Failed/orphaned runs), no matter how fast the turn actually was.
    if (run?.runId) {
      await runtimeBest(this.cfg.serverUrl, `/runs/${run.runId}/finish`, token, {
        status: exitCode === 0 ? 'completed' : 'failed',
        summary: engineError ?? `byoa-agenda ${this.adapter.id} run (exit ${exitCode})`,
        error: engineError,
        model: turnModel ?? this.agent.model,
        usage: turnUsage ? usageFromClaude(turnUsage) : null,
      })
    }
    console.log(`[computer] ${this.agent.id} agenda turn DONE — exit ${exitCode}`)
  }

  /** Fire-and-forget entry to a turn. The ONLY way wakes/polls trigger runTurn,
   *  so a rejection can never become an unhandled promise rejection (which on
   *  Node ≥15 crashes the whole daemon). runTurn already catches internally;
   *  this is the belt-and-suspenders second layer. */
  private kickTurn(reason: string): void {
    void this.runTurn(reason).catch((err) => {
      console.error(`[computer] ${this.agent.id} runTurn rejected (swallowed):`,
        err instanceof Error ? err.message : err)
    })
  }

  /** Debounced entry to a turn (debounce + coalesce).
   *  If a turn is already running, the existing in-turn coalesce (pendingRerun)
   *  handles it — start nothing, the running turn will rerun. Otherwise the first
   *  wake ARMS a short timer; subsequent wakes within the window fold in (return
   *  early). When it fires we run ONE turn that snapshots ALL unread — so a burst
   *  becomes a single big-engine spawn. The poll path and SSE wakes route here. */
  private scheduleWake(
    reason: string,
    convo?: string | null,
    backgroundBrief?: WakeBackgroundBrief | null,
  ): void {
    if (this.stopped) return
    this.pendingBackgroundBrief = mergeWakeBackgroundBriefs(
      this.pendingBackgroundBrief,
      backgroundBrief,
    )
    if (this.busy) {
      // A turn is already running. Coalesce as usual (the rerun re-reads the inbox),
      // BUT if this wake is a DIRECT ping, STEER it into the running turn so the
      // agent answers it mid-task instead of making it wait for the turn to end.
      this.kickTurn(reason)
      if (convo) void this.maybeSteer(convo)
      return
    }
    if (this.wakeDebounceTimer) return
    this.wakeDebounceTimer = setTimeout(() => {
      this.wakeDebounceTimer = null
      this.kickTurn(reason)
    }, WAKE_DEBOUNCE_MS)
    this.wakeDebounceTimer.unref?.()
  }

  /** Same-turn steering: when a DIRECT ping (DM / @me / a human
   *  addressing me) arrives WHILE a turn is running, inject it into the live
   *  persistent session so the agent answers it mid-task, then continues — instead
   *  of the ping waiting for the (possibly long) turn to end. Best-effort; only
   *  direct pings, deduped per message, never interrupts the main task. */
  private async maybeSteer(convo: string): Promise<void> {
    const session = this.engineSession
    if (!session?.alive || this.sideSteering) return
    this.sideSteering = true
    try {
      await this.ensureToken()
      // PROBE: this is the "should I steer?" check — we filter by direct/
      // mention/human below, and only ~20% of probes actually result in a
      // steer (most wakes are group chatter, not direct). Use ?probe=1 so
      // the server does NOT advance the freshness-preflight baseline for
      // this read; if the steer fires, the agent will see the rows via
      // the actual steer text, and any duplicate-collision risk remains
      // protected by cmdReply's preflight against the baseline that
      // snapshotUnread set at the start of this turn.
      const inbox = await runtimeGet<RuntimeInboxResponse>(this.cfg.serverUrl, '/inbox?probe=1', this.token)
      const rows = (inbox?.rows ?? []).filter((r) => r.conversation_id === convo)
      if (rows.length === 0) return
      const direct = rows.some((r) =>
        r.conversation_kind === 'direct' ||
        r.author_kind === 'human' ||
        (typeof r.body === 'string' && r.body.includes(`@${this.agent.id}`)))
      if (!direct) {
        if (!STEER_GROUP_IN_TURN) return
        // Content-free GROUP nudge (opt-in): tell the busy agent that
        // activity happened WITHOUT injecting bodies — throttled, deduped by latest
        // id. The agent glances + posts through the normal server gates (freshness
        // preflight, compose-anchor, verbatim-dup); the coalesced rerun stays as the
        // coordination-safe backstop, so this only ever ACCELERATES pickup.
        const nowMs = Date.now()
        const latestGroup = rows[rows.length - 1]
        if (!latestGroup.id || latestGroup.id === this.lastGroupSteeredMsgId) return
        if (nowMs - this.lastGroupSteerAt < GROUP_STEER_MIN_INTERVAL_MS) return
        this.lastGroupSteeredMsgId = latestGroup.id
        this.lastGroupSteerAt = nowMs
        session.steer(
          `⚡ ${rows.length} new message(s) arrived in ${convo} while you work — bodies withheld to keep you focused. At a natural pause, \`cumora glance ${convo}\` and handle it if it's yours (yield/claim as usual); otherwise keep going. Do NOT drop your current task.`,
        )
        console.log(`[computer] ${this.agent.id} GROUP-NOTICE → live turn (${rows.length} msg(s) in ${convo}, content-free)`)
        return
      }
      const latest = rows[rows.length - 1]
      if (!latest.id || latest.id === this.lastSteeredMsgId) return // dedup repeated wakes for the same ping
      const hasImage = normalizeAttachments(latest.attachments ?? latest.attachment).some(isImageAttachment)
      if (hasImage) {
        this.lastSteeredMsgId = latest.id
        console.log(`[computer] ${this.agent.id} STEER deferred (image attachment will be sent with the next full turn)`)
        return
      }
      this.lastSteeredMsgId = latest.id
      const who = latest.author_name ?? 'someone'
      const body = (latest.body ?? '').replace(/\s+/g, ' ').slice(0, 300)
      session.steer(
        `⚡ A direct message arrived while you work — answer it BRIEFLY, then resume your current task (do NOT drop it). ${who} in ${convo}: "${body}". Reply one line now: \`cumora reply ${convo} 'text'\` — a quick answer, or "on it, mid-task, will follow up". Then continue what you were doing.`,
      )
      console.log(`[computer] ${this.agent.id} STEER → live turn (direct msg in ${convo} from ${who})`)
    } catch { /* best-effort; the coalesced rerun still handles it at turn end */ } finally {
      this.sideSteering = false
    }
  }

  /** Run one turn. Coalesces concurrent wakes: a wake during a run schedules
   *  exactly one rerun afterward (the inbox is the source of truth). `reason`
   *  is logged so the service log shows WHAT drove each turn (sse-wake /
   *  sse-steer / poll / reconnect-catchup) — key for diagnosing receipt latency
   *  (e.g. a turn that only ever fires via 'poll' means SSE wakes aren't
   *  arriving and you're eating up to INBOX_POLL_MS of delay). */
  private async runTurn(reason: string): Promise<void> {
    if (this.busy) {
      this.pendingRerun = true
      console.log(`[computer] ${this.agent.id} turn busy — coalescing (${reason})`)
      return
    }
    this.busy = true
    this.attachmentCache.beginTurn()
    let activeBackgroundBrief: WakeBackgroundBrief | null = null
    try {
      do {
        this.pendingRerun = false
        // Triage-trouble backoff: while triage is cooling down (after a rate-limit
        // or a fail-open), skip the WHOLE turn — no triage call, no engine spawn —
        // so we neither hammer a broken/throttled triage nor burn the big brain.
        // The poll just no-ops until the window passes; unread messages are
        // untouched and get triaged then.
        if (Date.now() < this.triageBackoffUntil) {
          const leftS = Math.round((this.triageBackoffUntil - Date.now()) / 1000)
          console.log(`[computer] ${this.agent.id} skip (${reason}): triage backoff, ${leftS}s left`)
          break
        }
        // Big-brain rate-limit cooldown: the last attempt got throttled by the
        // provider. Skip this turn cleanly (no triage call either — even small
        // brain is wasted if we can't follow up with the big one). Unread is
        // kept (no ack), so the next wake AFTER the cooldown will pick it up.
        if (Date.now() < this.engineBackoffUntil) {
          const leftS = Math.round((this.engineBackoffUntil - Date.now()) / 1000)
          console.log(`[computer] ${this.agent.id} skip (${reason}): engine paused (${this.engineBackoffWhy}), ${leftS}s left`)
          break
        }
        const turnStart = Date.now()
        await this.ensureToken()
        const token = this.token
        // Consume the wake's conversation, so a later turn that reuses no wake
        // can't flash phantom "typing" in whatever conversation last woke us.
        // (The fallback below is derived from CURRENTLY unread messages, so it
        // can't go stale the way a leftover wake value could.)
        const wakeConvo = this.lastWakeConvo
        this.lastWakeConvo = null
        activeBackgroundBrief = this.pendingBackgroundBrief
        this.pendingBackgroundBrief = null
        // Snapshot what's unread BEFORE triaging, so triage provably sees a
        // superset of what we may ack — a real task that lands during/after
        // triage keeps a higher id, stays out of `seen`, and so survives to
        // drive the coalesced rerun rather than being silently acked away.
        const { seen, digest, hasReal, projectIds, imagePaths } = await this.snapshotUnread(token)
        // Which conversation should show "<agent> is typing…"? Prefer the one the
        // wake named, but fall back to the unread we just snapshotted, because a
        // wake often carries no conversation at all:
        //
        //   - a POLL-driven turn never has one (only an SSE wake sets
        //     lastWakeConvo), and polling is the ONLY path left whenever the
        //     wake-stream is down;
        //   - a wake that arrives while this agent is mid-turn is coalesced, and
        //     scheduleWake's busy branch re-kicks without a conversation.
        //
        // Both cases are exactly when a human IS waiting, and with no indicator
        // the agent reads as dead: it can work for minutes — engine spawned, turn
        // running — while the room shows nothing at all.
        const convo = typingConversation(wakeConvo, seen)
        // HARD COST GATE (content-blind, fail-closed): system-only inbox noise
        // is not a task. A validated manual backgroundBrief IS a task, though:
        // Kanban assignment/mention wakes deliberately have no chat row, and
        // dropping that SSE payload here was why BYOA cards stayed in Todo.
        if (!wakeHasActionableInput(hasReal, activeBackgroundBrief)) {
          await this.ackSeen(token, seen)
          await this.postStatus(token, 'avail')
          // No per-tick log: this is the idle steady state (every poll × agent),
          // same reasoning as the 'inbox empty' skip below.
          // Chat is idle → maybe there's assigned BOARD work to proactively pick up
          // (quiet+throttle gated, so this isn't a per-poll cost).
          await this.maybeAgendaTurn(token)
          continue
        }
        // A deliberate manual brief is already actionable, just like the cloud
        // `briefedManual` path. Only ordinary inbox wakes need the small-brain
        // triage decision.
        const triage = activeBackgroundBrief ? null : await this.inboxTriage(token)
        if (this.stopped) break
        const triageMs = Date.now() - turnStart // ensureToken + snapshot + triage
        // Triage was rate-limited → STOP. Do NOT retry, do NOT wake the big brain,
        // do NOT ack (the message is retried after the cooldown). Back off
        // exponentially so a throttled model can't be hammered into burning the
        // user's quota. This is the guard against the infinite-retry runaway.
        if (triage?.source === 'rate-limited') {
          this.triageTroubleStreak += 1
          const backoff = Math.min(10 * 60_000, 30_000 * 2 ** (this.triageTroubleStreak - 1))
          this.triageBackoffUntil = Date.now() + backoff
          console.warn(`[computer] ${this.agent.id} triage RATE-LIMITED (#${this.triageTroubleStreak}, triage ${triageMs}ms) — backing off ${Math.round(backoff / 1000)}s, NOT waking the big brain, not acking`)
          await this.postStatus(token, 'avail')
          break
        }
        // FAIL-OPEN is a triage FAILURE, not a confirmed real task — so it must
        // NEVER wake the expensive big brain (that escalation was the leak that
        // burned quota). Treat it like a rate-limit: skip, do NOT ack (retry next
        // poll once triage recovers), and back off so a persistently-broken triage
        // isn't re-hit — and never spends opus — every poll.
        if (triage?.source === 'fail-open') {
          this.triageTroubleStreak += 1
          const backoff = Math.min(10 * 60_000, 30_000 * 2 ** (this.triageTroubleStreak - 1))
          this.triageBackoffUntil = Date.now() + backoff
          console.warn(`[computer] ${this.agent.id} triage FAIL-OPEN (#${this.triageTroubleStreak}, triage ${triageMs}ms) — NOT waking the big brain, backing off ${Math.round(backoff / 1000)}s, not acking`)
          await this.postStatus(token, 'avail')
          break
        }
        // A clean, usable triage clears any prior backoff.
        this.triageTroubleStreak = 0
        this.triageBackoffUntil = 0
        if (triage?.actionable === false) {
          const skipReason = typeof triage.reason === 'string' ? triage.reason : 'not relevant'
          // Only log a MEANINGFUL skip. An empty inbox is the idle steady state
          // (every INBOX_POLL_MS tick × every agent) — logging it floods the
          // console with identical "inbox empty" lines and tells us nothing.
          if (skipReason !== 'inbox empty') {
            console.log(`[computer] ${this.agent.id} skip (${reason}, triage ${triageMs}ms): ${skipReason}`)
          }
          // Ack the chatter the small brain just dismissed. Without this the
          // unread sticks and the INBOX_POLL_MS drain re-triages it forever —
          // the loop that woke (or nearly woke) the big brain on every tick.
          await this.ackSeen(token, seen)
          await this.postStatus(token, 'avail')
          // Chat had nothing for us → maybe proactively pick up assigned board work.
          await this.maybeAgendaTurn(token)
          continue
        }
        // Mirror the cloud agent EXACTLY (turn.ts): the small brain ONLY gated
        // (actionable). It does NOT decide who replies, how, or — for a relay /
        // chain — who continues, and it NEVER writes content. Wake the big engine,
        // hand it the triage note + the shared glance-yield protocol, and let it
        // self-coordinate IN-TURN (glance → yield to earlier claimants → continue
        // the chain, never restart). That is the exact path that lets the cloud pod
        // play 成语接龙 cleanly. The old BYOA-only orchestration here — responseMode
        // routing, one-of-us claimReply, mechanical direct-post, relay turn-claim —
        // was the divergence that broke chains and is GONE. Cost backstops remain:
        // the actionable gate above + the per-minute activation rate floor.
        const gateLabel = activeBackgroundBrief
          ? `manual brief ${activeBackgroundBrief.source ?? 'unknown'}`
          : `triage ${triageMs}ms`
        console.log(`[computer] ${this.agent.id} turn START (${reason}) — ${gateLabel}, spawning ${this.adapter.id}${convo ? ` for ${convo}` : ''}`)
        await this.postStatus(token, 'thinking')
        // "<agent> is typing…" in the conversation that woke us, refreshed
        // while the engine works (BYOA runs can be long), cleared at the end.
        let typingTimer: ReturnType<typeof setInterval> | undefined
        if (convo) {
          const ping = (): void => { void runtimeBest(this.cfg.serverUrl, '/typing', token, { conversationId: convo, done: false }) }
          // Stamp every conversation in this wake, not just the trigger.
          // Mixed-project wakes then fall back to GLOBAL on memory writes
          // instead of guessing the trigger group's project.
          const wakeConvos = [...seen.keys()]
          const thinkingIds = wakeConvos.length > 0 ? wakeConvos : [convo]
          const thinkingPing = (): void => { void runtimeBest(this.cfg.serverUrl, '/thinking/mark', token, { conversationIds: thinkingIds, ttlSec: 60 }) }
          ping()
          thinkingPing()
          typingTimer = setInterval(() => {
            ping()
            thinkingPing()
          }, 6000)
          // Compose-anchor is now stamped by the /thinking/mark handler on
          // server side (it has the agent + convo already), pinned to THIS
          // turn's start. Independent of the seen-baseline (which glance/
          // messages advance) — so a peer post landing during compose still
          // HOLDs the reply even after the agent later glances and "absorbs"
          // it. Closes the 光-光 collision: two agents both saw 爻, both
          // drafted 光, and the second glance silently advanced past the
          // first poster's message; preflight previously saw "nothing newer."
        }
        const run = (await runtimeBest(this.cfg.serverUrl, '/runs', token, {
          trigger: {
            source: activeBackgroundBrief ? 'byoa-manual' : 'byoa',
            engine: this.adapter.id,
            ...(activeBackgroundBrief
              ? {
                  backgroundBrief: {
                    source: activeBackgroundBrief.source ?? 'manual',
                    title: activeBackgroundBrief.title,
                  },
                }
              : {}),
          },
        })) as { runId?: string } | null
        // Pin runId so per-hop ledger rows link back to this turn (see
        // maybeAgendaTurn for the same hook).
        this.currentRunId = run?.runId ?? null
        const stopRunBeat = this.beatRun(token, run?.runId)
        let exitCode = 0
        let engineError: string | null = null
        let turnUsage: EngineUsage | undefined
        let turnModel: string | null | undefined
        // Per-computer concurrency gate + deterministic spawn pacer.
        // Pacer enforces a minimum interval between back-to-back spawns
        // (shared with triage path) so the provider never sees a burst of
        // N simultaneous starts. Random jitter (the earlier approach)
        // was probabilistic — by chance several waiters could roll near-
        // zero and still slam the API; deterministic pacing makes the
        // burst rate a hard 1/(MIN_SPAWN_INTERVAL_MS) regardless of
        // concurrent waiter count.
        await bigBrainSem.acquire()
        await spawnPacer.gate()
        const semQueueDepth = bigBrainSem.queueDepth
        if (semQueueDepth > 0) {
          console.log(`[computer] ${this.agent.id} big-brain sem acquired (queue depth was ${semQueueDepth + 1} including self)`)
        }
        try {
          const turnBackgroundBrief = activeBackgroundBrief
          const [memoryDigest, triageNote, roster] = await Promise.all([
            this.memoryDigest(projectIds),
            Promise.resolve(this.formatTriageNote(triage)),
            // Live team roster (names + roles + ids), fetched fresh from the
            // server so a locally-run agent knows WHO its teammates are and what
            // each does — the cloud agent gets this in its system prompt. Only
            // fetched here, right before a real turn, so no-op wakes pay nothing.
            runtimeGet<{ roster: string }>(this.cfg.serverUrl, '/roster', token)
              .then((r) => r?.roster ?? '').catch(() => ''),
          ])
          this.teardown.signal.throwIfAborted()
          const delta = turnBackgroundBrief
            ? this.manualBriefDelta(turnBackgroundBrief, memoryDigest, digest, roster)
            : this.chatDelta(memoryDigest, triageNote, digest, roster)
          const result = await this.runWithSessionRecovery(delta, imagePaths)
          exitCode = result.exitCode
          turnUsage = result.usage
          turnModel = result.model
          if (result.error) engineError = this.visibleEngineError(exitCode, result.failure?.message ?? result.error)
          // A stale resume OR a context-window overflow means this session can't
          // be carried forward — drop it AND tear down any persistent process so
          // the next wake starts clean (otherwise --resume re-overflows forever).
          if (engineError && result.failure?.kind !== 'resume-not-found' && this.mustResetSession(engineError, false)) {
            await this.resetEngineSession(this.resetReason(engineError))
          }
        } catch (err) {
          console.error(`[computer] ${this.agent.id} engine spawn failed:`, redactProviderSecret(err instanceof Error ? err.message : String(err), this.provider))
          exitCode = 1
          engineError = this.visibleEngineError(exitCode, err instanceof Error ? (err.stack || err.message) : String(err))
        } finally {
          stopRunBeat()
          if (typingTimer) clearInterval(typingTimer)
          // Per-turn ledger drain (mirrors the agenda finally above).
          this.currentRunId = null
          void this.reporter.flush()
          if (convo) {
            await runtimeBest(this.cfg.serverUrl, '/typing', token, { conversationId: convo, done: true })
            await runtimeBest(this.cfg.serverUrl, '/thinking/unmark', token, { conversationIds: [convo] })
          }
          // Release the semaphore slot regardless of success / error — the
          // next queued agent can now spawn. MUST be in the same finally
          // that runs after the spawn await completes (success / error /
          // abort), otherwise a stuck slot starves the whole computer.
          bigBrainSem.release()
        }
        // Rate-limit case: when the underlying provider (Anthropic / OpenAI)
        // throttles us, this is NOT an agent-visible failure — the unread
        // survives (we skip ackSeen below for any engineError), the next wake
        // re-attempts, and jitter above plus this skip-the-notice keeps the
        // user from seeing a row of "byoa_engine_failed" markers in chat for
        // what is really a transient provider throttle. Persist a quieter
        // signal to the run row instead so it shows up in observability.
        const outcome = classifyTurnOutcome(engineError)
        const rateLimited = outcome === 'rate-limited'
        // An engine nobody has logged into will fail the same way on the next
        // poll, and the one after that. Cool down like a rate limit so the
        // machine stops spinning, but tell the user — a silent backoff on a
        // fixable problem is just a slower way of never working.
        if (outcome === 'operator-fix') {
          console.warn(`[computer] ${this.agent.id} engine needs operator action — pausing ${Math.round(ENGINE_BACKOFF_AFTER_OPERATOR_FIX_MS / 60000)}min: ${engineError?.slice(0, 160)}`)
        }
        if (engineError && !rateLimited) {
          await this.publishEngineFailure({
            token,
            runId: run?.runId,
            conversationId: convo,
            error: engineError,
            exitCode,
          })
        }
        if (engineError && rateLimited) {
          // ENTER cooldown: this agent skips its own turns for the
          // configured window. The unread is kept (no ack, see below);
          // the next wake AFTER the cooldown will pick it up cleanly.
          // Also clear pendingRerun so the do-while loop exits — there's
          // no point in immediately re-attempting against the same throttle.
          // ALSO tell the global adaptive pacer to slow down — multiple
          // agents hitting rate-limit means the current interval is too
          // aggressive for the account's actual burst quota.
          this.pendingRerun = false
          spawnPacer.onRateLimited()
          console.warn(`[computer] ${this.agent.id} engine RATE-LIMITED (sem queue depth was ${semQueueDepth}) — cooling down ${Math.round(ENGINE_BACKOFF_AFTER_RATE_LIMIT_MS / 1000)}s, pacer now ${spawnPacer.intervalMs}ms`)
        } else if (outcome === 'ok') {
          // Clean turn → signal the pacer; the backoff itself is cleared below.
          spawnPacer.onOk()
        }
        this.applyTurnBackoff(outcome)
        if (run?.runId) {
          await runtimeBest(this.cfg.serverUrl, `/runs/${run.runId}/finish`, token, {
            status: exitCode === 0 ? 'completed' : 'failed',
            summary: rateLimited ? `rate-limited (deferred for retry)` : (engineError ?? `byoa ${this.adapter.id} run (exit ${exitCode})`),
            error: rateLimited ? null : engineError,
            model: turnModel ?? this.agent.model,
            usage: turnUsage ? usageFromClaude(turnUsage) : null,
          })
        }
        if (engineError && activeBackgroundBrief) {
          this.pendingBackgroundBrief = mergeWakeBackgroundBriefs(
            activeBackgroundBrief,
            this.pendingBackgroundBrief,
          )
        }
        activeBackgroundBrief = null
        // Clean turn → ack everything this turn saw. If the engine replied it
        // already advanced these cursors (monotonic ack is a no-op then); if it
        // read the room and chose silence, this is what stops the same inbox
        // from re-waking the big brain on the next drain. On engine FAILURE we
        // skip the ack so the unread survives for a retry / next wake.
        if (!engineError) await this.ackSeen(token, seen)
        await this.postStatus(token, 'avail')
        // A chat turn resets the "quiet" anchor: an agent that just acted in chat
        // isn't immediately pulled into an agenda turn (mirrors the cloud idle
        // scheduler only picking agents quiet for N minutes).
        this.lastTurnEndedAt = Date.now()
        console.log(`[computer] ${this.agent.id} turn DONE (${reason}) — total ${Date.now() - turnStart}ms, exit ${exitCode}${this.pendingRerun ? ' · rerun queued' : ''}`)
        reason = 'rerun (coalesced wake)'
      } while (this.pendingRerun && !this.stopped)
    } catch (err) {
      if (activeBackgroundBrief) {
        this.pendingBackgroundBrief = mergeWakeBackgroundBriefs(
          activeBackgroundBrief,
          this.pendingBackgroundBrief,
        )
        activeBackgroundBrief = null
      }
      // A turn-level failure — token mint 502 (e.g. a server pod rolling), a
      // runtime hiccup, a transient network drop — must NEVER escape and crash
      // the daemon, which would take EVERY hosted agent offline at once. Log it
      // and end this turn; the next wake or INBOX_POLL_MS drain retries with a
      // fresh token. (ensureToken is in this try, so its throws land here.)
      console.error(`[computer] ${this.agent.id} turn aborted (will retry on next wake/poll):`,
        err instanceof Error ? err.message : err)
    } finally {
      await this.attachmentCache.endTurn().catch((error) => {
        console.warn(`[computer] ${this.agent.id} attachment cache sweep failed`, error)
      })
      this.busy = false
    }
  }

  /** Hold the wake-stream open; reconnect with backoff. First connect (and
   *  every reconnect) does a catch-up turn — the inbox is durable. */
  private async streamLoop(): Promise<void> {
    let backoff = 1000
    while (!this.stopped) {
      let connectedAt: number | null = null
      const abort = new AbortController()
      this.streamAbort = abort
      try {
        const token = await this.ensureToken()
        const res = await fetch(`${this.cfg.serverUrl}/runtime/wake-stream`, {
          headers: { Authorization: `Bearer ${token}`, Accept: 'text/event-stream' },
          signal: abort.signal,
        })
        if (!res.ok || !res.body) {
          if (res.status === 401 || res.status === 403) this.invalidateToken(token)
          throw new Error(`wake-stream HTTP ${res.status}`)
        }
        console.log(`[computer] ${this.agent.id} wake-stream connected (engine: ${this.adapter.id})`)
        connectedAt = Date.now()
        this.streamLastSeenAt = connectedAt
        this.kickTurn('reconnect-catchup') // cold-start / reconnect catch-up
        // Every event AND every `: ping` comment is proof the stream is alive;
        // the fallback poll (fallbackPollDue) keys off this timestamp.
        const alive = (): void => { this.streamLastSeenAt = Date.now() }
        for await (const evt of parseSseStream(res.body as unknown as AsyncIterable<unknown>, { onComment: alive })) {
          alive()
          if (this.stopped) break
          if (evt.event === 'wake' || evt.event === 'steer') {
            // 'wake': normal new-activity nudge. 'steer': a peer posted while we
            // were mid-turn. We can't inject into the running engine (claude -p
            // has no mid-turn interrupt), but with continuous context (--resume)
            // a catch-up turn re-reads the now-durable message and the agent
            // sees the relay with full memory of its place — so it continues
            // the sequence instead of racing on a stale snapshot. A steer that
            // lands while busy is coalesced into exactly one rerun (pendingRerun).
            const wake = parseWakeData(evt.data)
            const convo = wake.conversationId
            const backgroundBrief = evt.event === 'wake' && wake.options.trigger === 'manual'
              ? wake.options.backgroundBrief ?? null
              : null
            // evt.at = server's publish time. The gap to now is the
            // server→daemon delivery latency (the first place to look when
            // "receiving a message is slow"). Includes any client/server clock
            // skew, so read it as a trend, not an absolute.
            const deliveryMs = wake.at === null ? null : Date.now() - wake.at
            if (convo) this.lastWakeConvo = convo
            const trigger = wake.options.trigger ? `:${wake.options.trigger}` : ''
            console.log(`[computer] ${this.agent.id} SSE ${evt.event}${trigger} received${convo ? ` convo=${convo}` : ''}${backgroundBrief ? ` brief=${backgroundBrief.source ?? 'manual'}` : ''}${deliveryMs != null ? ` deliveryLatency=${deliveryMs}ms` : ''}`)
            this.scheduleWake(`sse-${evt.event}${trigger}`, convo, backgroundBrief)
          }
          // 'ready' is a no-op keepalive.
        }
        // The stream ended WITHOUT throwing — a clean server-side close. This
        // used to fall straight back to the loop head and re-fetch with ZERO
        // delay, re-firing reconnect-catchup every pass: measured at ~15k
        // requests/second against the API from the operator's own machine.
        if (!this.stopped) {
          console.warn(`[computer] ${this.agent.id} wake-stream closed by server · retry in ${backoff}ms`)
        }
      } catch (err) {
        if (this.stopped) break
        const _cause = (err as { cause?: { code?: string; message?: string } } | null)?.cause
        console.warn(`[computer] ${this.agent.id} stream error: ${err instanceof Error ? err.message : err}${_cause ? ` cause=${_cause.code ?? _cause.message ?? JSON.stringify(_cause)}` : ''} · retry in ${backoff}ms`)
      }
      this.streamLastSeenAt = null
      if (this.streamAbort === abort) this.streamAbort = null
      if (this.stopped) break
      // BOTH exits back off. Reset the ladder only after a connection that
      // actually stayed up — a 200 that closes immediately must not reset it, or
      // the delay can never grow away from a pathological endpoint.
      if (wakeStreamWasStable(connectedAt === null ? null : Date.now() - connectedAt)) backoff = 1000
      await new Promise((r) => setTimeout(r, backoff))
      backoff = Math.min(backoff * 2, 30_000)
    }
  }
}

// ─── run loop ───────────────────────────────────────────────────────────

/** Prefix every daemon log line with an ISO-8601 timestamp so the service log
 *  (~/.cumora/daemon.log) is diagnosable: when a wake arrived, how long a turn
 *  took, etc. Only for the long-running daemon (doRun) — the one-shot
 *  --status/--version/--logs commands stay clean. */
/** Cap ~/.cumora/daemon.log so it can't fill the disk. The supervisor (launchd /
 *  systemd) holds the file open in APPEND mode, so we can't rename it (that would
 *  orphan its fd and silently stop logging). Instead we copy-truncate (logrotate's
 *  copytruncate): keep the last full chunk as daemon.log.1, then truncate the live
 *  file IN PLACE — same inode, the supervisor keeps appending to it. Total stays
 *  ~2×MAX. Best-effort and silent when there's no file (a foreground run). */
async function rotateLogsIfNeeded(): Promise<void> {
  try {
    const logPath = join(CONFIG_DIR, 'daemon.log')
    const st = await stat(logPath)
    if (st.size <= MAX_LOG_BYTES) return
    await copyFile(logPath, `${logPath}.1`)
    await truncate(logPath, 0)
    console.log(`[computer] daemon.log passed ${Math.round(MAX_LOG_BYTES / 1048576)}MB — rotated (kept daemon.log.1, truncated live log)`)
  } catch { /* no log file (foreground) or transient FS error — never crash the daemon */ }
}

function installTimestampedLogging(): void {
  const wrap = (fn: (...a: unknown[]) => void): typeof fn => (...a: unknown[]) => fn(new Date().toISOString(), ...a)
  console.log = wrap(console.log.bind(console)) as typeof console.log
  console.warn = wrap(console.warn.bind(console)) as typeof console.warn
  console.error = wrap(console.error.bind(console)) as typeof console.error
}

async function doRun(serverOverride?: string): Promise<void> {
  installTimestampedLogging()
  if (allowUnsandboxedByoa()) {
    console.warn('[computer] SECURITY WARNING: CUMORA_BYOA_ALLOW_UNSANDBOXED=1 — local model engines may read host files, inherit credentials, and use the network')
  } else {
    for (const name of [
      'CUMORA_CLAUDE_ARGS', 'CUMORA_CODEX_ARGS', 'CUMORA_GROK_ARGS',
      'CUMORA_CURSOR_ARGS', 'CUMORA_OPENCODE_ARGS', 'CUMORA_PI_ARGS',
      'CUMORA_GEMINI_ARGS', 'CUMORA_TRIAGE_ARGS',
    ]) {
      if (process.env[name]) console.warn(`[computer] ignoring ${name}: custom engine argv requires CUMORA_BYOA_ALLOW_UNSANDBOXED=1`)
    }
  }
  // Global safety net: a long-running daemon hosting every one of the user's
  // agents must NOT die because one async path threw — a transient 502 from a
  // server pod rolling, a network blip, a malformed event. Node ≥15 turns an
  // unhandled rejection into a fatal exit by default; an uncaught exception is
  // fatal too. We log and KEEP RUNNING so the agents stay online and self-heal
  // on the next wake / poll. Installed once, here at the top of the run loop.
  process.on('unhandledRejection', (reason) => {
    console.error('[computer] unhandledRejection (kept alive):', reason instanceof Error ? reason.stack || reason.message : reason)
  })
  process.on('uncaughtException', (err) => {
    console.error('[computer] uncaughtException (kept alive):', err instanceof Error ? err.stack || err.message : err)
  })

  const cfg = await loadConfig()
  if (!cfg) {
    console.error('[computer] not paired. Run: cumora agent computer --pair <code> [--server <url>]')
    process.exitCode = 1
    return
  }
  if (serverOverride) cfg.serverUrl = serverOverride
  let initialEngines: EngineId[]
  try {
    initialEngines = [...(await requireLocalEngine()).runnable]
  } catch (err) {
    console.error(`[computer] ${err instanceof Error ? err.message : String(err)}`)
    process.exitCode = 70
    return
  }
  const engineInventory: EngineInventory = { current: initialEngines }
  console.log(`[computer] cumora ${CURRENT_VERSION} · starting ${cfg.computerId} @ ${cfg.serverUrl} (engines: ${engineInventory.current.join(', ')})`)
  // Record what THIS process is running, keyed by pid, so `--status` can report
  // the version of the live service instance reliably (cross-checked against the
  // running pid — survives log rotation, no log-scraping).
  const windowsShutdownRequest = process.platform === 'win32'
    ? windowsShutdownRequestPath(process.pid)
    : null
  if (windowsShutdownRequest) await rm(windowsShutdownRequest, { force: true }).catch(() => {})
  await writeRunningState()
  if (!SUPERVISED) {
    console.log(`[computer] 💡 tip: run \`npx cumora@latest agent computer --install-service\` to keep this running in the background — auto-start when you sign in, auto-restart on crash, and auto-update. (This terminal must stay open otherwise.)`)
  }

  const runners = new Map<string, AgentRunner>()
  const codexMigrationFailures = new Map<string, { message: string; reported: Set<string>; token: string; tokenExpiresAt: number }>()
  const engineInventoryStabilizer = new EngineInventoryStabilizer()

  const syncOnce = async (): Promise<void> => {
    let agents: AgentInfo[]
    try {
      agents = await api<AgentInfo[]>(cfg.serverUrl, '/api/computers/me/agents?providerProfiles=1', {
        headers: { Authorization: `Bearer ${cfg.deviceToken}` },
      })
    } catch (err) {
      console.warn('[computer] agent sync failed:', err instanceof Error ? err.message : err)
      return
    }
    const available = engineInventory.current
    let profiles: ProviderProfile[] = []
    try { profiles = readProviderProfiles(join(CONFIG_DIR, 'providers.json')) }
    catch (err) { console.warn('[computer]', (err as Error).message) }
    for (const agent of agents) {
      const provider = profiles.find((p) => p.id === agent.providerProfile)
      // A bound profile must never fall through to another engine or account.
      const engine = agent.providerProfile
        ? (provider && !allowUnsandboxedByoa() && agent.engine === 'claude' && available.includes('claude') ? 'claude' : null)
        : resolveAvailableEngine(agent.engine, available)
      if (agent.providerProfile && !engine) console.warn(`[computer] provider unavailable for ${agent.id}; runner stopped`)
      if (!engine) {
        // A successful rescan may legitimately find that the last installed CLI
        // was removed. Stop an existing runner instead of leaving it alive on an
        // engine this machine no longer has.
        const existing = runners.get(agent.id)
        if (existing) {
          console.log(`[computer] no installed engine remains for ${agent.name} (${agent.id}) → stopping runner`)
          runners.delete(agent.id)
          await existing.stop({ forceEngine: true })
        }
        continue
      }
      const existing = runners.get(agent.id)
      if (existing) {
        if (existing.configMatches(agent, engine, provider)) continue
        // Engine/model/persona was edited in Cumora — restart the runner so the
        // change takes effect on the next wake without a daemon restart.
        console.log(`[computer] agent ${agent.name} (${agent.id}) config changed → restarting on ${engine}`)
        runners.delete(agent.id)
        await existing.stop({ forceEngine: true })
      }
      if (engine === 'codex') {
        try {
          // Migrate before creating a runner or broker. A missing transcript
          // pauses only this agent; retry on the next sync without log spam.
          await migrateCodexSession(agent.id)
          codexMigrationFailures.delete(agent.id)
        } catch (err) {
          const message = err instanceof Error ? err.message : String(err)
          const remedy = `Restore the rollout in the original Codex home, or run \`${CODEX_MIGRATE_COMMAND}\` with CODEX_HOME set to that home. Migration retries automatically.`
          let failure = codexMigrationFailures.get(agent.id)
          if (!failure || failure.message !== message) {
            failure = { message, reported: new Set(), token: '', tokenExpiresAt: 0 }
            codexMigrationFailures.set(agent.id, failure)
            console.error(`[computer] ${agent.id} paused: ${message} ${remedy}`)
          }
          try {
            if (!failure.token || Date.now() >= failure.tokenExpiresAt - TOKEN_REFRESH_SKEW_MS) {
              const { token, expiresInSeconds } = await api<{ token: string; expiresInSeconds: number }>(cfg.serverUrl, `/api/agents/${agent.id}/runtime-token`, {
                method: 'POST', headers: { Authorization: `Bearer ${cfg.deviceToken}` },
                body: JSON.stringify({ providerProfile: agent.providerProfile ?? null }),
              })
              failure.token = token
              failure.tokenExpiresAt = Date.now() + expiresInSeconds * 1000
            }
            const { token, reported } = failure
            const conversationIds = await failureConversationIds(cfg.serverUrl, token, null)
            await Promise.all(conversationIds.filter(id => !reported.has(id)).map(async conversationId => {
              const result = await runtimeBest(cfg.serverUrl, '/notices', token, {
                conversationId,
                noticeKind: 'byoa_engine_failed',
                text: `${agent.name} is paused because its Codex session could not be migrated: ${conciseError(message).split(homedir()).join('~')}\n${remedy}`,
                dedupeKey: `codex_migration_failed:${agent.id}:${conversationId}:${hashText(message)}`,
                dedupeTtlSec: 900,
              })
              if (result !== null) reported.add(conversationId)
            }))
          } catch { /* Retry notification on the next sync without blocking other agents. */ }
          continue
        }
      }
      const runner = new AgentRunner(cfg, agent, engine, provider)
      runners.set(agent.id, runner)
      console.log(`[computer] hosting agent ${agent.name} (${agent.id}) on ${engine}`)
      await runner.start()
    }
    // Agents removed from this computer: stop their runners.
    const live = new Set(agents.map((a) => a.id))
    for (const id of codexMigrationFailures.keys()) {
      if (!live.has(id)) codexMigrationFailures.delete(id)
    }
    for (const [id, runner] of runners) {
      if (!live.has(id)) {
        runners.delete(id)
        await runner.stop({ forceEngine: true, purgeAttachments: true })
      }
    }
  }

  // Poll ticks and reconnects can overlap. Serialize reconciliation so a later
  // pass cannot create a replacement while the prior pass is still awaiting
  // termination of that Agent's old process tree.
  let syncInFlight: Promise<void> | null = null
  const sync = (): Promise<void> => {
    if (syncInFlight) return syncInFlight
    const running = syncOnce().finally(() => {
      if (syncInFlight === running) syncInFlight = null
    })
    syncInFlight = running
    return running
  }

  // Last snapshot we successfully described to the server, as a JSON fingerprint.
  let lastEngineSnapshot = ''
  let lastCapabilityWarning = ''

  // Engines this machine can currently run, re-scanned on a slow timer. Reported
  // on every heartbeat so installing another supported CLI takes effect without
  // re-pairing — the daemon is already online and can see PATH itself, so there
  // is no reason to make the user mint a new pairing token for it.
  const scanEnginesOnce = async (forceReport: boolean): Promise<void> => {
    try {
      const detected = await detectEnginesWithStatus()
      if (!detected.reliable) return  // broken `which` / `where` — keep the last good list
      const evaluated = await evaluateRunnableEngines(detected.engines)
      const next = engineInventoryStabilizer.stabilize(engineInventory.current, detected.engines, evaluated)
      const blocked = evaluated.blocked.filter(({ id }) => !next.includes(id))
      const retainedTransient = [...new Set([
        ...evaluated.temporarilyUnverifiable ?? [],
        ...evaluated.blocked.filter(({ id, state }) => state === 'temporarily-unverifiable' && next.includes(id)).map(({ id }) => id),
      ])]
      const capabilityWarning = [
        ...blocked.map(({ id, reason }) => `${id} (${reason})`),
        ...retainedTransient.map((id) => `${id} (version temporarily unverifiable; retaining last-known-good availability)`),
      ].join('; ')
      if (capabilityWarning !== lastCapabilityWarning) {
        lastCapabilityWarning = capabilityWarning
        if (capabilityWarning) console.warn(`[computer] secure engine capability update: ${capabilityWarning}`)
      }
      const previous = engineInventory.current
      const changed = replaceEngineInventory(engineInventory, next)
      if (changed) {
        console.log(`[computer] engines on PATH changed: ${previous.join(', ') || 'none'} → ${next.join(', ') || 'none'}`)
      }
      // Heartbeat already advertises the live inventory. This snapshot is
      // only the PATH display the app reads — pairable engines, never the
      // detect-only bins Electron lists on the Me page. It carries each
      // engine's version *as installed on this machine*: the app renders it
      // verbatim and never probes its own PATH, because whoever is looking at
      // the card is usually not sitting at the machine it describes.
      // Blocked engines ride along as extra display rows carrying the reason
      // they were refused. Until now that reason existed only as the
      // console.warn above — on a machine the operator is usually not sitting
      // at — so an engine could disappear from the card with no explanation
      // anywhere they could see. They stay OUT of `next`: that list becomes
      // available_engines and picks an agent's adapter.
      const blockedIds = blocked.map(({ id }) => id)
      // One enrich over the whole list: it maps entry-by-entry, so splitting it
      // bought nothing and only risked the two halves drifting apart.
      const snapshot = await enrichDetectedEngines([
        ...await snapshotDetectedEngines(next),
        ...await blockedSnapshotRows(blocked),
      ], forceReport)
      // Report on version drift too, not just install/uninstall — upgrading an
      // engine in place leaves the engine *list* identical, and that is exactly
      // when the card's version line goes stale. The blocked reasons are part
      // of the fingerprint: fixing the cause (upgrading the CLI, installing
      // bwrap) has to clear the card, not wait for an unrelated change.
      let profiles: ProviderProfile[] = []
      try { profiles = readProviderProfiles(join(CONFIG_DIR, 'providers.json')) }
      catch (err) { console.warn('[computer]', (err as Error).message) }
      const advertisedSnapshot = snapshot.map((entry) => entry.id === 'claude'
        ? { ...entry, providerProfiles: allowUnsandboxedByoa() ? [] : profiles.map(providerProfileMetadata) } : entry)
      const fingerprint = JSON.stringify(advertisedSnapshot)
      lastEngineSnapshot = await reportEngineSnapshot(
        fingerprint,
        lastEngineSnapshot,
        forceReport,
        () => api(cfg.serverUrl, '/api/computers/me/engines', {
          method: 'POST',
          headers: { Authorization: `Bearer ${cfg.deviceToken}` },
          body: JSON.stringify({ engines: next, detected: advertisedSnapshot, blocked: blockedIds }),
        }),
      )
      // This is the same live inventory sync() uses to choose an agent's
      // adapter. Updating only a heartbeat cache would advertise a newly
      // installed engine while silently running that agent on the old default.
    } catch (err) {
      // Transient — the next tick retries, and that is now true of the report
      // above too. Say so anyway: a scan failing every five minutes for a
      // non-transient reason used to leave no trace anywhere.
      console.warn('[computer] engine scan failed:', err instanceof Error ? err.message : err)
    }
  }

  // Timer/startup/requested scans can land together. Share an in-flight scan;
  // if a forced request arrives during it, run once more so its acknowledgement
  // cannot be swallowed by the older scan finishing afterward.
  const rescanEngines = createEngineRescanQueue(scanEnginesOnce)

  const heartbeat = async (): Promise<void> => {
    try {
      const response = await fetch(`${cfg.serverUrl}/api/computers/heartbeat`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${cfg.deviceToken}` },
        // A heartbeat that never answers must not outlive its own interval, or
        // the beats queue up behind a dead socket and the computer reads offline.
        signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
        // `supervised` tells the server HOW this daemon runs (service vs. a
        // foreground command), so the app's upgrade banner can show the right
        // update instructions for this machine.
        body: JSON.stringify({ version: CURRENT_VERSION, supervised: SUPERVISED, engines: engineInventory.current }),
      })
      if (!response.ok) return
      const heartbeatResult = await response.json().catch(() => null) as { detectRequested?: boolean } | null
      if (heartbeatResult?.detectRequested) void rescanEngines(true)
    } catch { /* transient — next tick retries */ }
  }

  let shuttingDown = false
  // Serialize control events; the server refuses a second pending update.
  //
  // shortcut: an update is not deferred until agents are idle, so on Windows it
  // can lose to a CLI that is mid-turn (EPERM); the card then still reads
  // outdated and the daemon log says why. Upgrade to an idle wait if that shows
  // up in practice.
  let updating = Promise.resolve()
  const updateEngine = (id: string, requestId: string): Promise<void> => {
    if (!ENGINE_IDS.includes(id as EngineId)) return updating
    updating = updating.then(async () => {
      const report = (status: 'running' | 'succeeded' | 'failed', error?: string) =>
        api(cfg.serverUrl, `/api/computers/me/engine-updates/${encodeURIComponent(requestId)}`, {
          method: 'POST',
          headers: { Authorization: `Bearer ${cfg.deviceToken}` },
          body: JSON.stringify({ status, error }),
        })
      // Claim before starting: another stream/process must not run this twice.
      try { await report('running') }
      catch (err) {
        console.warn(`[computer] ${id} update was not accepted:`, err instanceof Error ? err.message : err)
        return
      }
      let result: { ok: boolean; error?: string }
      try {
        const entry = (await snapshotDetectedEngines([id as EngineId]))[0]
        const updated = await runEngineUpdate(id, entry?.path ?? null)
        result = updated
        if (!updated.ok) console.warn(`[computer] ${id} update failed (${updated.command}): ${updated.error}`)
        else console.log(`[computer] ${id} updated: ${updated.command}`)
      } catch (err) {
        result = { ok: false, error: err instanceof Error ? err.message : String(err) }
        console.warn(`[computer] ${id} update failed:`, result.error)
      }
      await rescanEngines(true).catch(() => {})
      await report(result.ok ? 'succeeded' : 'failed', result.error)
    }).catch((err) => {
      console.warn(`[computer] ${id} update result could not be reported:`, err instanceof Error ? err.message : err)
    })
    return updating
  }
  const controlStreamAbort = new AbortController()
  const controlStreamLoop = async (): Promise<void> => {
    let backoff = 1000
    while (!shuttingDown) {
      let connectedAt: number | null = null
      try {
        const response = await fetch(`${cfg.serverUrl}/api/computers/me/control-stream`, {
          headers: { Authorization: `Bearer ${cfg.deviceToken}`, Accept: 'text/event-stream' },
          signal: controlStreamAbort.signal,
        })
        if (!response.ok || !response.body) throw new Error(`computer control-stream HTTP ${response.status}`)
        connectedAt = Date.now()
        console.log('[computer] control-stream connected')
        for await (const event of parseSseStream(response.body as unknown as AsyncIterable<unknown>)) {
          if (shuttingDown) break
          if (event.event === 'ready') {
            // Pick up a durable request that may have been persisted while this
            // stream was disconnected, without waiting for the next 30s tick.
            void heartbeat()
            continue
          }
          const signal = event.data ? parseComputerControlEvent(event.data) : null
          if (signal?.kind === 'engine.detect') void rescanEngines(true)
          else if (signal?.kind === 'engine.update') void updateEngine(signal.engine, signal.id)
        }
        if (!shuttingDown) console.warn(`[computer] control-stream closed by server · retry in ${backoff}ms`)
      } catch (error) {
        if (shuttingDown || controlStreamAbort.signal.aborted) break
        console.warn(`[computer] control-stream error: ${error instanceof Error ? error.message : String(error)} · retry in ${backoff}ms`)
      }
      if (shuttingDown) break
      if (wakeStreamWasStable(connectedAt === null ? null : Date.now() - connectedAt)) backoff = 1000
      await new Promise((resolve) => setTimeout(resolve, backoff))
      backoff = Math.min(backoff * 2, 30_000)
    }
  }

  await heartbeat()
  await sync()
  if (runners.size === 0) {
    console.log('[computer] no agents assigned to this computer yet. Assign one in Cumora; polling…')
  }
  const poll = setInterval(() => { void sync() }, AGENT_POLL_MS)
  const beat = setInterval(() => { void heartbeat() }, HEARTBEAT_MS)
  const rescan = setInterval(() => { void rescanEngines() }, ENGINE_RESCAN_MS)
  rescan.unref?.()
  // Pairing reports a cheap paths-only snapshot so the user is not kept waiting
  // on CLI spawns. Fill in the versions right after startup instead of leaving
  // the card blank until the first 5-minute tick.
  void rescanEngines()
  void controlStreamLoop()
  // Keep the service log from filling the disk: rotate at boot, then periodically.
  void rotateLogsIfNeeded()
  const logrot = setInterval(() => { void rotateLogsIfNeeded() }, LOG_ROTATE_MS)
  logrot.unref?.()

  let upd: ReturnType<typeof setInterval> | undefined
  let idleWatch: ReturnType<typeof setInterval> | undefined
  let controlWatch: ReturnType<typeof setInterval> | undefined
  const anyBusy = (): boolean => [...runners.values()].some((r) => r.isBusy)

  // Graceful shutdown: stop accepting new wakes, give any in-flight turn a brief
  // window to FINISH (so it persists its session id + finalizes its run) before we
  // kill the engine child. A long task won't finish in the window and gets killed,
  // but its session id is on disk → the relaunched daemon `--resume`s it.
  const shutdown = async (why: string): Promise<void> => {
    if (shuttingDown) return
    shuttingDown = true
    controlStreamAbort.abort()
    clearInterval(poll); clearInterval(beat); clearInterval(logrot); clearInterval(rescan)
    if (upd) clearInterval(upd)
    if (idleWatch) clearInterval(idleWatch)
    if (controlWatch) clearInterval(controlWatch)
    if (windowsShutdownRequest) await rm(windowsShutdownRequest, { force: true }).catch(() => {})
    for (const runner of runners.values()) runner.beginStop() // no new turns; leave in-flight running
    const deadline = Date.now() + SHUTDOWN_GRACE_MS
    if (anyBusy()) console.log(`[computer] ${why}: waiting up to ${Math.round(SHUTDOWN_GRACE_MS / 1000)}s for in-flight turn(s) to finish…`)
    while (anyBusy() && Date.now() < deadline) await new Promise((r) => setTimeout(r, 500))
    // process.exit() follows immediately, so engine-specific delayed fallbacks
    // cannot run. Force each child to receive its termination signal first.
    await Promise.all([...runners.values()].map((runner) => runner.stop({ forceEngine: true })))
    console.log(`[computer] shutting down (${why})`)
    process.exit(0)
  }
  process.on('SIGINT', () => { void shutdown('SIGINT') })
  process.on('SIGTERM', () => { void shutdown('SIGTERM') })
  if (windowsShutdownRequest) {
    controlWatch = setInterval(() => {
      if (existsSync(windowsShutdownRequest)) void shutdown('service control')
    }, 250)
    controlWatch.unref?.()
  }

  // Self-update: compare to npm's latest periodically. When supervised
  // (--install-service), a clean exit relaunches the service on cumora@latest =
  // the update. Crucially we do NOT interrupt a live turn for a (non-urgent)
  // update: once an update is detected we wait for ALL agents to go idle, then
  // exit. First check a minute after boot, then every UPDATE_CHECK_MS.
  let updateReady = false
  const exitForUpdateWhenIdle = (): void => {
    if (!updateReady || shuttingDown) return
    if (anyBusy()) return // mid-turn — defer; the idle watch retries
    void shutdown('auto-update')
  }
  const runUpdateCheck = (): void => {
    void checkForUpdate(() => {
      if (!updateReady) {
        updateReady = true
        console.log('[computer] update ready — will restart to apply it as soon as all agents are idle')
      }
      exitForUpdateWhenIdle()
    })
  }
  upd = setInterval(runUpdateCheck, UPDATE_CHECK_MS)
  idleWatch = setInterval(exitForUpdateWhenIdle, 30_000); idleWatch.unref?.()
  setTimeout(runUpdateCheck, 60_000).unref?.()
}

// ─── self-update + service ────────────────────────────────────────────────

/** Compare the running version to npm's `latest`. If behind: when supervised,
 *  exit cleanly so the service relaunches on `cumora@latest` (= the update);
 *  otherwise just log that an update is available. Never throws. */
async function checkForUpdate(onSupervisedUpdate: () => void): Promise<void> {
  try {
    const res = await fetch('https://registry.npmjs.org/cumora/latest', { headers: { Accept: 'application/json' } })
    if (!res.ok) return
    const latest = (await res.json() as { version?: string })?.version
    if (typeof latest !== 'string' || !versionGt(latest, CURRENT_VERSION)) return
    if (SUPERVISED) {
      console.log(`[computer] 🆕 cumora ${latest} available (running ${CURRENT_VERSION}) — will restart to apply once idle (in-flight turns are never interrupted for an update)`)
      onSupervisedUpdate()
    } else {
      console.log(`[computer] 🆕 cumora ${latest} available (running ${CURRENT_VERSION}). Restart to update, or run \`cumora agent computer --install-service\` for auto-updates.`)
    }
  } catch { /* offline / npm hiccup — try the next tick */ }
}

/** Absolute path to npx next to the node that's running us, so the supervisor
 *  doesn't depend on its (minimal) PATH resolving `npx`. Falls back to PATH. */
export function resolveNpx(
  platform: NodeJS.Platform = process.platform,
  execPath = process.execPath,
): string {
  const executable = platform === 'win32' ? 'npx.cmd' : 'npx'
  const sibling = join(dirname(execPath), executable)
  return existsSync(sibling) ? sibling : executable
}

function windowsSupervisorPath(): string {
  return join(CONFIG_DIR, 'daemon-supervisor.ps1')
}

function windowsSupervisorLauncherPath(): string {
  return join(CONFIG_DIR, 'daemon-supervisor.vbs')
}

function windowsSupervisorDisabledPath(): string {
  return join(CONFIG_DIR, 'daemon-supervisor.disabled')
}

function windowsShutdownRequestPath(pid: number): string {
  return join(CONFIG_DIR, `shutdown-${pid}.request`)
}

function quotePowerShell(value: string): string {
  return `'${value.replaceAll("'", "''")}'`
}

/** The scheduled task starts this watchdog at login. It deliberately restarts
 *  after every daemon exit, including the clean exit used to apply an update. */
export function renderWindowsSupervisor(
  npx: string,
  serverUrl: string,
  logPath: string,
  disabledPath = windowsSupervisorDisabledPath(),
  path = process.env.PATH ?? '',
  // Carried only when the machine has nothing runnable without it — see
  // _needsUnsandboxedOptIn. Dropping it makes the supervised daemon exit 70 on
  // every start, and this loop restarts it every 5 seconds forever.
  carryUnsandboxed = false,
): string {
  return [
    "$ErrorActionPreference = 'Continue'",
    "$env:CUMORA_SUPERVISED = '1'",
    ...(carryUnsandboxed ? ["$env:CUMORA_BYOA_ALLOW_UNSANDBOXED = '1'"] : []),
    `$env:PATH = ${quotePowerShell(path)}`,
    '$utf8 = New-Object System.Text.UTF8Encoding($false)',
    `while (-not (Test-Path -LiteralPath ${quotePowerShell(disabledPath)})) {`,
    `  & ${quotePowerShell(npx)} -y cumora@latest agent computer --server ${quotePowerShell(serverUrl)} 2>&1 | ForEach-Object {`,
    `    [System.IO.File]::AppendAllText(${quotePowerShell(logPath)}, ([string]$_ + [Environment]::NewLine), $utf8)`,
    '  }',
    '  Start-Sleep -Seconds 5',
    '}',
    '',
  ].join('\r\n')
}

function quoteVbScript(value: string): string {
  return `"${value.replaceAll('"', '""')}"`
}

/** Task Scheduler's interactive PowerShell action can still acquire a visible
 *  Windows Terminal host on Windows 11, even with `-WindowStyle Hidden`. Launch
 *  through the GUI-subsystem wscript.exe instead; WScript.Shell.Run's window
 *  style 0 keeps PowerShell and its watchdog process tree hidden from birth. */
export function renderWindowsSupervisorLauncher(scriptPath: string): string {
  const command = `powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -WindowStyle Hidden -File "${scriptPath.replaceAll('"', '""')}"`
  return [
    'Set shell = CreateObject("WScript.Shell")',
    // Wait for the watchdog so Task Scheduler keeps the task in Running state
    // and refuses duplicate /Run requests while this supervisor is alive.
    `shell.Run ${quoteVbScript(command)}, 0, True`,
    '',
  ].join('\r\n')
}

export function windowsScheduledTaskCommand(launcherPath: string): string {
  return `wscript.exe //B //Nologo "${launcherPath.replaceAll('"', '""')}"`
}

export function windowsScheduledTaskCreateArgs(
  launcherPath: string,
  taskName = windowsTaskName(),
): string[] {
  return [
    '/Create', '/TN', taskName,
    '/TR', windowsScheduledTaskCommand(launcherPath),
    '/SC', 'ONLOGON', '/RL', 'LIMITED', '/IT', '/F',
  ]
}

export function windowsScheduledTaskSettingsCommand(taskName = windowsTaskName()): string {
  return `$settings = New-ScheduledTaskSettingsSet -ExecutionTimeLimit ([TimeSpan]::Zero) -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -StartWhenAvailable; Set-ScheduledTask -TaskName ${quotePowerShell(taskName)} -Settings $settings | Out-Null`
}

export function windowsScheduledTaskQueryCommand(taskName = windowsTaskName()): string {
  return `try { Get-ScheduledTask -TaskName ${quotePowerShell(taskName)} -ErrorAction Stop | Out-Null; exit 0 } catch { if ($_.FullyQualifiedErrorId -like 'CmdletizationQuery_NotFound_TaskName,*') { exit 3 }; Write-Error $_; exit 1 }`
}

async function isWindowsTaskInstalled(taskName = windowsTaskName()): Promise<boolean> {
  try {
    await execFileP('powershell.exe', [
      '-NoProfile', '-NonInteractive', '-Command', windowsScheduledTaskQueryCommand(taskName),
    ])
    return true
  } catch (err) {
    if (String((err as { code?: number | string }).code) === '3') return false
    throw err
  }
}

/** Install a per-user supervisor (LaunchAgent on macOS, systemd --user on
 *  Linux, Task Scheduler on Windows) that runs
 *  `npx -y cumora@latest agent computer --server <url>` with auto-restart +
 *  start-at-login. `@latest` + restart-on-update is what makes the daemon
 *  self-update (see checkForUpdate). Must be paired first. */
/** Does the supervised daemon need the unsandboxed compatibility opt-in to
 *  start at all?
 *
 *  The service definitions carry only PATH and CUMORA_SUPERVISED, so an opt-in
 *  that was set in the shell is dropped at install time. For a user whose only
 *  engine is a compatibility one (grok, cursor, gemini, qwen, opencode, pi,
 *  antigravity) that is fatal and silent: pairing succeeds in the foreground,
 *  the daemon then prints "run --install-service to keep this running", and the
 *  service it installs starts with an empty runnable set, exits 70, and is
 *  restarted forever by KeepAlive / Restart=always / Task Scheduler.
 *
 *  Answered by asking the real gate with the flag removed, so the flag is only
 *  ever persisted when dropping it would actually break the service — not
 *  baked into a background service because it happened to be set in the shell
 *  of someone whose secure engines were fine all along. */
export async function _needsUnsandboxedOptIn(env: NodeJS.ProcessEnv = process.env): Promise<boolean> {
  if (!allowUnsandboxedByoa(env)) return false
  try {
    const detected = await detectEnginesWithStatus()
    if (!detected.reliable || detected.engines.length === 0) return false
    const without = { ...env, CUMORA_BYOA_ALLOW_UNSANDBOXED: '' }
    const evaluated = await evaluateRunnableEngines(detected.engines, without)
    return evaluated.runnable.length === 0
  } catch {
    // Never let the probe stop an install. Not carrying the flag is the
    // status quo, and --status/--logs will show the exit 70 if it matters.
    return false
  }
}

async function installService(serverUrl: string): Promise<void> {
  if (!(await loadConfig())) {
    throw new Error('pair this computer first: cumora agent computer --pair <code>')
  }
  const npx = resolveNpx()
  const logPath = join(CONFIG_DIR, 'daemon.log')
  await mkdir(CONFIG_DIR, { recursive: true })
  const carryUnsandboxed = await _needsUnsandboxedOptIn()
  if (carryUnsandboxed) {
    console.warn('[computer] this machine has no secure engine, so the background service will')
    console.warn('[computer] carry CUMORA_BYOA_ALLOW_UNSANDBOXED=1 — without it the service exits 70')
    console.warn('[computer] on every start. Local engines may read host files and use the network.')
    console.warn('[computer] To undo: cumora agent computer --uninstall-service')
  }

  if (process.platform === 'darwin') {
    const dir = join(homedir(), 'Library', 'LaunchAgents')
    await mkdir(dir, { recursive: true })
    const plistPath = join(dir, `${SERVICE_LABEL}.plist`)
    const args = [npx, '-y', 'cumora@latest', 'agent', 'computer', '--server', serverUrl]
    const plist = `<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict>
  <key>Label</key><string>${SERVICE_LABEL}</string>
  <key>ProgramArguments</key><array>${args.map((a) => `<string>${a}</string>`).join('')}</array>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>StandardOutPath</key><string>${logPath}</string>
  <key>StandardErrorPath</key><string>${logPath}</string>
  <key>EnvironmentVariables</key><dict>
    <key>PATH</key><string>${process.env.PATH ?? ''}</string>
    <key>CUMORA_SUPERVISED</key><string>1</string>${carryUnsandboxed ? '\n    <key>CUMORA_BYOA_ALLOW_UNSANDBOXED</key><string>1</string>' : ''}
  </dict>
</dict></plist>
`
    await writeFile(plistPath, plist, 'utf8')
    await execFileP('launchctl', ['unload', plistPath]).catch(() => { /* not loaded yet */ })
    await execFileP('launchctl', ['load', plistPath])
    console.log(`[computer] installed LaunchAgent ${SERVICE_LABEL} — auto-start, auto-restart, auto-update. Logs: ${logPath}`)
    console.log(`[computer] you can now close this terminal; the service is running in the background.`)
    return
  }

  if (process.platform === 'linux') {
    const dir = join(homedir(), '.config', 'systemd', 'user')
    await mkdir(dir, { recursive: true })
    const unitPath = join(dir, 'cumora.service')
    const unit = `[Unit]
Description=Cumora BYOA daemon
After=network-online.target

[Service]
ExecStart=${npx} -y cumora@latest agent computer --server ${serverUrl}
Restart=always
RestartSec=5
Environment=PATH=${process.env.PATH ?? ''}
Environment=CUMORA_SUPERVISED=1${carryUnsandboxed ? '\nEnvironment=CUMORA_BYOA_ALLOW_UNSANDBOXED=1' : ''}

[Install]
WantedBy=default.target
`
    await writeFile(unitPath, unit, 'utf8')
    await execFileP('systemctl', ['--user', 'daemon-reload'])
    await execFileP('systemctl', ['--user', 'enable', '--now', 'cumora'])
    console.log(`[computer] installed systemd --user service 'cumora' — auto-start, auto-restart, auto-update. Logs: journalctl --user -u cumora -f`)
    return
  }

  if (process.platform === 'win32') {
    const scriptPath = windowsSupervisorPath()
    const launcherPath = windowsSupervisorLauncherPath()
    const disabledPath = windowsSupervisorDisabledPath()
    const taskName = windowsTaskName()
    const replacing = await isWindowsTaskInstalled(taskName)
    await writeFile(scriptPath, renderWindowsSupervisor(npx, serverUrl, logPath, disabledPath, process.env.PATH ?? '', carryUnsandboxed), 'utf8')
    await writeFile(launcherPath, renderWindowsSupervisorLauncher(scriptPath), 'utf8')
    try {
      // Always recreate with /F: an existing task may still point at the old
      // direct-PowerShell action, so merely replacing the scripts is not enough.
      await execFileP('schtasks.exe', windowsScheduledTaskCreateArgs(launcherPath, taskName))
      await execFileP('powershell.exe', [
        '-NoProfile', '-NonInteractive', '-Command', windowsScheduledTaskSettingsCommand(taskName),
      ])
    } catch (err) {
      if (!replacing) {
        try {
          await execFileP('schtasks.exe', ['/Delete', '/TN', taskName, '/F'])
        } catch (rollbackErr) {
          throw new Error(`scheduled task setup failed and rollback could not delete '${taskName}'; the watchdog script was kept in place (${rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr)})`, { cause: err })
        }
        await rm(scriptPath, { force: true }).catch(() => {})
        await rm(launcherPath, { force: true }).catch(() => {})
      }
      throw err
    }
    await writeFile(disabledPath, '', 'utf8')
    await killRunningDaemons()
    await stopWindowsWatchdog(taskName)
    // The old watchdog could have spawned a daemon between the first process
    // sweep and its own exit. Sweep once more only after it cannot relaunch one.
    await killRunningDaemons()
    await rm(disabledPath, { force: true })
    try {
      await execFileP('schtasks.exe', ['/Run', '/TN', taskName])
    } catch (err) {
      throw new Error(`scheduled task installed but could not be started; retry with --restart (${err instanceof Error ? err.message : String(err)})`)
    }
    console.log(`[computer] installed scheduled task '${taskName}' — start-at-login, auto-restart, auto-update. Logs: ${logPath}`)
    console.log(`[computer] you can now close this terminal; the task is running in the background.`)
    return
  }

  throw new Error(`--install-service is not supported on ${process.platform}`)
}

async function uninstallService(): Promise<void> {
  if (process.platform === 'darwin') {
    const plistPath = join(homedir(), 'Library', 'LaunchAgents', `${SERVICE_LABEL}.plist`)
    await execFileP('launchctl', ['unload', plistPath]).catch(() => { /* already gone */ })
    await rm(plistPath).catch(() => { /* already gone */ })
    console.log(`[computer] removed LaunchAgent ${SERVICE_LABEL}`)
    return
  }
  if (process.platform === 'linux') {
    await execFileP('systemctl', ['--user', 'disable', '--now', 'cumora']).catch(() => { /* already gone */ })
    await rm(join(homedir(), '.config', 'systemd', 'user', 'cumora.service')).catch(() => { /* already gone */ })
    await execFileP('systemctl', ['--user', 'daemon-reload']).catch(() => {})
    console.log(`[computer] removed systemd --user service 'cumora'`)
    return
  }
  if (process.platform === 'win32') {
    const taskName = windowsTaskName()
    const disabledPath = windowsSupervisorDisabledPath()
    await mkdir(CONFIG_DIR, { recursive: true })
    await writeFile(disabledPath, '', 'utf8')
    if (await isWindowsTaskInstalled(taskName)) {
      await execFileP('schtasks.exe', ['/Delete', '/TN', taskName, '/F'])
    }
    await killRunningDaemons()
    await stopWindowsWatchdog(taskName)
    await killRunningDaemons()
    if (await isWindowsTaskInstalled(taskName)) {
      throw new Error(`scheduled task '${taskName}' still exists after deletion`)
    }
    await rm(windowsSupervisorPath(), { force: true })
    await rm(windowsSupervisorLauncherPath(), { force: true })
    // Keep this sentinel on every failed stop path so a surviving watchdog
    // cannot revive a daemon after the command has reported an error.
    await rm(disabledPath, { force: true })
    console.log(`[computer] removed scheduled task '${taskName}'`)
    return
  }
  throw new Error(`--uninstall-service is not supported on ${process.platform}`)
}

function darwinPlistPath(): string {
  return join(homedir(), 'Library', 'LaunchAgents', `${SERVICE_LABEL}.plist`)
}
function linuxUnitPath(): string {
  return join(homedir(), '.config', 'systemd', 'user', 'cumora.service')
}

/** Is the background supervisor already installed on this machine? */
async function isServiceInstalled(): Promise<boolean> {
  if (process.platform === 'darwin') return existsSync(darwinPlistPath())
  if (process.platform === 'linux') return existsSync(linuxUnitPath())
  if (process.platform === 'win32') return isWindowsTaskInstalled()
  return false
}

/** Restart the already-installed service so it re-reads computer.json — used
 *  after a re-pair so the running service adopts the new config instead of a
 *  second foreground daemon racing it. */
async function reloadService(): Promise<void> {
  if (process.platform === 'darwin') {
    const p = darwinPlistPath()
    await execFileP('launchctl', ['unload', p]).catch(() => {})
    await execFileP('launchctl', ['load', p])
    return
  }
  if (process.platform === 'linux') {
    await execFileP('systemctl', ['--user', 'restart', 'cumora'])
    return
  }
  if (process.platform === 'win32') {
    const taskName = windowsTaskName()
    const disabledPath = windowsSupervisorDisabledPath()
    await mkdir(CONFIG_DIR, { recursive: true })
    await writeFile(disabledPath, '', 'utf8')
    await killRunningDaemons()
    await stopWindowsWatchdog(taskName)
    await killRunningDaemons()
    await rm(disabledPath, { force: true })
    await execFileP('schtasks.exe', ['/Run', '/TN', taskName])
  }
}

/** `--restart`: a friendly wrapper so users don't have to remember
 *  `launchctl kickstart …`. Restarts the installed service (which relaunches on
 *  cumora@latest, so it's also the "apply the update now" button). */
interface RestartServiceHooks {
  platform?: NodeJS.Platform
  isServiceInstalled?: () => Promise<boolean>
  loadConfig?: () => Promise<DaemonConfig | null>
  installService?: (serverUrl: string) => Promise<void>
  reloadService?: () => Promise<void>
}

export async function restartService(hooks: RestartServiceHooks = {}): Promise<void> {
  const platform = hooks.platform ?? process.platform
  const serviceInstalled = hooks.isServiceInstalled ?? isServiceInstalled
  if (!(await serviceInstalled())) {
    console.log('[computer] service not installed — run: npx cumora@latest agent computer --install-service')
    return
  }
  if (platform === 'win32') {
    const cfg = await (hooks.loadConfig ?? loadConfig)()
    if (!cfg) throw new Error('pair this computer first: cumora agent computer --pair <code>')
    await (hooks.installService ?? installService)(cfg.serverUrl)
    console.log('[computer] Windows service refreshed and restarted — its supervisor now launches cumora@latest')
  } else if (platform === 'darwin') {
    const uid = process.getuid?.() ?? 0
    try {
      await execFileP('launchctl', ['kickstart', '-k', `gui/${uid}/${SERVICE_LABEL}`])
    } catch {
      await (hooks.reloadService ?? reloadService)() // not currently loaded → load it
    }
  } else if (platform === 'linux') {
    await (hooks.reloadService ?? reloadService)()
  } else {
    throw new Error(`--restart is not supported on ${platform}`)
  }
  if (platform !== 'win32') {
    console.log('[computer] service restarted — it relaunches on cumora@latest (also applies any pending update). Check: npx cumora@latest agent computer --status')
  }
}

/** `--stop`: stop the background service NOW, without uninstalling it. The job is
 *  removed from the supervisor so KeepAlive/Restart won't relaunch it; the
 *  plist/unit stays on disk, so `--restart` brings it back. (To remove it
 *  entirely, use `--uninstall-service`.) */

/** One-shot CLI invocations: these do a thing and exit, so they are never the
 *  long-running daemon we mean to stop. Anchored to the `--` so the words can't
 *  match incidentally elsewhere in the command line. */
export const ONE_SHOT_FLAGS = [
  'stop', 'status', 'restart', 'logs', 'version', 'install-service',
  'uninstall-service', 'pair', 'doctor', 'provider', 'help',
  'codex-login', 'migrate-codex-sessions',
] as const
const ONE_SHOT_FLAG_RE = new RegExp(`--(?:${ONE_SHOT_FLAGS.join('|')})\\b`)

/** `--doctor` and `--help` also answer to bare `doctor` / `help` (parseArgs
 *  accepts both spellings), and those forms carry no `--` to anchor on. Anchor
 *  them to the command instead of matching the bare word, so a path like
 *  /opt/doctor-tools/ still reads as a daemon — the same rule the `--`
 *  anchoring exists for. */
const ONE_SHOT_SUBCOMMAND_RE = /\bagent computer (?:doctor|help)\b/

/** Is this `ps`-reported command line a long-running BYOA daemon that `--stop`
 *  should kill? True only for `agent computer` with no one-shot flag.
 *
 *  The npx *wrapper* used to be excluded here too, but that exclusion was both
 *  wrong and unnecessary: `npx -y cumora@latest agent computer --server …` is
 *  exactly how the LaunchAgent (and the docs) start a real daemon, and self/parent
 *  protection is already handled by dropping process.pid / process.ppid from the
 *  candidate set. Killing the wrapper's child is what actually stops the daemon,
 *  and the wrapper exits with it. */
export function isStoppableDaemonCommand(cmd: string): boolean {
  if (!isCumoraAgentCommand(cmd)) return false
  return !ONE_SHOT_FLAG_RE.test(cmd) && !ONE_SHOT_SUBCOMMAND_RE.test(cmd)
}

/** Is this `ps`-reported command line one of ours at all? Weaker than
 *  `isStoppableDaemonCommand` on purpose: it says nothing about whether the
 *  process is the long-running daemon, only that a pid we already have other
 *  evidence for has not been recycled by some unrelated program. */
export function isCumoraAgentCommand(cmd: string): boolean {
  return /agent computer/.test(cmd)
}

async function commandLineForPid(pid: number): Promise<string> {
  if (process.platform === 'win32') {
    const command = `(Get-CimInstance Win32_Process -Filter "ProcessId = ${pid}" -ErrorAction SilentlyContinue).CommandLine`
    return (await execFileP('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', command])).stdout.trim()
  }
  return (await execFileP('ps', ['-p', String(pid), '-o', 'command='])).stdout.trim()
}

interface WindowsProcessInfo {
  ProcessId: number
  CommandLine: string
  Name?: string
}

export function parseWindowsProcessList(output: string): WindowsProcessInfo[] {
  if (!output.trim()) return []
  const parsed = JSON.parse(output) as WindowsProcessInfo | WindowsProcessInfo[]
  return (Array.isArray(parsed) ? parsed : [parsed]).filter((item) =>
    Number.isInteger(item?.ProcessId) && item.ProcessId > 0 && typeof item.CommandLine === 'string')
}

async function windowsDaemonProcesses(): Promise<WindowsProcessInfo[]> {
  const command = [
    '$OutputEncoding = [Console]::OutputEncoding = New-Object System.Text.UTF8Encoding($false)',
    `@(Get-CimInstance Win32_Process -ErrorAction Stop | Where-Object { $_.CommandLine -match 'agent\\s+computer' } | Select-Object ProcessId, CommandLine) | ConvertTo-Json -Compress`,
  ].join('; ')
  const { stdout } = await execFileP('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', command])
  return parseWindowsProcessList(stdout)
}

async function windowsSupervisorProcesses(): Promise<WindowsProcessInfo[]> {
  const command = [
    '$OutputEncoding = [Console]::OutputEncoding = New-Object System.Text.UTF8Encoding($false)',
    `@(Get-CimInstance Win32_Process -ErrorAction Stop | Where-Object { ($_.Name -ieq 'powershell.exe' -or $_.Name -ieq 'pwsh.exe') -and $_.CommandLine -match 'daemon-supervisor\\.ps1' } | Select-Object ProcessId, CommandLine, Name) | ConvertTo-Json -Compress`,
  ].join('; ')
  const { stdout } = await execFileP('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', command])
  return parseWindowsProcessList(stdout).filter((item) => isWindowsSupervisorProcess(item))
}

export function isWindowsSupervisorProcess(
  item: WindowsProcessInfo,
  scriptPath = windowsSupervisorPath(),
): boolean {
  if (!item.Name || !['powershell.exe', 'pwsh.exe'].includes(item.Name.toLowerCase())) return false
  const match = item.CommandLine.match(/(?:^|\s)-File\s+(?:"([^"]+)"|(\S+))(?:\s|$)/i)
  const invokedScript = match?.[1] ?? match?.[2]
  return invokedScript?.toLowerCase() === scriptPath.toLowerCase()
}

async function stopWindowsWatchdog(taskName: string): Promise<void> {
  await execFileP('schtasks.exe', ['/End', '/TN', taskName]).catch(() => { /* deleted/already stopped */ })
  const deadline = Date.now() + 2_000
  let watchdogs = await windowsSupervisorProcesses()
  while (watchdogs.length > 0 && Date.now() < deadline) {
    await new Promise((resolve) => setTimeout(resolve, 100))
    watchdogs = await windowsSupervisorProcesses()
  }
  for (const watchdog of watchdogs) {
    await execFileP('taskkill.exe', ['/PID', String(watchdog.ProcessId), '/T', '/F']).catch(() => {})
  }
  const forceDeadline = Date.now() + 2_000
  watchdogs = await windowsSupervisorProcesses()
  while (watchdogs.length > 0 && Date.now() < forceDeadline) {
    await new Promise((resolve) => setTimeout(resolve, 100))
    watchdogs = await windowsSupervisorProcesses()
  }
  if (watchdogs.length > 0) {
    throw new Error(`Windows watchdog process(es) still running: ${watchdogs.map((item) => item.ProcessId).join(', ')}`)
  }
}

/** Stop any RUNNING daemon process — the supervised one (after the service is
 *  uninstalled), a foreground one, or a stray/orphaned one. Sources: the pid the
 *  daemon records in running.json, plus an OS process sweep for "agent computer". We
 *  verify each candidate's command line really is a long-running daemon (and is
 *  NOT this --stop command or another one-shot CLI) before stopping it. Windows
 *  uses a per-PID request file for graceful shutdown, then taskkill /T as the
 *  bounded fallback so engine descendants cannot be orphaned. */
async function killRunningDaemons(): Promise<void> {
  const candidates = new Set<number>()
  let recordedPid: number | null = null
  try {
    const pid = (JSON.parse(await readFile(RUNNING_STATE_PATH, 'utf8')) as { pid?: number }).pid
    if (typeof pid === 'number' && pid > 0) { candidates.add(pid); recordedPid = pid }
  } catch { /* no pid file */ }
  if (process.platform === 'win32') {
    for (const item of await windowsDaemonProcesses()) candidates.add(item.ProcessId)
  } else {
    try {
      const { stdout } = await execFileP('pgrep', ['-f', 'agent computer'])
      for (const l of stdout.split('\n')) { const p = parseInt(l.trim(), 10); if (p > 0) candidates.add(p) }
    } catch { /* none / pgrep unavailable */ }
  }
  candidates.delete(process.pid)
  if (typeof process.ppid === 'number') candidates.delete(process.ppid)

  // running.json is written by `doRun` itself, so a pid recorded there HAS
  // become the long-running daemon whatever its flags say. That matters because
  // one real daemon's command line does carry a one-shot flag: `--pair` on a
  // machine with no service installed pairs and then falls through to `doRun`,
  // which is the whole first-run onboarding path. Judging it by its flags left
  // `--stop` reporting "daemon process(es) killed" while that daemon kept
  // running, kept claiming agent turns, and could only be stopped by closing the
  // terminal. For that pid we only re-confirm it is still one of ours, so a
  // stale file whose pid the OS has recycled cannot make us kill a stranger.
  //
  // Every other candidate comes from a bare pgrep and carries no such evidence,
  // so it keeps the strict rule — a sibling one-shot CLI must never be killed.
  const isVictimCommand = (pid: number, cmd: string): boolean =>
    pid === recordedPid ? isCumoraAgentCommand(cmd) : isStoppableDaemonCommand(cmd)

  const victims: number[] = []
  for (const pid of candidates) {
    try {
      if (isVictimCommand(pid, await commandLineForPid(pid))) victims.push(pid)
    } catch { /* gone */ }
  }
  if (process.platform === 'win32') {
    if (victims.length > 0) await mkdir(CONFIG_DIR, { recursive: true })
    for (const pid of victims) {
      await writeFile(windowsShutdownRequestPath(pid), 'stop\n', 'utf8').catch(() => {})
    }
    const deadline = Date.now() + SHUTDOWN_GRACE_MS + 2_000
    let survivors = victims
    while (survivors.length > 0 && Date.now() < deadline) {
      await new Promise((resolve) => setTimeout(resolve, 250))
      const next: number[] = []
      for (const pid of survivors) {
        try {
          if (isVictimCommand(pid, await commandLineForPid(pid))) next.push(pid)
        } catch { /* exited */ }
      }
      survivors = next
    }
    for (const pid of survivors) {
      await execFileP('taskkill.exe', ['/PID', String(pid), '/T', '/F']).catch(() => {})
    }
    for (const pid of victims) await rm(windowsShutdownRequestPath(pid), { force: true }).catch(() => {})
    const forceDeadline = Date.now() + 2_000
    const stillRunning = async (): Promise<WindowsProcessInfo[]> =>
      (await windowsDaemonProcesses()).filter((item) =>
        item.ProcessId !== process.pid && item.ProcessId !== process.ppid &&
        isVictimCommand(item.ProcessId, item.CommandLine))
    let remaining = await stillRunning()
    while (remaining.length > 0 && Date.now() < forceDeadline) {
      await new Promise((resolve) => setTimeout(resolve, 100))
      remaining = await stillRunning()
    }
    if (remaining.length > 0) {
      throw new Error(`Windows daemon process(es) still running: ${remaining.map((item) => item.ProcessId).join(', ')}`)
    }
  } else {
    for (const pid of victims) { try { process.kill(pid, 'SIGTERM') } catch { /* gone */ } }
    if (victims.length > 0) {
      await new Promise((r) => setTimeout(r, 1500))
      for (const pid of victims) { try { process.kill(pid, 0); process.kill(pid, 'SIGKILL') } catch { /* already exited */ } }
    }
  }
  if (victims.length > 0) {
    console.log(`[computer] stopped ${victims.length} running daemon process(es)`)
  }
  await rm(RUNNING_STATE_PATH, { force: true }).catch(() => {})
}

/** `--stop`: a FULL stop — uninstall the background service (so the supervisor
 *  can't relaunch it) AND kill any daemon process still running. After this the
 *  agents are fully offline until you re-pair / re-install. */
async function stopService(): Promise<void> {
  if (process.platform === 'win32') {
    // Always clean up on Windows: a manually deleted task may still have left a
    // watchdog process or script behind, and that watchdog can relaunch a daemon.
    await uninstallService()
  } else if (await isServiceInstalled()) {
    await uninstallService() // removes the plist/unit + unloads → kills the supervised process
  } else {
    console.log('[computer] no background service installed — killing any running daemon process directly.')
  }
  if (process.platform !== 'win32') await killRunningDaemons()
  console.log('[computer] stopped — service removed and daemon process(es) killed. Re-pair to start again: npx cumora@latest agent computer --pair <code>')
}

/** `--status`: a one-glance summary — version, pairing, whether the background
 *  service is installed + running (PID / last exit), and where the logs are. */
async function printStatus(): Promise<void> {
  const cfg = await loadConfig()
  // The version of the binary running THIS command. May differ from what the
  // background service is actually running (it auto-updates on its own cycle),
  // so we report the service's running version separately, read from its log.
  console.log(`cli:     cumora ${CURRENT_VERSION} (this command)`)
  console.log(cfg ? `paired:  computer ${cfg.computerId} @ ${cfg.serverUrl}` : 'paired:  NO — run: npx cumora@latest agent computer --pair <code>')
  if (!(await isServiceInstalled())) {
    console.log('service: not installed — run: npx cumora@latest agent computer --install-service')
    return
  }
  let livePid: number | null = null
  if (process.platform === 'darwin') {
    try {
      const { stdout } = await execFileP('launchctl', ['list', SERVICE_LABEL])
      const pid = stdout.match(/"PID"\s*=\s*(\d+)/)?.[1]
      livePid = pid ? Number(pid) : null
      const exit = stdout.match(/"LastExitStatus"\s*=\s*(-?\d+)/)?.[1]
      console.log(livePid ? `service: installed · running (pid ${livePid})` : `service: installed · NOT running${exit ? ` (last exit ${exit})` : ''}`)
    } catch {
      console.log('service: installed · not loaded (try: launchctl load ~/Library/LaunchAgents/' + SERVICE_LABEL + '.plist)')
    }
  } else if (process.platform === 'linux') {
    const active = await execFileP('systemctl', ['--user', 'is-active', 'cumora']).then((r) => r.stdout.trim()).catch(() => 'inactive')
    const pid = await execFileP('systemctl', ['--user', 'show', 'cumora', '-p', 'MainPID', '--value']).then((r) => r.stdout.trim()).catch(() => '')
    livePid = pid && pid !== '0' ? Number(pid) : null
    console.log(`service: installed · ${active}${livePid ? ` (pid ${livePid})` : ''}`)
  } else if (process.platform === 'win32') {
    try {
      const state = JSON.parse(await readFile(RUNNING_STATE_PATH, 'utf8')) as { pid?: number }
      if (typeof state.pid === 'number' && isStoppableDaemonCommand(await commandLineForPid(state.pid))) {
        livePid = state.pid
      }
    } catch { /* task is between restarts or has not started yet */ }
    console.log(livePid
      ? `service: installed · running (pid ${livePid}, Task Scheduler)`
      : `service: installed · registered in Task Scheduler`)
  }
  const running = await resolveRunningVersion(livePid)
  if (running) {
    console.log(`running: cumora ${running}${running === CURRENT_VERSION ? ' (latest)' : ' (differs from this cli — `npx cumora@latest agent computer --restart` to pick up the latest)'}`)
  } else {
    console.log('running: unknown — `npx cumora@latest agent computer --restart` to (re)start it and record the version')
  }
  console.log(`logs:    ${process.platform === 'linux' ? 'journalctl --user -u cumora -f' : join(CONFIG_DIR, 'daemon.log')}  (or: npx cumora@latest agent computer --logs)`)
}

const RUNNING_STATE_PATH = join(CONFIG_DIR, 'running.json')

/** On startup the live daemon records {version, pid, startedAt} here so
 *  `--status` can report the running instance's exact version — verified by pid
 *  so a stale file (from a since-exited process) is ignored. */
async function writeRunningState(): Promise<void> {
  try {
    await mkdir(CONFIG_DIR, { recursive: true })
    await writeFile(RUNNING_STATE_PATH, JSON.stringify({ version: CURRENT_VERSION, pid: process.pid, startedAt: new Date().toISOString() }), 'utf8')
  } catch { /* best-effort; --status falls back to the log */ }
}

/** The version the SERVICE is running right now. Primary source: running.json,
 *  trusted only when its recorded pid IS the live service pid (so it reflects
 *  THIS instance, not a stale one). Fallback: the latest startup line in the log
 *  (works for builds that log a version but predate running.json). '' if unknown
 *  (e.g. the running build predates both — restart it once to record it). */
async function resolveRunningVersion(livePid: number | null): Promise<string> {
  try {
    const st = JSON.parse(await readFile(RUNNING_STATE_PATH, 'utf8')) as { version?: string; pid?: number }
    if (typeof st.version === 'string' && st.version && livePid != null && st.pid === livePid) return st.version
  } catch { /* no/again-bad state file — fall back to log scan */ }
  try {
    const text = process.platform === 'linux'
      ? (await execFileP('journalctl', ['--user', '-u', 'cumora', '-n', '400', '--no-pager'])).stdout
      : await readFile(join(CONFIG_DIR, 'daemon.log'), 'utf8')
    const m = [...text.matchAll(/cumora (\d+\.\d+\.\d+) · starting/g)]
    return m.length ? m[m.length - 1][1] : ''
  } catch { return '' }
}

/** `--logs`: follow the service's output. macOS/Windows tail the log file;
 *  Linux streams journald (systemd doesn't write a file). Runs until Ctrl+C. */
async function tailLogs(): Promise<void> {
  if (process.platform === 'linux') {
    await new Promise<void>((resolve) => {
      const c = spawn('journalctl', ['--user', '-u', 'cumora', '-n', '100', '-f'], { stdio: 'inherit' })
      c.on('close', () => resolve()); c.on('error', () => resolve())
    })
    return
  }
  const logPath = join(CONFIG_DIR, 'daemon.log')
  if (!existsSync(logPath)) {
    console.log(`no log at ${logPath} yet — is the service installed and running? (npx cumora@latest agent computer --status)`)
    return
  }
  await new Promise<void>((resolve) => {
    const c = process.platform === 'win32'
      ? spawn('powershell.exe', [
          '-NoProfile', '-NonInteractive', '-Command',
          `Get-Content -LiteralPath ${quotePowerShell(logPath)} -Encoding UTF8 -Tail 100 -Wait`,
        ], { stdio: 'inherit' })
      : spawn('tail', ['-n', '100', '-f', logPath], { stdio: 'inherit' })
    c.on('close', () => resolve()); c.on('error', () => resolve())
  })
}

// ─── doctor ─────────────────────────────────────────────────────────────

/** Which engines could actually carry a wake right now.
 *
 *  Brain health is necessary but not sufficient. `requireLocalEngine` also
 *  refuses to start the daemon when no installed engine can enforce the BYOA
 *  boundary — an unsandboxed engine without the opt-in, or a secure one below
 *  its version floor. Scoring the doctor on brain health alone printed a green
 *  verdict and exit 0 on machines where `--pair` exits 70.
 *
 *  `runnable` is null when the gate could not be evaluated at all (PATH scan
 *  failed). The diagnostic must not become a crash, so that degrades to the
 *  older brain-only answer rather than declaring everything unusable. */
export function doctorUsableEngines(
  results: ReadonlyArray<{
    id: EngineId
    installed: boolean
    big?: { ok: boolean } | null
    small?: { ok: boolean } | null
  }>,
  runnable: { runnable: readonly EngineId[] } | null,
): EngineId[] {
  return results
    .filter((r) => r.installed && r.big?.ok === true && r.small?.ok === true)
    .map((r) => r.id)
    .filter((id) => runnable === null || runnable.runnable.includes(id))
}

/** `cumora agent computer --doctor`: diagnose every local engine on this
 *  machine — is it installed, and are its BIG brain (main reasoning) and SMALL
 *  brain (the triage cerebellum) reachable + authed? Each tier gets a trivial
 *  one-shot probe over the SAME spawn path real wakes use. Pure local: no
 *  cloud, no DB, no pairing required.
 *
 *  Brain health is necessary but NOT sufficient, and the verdict used to be
 *  drawn from it alone. `requireLocalEngine` also refuses to start the daemon
 *  when no installed engine can enforce the BYOA boundary — an unsandboxed
 *  engine without the opt-in, or a secure one below its version floor. On a
 *  machine in that state the doctor printed a green verdict and exit 0 while
 *  `--pair` exited 70, which is the worst possible advice for the person who
 *  ran the diagnostic precisely because something was already wrong. So the
 *  verdict now asks the same gate the daemon does, and an engine only counts
 *  when it is both healthy AND runnable. */
async function runDoctor(providerId?: string): Promise<void> {
  const provider = providerId !== undefined
    ? readProviderProfiles(join(CONFIG_DIR, 'providers.json')).find((p) => p.id === providerId) : undefined
  if (providerId !== undefined && !provider) throw new Error('provider profile not found in providers.json')
  console.log(`cumora ${CURRENT_VERSION} · engine doctor`)
  console.log('probing local engines (big brain = main reasoning, small brain = triage cerebellum)…\n')

  const results = await runEngineDoctor({
    env: provider ? providerProfileEnv(process.env, provider) : undefined,
    engines: provider ? ['claude'] : undefined,
    onLog: (l) => console.error(`  · ${redactProviderSecret(l, provider)}`),
  })
  for (const result of results) {
    for (const health of [result.big, result.small, result.wake]) {
      if (health) health.detail = redactProviderSecret(health.detail, provider)
    }
  }
  console.log('')

  // Ask the same gate the daemon does. A healthy brain on an engine this
  // machine is not allowed to run is not a machine that can run an agent.
  const runnable = await (async () => {
    try {
      const detected = await detectEnginesWithStatus()
      if (!detected.reliable || detected.engines.length === 0) return null
      return await evaluateRunnableEngines(detected.engines)
    } catch {
      // The gate is advisory HERE — never let it turn a diagnostic into a
      // crash. Falling back to null keeps the old brain-only verdict.
      return null
    }
  })()

  let anyUsable = false
  for (const r of results) {
    if (!r.installed) {
      console.log(`✖ ${r.id} — not found on PATH`)
      // The binary is not always the engine id — cursor ships `cursor-agent`,
      // antigravity ships `agy`. missingEngineMessage() in this file gets that
      // right; this line used to contradict it.
      console.log(r.id === 'codex'
        ? `    install the \`codex\` CLI, run \`${CODEX_LOGIN_COMMAND}\`, then re-run --doctor\n`
        : `    install the \`${getAdapter(r.id)?.bin ?? r.id}\` CLI and run it once to sign in, then re-run --doctor\n`)
      continue
    }
    console.log(`● ${r.id} — ${r.path}`)
    for (const [label, h] of [['big brain  ', r.big], ['small brain', r.small]] as const) {
      if (!h) continue
      if (h.ok) {
        console.log(`    ✓ ${label}  ok (${h.ms}ms)`)
      } else {
        console.log(`    ✖ ${label}  FAILED (${h.ms}ms): ${h.detail}`)
        console.log(`        → ${authFailureHint(r.id, h.detail)}`)
      }
    }
    // Wake-path line. Hidden when skipped (the wake collapses to one-shot exec on
    // this machine — the brain probes above already cover that shape, so a wake
    // line would be noise). Failure is shown but NOT counted against "anyUsable"
    // because run()'s one-shot exec is a working fallback whenever the wake-path
    // breaks — the user just doesn't get persistent-session benefits.
    if (r.wake && !r.wake.skipped) {
      if (r.wake.ok) {
        console.log(`    ✓ wake path   ok (${r.wake.ms}ms)`)
      } else {
        console.log(`    ⚠ wake path   FAILED (${r.wake.ms}ms): ${r.wake.detail}`)
        console.log(`        → persistent-session path unavailable; agents will fall back to one-shot exec`)
      }
    }
    const blockedReason = runnable?.blocked.find((b) => b.id === r.id)?.reason
    if (blockedReason) {
      console.log(`    ✖ not runnable  ${blockedReason}`)
      console.log('        → healthy brains, but the daemon will refuse to start on this engine')
    }
    console.log('')
  }
  anyUsable = doctorUsableEngines(results, runnable).length > 0

  if (!anyUsable) {
    console.log('✖ no engine is both healthy and runnable — this machine cannot currently run a BYOA agent.')
    if (runnable && runnable.runnable.length === 0) {
      // Print exactly what `--pair` would print, so the two never disagree.
      const why = runnable.blocked.length > 0
        ? incapableEngineMessage(runnable.blocked)
        : sandboxedEngineMessage(ENGINE_IDS.filter((id) => results.some((r) => r.id === id && r.installed)))
      console.log('')
      for (const line of why.split('\n')) console.log(`  ${line}`)
      console.log('')
    }
    console.log('  fix the failures above (usually: open the engine\'s app and sign in / refresh quota), then re-run:')
    console.log('    cumora agent computer --doctor')
    process.exitCode = 1
  } else {
    console.log('✓ at least one engine is healthy and runnable — BYOA agents on this machine can wake their brains.')
  }
}

// ─── entry ──────────────────────────────────────────────────────────────

export async function runComputerDaemon(argv: string[]): Promise<void> {
  const args = parseArgs(argv)
  if (args.provider !== undefined && !args.doctor) throw new Error('--provider requires --doctor')
  const serverUrl = (args.server || DEFAULT_SERVER).replace(/\/+$/, '')
  if (args.help) { console.log(helpText()); return }
  if (args.version) { console.log(CURRENT_VERSION); return }
  if (args.codexLogin) { await loginCodexRuntime(); return }
  if (args.migrateCodexSessions) {
    const agents = await migrateCodexSessions()
    console.log(`Migrated ${agents.length} Codex session(s) to ${codexRuntimeHome()}${agents.length ? `: ${agents.join(', ')}` : ''}. Personal Codex data was left in place.`)
    return
  }
  if (args.doctor) { await runDoctor(args.provider); return }
  if (args.restart) { await restartService(); return }
  if (args.stop) { await stopService(); return }
  if (args.status) { await printStatus(); return }
  if (args.logs) { await tailLogs(); return }
  if (args.uninstallService) { await uninstallService(); return }
  // Pair first (saves config) so a combined `--pair … --install-service` can
  // pair AND hand off to the supervisor in one paste.
  if (args.pair) {
    await doPair(args.pair, serverUrl, args.engine)
  }
  // Installing the service is terminal: it writes the supervisor (which runs
  // the daemon itself) and exits — we don't ALSO run a foreground daemon here.
  if (args.installService) {
    const cfg = await loadConfig()
    await installService(args.server ? serverUrl : (cfg?.serverUrl ?? serverUrl))
    return
  }
  // Re-paired on a machine already managed by the background service: reload
  // the service so it adopts the new config (e.g. moved to another company),
  // instead of starting a SECOND foreground daemon that races the service.
  if (args.pair && await isServiceInstalled()) {
    await reloadService()
    console.log(`[computer] re-paired — reloaded the background service with the new config. (No foreground daemon needed; you can close this terminal.)`)
    return
  }
  await doRun(args.server ? serverUrl : undefined)
}