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
61.5 KB
Raw Blame
/**
 * Computer registry — server-side state + auth for BYOA "Computers".
 *
 * A Computer is the host an agent runs on (see docs/BYOA.md). Cumora Cloud
 * is the built-in managed computer; the user pairs their own machines (a
 * Mac, a VPS) which run the `cumora agent computer` daemon and a local
 * engine (Claude Code / Codex / Grok Build / Cursor Agent / OpenCode).
 *
 * This module owns the data-access + credential plumbing so the route
 * layer (api/router.ts) stays thin and this logic stays unit-testable:
 *   - pairing tokens (persistent, DB-backed, company-scoped or computer-scoped)
 *   - device tokens (opaque, hashed at rest in computers.credential_hash;
 *     revocable by setting computers.revoked_at)
 *   - per-agent runtime JWTs minted for a paired device (reuses
 *     runtime/jwt.ts — the same token a pod gets)
 */
import { type ProviderProfileMetadata, isProviderProfileId, sanitizeProviderProfiles } from './provider-profiles.js'
import { InvalidModelIdError, modelIdOrNull, parseModelId } from './model-id.js'
import { createHash, randomBytes, randomUUID } from 'node:crypto'
import { pool } from '../../db/pool.js'
import { audit } from '../../auth.js'
import { CH_STATUS } from '../../redis.js'
import { enqueueBroadcast, nudgeRealtimeOutbox } from '../../realtime-outbox.js'
import { normalizeTier, type Tier } from '../../tier.js'
import { signAgentToken } from '../runtime/jwt.js'
import type { EngineModelCatalog, EngineModelOption, FastModelScope, ModelCatalogSource } from './model-catalog.js'

export type ComputerKind = 'cloud' | 'local' | 'vps'
export type EngineId = 'managed' | 'claude' | 'codex' | 'grok' | 'cursor' | 'opencode' | 'pi' | 'gemini' | 'qwen' | 'antigravity' | 'zcode' | 'maka' | 'omp'
export type ComputerStatus = 'online' | 'offline' | 'busy'

/** How long a paired computer can go without a heartbeat before the sweep
 *  marks it offline. The daemon heartbeats every ~30s. */
export const COMPUTER_STALE_MS = 90_000

/** Broadcast a computer's status to its company's WS clients. Mirrors
 *  status.ts's participant-status broadcast: same channel, companyId-tagged
 *  so the WS bridge fans it only to that tenant. */
async function broadcastComputerStatus(
  computerId: string, companyId: string, status: ComputerStatus,
): Promise<void> {
  try {
    await enqueueBroadcast(pool, CH_STATUS, { type: 'computers.status', computerId, status, companyId })
    nudgeRealtimeOutbox()
  } catch (error) {
    console.warn(
      `[computer] durable ${computerId}=${status} update committed but outbox insert failed`,
      error,
    )
  }
}

/** Announce a just-paired computer as online. Split out from {@link pairComputer}
 *  so the /pair route can defer it until AFTER the starter team is seeded — the
 *  desktop flips its onboarding gate on this event and immediately reloads its
 *  roster, so the agents + "Everyone" group must already exist when it fires. */
export async function announceComputerOnline(computerId: string, companyId: string): Promise<void> {
  await broadcastComputerStatus(computerId, companyId, 'online')
}

/** Engines a paired (non-cloud) computer is allowed to advertise.
 *
 *  Spelled as a Record over the engine union rather than a Set literal so the
 *  COMPILER is what notices a new engine, not a reviewer: adding an id to
 *  EngineId makes this fail to compile until the id is classified here. A
 *  plain `new Set([...])` accepted an incomplete list silently, and the engine
 *  left out of it could be detected and shown but never actually paired. */
const PAIRABLE: Record<Exclude<EngineId, 'managed'>, true> = {
  claude: true, codex: true, grok: true, cursor: true, opencode: true, pi: true, gemini: true,
  qwen: true,
  antigravity: true,
  zcode: true,
  maka: true,
  omp: true,
}
export const PAIRABLE_ENGINES: ReadonlySet<string> = new Set<string>(Object.keys(PAIRABLE))

type Queryable = {
  query<T extends object = Record<string, unknown>>(
    text: string,
    params?: readonly unknown[],
  ): Promise<{ rows: T[]; rowCount?: number | null }>
}

/** Merge a fresh PATH detection into a computer's advertised engine list.
 *
 *  `available_engines[0]` is the computer's DEFAULT — pairComputer's comment
 *  puts it plainly: "first = default", and it decides the engine for the starter
 *  team and for any agent assigned without an explicit override. So a re-detect
 *  must never reorder silently: if the current default is still installed it
 *  stays first, and the rest follow detection order. Installing a new CLI adds
 *  it to the tail; uninstalling one drops it.
 *
 *  Returns null when there is nothing to write — a fully-unknown detection or a
 *  list identical to what is stored. An explicitly empty detection is valid:
 *  the daemon only reports it after a successful scan, so it means the final
 *  supported CLI was uninstalled and the stale inventory must be cleared.
 *
 *  Exported for tests. */
export function mergeDetectedEngines(current: string[], detected: string[]): string[] | null {
  const fresh = detected.filter((e) => PAIRABLE_ENGINES.has(e))
  // Non-empty but entirely unknown means a newer daemon is naming only engines
  // this server cannot run yet. Do not let that compatibility case wipe known
  // state; [] itself remains a trustworthy, successful empty PATH scan.
  if (detected.length > 0 && fresh.length === 0) return null
  const seen = new Set<string>()
  const next: string[] = []
  const currentDefault = current[0]
  // Keep the default pinned to the front while it is still installed.
  if (currentDefault && fresh.includes(currentDefault)) { next.push(currentDefault); seen.add(currentDefault) }
  for (const e of fresh) { if (!seen.has(e)) { next.push(e); seen.add(e) } }
  const same = next.length === current.length && next.every((e, i) => e === current[i])
  return same ? null : next
}

const ENGINE_BINS: Record<Exclude<EngineId, 'managed'>, string> = {
  claude: 'claude',
  codex: 'codex',
  grok: 'grok',
  cursor: 'cursor-agent',
  opencode: 'opencode',
  pi: 'pi',
  gemini: 'gemini',
  qwen: 'qwen',
  antigravity: 'agy',
  zcode: 'zcode',
  maka: 'maka',
  omp: 'omp',
}

/** Cached PATH snapshot from the daemon. The app reads this; it never probes. */
export interface DetectedEngine {
  providerProfiles?: ProviderProfileMetadata[]
  id: string
  bin: string
  path: string | null
  /** Version of this engine as installed on the reporting computer, the newest
   *  one upstream, and how to update it there. Absent when reported by a daemon
   *  older than the version probe, or when the probe could not read a version —
   *  the app renders the path alone rather than guessing. */
  version?: string | null
  latest?: string | null
  outdated?: boolean
  updateCommand?: string | null
  /** Why Cumora will not drive this engine even though it is installed here —
   *  "version 2.0.9 is older than the secure minimum 2.1.248", "missing sandbox
   *  dependency: bubblewrap (bwrap)". Absent when the engine is runnable.
   *
   *  This travels because the person reading the card is usually not sitting at
   *  the machine it describes — the same reason the version fields do. The
   *  daemon knew the reason all along and only wrote it to its own stdout, so
   *  an engine could vanish from a computer with no explanation anywhere the
   *  operator was looking. */
  blockedReason?: string | null
  modelCatalog?: EngineModelCatalog
}

/** Trim a daemon-reported display string, or drop it. Control characters are
 *  stripped so a version line can never smuggle newlines into the update
 *  command the Me page offers the user to copy and run. */
function displayString(value: unknown, max: number): string | null {
  if (typeof value !== 'string') return null
  const clean = value.replace(/[\u0000-\u001f\u007f]/g, ' ').trim()
  return clean ? clean.slice(0, max) : null
}

