thinkpool-pair 0.7.357 → 0.7.359

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 }

package/service.mjs

@@ -26,6 +26,7 @@ import { hostMemoryAdmission } from './host-memory.mjs'
 import { readSupervisorReady, supervisorReadyMatches } from './supervisor-ready.mjs'
 import { pairCli } from './command-guidance.mjs'
 import { loadKeepAwakePreference } from './keep-awake.mjs'
+import { scheduledRunsEnabled } from './scheduled-runs.mjs'
 
 // Service identity. Account mode has no room → a single stable id so there's
 // exactly one account service per machine (a second install replaces it).
@@ -131,7 +132,7 @@ export function provisionRuntime(version, { exec = execSync, root = path.join(os
 
 // Pure artifact builder — returned shape is testable without side effects.
 // room falsy → ACCOUNT service (bare `thinkpool-pair`, auto-serves all sessions).
-export function buildArtifact(platform, { room = null, cmdArgs = [], autoUpdate = false, version = VERSION, staleProof = false, runtimeEntry = null } = {}) {
+export function buildArtifact(platform, { room = null, cmdArgs = [], autoUpdate = false, version = VERSION, staleProof = false, runtimeEntry = null, scheduledRuns = scheduledRunsEnabled() } = {}) {
   const npx = npxPath(platform)
   // Account mode discovers each room's own bound directory, so its supervisor must use
   // a stable home cwd. Persisting the caller's managed worktree here makes the service
@@ -161,6 +162,11 @@ export function buildArtifact(platform, { room = null, cmdArgs = [], autoUpdate
   // In-process self-update (account.mjs / bridge.mjs) is gated on this env — only on when
   // the user explicitly opted into auto-update.
   const autoUpdateEnv = autoUpdate ? { THINKPOOL_PAIR_AUTOUPDATE: '1' } : {}
+  // Persistent services rebuild a deliberately tiny environment. Preserve this
+  // activation only as the exact boolean true; arbitrary caller values are omitted.
+  const scheduledRunsEnv = scheduledRuns === true
+    ? { darwin: '<key>TP_SCHEDULED_RUNS_ENABLED</key><string>1</string>', linux: 'Environment=TP_SCHEDULED_RUNS_ENABLED=1\n', win32: 'set "TP_SCHEDULED_RUNS_ENABLED=1"\r\n' }
+    : { darwin: '', linux: '', win32: '' }
 
   if (platform === 'darwin') {
     // launchd KeepAlive supervises. Stable runtimes execute directly; the legacy npx
@@ -187,7 +193,7 @@ export function buildArtifact(platform, { room = null, cmdArgs = [], autoUpdate
   <key>WorkingDirectory</key><string>${xml(cwd)}</string>
   <key>StandardOutPath</key><string>${xml(log)}</string>
   <key>StandardErrorPath</key><string>${xml(log)}</string>
-  <key>EnvironmentVariables</key><dict><key>PATH</key><string>${xml(servicePath)}</string>${runtimeEntry ? '' : `<key>NPM_CONFIG_CACHE</key><string>${xml(npmCache)}</string>`}${autoUpdate ? '<key>THINKPOOL_PAIR_AUTOUPDATE</key><string>1</string>' : ''}</dict>
+  <key>EnvironmentVariables</key><dict><key>PATH</key><string>${xml(servicePath)}</string>${runtimeEntry ? '' : `<key>NPM_CONFIG_CACHE</key><string>${xml(npmCache)}</string>`}${autoUpdate ? '<key>THINKPOOL_PAIR_AUTOUPDATE</key><string>1</string>' : ''}${scheduledRunsEnv.darwin}</dict>
 </dict></plist>\n`
     // The destructive reload is intentionally NOT represented as an inline `post`
     // command. installService stages this plist and hands the transaction to an
@@ -223,7 +229,7 @@ RestartSec=2
 RestartPreventExitStatus=0
 WorkingDirectory=${cwd}
 Environment=PATH=${servicePath}
-${runtimeEntry ? '' : `Environment=NPM_CONFIG_CACHE=${npmCache}\n`}${autoUpdate ? 'Environment=THINKPOOL_PAIR_AUTOUPDATE=1\n' : ''}StandardOutput=append:${log}
+${runtimeEntry ? '' : `Environment=NPM_CONFIG_CACHE=${npmCache}\n`}${autoUpdate ? 'Environment=THINKPOOL_PAIR_AUTOUPDATE=1\n' : ''}${scheduledRunsEnv.linux}StandardOutput=append:${log}
 StandardError=append:${log}
 
 [Install]
@@ -244,7 +250,7 @@ WantedBy=default.target
       : room
       ? ['npx', '-y', ...onlineFlag, verSpec, room, '--supervise', ...tail].join(' ')
       : ['npx', '-y', ...onlineFlag, verSpec].join(' ')
-    const content = `@echo off\r\ntitle thinkpool-pair ${id}\r\n${runtimeEntry ? '' : `set "NPM_CONFIG_CACHE=${npmCache}"\r\n`}${inner}\r\n`
+    const content = `@echo off\r\ntitle thinkpool-pair ${id}\r\n${runtimeEntry ? '' : `set "NPM_CONFIG_CACHE=${npmCache}"\r\n`}${scheduledRunsEnv.win32}${inner}\r\n`
     return { file, content, logDir, post: [], note: 'Installed to the Startup folder — runs at login' + (room ? ' with --supervise (auto-restart on crash).' : ' (account mode).') + ' Start it now without rebooting by double-clicking the .cmd, or run it from a terminal.' }
   }
 

package/session-store.mjs

@@ -292,6 +292,123 @@ export function deleteSession(room, id) {
   catch (error) { persistenceError('archive closed session snapshot', p, error); return false }
 }
 
+// Scheduled outcomes use a separate host outbox from live session snapshots.
+// A person may close the visible terminal while its idempotent database finish
+// is retrying; keeping the intent here lets a restart complete that write without
+// loadAll() resurrecting the deliberately closed terminal.
+const scheduledOutcomesFile = (room) => path.join(dir(room), '.scheduled-outcomes')
+const safeTerminalId = (value) => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:@-]{0,159}$/.test(value)
+const safeRunId = (value) => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:@-]{0,159}$/.test(value)
+const readScheduledOutcomeMap = (room) => {
+  try {
+    const value = JSON.parse(fs.readFileSync(scheduledOutcomesFile(room), 'utf8'))
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {}
+  } catch { return {} }
+}
+// Pending entries from the original format are raw intents. Once the database
+// finish and recorded session snapshot are both durable, replace that raw entry
+// with a versioned acknowledgement tombstone before attempting deletion. The
+// tombstone is intentionally independent of the live/archived session record:
+// restart recovery can therefore identify an acknowledged exact run and retry
+// deletion only, without issuing another finish RPC or reclassifying its result.
+const scheduledOutcomeRecord = (value) => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null
+  if (value.v === 1 && value.state === 'acknowledged') {
+    const intent = value.intent
+    return intent && typeof intent === 'object' && !Array.isArray(intent) &&
+      safeRunId(intent.runId) && value.runId === intent.runId
+      ? { intent, acknowledged: true }
+      : null
+  }
+  return safeRunId(value.runId) ? { intent: value, acknowledged: false } : null
+}
+export function savePendingScheduledOutcome(room, terminalId, intent) {
+  if (!safeTerminalId(terminalId) || !intent || typeof intent !== 'object' || Array.isArray(intent) || !safeRunId(intent.runId)) return false
+  try {
+    ensureDir(room)
+    const pending = readScheduledOutcomeMap(room)
+    pending[terminalId] = intent
+    atomicCommit(scheduledOutcomesFile(room), JSON.stringify(pending))
+    return true
+  } catch (error) {
+    persistenceError('write scheduled outcome outbox', scheduledOutcomesFile(room), error)
+    return false
+  }
+}
+export function loadPendingScheduledOutcomes(room) {
+  return Object.entries(readScheduledOutcomeMap(room))
+    .map(([terminalId, value]) => ({ terminalId, record: scheduledOutcomeRecord(value) }))
+    .filter(({ terminalId, record }) => safeTerminalId(terminalId) && record)
+    .map(({ terminalId, record }) => ({
+      terminalId,
+      intent: record.intent,
+      ...(record.acknowledged ? { acknowledged: true } : {}),
+    }))
+    .slice(0, LIVE_SESSION_MAX)
+}
+export function loadPendingScheduledOutcome(room, terminalId) {
+  if (!safeTerminalId(terminalId)) return null
+  return scheduledOutcomeRecord(readScheduledOutcomeMap(room)[terminalId])?.intent || null
+}
+export function acknowledgePendingScheduledOutcome(room, terminalId, runId) {
+  if (!safeTerminalId(terminalId) || !safeRunId(runId)) return false
+  try {
+    const pending = readScheduledOutcomeMap(room)
+    const record = scheduledOutcomeRecord(pending[terminalId])
+    if (!record || record.intent.runId !== runId) return false
+    if (record.acknowledged) return true
+    pending[terminalId] = {
+      v: 1,
+      state: 'acknowledged',
+      runId,
+      intent: record.intent,
+    }
+    atomicCommit(scheduledOutcomesFile(room), JSON.stringify(pending))
+    return true
+  } catch (error) {
+    persistenceError('acknowledge scheduled outcome outbox', scheduledOutcomesFile(room), error)
+    return false
+  }
+}
+export function deletePendingScheduledOutcome(room, terminalId) {
+  if (!safeTerminalId(terminalId)) return false
+  try {
+    const pending = readScheduledOutcomeMap(room)
+    if (!(terminalId in pending)) return true
+    delete pending[terminalId]
+    if (Object.keys(pending).length) atomicCommit(scheduledOutcomesFile(room), JSON.stringify(pending))
+    else fs.rmSync(scheduledOutcomesFile(room), { force: true })
+    return true
+  } catch (error) {
+    persistenceError('delete scheduled outcome outbox', scheduledOutcomesFile(room), error)
+    return false
+  }
+}
+
+// A database acknowledgement is not locally committed until the corresponding
+// live-session snapshot has synchronously recorded scheduleOutcomeRecorded=true
+// AND the exact outbox is durably marked acknowledged. Keep deletion behind both
+// barriers so a restart always sees one of:
+//   1. pending outbox intent to replay idempotently;
+//   2. an acknowledged outbox tombstone to delete only; or
+//   3. a recorded session snapshot with no outbox.
+// `flushRecordedSnapshot` is intentionally injected by bridge.mjs because only
+// the live entry can produce its complete session payload.
+export function commitRecordedScheduledOutcome(room, terminalId, flushRecordedSnapshot) {
+  let snapshotRecorded = false
+  try {
+    snapshotRecorded = typeof flushRecordedSnapshot === 'function' && flushRecordedSnapshot() === true
+  } catch (error) {
+    persistenceError('record scheduled outcome in session snapshot', path.join(dir(room), `${terminalId}.json`), error)
+  }
+  if (!snapshotRecorded) return { ok: false, snapshotRecorded: false, outboxAcknowledged: false, outboxDeleted: false }
+  const intent = loadPendingScheduledOutcome(room, terminalId)
+  const outboxAcknowledged = acknowledgePendingScheduledOutcome(room, terminalId, intent?.runId)
+  if (!outboxAcknowledged) return { ok: false, snapshotRecorded: true, outboxAcknowledged: false, outboxDeleted: false }
+  const outboxDeleted = deletePendingScheduledOutcome(room, terminalId)
+  return { ok: outboxDeleted, snapshotRecorded: true, outboxAcknowledged: true, outboxDeleted }
+}
+
 // Most-recently-saved structured session for the room (drives attached restore).
 export function loadLatest(room) {
   const recs = listRecs(room).sort((a, b) => (b.savedAt || 0) - (a.savedAt || 0))

package/thinkpool-capabilities.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "bundleVersion": 18,
+  "bundleVersion": 19,
   "contracts": [
     {
       "id": "room-coordination",
@@ -188,9 +188,9 @@
     },
     {
       "id": "design-workspace",
-      "version": 7,
-      "interactionPrompt": "DESIGN EDITING MODEL: every complete bridge preview_capture card and every trusted source-backed mockup card offers Edit in Design. The bridge freezes a safe rendered-DOM snapshot for application previews; Design edits are then applied by the producing lane to the real application source and verified by a fresh correlated desktop+mobile capture. For source-aware application previews, the bridge validates each opaque source identity against its contained host-only map and the current source-file hash before sharing an exact source location privately with the producing lane; uninstrumented elements keep the selector-based fallback, while stale or mismatched identities fail closed. For authored HTML, the producing lane edits the canonical authored HTML source directly. Edit in Design—not ordinary Preview or unrelated artifact delivery—arms a persistent room-level Design workspace, opens the artifact directly in editable mode, and adds Design · Page name beneath the producing terminal in its Ensemble row for both partners; it creates no terminal, agent runtime, or worker slot. The virtual lane can be closed from that Ensemble row without deleting the artifact. Once armed, the Design lane reopens the active artifact at its latest verified revision without another agent turn, history search, HTML/path request, or re-selection. Design is the default canvas there and Preview is only a temporary interaction mode. Direct text, supported movement, and selected-image changes auto-stage as optimistic drafts in the bounded changes queue; queued edits can be reopened, revised, or removed before Apply. Apply changes sends the ordered batch once to the producing lane, and a successful correlated desktop+mobile render advances the verified revision for the room. Never call a staged draft saved or live. When a person asks for many mockups or options that can share a surface, prefer one source-backed multi-option board or gallery in one file and one card so they can compare together; create separate files/cards only when the person explicitly requests independently editable artifacts or the options cannot be represented faithfully together.",
-      "turnReminder": "DESIGN ROUTE: intentional application-preview deliverables use preview_capture with card=true; correlated Design recaptures are recognized automatically. Authored HTML uses the source-backed render helper. Both must produce editable Thinkpool Design cards with verified desktop and mobile renders. Ordinary verification captures stay inline evidence and must not create cards. Cards are delivered after the final agent response so they remain the newest transcript item. Edit in Design explicitly arms the persistent Design workspace and adds its virtual Design · Page beneath the producing terminal in the Ensemble row; Preview alone does not arm it. For large direction sets, consolidate compatible options into one source-backed comparison board/gallery and one card; use separate files/cards only when independent editing is explicitly requested or technically necessary. Do not duplicate the card renders as inline PNGs. Use inline PNG evidence only when no interactive Design artifact is available.",
+      "version": 8,
+      "interactionPrompt": "DESIGN EDITING MODEL: every complete bridge preview_capture card and every trusted source-backed mockup card offers Edit in Design. The bridge freezes a safe rendered-DOM snapshot for application previews; Design edits are then applied by the producing lane to the real application source and verified by a fresh correlated desktop+mobile capture. For source-aware application previews, the bridge validates each opaque source identity against its contained host-only map and the current source-file hash before sharing an exact source location privately with the producing lane; uninstrumented elements keep the selector-based fallback, while stale or mismatched identities fail closed. For authored HTML, the producing lane edits the canonical authored HTML source directly. Edit in Design—not ordinary Preview or unrelated artifact delivery—arms a persistent room-level Design workspace, opens the artifact directly in editable mode, and adds Design · Page name beneath the producing terminal in its Ensemble row for both partners; it creates no terminal, agent runtime, or worker slot. The virtual lane can be closed from that Ensemble row without deleting the artifact. Once armed, the Design lane reopens the active artifact at its latest verified revision without another agent turn, history search, HTML/path request, or re-selection. Design is the default canvas there and Preview is only a temporary interaction mode. A remote discrete selection may show one bounded, normalized location pulse in the partner's color; it never grants authority, persists an event, or loops. Direct text, supported movement, and selected-image changes auto-stage as optimistic drafts in the bounded changes queue; queued edits can be reopened, revised, or removed before Apply. Apply changes sends the ordered batch once to the producing lane, and a successful correlated desktop+mobile render advances the verified revision for the room. Compare is available only for the exact immutable verified parent/current revision pair and uses its captured desktop or mobile images; staged, stale, cross-page, or incomplete pairs fail closed. Design visual runtimes honor live reduced motion, suspend when hidden or off-screen, cap DPR, and tear down deterministically. Never call a staged draft saved or live. When a person asks for many mockups or options that can share a surface, prefer one source-backed multi-option board or gallery in one file and one card so they can compare together; create separate files/cards only when the person explicitly requests independently editable artifacts or the options cannot be represented faithfully together.",
+      "turnReminder": "DESIGN ROUTE: intentional application-preview deliverables use preview_capture with card=true; correlated Design recaptures are recognized automatically. Authored HTML uses the source-backed render helper. Both must produce editable Thinkpool Design cards with verified desktop and mobile renders. Ordinary verification captures stay inline evidence and must not create cards. Cards are delivered after the final agent response so they remain the newest transcript item. Edit in Design explicitly arms the persistent Design workspace and adds its virtual Design · Page beneath the producing terminal in the Ensemble row; Preview alone does not arm it. Compare may expose only the exact immutable verified parent/current revision pair; never label a staged or incomplete capture verified. Remote selection pulses are one-shot collaboration receipts, not authority or ambient decoration. For large direction sets, consolidate compatible options into one source-backed comparison board/gallery and one card; use separate files/cards only when independent editing is explicitly requested or technically necessary. Do not duplicate the card renders as inline PNGs. Use inline PNG evidence only when no interactive Design artifact is available.",
       "impact": [
         {"path": "src/pages/code/design/"},
         {"path": "src/pages/code/structured.jsx", "diffPattern": "Edit in Design|openMockup|tp-mockup-view|sourceKnown"},
@@ -203,6 +203,8 @@
         {"path": "src/pages/code/room.jsx", "pattern": "designLaneSelected"},
         {"path": "src/pages/code/design/DesignViewer.jsx", "pattern": "createPortal\\(surface, laneHost\\)"},
         {"path": "src/pages/code/design/DesignViewer.jsx", "pattern": "Apply \\${pendingEditCount}"},
+        {"path": "src/pages/code/design/workspace.js", "pattern": "resolveVerifiedDesignComparison"},
+        {"path": "src/pages/code/design/visual-runtime.js", "pattern": "DESIGN_VISUAL_RUNTIME_CONTRACT"},
         {"path": "src/pages/code/design/queue.js", "pattern": "designBatchPayload"},
         {"path": "bridge/design-edit.mjs", "pattern": "validateDesignBatchRequest"}
       ]