thinkpool-pair 0.7.358 → 0.7.359

package/scheduled-run-admission.mjs

@@ -0,0 +1,364 @@
+// Host-wide scheduled-run admission for account-served room bridge children.
+//
+// Every room bridge is a separate process, so a process-local count/window cannot
+// enforce the laptop safety boundary. This ledger serializes admissions under
+// TP_PAIR_ROOT. It stores only hashes and millisecond timestamps: never room codes,
+// prompts, provider/model names, credentials, endpoints, or host paths.
+
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { createHash, randomUUID } from 'node:crypto'
+import { SPAWN } from './cross-terminal.mjs'
+
+const VERSION = 1
+const LEDGER_NAME = 'scheduled-run-admission.json'
+const LOCK_NAME = '.scheduled-run-admission.lock'
+const MAX_LEDGER_BYTES = 128 * 1024
+const DEFAULT_LOCK_WAIT_MS = 1_000
+const DEFAULT_STALE_LOCK_MS = 30_000
+const DEFAULT_RETRY_MS = 12
+const DEFAULT_MAX_LEASE_MS = 31 * 60 * 1_000
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._:@-]{0,255}$/
+
+const rootPath = (root) => path.resolve(root || process.env.TP_PAIR_ROOT || path.join(os.homedir(), '.thinkpool-pair'))
+const pathsFor = (root) => {
+  const dir = rootPath(root)
+  return {
+    dir,
+    ledger: path.join(dir, LEDGER_NAME),
+    lock: path.join(dir, LOCK_NAME),
+  }
+}
+const digest = (value) => createHash('sha256').update(String(value)).digest('hex')
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+const finiteInt = (value) => Number.isSafeInteger(value) && value >= 0
+const exactKeys = (value, expected) =>
+  value && typeof value === 'object' &&
+  Object.keys(value).sort().join('\0') === [...expected].sort().join('\0')
+
+function normalizeLimits (limits = {}) {
+  const machineMax = Number.isSafeInteger(limits.machineMax) && limits.machineMax > 0 ? limits.machineMax : SPAWN.machineMax
+  const perWindowCap = Number.isSafeInteger(limits.perWindowCap) && limits.perWindowCap > 0 ? limits.perWindowCap : SPAWN.perWindowCap
+  const windowMs = Number.isSafeInteger(limits.windowMs) && limits.windowMs > 0 ? limits.windowMs : SPAWN.windowMs
+  const maxLeaseMs = Number.isSafeInteger(limits.maxLeaseMs) && limits.maxLeaseMs > 0 ? limits.maxLeaseMs : DEFAULT_MAX_LEASE_MS
+  return Object.freeze({ machineMax, perWindowCap, windowMs, maxLeaseMs })
+}
+
+function emptyLedger () {
+  return { version: VERSION, leases: [], spawnTimes: [] }
+}
+
+function validLease (lease) {
+  return Boolean(exactKeys(lease, ['runKey', 'terminalKey', 'tokenHash', 'acquiredAt', 'expiresAt']) &&
+    /^[a-f0-9]{64}$/.test(lease.runKey) &&
+    /^[a-f0-9]{64}$/.test(lease.terminalKey) &&
+    /^[a-f0-9]{64}$/.test(lease.tokenHash) &&
+    finiteInt(lease.acquiredAt) &&
+    finiteInt(lease.expiresAt) &&
+    lease.expiresAt > lease.acquiredAt)
+}
+
+function readLedger (file, limits) {
+  let fd = null
+  let raw
+  try {
+    fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0))
+    const stat = fs.fstatSync(fd)
+    if (!stat.isFile() || stat.size > MAX_LEDGER_BYTES) throw new Error('invalid_admission_ledger')
+    raw = fs.readFileSync(fd, 'utf8')
+  } catch (error) {
+    if (error?.code === 'ENOENT') return emptyLedger()
+    throw error
+  } finally {
+    if (fd != null) fs.closeSync(fd)
+  }
+  const parsed = JSON.parse(raw)
+  if (!exactKeys(parsed, ['version', 'leases', 'spawnTimes']) || parsed.version !== VERSION || !Array.isArray(parsed.leases) || !Array.isArray(parsed.spawnTimes)) throw new Error('invalid_admission_ledger')
+  // Generous parse bounds let a future lower configured cap prune an older
+  // snapshot, while still refusing attacker-sized or corrupted structures.
+  if (parsed.leases.length > Math.max(64, limits.machineMax * 4) || parsed.spawnTimes.length > Math.max(128, limits.perWindowCap * 8)) throw new Error('unbounded_admission_ledger')
+  if (!parsed.leases.every(validLease) || !parsed.spawnTimes.every(finiteInt)) throw new Error('invalid_admission_ledger')
+  if (new Set(parsed.leases.map((lease) => lease.runKey)).size !== parsed.leases.length ||
+      new Set(parsed.leases.map((lease) => lease.terminalKey)).size !== parsed.leases.length) throw new Error('duplicate_admission_ledger')
+  return parsed
+}
+
+function pruneLedger (ledger, now, limits) {
+  // Never truncate still-active leases merely because a later process starts
+  // with a lower cap. Every active lease continues to consume capacity until
+  // exact release or expiry.
+  const leases = ledger.leases.filter((lease) => lease.expiresAt > now)
+  const spawnTimes = ledger.spawnTimes
+    .filter((at) => at > now - limits.windowMs && at <= now)
+    .sort((a, b) => a - b)
+  return {
+    ledger: { version: VERSION, leases, spawnTimes },
+    changed: leases.length !== ledger.leases.length || spawnTimes.length !== ledger.spawnTimes.length,
+  }
+}
+
+let tempSerial = 0
+function atomicWriteLedger (file, ledger) {
+  const serialized = `${JSON.stringify(ledger)}\n`
+  if (Buffer.byteLength(serialized) > MAX_LEDGER_BYTES) throw new Error('unbounded_admission_ledger')
+  const tmp = path.join(path.dirname(file), `.${path.basename(file)}.tmp.${process.pid}.${Date.now()}.${tempSerial++}`)
+  let fd = null
+  try {
+    fd = fs.openSync(tmp, 'wx', 0o600)
+    const bytes = Buffer.from(serialized)
+    for (let offset = 0; offset < bytes.length;) {
+      const written = fs.writeSync(fd, bytes, offset, bytes.length - offset)
+      if (written <= 0) throw new Error('short_admission_write')
+      offset += written
+    }
+    fs.fsyncSync(fd)
+    fs.closeSync(fd)
+    fd = null
+    fs.renameSync(tmp, file)
+    fs.chmodSync(file, 0o600)
+    // Persist the directory entry where the host filesystem supports it.
+    let dirFd = null
+    try {
+      dirFd = fs.openSync(path.dirname(file), 'r')
+      fs.fsyncSync(dirFd)
+    } catch {
+      // Windows and some network filesystems reject directory fsync. The
+      // replacement file itself was still fsynced before the atomic rename.
+    } finally {
+      if (dirFd != null) fs.closeSync(dirFd)
+    }
+  } catch (error) {
+    try { if (fd != null) fs.closeSync(fd) } catch { /* best effort */ }
+    try { fs.rmSync(tmp, { force: true }) } catch { /* best effort */ }
+    throw error
+  }
+}
+
+function ensureRoot (dir) {
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
+  const stat = fs.lstatSync(dir)
+  if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('invalid_pair_root')
+}
+
+function readLockOwner (lock) {
+  const file = path.join(lock, 'owner')
+  const stat = fs.lstatSync(file)
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1_024) return null
+  const owner = JSON.parse(fs.readFileSync(file, 'utf8'))
+  if (!exactKeys(owner, ['pid', 'token', 'createdAt']) ||
+      !Number.isSafeInteger(owner.pid) || owner.pid < 1 ||
+      typeof owner.token !== 'string' || !/^[a-f0-9-]{36}$/.test(owner.token) ||
+      !finiteInt(owner.createdAt)) return null
+  return owner
+}
+
+function ownerProcessState (pid) {
+  try {
+    process.kill(pid, 0)
+    return 'live'
+  } catch (error) {
+    if (error?.code === 'ESRCH') return 'dead'
+    // EPERM and every unknown platform error fail closed.
+    return 'unknown'
+  }
+}
+
+function recoverStaleLock (lock, staleLockMs, now) {
+  const stat = fs.lstatSync(lock)
+  if (!stat.isDirectory() || stat.isSymbolicLink() || now - stat.mtimeMs <= staleLockMs) return false
+  let owner = null
+  try { owner = readLockOwner(lock) } catch { return false }
+  if (!owner || ownerProcessState(owner.pid) !== 'dead') return false
+  // Rename is the recovery claim. Only the process that atomically moves this
+  // exact stale directory may remove it; contenders see ENOENT and retry. A
+  // live, permission-unknown, or malformed owner is never stolen.
+  const stale = `${lock}.stale.${process.pid}.${randomUUID()}`
+  fs.renameSync(lock, stale)
+  fs.rmSync(stale, { recursive: true, force: true })
+  return true
+}
+
+async function acquireLock ({ dir, lock }, { lockWaitMs = DEFAULT_LOCK_WAIT_MS, staleLockMs = DEFAULT_STALE_LOCK_MS, retryMs = DEFAULT_RETRY_MS } = {}) {
+  ensureRoot(dir)
+  const startedAt = Date.now()
+  while (Date.now() - startedAt <= lockWaitMs) {
+    const owner = Object.freeze({ pid: process.pid, token: randomUUID(), createdAt: Date.now() })
+    try {
+      fs.mkdirSync(lock, { mode: 0o700 })
+      fs.writeFileSync(path.join(lock, 'owner'), JSON.stringify(owner), { flag: 'wx', mode: 0o600 })
+      return owner
+    } catch (error) {
+      if (error?.code !== 'EEXIST') {
+        // If mkdir succeeded but writing the ownership marker failed, remove
+        // only the markerless lock we just created.
+        try {
+          if (fs.existsSync(lock) && !fs.existsSync(path.join(lock, 'owner'))) fs.rmdirSync(lock)
+        } catch { /* a contender/stale recovery may own the path now */ }
+        throw error
+      }
+      try {
+        if (recoverStaleLock(lock, staleLockMs, Date.now())) continue
+      } catch (recoveryError) {
+        if (!['ENOENT', 'EEXIST'].includes(recoveryError?.code)) throw recoveryError
+      }
+      await sleep(Math.max(1, retryMs))
+    }
+  }
+  throw new Error('admission_lock_timeout')
+}
+
+async function withLedgerLock (options, operation) {
+  const paths = pathsFor(options?.root)
+  let lockOwner = null
+  try {
+    lockOwner = await acquireLock(paths, options)
+    return await operation(paths)
+  } finally {
+    if (lockOwner) {
+      try {
+        // A paused process may resume after its stale lock was recovered. Never
+        // let that old holder remove the new holder's lock.
+        const ownerFile = path.join(paths.lock, 'owner')
+        const currentOwner = readLockOwner(paths.lock)
+        if (currentOwner?.pid === lockOwner.pid && currentOwner?.token === lockOwner.token) {
+          fs.rmSync(ownerFile, { force: true })
+          fs.rmdirSync(paths.lock)
+        }
+      } catch { /* stale recovery/host cleanup owns it */ }
+    }
+  }
+}
+
+function invalidIdentity (runId, terminalId) {
+  return typeof runId !== 'string' || !SAFE_ID.test(runId) || typeof terminalId !== 'string' || !SAFE_ID.test(terminalId)
+}
+
+// Acquire before the database claim and local spawn. `runId` may be the
+// deterministic occurrence key (schedule-id + next-run-at) because the database
+// UUID does not exist until claim_due_code_schedule succeeds.
+export async function acquireScheduledRunAdmission ({
+  runId,
+  terminalId,
+  deadlineAt,
+  now = Date.now(),
+  root,
+  limits,
+  lockWaitMs,
+  staleLockMs,
+  retryMs,
+} = {}) {
+  const policy = normalizeLimits(limits)
+  if (invalidIdentity(runId, terminalId) || !finiteInt(now) || !finiteInt(deadlineAt) || deadlineAt <= now || deadlineAt - now > policy.maxLeaseMs) {
+    return Object.freeze({ ok: false, code: 'invalid_admission_request' })
+  }
+  const token = randomUUID()
+  const runKey = digest(runId)
+  const terminalKey = digest(terminalId)
+  try {
+    return await withLedgerLock({ root, lockWaitMs, staleLockMs, retryMs }, ({ ledger: file }) => {
+      const loaded = readLedger(file, policy)
+      const { ledger, changed } = pruneLedger(loaded, now, policy)
+      const sameRun = ledger.leases.find((lease) => lease.runKey === runKey)
+      const sameTerminal = ledger.leases.find((lease) => lease.terminalKey === terminalKey)
+      if (sameRun || sameTerminal) {
+        if (changed) atomicWriteLedger(file, ledger)
+        return Object.freeze({
+          ok: false,
+          code: sameRun && sameTerminal && sameRun === sameTerminal
+            ? 'duplicate_lease'
+            : sameRun ? 'duplicate_run' : 'duplicate_terminal',
+        })
+      }
+      if (ledger.leases.length >= policy.machineMax) {
+        if (changed) atomicWriteLedger(file, ledger)
+        return Object.freeze({ ok: false, code: 'machine_cap' })
+      }
+      if (ledger.spawnTimes.length >= policy.perWindowCap) {
+        if (changed) atomicWriteLedger(file, ledger)
+        return Object.freeze({ ok: false, code: 'burst_cap', retryAt: ledger.spawnTimes[0] + policy.windowMs })
+      }
+      ledger.leases.push({ runKey, terminalKey, tokenHash: digest(token), acquiredAt: now, expiresAt: deadlineAt })
+      ledger.spawnTimes.push(now)
+      atomicWriteLedger(file, ledger)
+      return Object.freeze({
+        ok: true,
+        code: 'admitted',
+        lease: Object.freeze({ runId, terminalId, token, expiresAt: deadlineAt }),
+      })
+    })
+  } catch {
+    return Object.freeze({ ok: false, code: 'admission_unavailable' })
+  }
+}
+
+// Exact-pair + one-time token release makes outcome/close cleanup idempotent
+// without allowing one room child to free another child's active lease.
+export async function releaseScheduledRunAdmission ({
+  runId,
+  terminalId,
+  token,
+  now = Date.now(),
+  root,
+  limits,
+  lockWaitMs,
+  staleLockMs,
+  retryMs,
+} = {}) {
+  const policy = normalizeLimits(limits)
+  if (invalidIdentity(runId, terminalId) || typeof token !== 'string' || token.length < 16 || token.length > 128 || !finiteInt(now)) {
+    return Object.freeze({ ok: false, code: 'invalid_release_request' })
+  }
+  const runKey = digest(runId)
+  const terminalKey = digest(terminalId)
+  const tokenHash = digest(token)
+  try {
+    return await withLedgerLock({ root, lockWaitMs, staleLockMs, retryMs }, ({ ledger: file }) => {
+      const loaded = readLedger(file, policy)
+      const { ledger, changed } = pruneLedger(loaded, now, policy)
+      const index = ledger.leases.findIndex((lease) => lease.runKey === runKey && lease.terminalKey === terminalKey)
+      if (index < 0) {
+        if (ledger.leases.some((lease) => lease.runKey === runKey || lease.terminalKey === terminalKey)) {
+          return Object.freeze({ ok: false, code: 'lease_mismatch' })
+        }
+        if (changed) atomicWriteLedger(file, ledger)
+        return Object.freeze({ ok: true, code: 'already_released' })
+      }
+      if (ledger.leases[index].tokenHash !== tokenHash) return Object.freeze({ ok: false, code: 'lease_mismatch' })
+      ledger.leases.splice(index, 1)
+      atomicWriteLedger(file, ledger)
+      return Object.freeze({ ok: true, code: 'released' })
+    })
+  } catch {
+    return Object.freeze({ ok: false, code: 'admission_unavailable' })
+  }
+}
+
+// Secret-free diagnostics/tests: counts and expiry only.
+export async function inspectScheduledRunAdmissions ({
+  now = Date.now(),
+  root,
+  limits,
+  lockWaitMs,
+  staleLockMs,
+  retryMs,
+} = {}) {
+  const policy = normalizeLimits(limits)
+  if (!finiteInt(now)) return Object.freeze({ ok: false, code: 'invalid_inspection_request' })
+  try {
+    return await withLedgerLock({ root, lockWaitMs, staleLockMs, retryMs }, ({ ledger: file }) => {
+      const loaded = readLedger(file, policy)
+      const { ledger, changed } = pruneLedger(loaded, now, policy)
+      if (changed) atomicWriteLedger(file, ledger)
+      return Object.freeze({
+        ok: true,
+        code: 'inspected',
+        active: ledger.leases.length,
+        burst: ledger.spawnTimes.length,
+        nextExpiryAt: ledger.leases.length ? Math.min(...ledger.leases.map((lease) => lease.expiresAt)) : null,
+      })
+    })
+  } catch {
+    return Object.freeze({ ok: false, code: 'admission_unavailable' })
+  }
+}