function sanitizeVersionFields(rec: Record<string, unknown>): Partial<DetectedEngine> {
  const version = displayString(rec.version, 64)
  const latest = displayString(rec.latest, 64)
  const updateCommand = displayString(rec.updateCommand, 200)
  return {
    version,
    latest,
    // Never take the daemon's word for it over data we can check ourselves: a
    // stale `outdated: true` with both versions equal would nag forever.
    outdated: rec.outdated === true && !!version && !!latest && version !== latest,
    updateCommand,
  }
}

function sanitizeModelCatalog(raw: unknown): EngineModelCatalog | undefined {
  if (!raw || typeof raw !== 'object') return undefined
  const rec = raw as Record<string, unknown>
  const source: ModelCatalogSource = rec.source === 'protocol' || rec.source === 'cli' || rec.source === 'presets'
    ? rec.source
    : 'presets'
  const fastModelScope: FastModelScope = rec.fastModelScope === 'computer' || rec.fastModelScope === 'unsupported'
    ? rec.fastModelScope
    : 'agent'
  const models: EngineModelOption[] = []
  const seen = new Set<string>()
  if (Array.isArray(rec.models)) {
    for (const rawModel of rec.models.slice(0, 1024)) {
      if (!rawModel || typeof rawModel !== 'object') continue
      const model = rawModel as Record<string, unknown>
      const id = typeof model.id === 'string' ? modelIdOrNull(model.id) : null
      if (!id || seen.has(id)) continue
      seen.add(id)
      const recommendedFor = Array.isArray(model.recommendedFor)
        ? model.recommendedFor.filter((tier): tier is 'big' | 'small' => tier === 'big' || tier === 'small').slice(0, 2)
        : undefined
      models.push({
        id,
        label: displayString(model.label, 160) ?? id,
        description: displayString(model.description, 320),
        ...(recommendedFor?.length ? { recommendedFor } : {}),
        ...(typeof model.supportsFastMode === 'boolean' ? { supportsFastMode: model.supportsFastMode } : {}),
        ...(model.vision === 'supported' || model.vision === 'unsupported' || model.vision === 'unknown'
          ? { vision: model.vision }
          : {}),
      })
    }
  }
  return {
    models,
    defaultModel: displayString(rec.defaultModel, 160),
    defaultFastModel: displayString(rec.defaultFastModel, 160),
    ...(rec.prefersLocalDefault === true ? { prefersLocalDefault: true } : {}),
    supportsCustom: rec.supportsCustom !== false,
    fastModelScope,
    source,
    // Passed through, never defaulted: only a daemon that knows its list is
    // preset-free may say so, and the app withholds model rows without it.
    ...(rec.trustedModels === true ? { trustedModels: true } : {}),
    ...(rec.stale === true ? { stale: true } : {}),
  }
}

/** An engine we know is advertised but have no PATH/version report for. */
function unreportedEngine(id: string): DetectedEngine {
  return {
    id, bin: ENGINE_BINS[id as keyof typeof ENGINE_BINS] ?? id, path: null,
    version: null, latest: null, outdated: false, updateCommand: null, blockedReason: null,
  }
}

/**
 * Shape the daemon's PATH report for storage and display.
 *
 * `runnableIds` are the engines the daemon will actually wake; `blockedIds` are
 * installed but refused, and appear ONLY here. That separation is the safety
 * property of this function: `available_engines` is what picks an agent's
 * adapter, so a blocked engine reaching it would run the very thing the
 * sandbox gate declined. Blocked ids are therefore never returned to the
 * caller as runnable and never influence `ordered` — they ride along as extra
 * display rows carrying the reason they were refused.
 */
export function sanitizeDetectedEngines(
  raw: unknown,
  engineIds: string[],
  blockedIds: string[] = [],
): DetectedEngine[] {
  const runnable = engineIds.filter((id) => PAIRABLE_ENGINES.has(id))
  const blocked = blockedIds.filter((id) => PAIRABLE_ENGINES.has(id) && !runnable.includes(id))
  const allowed = [...runnable, ...blocked]
  if (!Array.isArray(raw)) return allowed.map(unreportedEngine)
  const byId = new Map<string, DetectedEngine>()
  for (const item of raw) {
    if (!item || typeof item !== 'object') continue
    const rec = item as Record<string, unknown>
    const id = typeof rec.id === 'string' ? rec.id : ''
    if (!PAIRABLE_ENGINES.has(id) || !allowed.includes(id)) continue
    const bin = typeof rec.bin === 'string' && rec.bin.trim() ? rec.bin.trim() : (ENGINE_BINS[id as keyof typeof ENGINE_BINS] ?? id)
    const path = typeof rec.path === 'string' && rec.path.trim() ? rec.path.trim() : null
    // A reason is only meaningful on an engine we actually refused. Accepting
    // one on a runnable engine would let a daemon mark a working engine broken.
    const blockedReason = blocked.includes(id) ? displayString(rec.blockedReason, 200) : null
    const modelCatalog = sanitizeModelCatalog(rec.modelCatalog)
    byId.set(id, {
      id, bin, path, ...sanitizeVersionFields(rec), blockedReason,
      ...(modelCatalog ? { modelCatalog } : {}),
      ...(id === 'claude' && Array.isArray(rec.providerProfiles) ? { providerProfiles: sanitizeProviderProfiles(rec.providerProfiles) } : {}),
    })
  }
  // Every row carries the same keys, reported or not, so the app never has to
  // distinguish "field absent" from "nothing installed to report".
  return allowed.map((id) => byId.get(id) ?? unreportedEngine(id))
}

/** Per-engine default model settings stored on a Computer.
 *  Structure: { "claude": { "model": "x", "fastModel": "y" }, ... } */
export interface EngineDefaults {
  model?: string | null
  fastModel?: string | null
}

export type EngineDefaultsMap = Record<string, EngineDefaults>

export interface ComputerRow {
  id: string
  company_id: string
  owner_user_id: string | null
  name: string
  kind: ComputerKind
  available_engines: string[]
  status: 'online' | 'offline' | 'busy'
  last_seen_at: string | null
  paired_at: string | null
  revoked_at: string | null
  created_at: string
  /** The cumora daemon's reported version; NULL for cloud or a pre-version daemon. */
  daemon_version: string | null
  /** TRUE = runs under the --install-service supervisor (launchd/systemd),
   *  FALSE = a manually-run foreground command, NULL = cloud / an old daemon
   *  that doesn't report it. Drives run-mode-specific update instructions. */
  daemon_supervised: boolean | null
  detected_engines: DetectedEngine[]
  engines_detected_at: string | null
  detect_requested_at: string | null
  /** Per-engine default model settings. Agents inherit these when their own
   *  model/fastModel is not set. */
  engine_defaults: EngineDefaultsMap
}

/** A computer plus the computed upgrade signal the app uses to show the banner. */
export interface ComputerWithUpgrade extends ComputerRow {
  /** The newest published cumora version (npm 'latest'), or null if unknown. */
  latest_daemon_version: string | null
  /** True iff this is a BYOA daemon running behind the latest version (or one so
   *  old it never reported a version). Cloud computers are never outdated. */
  daemon_outdated: boolean
}

/** semver-ish "a > b" over dotted numbers. Pre-release/build tags are ignored
 *  (we only ship plain x.y.z), so a bare numeric compare is enough. */
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
}

// Newest published cumora version, cached so listComputers doesn't hit npm on
// every call. Refreshes hourly; fail-safe (keeps the last good value, or null
// when never fetched — and null means we never flag anyone outdated).
let latestCache: { version: string | null; at: number } = { version: null, at: 0 }
const LATEST_TTL_MS = 60 * 60 * 1000
async function getLatestDaemonVersion(): Promise<string | null> {
  const now = Date.now()
  if (latestCache.version && now - latestCache.at < LATEST_TTL_MS) return latestCache.version
  try {
    const res = await fetch('https://registry.npmjs.org/cumora/latest', { headers: { Accept: 'application/json' } })
    if (res.ok) {
      const v = (await res.json() as { version?: string })?.version
      if (typeof v === 'string' && v) latestCache = { version: v, at: now }
    }
  } catch { /* offline — keep the last good value */ }
  return latestCache.version
}

const AGENT_TOKEN_TTL_SECONDS = 2 * 60 * 60 // 2h; daemon refreshes before expiry

function hashToken(token: string): string {
  return createHash('sha256').update(token).digest('base64url')
}

/** Deterministic id for a company's managed Cumora Cloud computer, so it can
 *  be resolved without a lookup and stays idempotent across migrations. */
export function cloudComputerId(companyId: string): string {
  return `cloud-${companyId}`
}

/** Idempotently create the managed Cumora Cloud computer for a company.
 *  Called at company-creation time (the migration back-fills existing ones). */
export async function ensureCloudComputer(companyId: string): Promise<void> {
  await pool.query(
    `INSERT INTO computers (id, company_id, name, kind, available_engines, status)
     VALUES ($1, $2, 'Cumora Cloud', 'cloud', '["managed"]'::jsonb, 'online')
     ON CONFLICT (id) DO NOTHING`,
    [cloudComputerId(companyId), companyId],
  )
}

/** Return the company's persistent add-computer token, minting it once on first
 *  request. Unlike the old short-lived Redis code, this never expires, so a
 *  historical "add a computer" command (`--pair <token>`) stays usable. The
 *  token maps to exactly one company; a computer paired with it can only join
 *  that company. No computer row is created here. */
export async function issuePairingCode(args: {
  companyId: string
  ownerUserId: string
  computerId?: string | null
}): Promise<{ code: string; expiresInSeconds: number | null }> {
  const { rows } = await pool.query<{ pair_token: string | null }>(
    `SELECT pair_token FROM companies WHERE id = $1`, [args.companyId],
  )
  let token = rows[0]?.pair_token ?? null
  if (!token) {
    const fresh = randomBytes(24).toString('base64url') // ~32 chars, long for safety
    // Set only if still null so concurrent issuers converge on one token.
    await pool.query(`UPDATE companies SET pair_token = $1 WHERE id = $2 AND pair_token IS NULL`, [fresh, args.companyId])
    const r2 = await pool.query<{ pair_token: string | null }>(`SELECT pair_token FROM companies WHERE id = $1`, [args.companyId])
    token = r2.rows[0]?.pair_token ?? fresh
  }
  return { code: token, expiresInSeconds: null }
}

/** Rotate the workspace's add-computer token. Owner authorization is enforced
 *  by the route before this data-access operation. Existing computer
 *  credentials and computer-specific reconnect tokens remain valid. */
export async function rotateCompanyPairingCode(args: {
  companyId: string
  ownerUserId: string
  ip?: string | null
  userAgent?: string | null
}): Promise<{ code: string; expiresInSeconds: null } | { error: 'not_found' }> {
  const code = randomBytes(24).toString('base64url')
  let updated: { rows: { id: string }[] }
  try {
    updated = await pool.query<{ id: string }>(
      `UPDATE companies SET pair_token = $1 WHERE id = $2 RETURNING id`,
      [code, args.companyId],
    )
  } catch {
    // PostgreSQL unique-violation details can include the conflicting value.
    // Never propagate or log an exception that might contain the fresh code.
    throw new Error('workspace pairing code rotation failed')
  }
  if (!updated.rows[0]) return { error: 'not_found' }

  // Audit is deliberately best-effort: the UPDATE has already invalidated
  // the previous code, and audit availability must not restore it.
  await audit({
    kind: 'company_pair_token_rotated',
    userId: args.ownerUserId,
    companyId: args.companyId,
    ip: args.ip,
    userAgent: args.userAgent,
  })
  return { code, expiresInSeconds: null }
}

/** Return a persistent reconnect token for one existing non-cloud computer.
 *  Unlike the company add token, this token is bound to the computer row itself,
 *  so running the command from the Computer detail view re-attaches that exact
 *  Computer and keeps its agents. */
export async function issueRepairCode(args: {
  companyId: string
  ownerUserId: string
  computerId: string
}): Promise<{ code: string; expiresInSeconds: number | null } | null> {
  const { rows } = await pool.query<{ pair_token: string | null }>(
    `SELECT pair_token FROM computers WHERE id = $1 AND company_id = $2 AND kind <> 'cloud' AND revoked_at IS NULL LIMIT 1`,
    [args.computerId, args.companyId],
  )
  if (!rows[0]) return null
  let token = rows[0].pair_token
  if (!token) {
    const fresh = randomBytes(24).toString('base64url')
    await pool.query(
      `UPDATE computers SET pair_token = $1 WHERE id = $2 AND company_id = $3 AND pair_token IS NULL`,
      [fresh, args.computerId, args.companyId],
    )
    const r2 = await pool.query<{ pair_token: string | null }>(
      `SELECT pair_token FROM computers WHERE id = $1 AND company_id = $2`,
      [args.computerId, args.companyId],
    )
    token = r2.rows[0]?.pair_token ?? fresh
  }
  return { code: token, expiresInSeconds: null }
}

/** Redeem a persistent pairing token. Computer-specific reconnect tokens update
 *  that exact row. Company add-computer tokens create a row or re-attach by
 *  hostname to avoid duplicates when the same machine runs the command again. */