package/scheduled-runs.mjs

@@ -0,0 +1,268 @@
+// Durable, bridge-local execution for the deliberately small unattended-run V1.
+// This module owns no credentials and never executes a provider itself: it admits a
+// pre-bound schedule, asks the database to fence one occurrence, then lets bridge.mjs
+// open an ordinary visible top-level terminal.
+
+import { randomUUID } from 'node:crypto'
+import { SPAWN, spawnDecision } from './cross-terminal.mjs'
+
+const RUN_KINDS = new Set(['once', 'daily', 'weekly'])
+const RUNTIMES = new Set(['claude', 'codex', 'hermes'])
+const OUTCOMES = new Set(['delivered', 'needs_decision', 'failed', 'canceled'])
+const REF_TYPES = new Set(['artifact', 'preview', 'commit', 'test', 'flow_task', 'control_item'])
+const SECRET = /(?:sk-[a-z0-9_-]{8,}|gsk_[a-z0-9_-]{8,}|AIza[a-z0-9_-]{8,}|gh[pousr]_[a-z0-9]{20,}|github_pat_[a-z0-9_]{20,}|xox[baprs]-[a-z0-9-]{10,}|AKIA[0-9A-Z]{16}|sbp_[a-z0-9]{20,}|eyJ[a-z0-9_-]{16,}\.[a-z0-9_-]{16,}\.[a-z0-9_-]{8,}|bearer\s+[a-z0-9._-]{8,}|(?:token|secret|api[_-]?key|authorization)\s*=)/i
+const HOST_PATH = /(?:^|\s)(?:~\/|\/Users\/|\/home\/|\/private\/|\/tmp\/|[A-Za-z]:\\|\.\.[\\/])/i
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._:@-]{0,159}$/
+const OUTCOME_CODE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$/
+const formatterCache = new Map()
+
+// This is deliberately opt-in. A packaged bridge with schedules in its database
+// remains inert unless its owner explicitly enables unattended execution.
+export const scheduledRunsEnabled = (value = process.env.TP_SCHEDULED_RUNS_ENABLED) => value === '1'
+// Secret-free room projection. Clients need only the host owner's opt-in state,
+// never the scheduler's authentication, lease/fencing, or execution internals.
+export const scheduledRunsCapability = (value = process.env.TP_SCHEDULED_RUNS_ENABLED) => Object.freeze({
+  enabled: scheduledRunsEnabled(value),
+})
+
+const text = (value, max) => typeof value === 'string' && value.trim().length > 0 && value.length <= max && !SECRET.test(value) && !HOST_PATH.test(value)
+const date = (value) => value instanceof Date ? value : new Date(value)
+const validDate = (value) => !Number.isNaN(date(value).getTime())
+const timeParts = (zone, at) => {
+  let formatter = formatterCache.get(zone)
+  if (!formatter) {
+    formatter = new Intl.DateTimeFormat('en-CA', { timeZone: zone, weekday: 'short', hour: '2-digit', minute: '2-digit', hourCycle: 'h23' })
+    formatterCache.set(zone, formatter)
+  }
+  const parts = Object.fromEntries(formatter.formatToParts(at).filter((part) => part.type !== 'literal').map((part) => [part.type, part.value]))
+  return { weekday: ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'].indexOf(parts.weekday), time: `${parts.hour}:${parts.minute}` }
+}
+
+export function scheduleValidationError (input = {}) {
+  if (!input || typeof input !== 'object' || !RUN_KINDS.has(input.kind)) return 'invalid_kind'
+  if (!text(input.title, 120) || !text(input.prompt, 12_000)) return 'unsafe_or_invalid_text'
+  if (!RUNTIMES.has(input.runtime)) return 'invalid_runtime'
+  if (input.provider != null && (!text(input.provider, 80) || !SAFE_ID.test(input.provider))) return 'invalid_provider'
+  if (input.model != null && (!text(input.model, 160) || !SAFE_ID.test(input.model))) return 'invalid_model'
+  if (!Number.isInteger(input.maxRuntimeMinutes) || input.maxRuntimeMinutes < 1 || input.maxRuntimeMinutes > 30) return 'invalid_max_runtime'
+  try { new Intl.DateTimeFormat('en', { timeZone: input.timezone }) } catch { return 'invalid_timezone' }
+  if (input.kind === 'once' && !validDate(input.at)) return 'invalid_once_time'
+  if (input.kind !== 'once' && !/^\d{2}:\d{2}$/.test(input.time) || input.kind !== 'once' && (Number(input.time.slice(0, 2)) > 23 || Number(input.time.slice(3)) > 59)) return 'invalid_local_time'
+  if (input.kind === 'weekly' && (!Number.isInteger(input.weekday) || input.weekday < 0 || input.weekday > 6)) return 'invalid_weekday'
+  return null
+}
+
+export function normalizeSchedule (input = {}, now = new Date()) {
+  const error = scheduleValidationError(input)
+  if (error) return Object.freeze({ ok: false, code: error })
+  const normalized = {
+    kind: input.kind, title: input.title.trim(), prompt: input.prompt.trim(), runtime: input.runtime,
+    provider: input.provider || null, model: input.model || null, timezone: input.timezone,
+    maxRuntimeMinutes: input.maxRuntimeMinutes, ...(input.kind === 'once' ? { at: date(input.at).toISOString() } : { time: input.time, ...(input.kind === 'weekly' ? { weekday: input.weekday } : {}) }),
+  }
+  const nextRunAt = nextScheduledAt(normalized, now)
+  if (!nextRunAt) return Object.freeze({ ok: false, code: 'schedule_exhausted' })
+  return Object.freeze({ ok: true, value: Object.freeze(normalized), nextRunAt: nextRunAt.toISOString() })
+}
+
+// Search minute boundaries in local calendar time. This is intentionally a small,
+// deterministic preset scheduler: nonexistent DST minutes are skipped, repeated minutes
+// choose the first future instant, and raw cron is not accepted anywhere.
+export function nextScheduledAt (schedule, after = new Date()) {
+  if (schedule?.kind === 'once') {
+    const once = date(schedule.at)
+    return validDate(once) && once.getTime() > date(after).getTime() ? once : null
+  }
+  const start = Math.floor(date(after).getTime() / 60_000) * 60_000 + 60_000
+  for (let ms = start, end = start + 400 * 86_400_000; ms < end; ms += 60_000) {
+    const local = timeParts(schedule.timezone, new Date(ms))
+    if (local.time === schedule.time && (schedule.kind === 'daily' || local.weekday === schedule.weekday)) return new Date(ms)
+  }
+  return null
+}
+
+export function classifyRunOutcome ({ result = null, evidenceRefs = [], pendingControls = [], runId = null, canceled = false } = {}) {
+  // A hard runtime ceiling is the terminal outcome even if the aborted runtime
+  // still has a pending permission or produced earlier evidence.
+  if (result?.subtype === 'runtime_limit') return Object.freeze({ outcome: 'failed', code: 'runtime_limit' })
+  if (canceled || ['aborted', 'canceled', 'cancelled', 'interrupted'].includes(result?.subtype)) return Object.freeze({ outcome: 'canceled', code: 'canceled' })
+  const evidence = (Array.isArray(evidenceRefs) ? evidenceRefs : []).filter((ref) => ref && REF_TYPES.has(ref.type) && typeof ref.id === 'string' && SAFE_ID.test(ref.id)).slice(0, 16)
+  if (evidence.length) return Object.freeze({ outcome: 'delivered', code: 'evidence_delivered', evidence })
+  const pending = (Array.isArray(pendingControls) ? pendingControls : []).find((item) =>
+    item?.status === 'pending' && item?.id && item?.request_context?.run_id &&
+    (!runId || item.request_context.run_id === runId) &&
+    Number.isSafeInteger(Number(item.source_event_from_seq)))
+  if (pending) return Object.freeze({ outcome: 'needs_decision', code: 'pending_pair_control', controlItemId: pending.id })
+  if (result?.subtype === 'success') return Object.freeze({ outcome: 'failed', code: 'missing_deliverable' })
+  return Object.freeze({ outcome: 'failed', code: result?.subtype || 'runtime_failed' })
+}
+
+const sanitizedEvidence = (refs) => (Array.isArray(refs) ? refs : [])
+  .filter((ref) => ref && REF_TYPES.has(ref.type) && typeof ref.id === 'string' && SAFE_ID.test(ref.id))
+  .slice(0, 16)
+  .map((ref) => Object.freeze({ type: ref.type, id: ref.id }))
+
+// The host outbox persists only the minimum replayable intent. Never persist
+// result text, permission input, prompts, credentials, endpoints, or host paths.
+export function sanitizeScheduledOutcomeIntent ({ runId, result = null, evidenceRefs = [], canceled = false } = {}) {
+  if (typeof runId !== 'string' || !SAFE_ID.test(runId)) return null
+  const subtype = typeof result?.subtype === 'string' && OUTCOME_CODE.test(result.subtype) ? result.subtype : 'runtime_failed'
+  return Object.freeze({
+    runId,
+    result: Object.freeze({ subtype }),
+    evidenceRefs: Object.freeze(sanitizedEvidence(evidenceRefs)),
+    canceled: canceled === true,
+  })
+}
+
+// A restored result/decision outbox owns the occurrence until its idempotent
+// database finish is acknowledged. An elapsed runtime deadline must not replace
+// that already-chosen outcome, and the scheduler must not expire occurrences
+// while any such durable intent is still awaiting reconciliation.
+export function scheduledRunDeadlineRequired ({ runId, deadlineAt, outcomeRecorded = false, outcomePending = null } = {}) {
+  return Boolean(runId && Number.isFinite(deadlineAt) && !outcomeRecorded && !outcomePending)
+}
+export function scheduledOutcomeReconciliationComplete (pendingOutcomes = []) {
+  return Array.isArray(pendingOutcomes) && pendingOutcomes.length === 0
+}
+
+// Scheduled runs share the ordinary spawn kill-switch, machine cap, and burst
+// window, but are not Ensemble dispatches and therefore never consume a plan
+// quota. The returned window is pruned and bounded; callers persist it only when
+// ok=true.
+export function scheduledRunSpawnAdmission ({ spawnTimes = [], now = Date.now(), totalLive = 0, disabled = false } = {}, limits = SPAWN) {
+  const o = { ...SPAWN, ...(limits || {}) }
+  const recent = (Array.isArray(spawnTimes) ? spawnTimes : [])
+    .filter((value) => Number.isFinite(value) && value > now - o.windowMs)
+    .slice(-(o.perWindowCap || 1))
+  const gate = spawnDecision({
+    hop: 0,
+    spawnTimes: recent,
+    now,
+    spawnedLive: 0,
+    totalLive,
+    plan: 'free',
+    disabled,
+  }, o)
+  return Object.freeze({
+    ...gate,
+    spawnTimes: Object.freeze(gate.ok ? [...recent, now].slice(-o.perWindowCap) : recent),
+  })
+}
+
+export function preflightScheduledRun ({ schedule, occurrence, ownerId, bridgeId, bridgeFencing, providerAvailable, capsOk = true, now = new Date() } = {}) {
+  if (!schedule?.enabled) return Object.freeze({ ok: false, code: 'schedule_disabled' })
+  if (!occurrence?.id || occurrence.schedule_revision !== schedule.revision) return Object.freeze({ ok: false, code: 'stale_schedule_revision' })
+  if (!ownerId || !bridgeId || !Number.isSafeInteger(bridgeFencing) || bridgeFencing < 1 || occurrence.owner_id !== ownerId || occurrence.bridge_id !== bridgeId || occurrence.bridge_fencing !== bridgeFencing) return Object.freeze({ ok: false, code: 'owner_bridge_mismatch' })
+  if (!capsOk) return Object.freeze({ ok: false, code: 'runtime_cap_exceeded' })
+  if (typeof providerAvailable !== 'function' || !providerAvailable(schedule)) return Object.freeze({ ok: false, code: 'provider_unavailable' })
+  if (!occurrence.lease_expires_at || date(occurrence.lease_expires_at).getTime() <= date(now).getTime()) return Object.freeze({ ok: false, code: 'lease_expired' })
+  return Object.freeze({ ok: true, code: 'admitted' })
+}
+
+const rpc = async ({ fetchImpl, supabaseUrl, headers, name, body }) => {
+  const response = await fetchImpl(`${String(supabaseUrl).replace(/\/$/, '')}/rest/v1/rpc/${name}`, { method: 'POST', headers, body: JSON.stringify(body) })
+  if (!response?.ok) throw new Error(`${name}_failed`)
+  return response.json()
+}
+
+export async function pollDueScheduledRuns ({ enabled = false, fetchImpl = globalThis.fetch, supabaseUrl, anonKey, token, roomCode, bridgeId, bridgeFencing, ownerId, providerAvailable, openTerminal, admitRun, releaseRun, makeTerminalId = randomUUID, capsOk = () => true, now = new Date() } = {}) {
+  if (!enabled) return Object.freeze({ ok: false, code: 'feature_disabled', runs: [] })
+  if (typeof fetchImpl !== 'function' || !supabaseUrl || !anonKey || !token || !roomCode || !bridgeId || !Number.isSafeInteger(bridgeFencing) || bridgeFencing < 1 || !ownerId || typeof openTerminal !== 'function' || typeof admitRun !== 'function' || typeof releaseRun !== 'function' || typeof makeTerminalId !== 'function') return Object.freeze({ ok: false, code: 'runner_unavailable', runs: [] })
+  const headers = { apikey: anonKey, Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' }
+  const normalizedRoomCode = String(roomCode).trim().toUpperCase()
+  try {
+    // An opened row can outlive its local terminal if the room process dies in
+    // the durable-open/local-open gap. Once its lease (runtime ceiling + grace)
+    // expires, turn that ambiguity into one explicit failure instead of leaving
+    // the occurrence permanently "running".
+    const expired = await rpc({ fetchImpl, supabaseUrl, headers, name: 'expire_code_scheduled_runs', body: {
+      p_room_code: normalizedRoomCode, p_bridge_id: bridgeId, p_bridge_fencing: bridgeFencing, p_limit: 24,
+    } })
+    if (!expired?.ok) throw new Error('expire_code_scheduled_runs_failed')
+    const due = await rpc({ fetchImpl, supabaseUrl, headers, name: 'list_due_code_schedules', body: {
+      p_room_code: normalizedRoomCode, p_limit: 12,
+    } })
+    const runs = []
+    for (const schedule of Array.isArray(due) ? due : []) {
+      if (String(schedule?.session_code || '').trim().toUpperCase() !== normalizedRoomCode) {
+        runs.push({ scheduleId: schedule?.id, code: 'room_scope_mismatch' })
+        continue
+      }
+      if (!capsOk(schedule)) { runs.push({ scheduleId: schedule.id, code: 'runtime_cap_exceeded' }); continue }
+      if (typeof providerAvailable !== 'function' || !providerAvailable(schedule)) { runs.push({ scheduleId: schedule.id, code: 'provider_unavailable' }); continue }
+      const terminalId = makeTerminalId()
+      if (typeof terminalId !== 'string' || !SAFE_ID.test(terminalId)) { runs.push({ scheduleId: schedule.id, code: 'terminal_id_unavailable' }); continue }
+      const definition = { ...(schedule.schedule_spec || {}), kind: schedule.schedule_kind || schedule.kind, timezone: schedule.timezone }
+      const next = definition.kind === 'once' ? new Date('9999-12-31T23:59:00.000Z') : nextScheduledAt(definition, new Date(schedule.next_run_at))
+      if (!next) { runs.push({ scheduleId: schedule.id, code: 'next_run_invalid' }); continue }
+      const occurrenceKey = `${schedule.id}:${schedule.next_run_at}`
+      const leaseSeconds = Math.min(1_860, Math.max(60, schedule.max_runtime_minutes * 60 + 60))
+      const deadlineAt = date(now).getTime() + leaseSeconds * 1000
+      let admission = null
+      try { admission = await admitRun({ schedule, runId: occurrenceKey, terminalId, deadlineAt }) } catch { admission = null }
+      if (!admission?.ok) { runs.push({ scheduleId: schedule.id, code: admission?.code || 'spawn_not_admitted' }); continue }
+      let leaseTransferred = false
+      try {
+        const claimed = await rpc({ fetchImpl, supabaseUrl, headers, name: 'claim_due_code_schedule', body: {
+          p_schedule_id: schedule.id, p_expected_revision: schedule.revision, p_bridge_id: bridgeId,
+          p_bridge_fencing: bridgeFencing, p_occurrence_key: occurrenceKey, p_lease_seconds: leaseSeconds,
+        } })
+        if (!claimed?.ok || !claimed?.run) { runs.push({ scheduleId: schedule.id, code: claimed?.code || 'claim_failed' }); continue }
+        const admitted = preflightScheduledRun({ schedule, occurrence: claimed.run, ownerId, bridgeId, bridgeFencing, providerAvailable, capsOk: true, now })
+        if (!admitted.ok) { runs.push({ scheduleId: schedule.id, runId: claimed.run.id, code: admitted.code }); continue }
+        const opened = await rpc({ fetchImpl, supabaseUrl, headers, name: 'open_code_scheduled_run', body: {
+          p_run_id: claimed.run.id, p_bridge_id: bridgeId, p_bridge_fencing: bridgeFencing, p_terminal_id: terminalId, p_next_run_at: next.toISOString(),
+        } })
+        if (!opened?.ok) { runs.push({ scheduleId: schedule.id, runId: claimed.run.id, code: opened?.code || 'open_not_persisted' }); continue }
+        const openedRun = opened.run || claimed.run
+        let started = null
+        try { started = await openTerminal({ schedule, run: openedRun, terminalId, admission: admission.lease }) }
+        catch { started = null }
+        if (started) {
+          leaseTransferred = true
+          runs.push({ scheduleId: schedule.id, runId: claimed.run.id, code: 'opened' })
+          continue
+        }
+        const failed = await rpc({ fetchImpl, supabaseUrl, headers, name: 'finish_code_scheduled_run', body: {
+          p_run_id: claimed.run.id, p_bridge_id: bridgeId, p_bridge_fencing: bridgeFencing,
+          p_outcome: 'failed', p_outcome_code: 'terminal_open_failed', p_evidence_refs: [], p_decision_item_id: null,
+        } })
+        runs.push({ scheduleId: schedule.id, runId: claimed.run.id, code: failed?.ok ? 'open_failed' : (failed?.code || 'open_failed_unrecorded') })
+      } finally {
+        if (!leaseTransferred) {
+          try { await releaseRun(admission.lease) } catch { /* expiry remains the fail-closed release */ }
+        }
+      }
+    }
+    return Object.freeze({ ok: true, code: 'polled', runs: Object.freeze(runs) })
+  } catch { return Object.freeze({ ok: false, code: 'runner_read_failed', runs: [] }) }
+}
+
+export async function finishScheduledRun ({ fetchImpl = globalThis.fetch, supabaseUrl, anonKey, token, roomCode, runId, bridgeId, bridgeFencing, result, evidenceRefs, canceled = false } = {}) {
+  if (!supabaseUrl || !anonKey || !token || !roomCode || !runId || !bridgeId || !Number.isSafeInteger(bridgeFencing) || bridgeFencing < 1) return Object.freeze({ ok: false, code: 'outcome_unavailable' })
+  const headers = { apikey: anonKey, Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' }
+  try {
+    const pendingControls = await rpc({ fetchImpl, supabaseUrl, headers, name: 'list_code_pair_controls', body: { p_session_code: String(roomCode).toUpperCase(), p_status: 'pending', p_limit: 100 } })
+    const outcome = classifyRunOutcome({ result, evidenceRefs, pendingControls, runId, canceled })
+    const written = await rpc({ fetchImpl, supabaseUrl, headers, name: 'finish_code_scheduled_run', body: {
+      p_run_id: runId, p_outcome: outcome.outcome, p_outcome_code: outcome.code,
+      p_bridge_id: bridgeId, p_bridge_fencing: bridgeFencing,
+      p_evidence_refs: outcome.evidence || [], p_decision_item_id: outcome.controlItemId || null,
+    } })
+    return Object.freeze({ ok: Boolean(written?.ok), code: written?.code || 'outcome_write_failed', outcome })
+  } catch { return Object.freeze({ ok: false, code: 'outcome_write_failed' }) }
+}
+
+export async function finishScheduledRunWithRetry (args = {}, { attempts = 3, delays = [100, 400], sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)) } = {}) {
+  const count = Math.max(1, Math.min(5, Number.isInteger(attempts) ? attempts : 3))
+  let last = Object.freeze({ ok: false, code: 'outcome_write_failed' })
+  for (let attempt = 0; attempt < count; attempt++) {
+    last = await finishScheduledRun(args)
+    if (last.ok) return last
+    if (attempt + 1 < count) await sleep(Math.max(0, Math.min(5000, Number(delays[attempt] ?? delays.at(-1) ?? 0) || 0)))
+  }
+  return last
+}
+
+export { OUTCOMES }