export async function pairComputer(args: {
  code: string
  hostName?: string
  engines?: string[]
  /** Optional PATH snapshot from the daemon (bin + resolved path). */
  detected?: unknown
  /** Installed engines the daemon refused to run, so the card can say why from
   *  the very first pairing rather than only after the next PATH rescan — which
   *  is minutes later, and right after pairing is exactly when "why is only
   *  codex here?" gets asked. Display-only; never joins available_engines. */
  blocked?: string[]
  /** The daemon's running version, stored so the app can flag outdated daemons. */
  version?: string
  /** Whether the daemon runs supervised (service) vs. as a foreground command. */
  supervised?: boolean
  /** Skip the online WS broadcast so the caller can fire it later (e.g. after
   *  seeding the starter team). The DB row is still marked online; only the
   *  client-facing notification is deferred. Caller must then call
   *  {@link announceComputerOnline}. */
  deferBroadcast?: boolean
}): Promise<{ computerId: string; companyId: string; deviceToken: string } | null> {
  const engines = (args.engines ?? []).filter((e) => PAIRABLE_ENGINES.has(e))
  const blocked = args.blocked ?? []
  const detected = sanitizeDetectedEngines(args.detected, engines, blocked)
  const detectedJson = JSON.stringify(detected)
  const version = typeof args.version === 'string' && args.version ? args.version.slice(0, 32) : null
  const supervised = typeof args.supervised === 'boolean' ? args.supervised : null
  const deviceToken = randomBytes(32).toString('base64url')
  const reportedName = (args.hostName ?? '').slice(0, 80)
  const name = reportedName || 'My computer'

  const exact = await pool.query<{ id: string; company_id: string; available_engines: string[] }>(
    `SELECT id, company_id, available_engines FROM computers
      WHERE pair_token = $1 AND kind <> 'cloud' AND revoked_at IS NULL
      LIMIT 1`,
    [args.code],
  )
  if (exact.rows[0]) {
    const { id, company_id: companyId, available_engines: currentEngines } = exact.rows[0]
    // A reconnect is an inventory refresh, not a default-engine change. Keep
    // the existing default first while it is still installed; if it vanished,
    // mergeDetectedEngines naturally falls back to the daemon's scan order.
    const orderedEngines = mergeDetectedEngines(currentEngines ?? [], engines) ?? (currentEngines ?? [])
    const reconnectDetectedJson = JSON.stringify(sanitizeDetectedEngines(args.detected, orderedEngines, blocked))
    await pool.query(
      `UPDATE computers
          SET credential_hash = $1, available_engines = $2::jsonb,
              name = COALESCE(NULLIF($3, ''), name),
              daemon_version = COALESCE($5, daemon_version),
              daemon_supervised = COALESCE($6, daemon_supervised),
              detected_engines = $7::jsonb, engines_detected_at = NOW(), detect_requested_at = NULL,
              status = 'online', last_seen_at = NOW(), paired_at = NOW()
        WHERE id = $4`,
      [hashToken(deviceToken), JSON.stringify(orderedEngines), reportedName, id, version, supervised, reconnectDetectedJson],
    )
    if (!args.deferBroadcast) await broadcastComputerStatus(id, companyId, 'online')
    return { computerId: id, companyId, deviceToken }
  }

  // A workspace token is read and redeemed under one row lock. Rotation's
  // UPDATE waits for this transaction, so after a rotation returns no pairing
  // that started with the old code can still commit. Reconnect tokens above
  // remain computer-scoped and keep their existing path and semantics.
  const client = await pool.connect()
  let paired: { computerId: string; companyId: string; deviceToken: string } | null = null
  try {
    await client.query('BEGIN')
    const { rows } = await client.query<{ id: string; owner_user_id: string | null }>(
      `SELECT id, owner_user_id FROM companies WHERE pair_token = $1 FOR SHARE`,
      [args.code],
    )
    if (!rows[0]) {
      await client.query('ROLLBACK')
      return null
    }
    const companyId = rows[0].id
    const ownerUserId = rows[0].owner_user_id

    // Re-attach if a non-cloud computer with this hostname already exists in
    // the company — a re-run of the persistent command from the same machine.
    // Re-mint the device token + refresh engines/status; never create a duplicate.
    const existing = await client.query<{ id: string }>(
      `SELECT id FROM computers
         WHERE company_id = $1 AND kind <> 'cloud' AND revoked_at IS NULL AND name = $2
         ORDER BY paired_at DESC NULLS LAST LIMIT 1`,
      [companyId, name],
    )
    if (existing.rows[0]) {
      const id = existing.rows[0].id
      await client.query(
        `UPDATE computers
            SET credential_hash = $1, available_engines = $2::jsonb,
                daemon_version = COALESCE($4, daemon_version),
                daemon_supervised = COALESCE($5, daemon_supervised),
                detected_engines = $6::jsonb, engines_detected_at = NOW(), detect_requested_at = NULL,
                status = 'online', last_seen_at = NOW(), paired_at = NOW(), revoked_at = NULL
          WHERE id = $3`,
        [hashToken(deviceToken), JSON.stringify(engines), id, version, supervised, detectedJson],
      )
      paired = { computerId: id, companyId, deviceToken }
    } else {
      const computerId = `comp-${randomUUID().slice(0, 12)}`
      await client.query(
        `INSERT INTO computers
           (id, company_id, owner_user_id, name, kind, available_engines, status, credential_hash, paired_at, last_seen_at, daemon_version, daemon_supervised, detected_engines, engines_detected_at)
         VALUES ($1, $2, $3, $4, 'local', $5::jsonb, 'online', $6, NOW(), NOW(), $7, $8, $9::jsonb, NOW())`,
        [computerId, companyId, ownerUserId, name, JSON.stringify(engines), hashToken(deviceToken), version, supervised, detectedJson],
      )
      paired = { computerId, companyId, deviceToken }
    }
    await client.query('COMMIT')
  } catch (error) {
    await client.query('ROLLBACK').catch(() => {})
    throw error
  } finally {
    client.release()
  }
  if (!paired) return null
  if (!args.deferBroadcast) await broadcastComputerStatus(paired.computerId, paired.companyId, 'online')
  return paired
}

/** Daemon liveness ping. Bumps last_seen_at + the reported version; flips
 *  offline→online and broadcasts only on the transition (so a steady heartbeat
 *  is quiet). The version lets the app flag outdated daemons. */
export async function heartbeatComputer(
  computerId: string,
  version?: string,
  supervised?: boolean,
  detectedEngines?: string[],
): Promise<boolean> {
  const v = typeof version === 'string' && version ? version.slice(0, 32) : null
  const sup = typeof supervised === 'boolean' ? supervised : null
  // Liveness is the primary heartbeat contract. Refreshing the optional PATH
  // inventory must not run first: one transient read failure used to reject the
  // whole request, so a healthy daemon could be swept offline even though its
  // heartbeat reached the server.
  const bumped = await pool.query<{ detect_requested_at: string | null }>(
    `UPDATE computers SET last_seen_at = NOW(), daemon_version = COALESCE($2, daemon_version),
            daemon_supervised = COALESCE($3, daemon_supervised)
      WHERE id = $1 AND revoked_at IS NULL AND status = 'online' RETURNING detect_requested_at`,
    [computerId, v, sup],
  )
  let detectRequested = Boolean(bumped.rows[0]?.detect_requested_at)
  if (!bumped.rowCount) {
    const { rows } = await pool.query<{ company_id: string; detect_requested_at: string | null }>(
      `UPDATE computers SET status = 'online', last_seen_at = NOW(), daemon_version = COALESCE($2, daemon_version),
              daemon_supervised = COALESCE($3, daemon_supervised)
        WHERE id = $1 AND revoked_at IS NULL RETURNING company_id, detect_requested_at`,
      [computerId, v, sup],
    )
    detectRequested = Boolean(rows[0]?.detect_requested_at)
    if (rows[0]) await broadcastComputerStatus(computerId, rows[0].company_id, 'online')
  }

  // Keep the advertised engine list current WITHOUT a re-pair. This secondary
  // refresh is best-effort: a database hiccup here must not turn a successful
  // liveness update into an HTTP 500. Only paired computers participate; a
  // cloud computer advertises 'managed' and has no PATH inventory.
  if (detectedEngines) {
    try {
      const { rows } = await pool.query<{ available_engines: string[]; kind: ComputerKind }>(
        `SELECT available_engines, kind FROM computers WHERE id = $1 AND revoked_at IS NULL`,
        [computerId],
      )
      const row = rows[0]
      if (row && row.kind !== 'cloud') {
        const next = mergeDetectedEngines(row.available_engines ?? [], detectedEngines)
        if (next) {
          await pool.query(
            `UPDATE computers SET available_engines = $2::jsonb WHERE id = $1 AND revoked_at IS NULL`,
            [computerId, JSON.stringify(next)],
          )
        }
      }
    } catch (err) {
      console.warn('[computers] heartbeat engine refresh failed:', err instanceof Error ? err.message : err)
    }
  }
  return detectRequested
}

/** Mark paired computers offline once their heartbeat goes stale, and
 *  broadcast each transition. Cloud computers are always-on (skipped).
 *  Runs on a server interval. */
export async function sweepOfflineComputers(staleMs = COMPUTER_STALE_MS): Promise<void> {
  const { rows } = await pool.query<{ id: string; company_id: string }>(
    `UPDATE computers SET status = 'offline'
      WHERE kind <> 'cloud' AND status = 'online'
        AND (last_seen_at IS NULL OR last_seen_at < NOW() - ($1::int * interval '1 millisecond'))
      RETURNING id, company_id`,
    [staleMs],
  )
  for (const r of rows) await broadcastComputerStatus(r.id, r.company_id, 'offline')
}

/** How long resolveDevice trusts its own last_seen_at bump before writing
 *  again. Every device-token request used to be an UPDATE; with ~870 daemons
 *  each sending several requests a minute that row write (and its LWLock
 *  wait) was ~10% of production DB time for a timestamp nobody reads at that
 *  granularity: sweepOfflineComputers only asks "older than COMPUTER_STALE_MS
 *  (90s)?", and the daemon's own 30s heartbeat bumps the column anyway. Kept
 *  at a third of the stale window so a replica that only ever sees device
 *  requests (no heartbeat) still keeps the computer online. */
export const RESOLVE_DEVICE_TOUCH_MS = 30_000
const deviceTouchedAt = new Map<string, number>()
const DEVICE_TOUCH_MAP_CAP = 10_000

function rememberDeviceTouch(hash: string, now: number): void {
  if (deviceTouchedAt.size >= DEVICE_TOUCH_MAP_CAP) {
    for (const [key, at] of deviceTouchedAt) if (now - at >= RESOLVE_DEVICE_TOUCH_MS) deviceTouchedAt.delete(key)
    if (deviceTouchedAt.size >= DEVICE_TOUCH_MAP_CAP) deviceTouchedAt.clear()
  }
  deviceTouchedAt.set(hash, now)
}

/** Test hook: forget every remembered bump so the next call writes again. */
export function resetDeviceTouches(): void {
  deviceTouchedAt.clear()
}

/** Resolve a device token (Bearer) to its computer. Rejects revoked devices.
 *  Bumps last_seen_at as a cheap liveness heartbeat, at most once per
 *  RESOLVE_DEVICE_TOUCH_MS per token; in between it is a plain indexed read,
 *  so revocation still takes effect on the very next request. */
export async function resolveDevice(token: string): Promise<{ computerId: string; companyId: string } | null> {
  if (!token) return null
  const hash = hashToken(token)
  const now = Date.now()
  const touched = deviceTouchedAt.get(hash)
  if (touched !== undefined && now - touched < RESOLVE_DEVICE_TOUCH_MS) {
    const { rows } = await pool.query<{ id: string; company_id: string }>(
      `SELECT id, company_id FROM computers
        WHERE credential_hash = $1 AND revoked_at IS NULL`,
      [hash],
    )
    if (rows[0]) return { computerId: rows[0].id, companyId: rows[0].company_id }
    // Revoked or gone: drop the memo so a re-pair with the same secret bumps.
    deviceTouchedAt.delete(hash)
    return null
  }
  const { rows } = await pool.query<{ id: string; company_id: string }>(
    `UPDATE computers SET last_seen_at = NOW()
      WHERE credential_hash = $1 AND revoked_at IS NULL
      RETURNING id, company_id`,
    [hash],
  )
  if (!rows[0]) return null
  rememberDeviceTouch(hash, now)
  return { computerId: rows[0].id, companyId: rows[0].company_id }
}

/** Mint a short-lived per-agent runtime JWT for a paired device — but only if
 *  the agent is actually assigned to that device's computer (same company).
 *  This is the credential the daemon uses for the agent's wake-stream SSE and
 *  daemon-side runtime calls. It never enters the model process or agent home. */
export async function mintAgentRuntimeToken(args: {
  providerProfile?: string | null
  computerId: string
  agentId: string
}): Promise<{ token: string; expiresInSeconds: number } | null> {
  const { rows } = await pool.query<{
    company_id: string
    computer_id: string
    runtime_assignment_id: string
  }>(
    `SELECT p.company_id, p.computer_id, p.runtime_assignment_id
       FROM participants p
       JOIN computers c
         ON c.id = p.computer_id
        AND c.company_id = p.company_id
        AND c.revoked_at IS NULL
      WHERE p.id = $1 AND p.kind = 'agent' AND p.computer_id = $2
        AND p.departed_at IS NULL
        AND p.provider_profile IS NOT DISTINCT FROM $3::text
      LIMIT 1`,
    [args.agentId, args.computerId, args.providerProfile ?? null],
  )
  if (!rows[0]) return null
  const token = signAgentToken({
    agentId: args.agentId,
    companyId: rows[0].company_id,
    computerId: rows[0].computer_id,
    assignmentId: rows[0].runtime_assignment_id,
    ttlSeconds: AGENT_TOKEN_TTL_SECONDS,
  })
  return { token, expiresInSeconds: AGENT_TOKEN_TTL_SECONDS }
}

/** Agents assigned to a computer — the daemon's discovery list on boot.
 *  Includes the per-agent big-brain (`model`) + small-brain (`fastModel`)
 *  overrides so the daemon can pass them to the engine.
 *
 *  When a row has no explicit model, the computer's engine_defaults take
 *  precedence; then a reported custom-Claude provider default; then fall back
 *  to the deploy-level default (CUMORA_DEFAULT_CLAUDE_MODEL / etc.) so every
 *  BYOA daemon without a custom provider gets a consistent pin. Critical: a
 *  model upgrade in the underlying CLI (e.g. claude 4.7 → 4.8) silently
 *  changes agent behavior on every user's machine unless we pin here. A custom
 *  provider can explicitly make its unnamed local default authoritative so a
 *  vendor-specific deploy pin never crosses into the wrong namespace. */
export async function listAgentsForComputer(computerId: string, supportsProviderProfiles = false): Promise<
  Array<{ id: string; name: string; role: string | null; systemPrompt: string | null; engine: EngineId | null; model: string | null; fastModel: string | null; providerProfile: string | null; nativeFastMode: boolean; modelCatalog?: EngineModelCatalog }>
> {
  const { rows } = await pool.query<{
    id: string; name: string; role: string | null; systemPrompt: string | null
    engine: EngineId | null; model: string | null; fastModel: string | null
    providerProfile: string | null
    nativeFastMode: boolean
    availableEngines?: string[]; detectedEngines?: unknown; engineDefaults?: unknown
  }>(
    `SELECT p.id, p.name, p.role, p.system_prompt AS "systemPrompt", p.engine, p.model,
            p.fast_model AS "fastModel", p.provider_profile AS "providerProfile", p.native_fast_mode AS "nativeFastMode", c.available_engines AS "availableEngines",
            COALESCE(c.detected_engines, '[]'::jsonb) AS "detectedEngines",
            COALESCE(c.engine_defaults, '{}'::jsonb) AS "engineDefaults"
       FROM participants p
       JOIN computers c ON c.id = p.computer_id
      WHERE p.computer_id = $1 AND p.kind = 'agent' AND p.departed_at IS NULL
        AND ($2::boolean OR p.provider_profile IS NULL)
      ORDER BY p.name ASC`,
    [computerId, supportsProviderProfiles],
  )
  const claudeDefault = process.env.CUMORA_DEFAULT_CLAUDE_MODEL?.trim() || null
  const codexDefault = process.env.CUMORA_DEFAULT_CODEX_MODEL?.trim() || null
  const grokDefault = process.env.CUMORA_DEFAULT_GROK_MODEL?.trim() || null
  const cursorDefault = process.env.CUMORA_DEFAULT_CURSOR_MODEL?.trim() || null
  const openCodeDefault = process.env.CUMORA_DEFAULT_OPENCODE_MODEL?.trim() || null
  const piDefault = process.env.CUMORA_DEFAULT_PI_MODEL?.trim() || null
  const geminiDefault = process.env.CUMORA_DEFAULT_GEMINI_MODEL?.trim() || null
  const qwenDefault = process.env.CUMORA_DEFAULT_QWEN_MODEL?.trim() || null
  const antigravityDefault = process.env.CUMORA_DEFAULT_ANTIGRAVITY_MODEL?.trim() || null
  const zcodeDefault = process.env.CUMORA_DEFAULT_ZCODE_MODEL?.trim() || null
  // omp's catalog is whatever providers the operator's own ~/.omp/agent config
  // reaches, so there is no universal default to name — only a deploy pin.
  const ompDefault = process.env.CUMORA_DEFAULT_OMP_MODEL?.trim() || null
  return rows.map((r) => {
    const { availableEngines, detectedEngines, engineDefaults, ...agent } = r
    const localCatalog = sanitizeDetectedEngines(detectedEngines, availableEngines ?? [])
      .find((entry) => entry.id === agent.engine)?.modelCatalog
    // A profile's endpoint owns its model namespace: neither the computer's
    // engine_defaults nor the deploy-level pin may name a model for it.
    if (agent.providerProfile) return { ...agent, ...(localCatalog ? { modelCatalog: localCatalog } : {}) }
    // Parse the engine_defaults JSONB
    const defaults = (engineDefaults && typeof engineDefaults === 'object'
      ? engineDefaults as EngineDefaultsMap
      : {}) as EngineDefaultsMap
    const engineDefaultsForAgent = agent.engine ? defaults[agent.engine] : undefined
    // Resolve unpinned defaults locally each turn so a provider change cannot
    // turn an old catalog default into a permanent Agent pin.
    if (localCatalog?.prefersLocalDefault) {
      return {
        ...agent,
        ...(localCatalog ? { modelCatalog: localCatalog } : {}),
        model: agent.model ?? engineDefaultsForAgent?.model ?? null,
        fastModel: agent.fastModel ?? engineDefaultsForAgent?.fastModel ?? null,
      }
    }
    // Apply engine_defaults before deploy-level defaults
    const modelWithEngineDefault = agent.model ?? engineDefaultsForAgent?.model ?? null
    const fastModelWithEngineDefault = agent.fastModel ?? engineDefaultsForAgent?.fastModel ?? null
    if (modelWithEngineDefault) {
      return { ...agent, ...(localCatalog ? { modelCatalog: localCatalog } : {}), model: modelWithEngineDefault, fastModel: fastModelWithEngineDefault }
    }
    const dflt = r.engine === 'codex'
      ? codexDefault
      : r.engine === 'claude'
        ? claudeDefault
        : r.engine === 'grok'
          ? grokDefault
          : r.engine === 'cursor'
            ? cursorDefault
            : r.engine === 'opencode'
              ? openCodeDefault
              : r.engine === 'pi'
                ? piDefault
                : r.engine === 'gemini'
                  ? geminiDefault
                  : r.engine === 'qwen'
                    ? qwenDefault
                    : r.engine === 'antigravity'
                      ? antigravityDefault
                      : r.engine === 'zcode'
                        ? zcodeDefault
                        : r.engine === 'maka'
                          ? null
                          : r.engine === 'omp'
                            ? ompDefault
                            : null
    return dflt
      ? { ...agent, ...(localCatalog ? { modelCatalog: localCatalog } : {}), model: dflt, fastModel: fastModelWithEngineDefault }
      : { ...agent, ...(localCatalog ? { modelCatalog: localCatalog } : {}), fastModel: fastModelWithEngineDefault }
  })
}

/** All computers visible to a company (Cumora Cloud + the user's paired ones),
 *  each annotated with whether its daemon is outdated vs the latest published
 *  cumora version — so the app can surface an upgrade banner. */
export async function listComputers(companyId: string): Promise<ComputerWithUpgrade[]> {
  const { rows } = await pool.query<ComputerRow>(
    `SELECT id, company_id, owner_user_id, name, kind, available_engines, status,
            last_seen_at, paired_at, revoked_at, created_at, daemon_version, daemon_supervised,
            COALESCE(detected_engines, '[]'::jsonb) AS detected_engines,
            engines_detected_at, detect_requested_at,
            COALESCE(engine_defaults, '{}'::jsonb) AS engine_defaults
       FROM computers
      WHERE company_id = $1 AND revoked_at IS NULL
      ORDER BY (kind = 'cloud') DESC, created_at ASC`,
    [companyId],
  )
  const latest = await getLatestDaemonVersion()
  return rows.map((r) => ({
    ...r,
    latest_daemon_version: latest,
    // Only BYOA daemons can be outdated, and only when we actually know the
    // latest. A daemon that never reported a version (NULL) is pre-feature →
    // definitionally old → outdated.
    daemon_outdated:
      r.kind !== 'cloud' && latest != null &&
      (r.daemon_version == null || versionGt(latest, r.daemon_version)),
  }))
}

export interface ResolvedAgentHost {
  status: 'found'
  /** kind of computer the agent runs on, or null only when truly unassigned. */
  kind: ComputerKind | null
  /** Exact assigned computer. Null is the explicit unassigned state. */
  computerId: string | null
  /** Active agent tenant. A found result never carries an empty tenant. */
  companyId: string
  /** Opaque placement generation bound into every runtime token. */
  runtimeAssignmentId: string
  /** Tenant tier read in the same database snapshot as the host assignment. */
  tier: Tier
}

export interface MissingAgentHost {
  status: 'missing'
}

export interface FailedAgentHostResolution {
  status: 'error'
  code: 'lookup_failed' | 'invalid_assignment'
  reason: string
  cause?: unknown
}

/** A database failure is deliberately different from a valid unassigned Agent. */
export type AgentHostResolution =
  | ResolvedAgentHost
  | MissingAgentHost
  | FailedAgentHostResolution

export type ManagedPodPlacement =
  | { status: 'allowed'; companyId: string; computerId: string | null; runtimeAssignmentId: string }
  | {
      status: 'denied'
      code: 'agent_not_found' | 'placement_lookup_failed' | 'placement_denied'
      reason: string
    }

function isComputerKind(value: unknown): value is ComputerKind {
  return value === 'cloud' || value === 'local' || value === 'vps'
}

/** Resolve where an agent runs + its company. Not cached. Group-message
 *  fan-out calls this once per recipient, before it knows whether that
 *  recipient already has a live subscriber, so this is on the hot path.
 *  The SQL is a participant lookup plus a LATERAL owner-tier join ordered
 *  by `company_members.joined_at`, not a single primary-key probe. An
 *  in-process cache would also go stale independently on each replica
 *  when an agent is reassigned or a tier changes. LEFT JOIN so an unassigned
 *  agent (computer_id NULL) still returns its companyId with a null kind.
 *
 *  Do not throw lookup failures into the same shape as "missing": callers route
 *  execution from this result, so every state is explicit and exhaustively
 *  handled. Soft-reference corruption (missing/cross-tenant Computer) is also
 *  an error, never an implicit cloud assignment. */
export async function resolveAgentHost(
  agentId: string,
  db: Queryable = pool,
): Promise<AgentHostResolution> {
  try {
    const { rows } = await db.query<{
      company_id: string | null
      computer_id: string | null
      runtime_assignment_id: string | null
      resolved_computer_id: string | null
      computer_company_id: string | null
      kind: string | null
      revoked_at: Date | null
      resolved_company_id: string | null
      tier: string | null
    }>(
      `SELECT p.company_id,
              p.computer_id,
              p.runtime_assignment_id,
              c.id AS resolved_computer_id,
              c.company_id AS computer_company_id,
              c.kind,
              c.revoked_at,
              company.id AS resolved_company_id,
              COALESCE(owner_user.tier, owner_member.tier, 'free') AS tier
         FROM participants p
         LEFT JOIN computers c ON c.id = p.computer_id
         LEFT JOIN companies company ON company.id = p.company_id
         LEFT JOIN users owner_user ON owner_user.id = company.owner_user_id
         LEFT JOIN LATERAL (
           SELECT u.tier
             FROM company_members cm
             JOIN users u ON u.id = cm.user_id
            WHERE cm.company_id = company.id AND cm.role = 'owner'
            ORDER BY cm.joined_at ASC
            LIMIT 1
         ) owner_member ON TRUE
        WHERE p.id = $1
          AND p.kind = 'agent'
          AND p.departed_at IS NULL
        LIMIT 1`,
      [agentId],
    )
    const row = rows[0]
    if (!row) return { status: 'missing' }
    if (!row.company_id || !row.resolved_company_id || !row.runtime_assignment_id) {
      return {
        status: 'error',
        code: 'invalid_assignment',
        reason: `agent ${agentId} has no valid company assignment`,
      }
    }
    if (row.computer_id !== null) {
      if (!row.resolved_computer_id || !isComputerKind(row.kind)) {
        return {
          status: 'error',
          code: 'invalid_assignment',
          reason: `agent ${agentId} references an unavailable computer`,
        }
      }
      if (row.computer_company_id !== row.company_id) {
        return {
          status: 'error',
          code: 'invalid_assignment',
          reason: `agent ${agentId} computer assignment crosses company boundaries`,
        }
      }
      if (row.revoked_at !== null) {
        return {
          status: 'error',
          code: 'invalid_assignment',
          reason: `agent ${agentId} is assigned to a revoked computer`,
        }
      }
    }
    return {
      status: 'found',
      kind: row.computer_id === null ? null : row.kind as ComputerKind,
      computerId: row.computer_id,
      companyId: row.company_id,
      runtimeAssignmentId: row.runtime_assignment_id,
      tier: normalizeTier(row.tier),
    }
  } catch (cause) {
    return {
      status: 'error',
      code: 'lookup_failed',
      reason: `host lookup failed for agent ${agentId}`,
      cause,
    }
  }
}

/** Final managed-runtime policy used at the `ensurePod` boundary. */
export function managedPodPlacement(
  resolution: AgentHostResolution,
): ManagedPodPlacement {
  if (resolution.status === 'missing') {
    return { status: 'denied', code: 'agent_not_found', reason: 'no such agent' }
  }
  if (resolution.status === 'error') {
    return {
      status: 'denied',
      code: resolution.code === 'lookup_failed' ? 'placement_lookup_failed' : 'placement_denied',
      reason: resolution.reason,
    }
  }
  if (isByoaKind(resolution.kind)) {
    return {
      status: 'denied',
      code: 'placement_denied',
      reason: `managed pod denied: agent is assigned to a ${resolution.kind} computer`,
    }
  }
  if (resolution.tier === 'free') {
    return {
      status: 'denied',
      code: 'placement_denied',
      reason: 'managed pod denied: free tier is BYOA-only',
    }
  }
  return {
    status: 'allowed',
    companyId: resolution.companyId,
    computerId: resolution.computerId,
    runtimeAssignmentId: resolution.runtimeAssignmentId,
  }
}

/** A BYOA host (user-paired) runs a daemon, not a server-managed pod. */
export function isByoaKind(kind: ComputerKind | null): boolean {
  return kind === 'local' || kind === 'vps'
}

/** Resolve and lock a valid Computer placement without mutating an Agent.
 *
 * Creation uses this inside the participant INSERT transaction so a rejected
 * or revoked Computer can never leave behind an unassigned Agent. Existing
 * assignment callers retain their historical fallback behavior; creation sets
 * `strictEngine` so an unavailable explicit pin fails instead of silently
 * selecting the Computer default. */
export async function resolveComputerAssignment(args: {
  providerProfile?: string | null
  companyId: string
  computerId: string
  engine?: string
  /** When true (or when no engine is named), follow the computer default. */
  inherit?: boolean
  strictEngine?: boolean
}, db: Queryable = pool): Promise<{ kind: ComputerKind; engine: EngineId; inherit: boolean } | null> {
  const { rows } = await db.query<{ kind: ComputerKind; available_engines: string[]; detected_engines?: unknown }>(
    `SELECT kind, available_engines, detected_engines FROM computers
      WHERE id = $1 AND company_id = $2 AND revoked_at IS NULL
      LIMIT 1 FOR SHARE`,
    [args.computerId, args.companyId],
  )
  const computer = rows[0]
  if (!computer) return null

  let engine: EngineId
  let inherit = false
  if (computer.kind === 'cloud') {
    engine = 'managed'
    inherit = false
  } else {
    const advertised = computer.available_engines ?? []
    const wantInherit = args.inherit === true || !args.engine
    const requested = args.engine && PAIRABLE_ENGINES.has(args.engine) ? (args.engine as EngineId) : null
    if (!wantInherit && args.strictEngine && (!requested || !advertised.includes(requested))) {
      return null
    }
    const pick = (
      wantInherit
        ? advertised[0]
        : (requested && advertised.includes(requested) ? requested : advertised[0])
    ) as EngineId | undefined
    if (!pick) return null // a paired computer with no usable engine
    engine = pick
    inherit = wantInherit
  }

  if (args.providerProfile != null) {
    if (!isProviderProfileId(args.providerProfile) || engine !== 'claude' || inherit) return null
    const profiles = sanitizeDetectedEngines(computer.detected_engines, computer.available_engines)
      .find((entry) => entry.id === 'claude')?.providerProfiles ?? []
    if (!profiles.some((p) => p.id === args.providerProfile)) return null
  }
  return { kind: computer.kind, engine, inherit }
}

/** Assign an agent to a computer (move it between Cumora Cloud and a paired
 *  machine). Resolves the engine: 'managed' for cloud, else the requested
 *  engine if the computer advertises it, else the computer's first engine.
 *  Returns the resolved { kind, engine } or null if the computer/agent is
 *  invalid for this company. */
export async function assignAgentToComputer(args: {
  providerProfile?: string | null
  agentId: string
  companyId: string
  computerId: string
  engine?: string
  /** When true (or when no engine is named), follow the computer default. */
  inherit?: boolean
  /** Optional model pins to persist in the same participant UPDATE as the
   *  host/engine assignment. undefined leaves the value untouched; null clears it. */
  model?: string | null
  fastModel?: string | null
  nativeFastMode?: boolean
}): Promise<{ kind: ComputerKind; engine: EngineId; inherit: boolean } | null> {
  const placement = await resolveComputerAssignment({ ...args, strictEngine: true })
  if (!placement) return null

  const sets = ['computer_id = $1', 'engine = $2', 'engine_inherit = $3']
  const params: unknown[] = [args.computerId, placement.engine, placement.inherit]
  if (args.model !== undefined) {
    params.push(args.model)
    sets.push(`model = $${params.length}`)
  }
  if (args.fastModel !== undefined) {
    params.push(args.fastModel)
    sets.push(`fast_model = $${params.length}`)
  }
  if (args.nativeFastMode !== undefined) {
    params.push(args.nativeFastMode)
    sets.push(`native_fast_mode = $${params.length}`)
  }
  params.push(args.providerProfile ?? null)
  sets.push(`provider_profile = $${params.length}`)
  params.push(args.agentId, args.companyId)
  const { rowCount } = await pool.query(
    `UPDATE participants SET ${sets.join(', ')}
      WHERE id = $${params.length - 1} AND company_id = $${params.length} AND kind = 'agent'`,
    params,
  )
  if (!rowCount) return null
  return placement
}

/** Ask the online daemon to re-probe PATH on its next heartbeat. */
export async function requestEngineDetect(args: {
  computerId: string
  companyId: string
}): Promise<boolean> {
  const { rowCount } = await pool.query(
    `UPDATE computers SET detect_requested_at = NOW()
      WHERE id = $1 AND company_id = $2 AND kind <> 'cloud' AND revoked_at IS NULL`,
    [args.computerId, args.companyId],
  )
  return Boolean(rowCount)
}

/** Authorize an app-initiated engine update. The computer must be this
 *  company's, and the engine must be one it already reported as outdated — the
 *  card is the only place the button exists, and a daemon should never be told
 *  to run an updater for an engine nobody saw behind.
 *
 *  Nothing but the engine id travels: the daemon derives the command from its
 *  own spec, so a request can pick which known updater runs, never what it is. */
export async function canUpdateEngine(args: {
  computerId: string
  companyId: string
  engine: string
}): Promise<boolean> {
  if (!PAIRABLE_ENGINES.has(args.engine)) return false
  const { rows } = await pool.query<{ detected_engines: DetectedEngine[] }>(
    `SELECT COALESCE(detected_engines, '[]'::jsonb) AS detected_engines FROM computers
      WHERE id = $1 AND company_id = $2 AND kind <> 'cloud' AND revoked_at IS NULL LIMIT 1`,
    [args.computerId, args.companyId],
  )
  return (rows[0]?.detected_engines ?? []).some((e) => e.id === args.engine && e.outdated === true)
}

/** Daemon reports a fresh PATH snapshot. Keeps the current default first when
 *  that engine is still installed. */
export async function reportDetectedEngines(args: {
  computerId: string
  engines?: string[]
  detected?: unknown
  /** Installed engines the daemon refused to run. Display-only — they are
   *  deliberately kept out of `available_engines`, which chooses adapters. */
  blocked?: string[]
}): Promise<boolean> {
  const { rows } = await pool.query<{ available_engines: string[]; company_id: string }>(
    `SELECT available_engines, company_id FROM computers
      WHERE id = $1 AND kind <> 'cloud' AND revoked_at IS NULL LIMIT 1`,
    [args.computerId],
  )
  const row = rows[0]
  if (!row) return false
  const incoming = (args.engines ?? []).filter((e) => PAIRABLE_ENGINES.has(e))
  const prevDefault = (row.available_engines ?? []).find((e) => PAIRABLE_ENGINES.has(e))
  const ordered = prevDefault && incoming.includes(prevDefault)
    ? [prevDefault, ...incoming.filter((e) => e !== prevDefault)]
    : incoming
  const detected = sanitizeDetectedEngines(args.detected, ordered, args.blocked ?? [])
  await pool.query(
    `UPDATE computers
        SET available_engines = $2::jsonb,
            detected_engines = $3::jsonb,
            engines_detected_at = NOW(),
            detect_requested_at = NULL
      WHERE id = $1`,
    [args.computerId, JSON.stringify(ordered), JSON.stringify(detected)],
  )
  await broadcastComputerStatus(args.computerId, row.company_id, 'online')
  return true
}

/** Sanitize and validate engine defaults before storage. Only accepts known
 *  engine ids and model ids. `strict` throws on a bad id so a write is
 *  rejected; a read drops the bad id instead, so one stored value cannot
 *  make the computer's defaults unreadable. */
function sanitizeEngineDefaults(raw: unknown, strict = false): EngineDefaultsMap {
  if (!raw || typeof raw !== 'object') return {}
  const result: EngineDefaultsMap = {}
  for (const [engineId, defaults] of Object.entries(raw as Record<string, unknown>)) {
    if (!PAIRABLE_ENGINES.has(engineId)) continue
    if (!defaults || typeof defaults !== 'object') continue
    const rec = defaults as Record<string, unknown>
    // Empty/whitespace-only strings mean "clear" — same as an explicit null.
    const cleanModel = (value: unknown): string | null | undefined => {
      try {
        return parseModelId(value)
      } catch (error) {
        if (error instanceof InvalidModelIdError) {
          if (strict) throw error
          return undefined
        }
        throw error
      }
    }
    const model = cleanModel(rec.model)
    const fastModel = cleanModel(rec.fastModel)
    if (model !== undefined || fastModel !== undefined) {
      result[engineId] = {
        ...(model !== undefined ? { model } : {}),
        ...(fastModel !== undefined ? { fastModel } : {}),
      }
    }
  }
  return result
}

/** Update the per-engine default model settings for a computer.
 *  Merges with existing defaults — pass null for a field to clear it. */
export async function updateEngineDefaults(args: {
  computerId: string
  companyId: string
  defaults: EngineDefaultsMap
}): Promise<EngineDefaultsMap | null> {
  const client = await pool.connect()
  try {
    await client.query('BEGIN')
    // Lock before reading so concurrent partial updates merge into the latest state.
    const { rows } = await client.query<{ engine_defaults: unknown }>(
      `SELECT engine_defaults FROM computers
        WHERE id = $1 AND company_id = $2 AND kind <> 'cloud' AND revoked_at IS NULL LIMIT 1 FOR UPDATE`,
      [args.computerId, args.companyId],
    )
    if (!rows[0]) {
      await client.query('COMMIT')
      return null
    }
    const existing = sanitizeEngineDefaults(rows[0].engine_defaults)
    const merged = sanitizeEngineDefaults(args.defaults, true)
    // Deep merge: for each engine, merge model and fastModel
    for (const [engineId, defaults] of Object.entries(merged)) {
      if (defaults.model === null && defaults.fastModel === null) {
        // Both null means remove this engine's defaults entirely
        delete existing[engineId]
      } else {
        existing[engineId] = {
          ...(existing[engineId] ?? {}),
          ...(defaults.model !== undefined ? { model: defaults.model } : {}),
          ...(defaults.fastModel !== undefined ? { fastModel: defaults.fastModel } : {}),
        }
        // Clean up nulls
        if (existing[engineId].model === null) delete existing[engineId].model
        if (existing[engineId].fastModel === null) delete existing[engineId].fastModel
        if (!existing[engineId].model && !existing[engineId].fastModel) delete existing[engineId]
      }
    }
    await client.query(
      `UPDATE computers SET engine_defaults = $2::jsonb WHERE id = $1`,
      [args.computerId, JSON.stringify(existing)],
    )
    await client.query('COMMIT')
    return existing
  } catch (error) {
    await client.query('ROLLBACK').catch(() => {})
    throw error
  } finally {
    client.release()
  }
}

/** Get the per-engine default model settings for a computer. */
export async function getEngineDefaults(args: {
  computerId: string
  companyId: string
}): Promise<EngineDefaultsMap | null> {
  const { rows } = await pool.query<{ engine_defaults: unknown }>(
    `SELECT engine_defaults FROM computers
      WHERE id = $1 AND company_id = $2 AND kind <> 'cloud' AND revoked_at IS NULL LIMIT 1`,
    [args.computerId, args.companyId],
  )
  if (!rows[0]) return null
  return sanitizeEngineDefaults(rows[0].engine_defaults)
}

/** Make `engine` this computer's default and move every inheriting agent onto it. */
export async function setComputerDefaultEngine(args: {
  computerId: string
  companyId: string
  engine: string
}): Promise<{ engine: EngineId; updated: number } | null> {
  if (!PAIRABLE_ENGINES.has(args.engine)) return null
  const { rows } = await pool.query<{ available_engines: string[]; detected_engines: DetectedEngine[] }>(
    `SELECT available_engines, COALESCE(detected_engines, '[]'::jsonb) AS detected_engines
       FROM computers
      WHERE id = $1 AND company_id = $2 AND kind <> 'cloud' AND revoked_at IS NULL LIMIT 1`,
    [args.computerId, args.companyId],
  )
  const computer = rows[0]
  if (!computer) return null
  const advertised = computer.available_engines ?? []
  if (!advertised.includes(args.engine)) return null
  const engine = args.engine as EngineId
  const ordered = [engine, ...advertised.filter((e) => e !== engine)]
  const detected = sanitizeDetectedEngines(computer.detected_engines, ordered)
  await pool.query(
    `UPDATE computers
        SET available_engines = $2::jsonb, detected_engines = $3::jsonb
      WHERE id = $1`,
    [args.computerId, JSON.stringify(ordered), JSON.stringify(detected)],
  )
  const moved = await pool.query(
    `UPDATE participants SET engine = $1
      WHERE computer_id = $2 AND company_id = $3 AND kind = 'agent'
        AND departed_at IS NULL AND engine_inherit = TRUE`,
    [engine, args.computerId, args.companyId],
  )
  await broadcastComputerStatus(args.computerId, args.companyId, 'online')
  return { engine, updated: moved.rowCount ?? 0 }
}

/** Revoke a paired computer: the device token + every derived agent JWT stop
 *  working, and its agents go offline. Cloud computers cannot be revoked. */
export async function revokeComputer(args: { computerId: string; companyId: string }): Promise<boolean> {
  const { rowCount } = await pool.query(
    `UPDATE computers SET revoked_at = NOW(), status = 'offline', credential_hash = NULL
      WHERE id = $1 AND company_id = $2 AND kind <> 'cloud' AND revoked_at IS NULL`,
    [args.computerId, args.companyId],
  )
  if (!rowCount) return false
  await broadcastComputerStatus(args.computerId, args.companyId, 'offline')
  return true
}