pantheon-opencode 1.3.5 → 1.3.7

package/src/pantheon/retry-policy.ts

@@ -0,0 +1,212 @@
+/**
+ * R1 — Per-error-type retry + provider cooldown (LiteLLM pattern).
+ *
+ * Pure library (no SDK, no I/O). When a delegation fails, the error is
+ * classified (auth | rate_limit | timeout | other), the per-error-type
+ * retry policy from routing.yml `retry_policy` is applied with exponential
+ * backoff, and provider cooldown state (routing.yml `cooldown`) is tracked
+ * in-memory: after `allowed_fails` consecutive failures a provider is
+ * skipped for `cooldown_time_seconds`; a success resets the counter.
+ *
+ * YAGNI: no usage-based routing, no Redis — a simple in-memory cooldown
+ * map plus config.
+ *
+ * @module retry-policy
+ */
+
+// ─── Types ─────────────────────────────────────────────────────────────
+
+/** Error classes a delegation failure can be classified into. */
+export type ErrorType = 'auth' | 'rate_limit' | 'timeout' | 'other'
+
+/** Max retries per error class (routing.yml `retry_policy`). */
+export interface RetryPolicy {
+  auth: number
+  rate_limit: number
+  timeout: number
+  other: number
+}
+
+/** Provider cooldown config (routing.yml `cooldown`). */
+export interface CooldownConfig {
+  /** Consecutive failures before the provider is skipped. */
+  allowedFails: number
+  /** How long the provider stays skipped, in seconds. */
+  cooldownTimeSeconds: number
+}
+
+/** Defaults matching routing.yml `retry_policy`. */
+export const DEFAULT_RETRY_POLICY: RetryPolicy = {
+  auth: 0,
+  rate_limit: 3,
+  timeout: 2,
+  other: 1,
+}
+
+/** Defaults matching routing.yml `cooldown`. */
+export const DEFAULT_COOLDOWN: CooldownConfig = {
+  allowedFails: 3,
+  cooldownTimeSeconds: 60,
+}
+
+// ─── Error classification ──────────────────────────────────────────────
+
+const AUTH_RE = /(auth|unauthorized|401|403|api[ _-]?key|invalid credential|permission denied)/i
+const RATE_LIMIT_RE = /(rate[ _-]?limit|429|too many requests|quota|throttl)/i
+const TIMEOUT_RE = /(timeout|timed out|deadline|504|408|etimedout)/i
+
+/**
+ * Classify a thrown error into one of the four retry-policy buckets.
+ * Message-based matching (LiteLLM pattern); unknown errors → 'other'.
+ */
+export function classifyError(err: unknown): ErrorType {
+  const message = err instanceof Error ? err.message : String(err ?? '')
+  if (AUTH_RE.test(message)) return 'auth'
+  if (RATE_LIMIT_RE.test(message)) return 'rate_limit'
+  if (TIMEOUT_RE.test(message)) return 'timeout'
+  return 'other'
+}
+
+// ─── Exponential backoff ───────────────────────────────────────────────
+
+/**
+ * Exponential backoff delay for a retry attempt (0-based): base * 2^attempt,
+ * capped at maxMs. attempt 0 → base, attempt 1 → 2x base, etc.
+ */
+export function computeBackoffMs(attempt: number, baseMs = 1000, maxMs = 30_000): number {
+  const delay = baseMs * 2 ** attempt
+  return Math.min(delay, maxMs)
+}
+
+// ─── Provider cooldown tracker ─────────────────────────────────────────
+
+interface CooldownEntry {
+  fails: number
+  cooldownUntil: number
+}
+
+/**
+ * In-memory provider cooldown state. After `allowedFails` consecutive
+ * failures a provider is skipped until `cooldownUntil`; a success resets
+ * the counter. The clock is injectable for tests.
+ */
+export class ProviderCooldownTracker {
+  private readonly state = new Map<string, CooldownEntry>()
+  readonly config: CooldownConfig
+
+  constructor(config: CooldownConfig = DEFAULT_COOLDOWN) {
+    this.config = config
+  }
+
+  /** Record one failure for a provider; trips cooldown at allowedFails. */
+  recordFailure(provider: string): void {
+    const entry = this.state.get(provider) ?? { fails: 0, cooldownUntil: 0 }
+    entry.fails += 1
+    if (entry.fails >= this.config.allowedFails) {
+      entry.cooldownUntil = Date.now() + this.config.cooldownTimeSeconds * 1000
+    }
+    this.state.set(provider, entry)
+  }
+
+  /** Record a success — resets the failure counter (no spurious cooldown). */
+  recordSuccess(provider: string): void {
+    this.state.delete(provider)
+  }
+
+  /**
+   * Whether the provider is currently skipped. Expired cooldowns are
+   * cleared; entries that never tripped (cooldownUntil 0) are kept so the
+   * consecutive-failure counter survives the check.
+   */
+  isInCooldown(provider: string, now = Date.now()): boolean {
+    const entry = this.state.get(provider)
+    if (entry === undefined) return false
+    if (entry.cooldownUntil > now) return true
+    if (entry.cooldownUntil > 0) this.state.delete(provider)
+    return false
+  }
+
+  /** Remaining cooldown time in ms (0 when not in cooldown). */
+  remainingCooldownMs(provider: string, now = Date.now()): number {
+    const entry = this.state.get(provider)
+    if (entry === undefined) return 0
+    return Math.max(0, entry.cooldownUntil - now)
+  }
+
+  /** Current consecutive failure count for a provider. */
+  failCount(provider: string): number {
+    return this.state.get(provider)?.fails ?? 0
+  }
+}
+
+// ─── Retry policy engine ───────────────────────────────────────────────
+
+export type RetryDecisionReason = 'policy' | 'cooldown'
+
+export interface RetryDecision {
+  shouldRetry: boolean
+  /** Retries still available for this error class (0 when exhausted). */
+  retriesRemaining: number
+  /** Backoff delay to wait before the next attempt (ms). */
+  delayMs: number
+  /** Why the decision was made: policy budget or provider cooldown. */
+  reason: RetryDecisionReason
+}
+
+/**
+ * Combines error classification, the per-error-type retry policy, and the
+ * provider cooldown tracker into one decision point. Enforcement: when a
+ * delegation fails, call `decide(provider, err, attemptsUsed)`; when the
+ * result is content, call `recordSuccess`; when the budget is exhausted,
+ * call `recordFailure` so the cooldown can trip.
+ */
+export class RetryPolicyEngine {
+  private readonly cooldown: ProviderCooldownTracker
+  readonly policy: RetryPolicy
+  readonly backoffBaseMs: number
+
+  constructor(
+    policy: RetryPolicy = DEFAULT_RETRY_POLICY,
+    cooldown?: ProviderCooldownTracker,
+    backoffBaseMs = 1000,
+  ) {
+    this.policy = policy
+    this.backoffBaseMs = backoffBaseMs
+    this.cooldown = cooldown ?? new ProviderCooldownTracker()
+  }
+
+  /**
+   * Decide whether a failed dispatch should be retried.
+   *
+   * @param provider provider name (cooldown key, e.g. "opencode")
+   * @param err the failure (classified into auth/rate_limit/timeout/other)
+   * @param attemptsUsed retries already consumed for this dispatch
+   * @param now injectable clock (tests)
+   */
+  decide(provider: string, err: unknown, attemptsUsed: number, now = Date.now()): RetryDecision {
+    if (this.cooldown.isInCooldown(provider, now)) {
+      return { shouldRetry: false, retriesRemaining: 0, delayMs: 0, reason: 'cooldown' }
+    }
+    const type = classifyError(err)
+    const retriesRemaining = Math.max(0, this.policy[type] - attemptsUsed)
+    if (retriesRemaining <= 0) {
+      return { shouldRetry: false, retriesRemaining: 0, delayMs: 0, reason: 'policy' }
+    }
+    return {
+      shouldRetry: true,
+      retriesRemaining,
+      delayMs: computeBackoffMs(attemptsUsed, this.backoffBaseMs),
+      reason: 'policy',
+    }
+  }
+
+  /** Record a failure (feeds the cooldown tracker). */
+  recordFailure(provider: string, _err: unknown): void {
+    this.cooldown.recordFailure(provider)
+  }
+
+  /** Record a success (resets the provider's failure counter). */
+  recordSuccess(provider: string): void {
+    this.cooldown.recordSuccess(provider)
+  }
+}

package/src/pantheon/session-guard.ts

@@ -43,8 +43,6 @@ export function safeSessionPath(id: unknown): { path: { id: string } } | null {
  * Delegates to {@link safeSessionPath} — the single choke point. Returns
  * null for null/invalid ids so the caller skips the fetch.
  */
-export function buildChildrenPath(
-  id: string | null | undefined,
-): { path: { id: string } } | null {
+export function buildChildrenPath(id: string | null | undefined): { path: { id: string } } | null {
   return safeSessionPath(id)
 }

package/src/pantheon/step-cap.ts

@@ -0,0 +1,110 @@
+/**
+ * R4 — Per-agent step caps (max_steps).
+ *
+ * Pure library. routing.yml `agents.<name>.max_steps` gives each agent a
+ * step budget (e.g. explore: 25, reviewer: 25, oracle: 15). When an agent's
+ * step count reaches max_steps it is forced to summarize-and-stop: the
+ * delegation is either skipped with a capped summary (already at cap) or
+ * the prompt is appended with a stop instruction (cap hit mid-dispatch).
+ *
+ * The tracker is PERMANENT-PER-PROCESS: counters accumulate for the process
+ * lifetime and are intentionally NOT reset on successful delegations or
+ * session end — a per-session reset would let an agent exceed its process
+ * budget over a long session. `reset()` exists as a tested utility for
+ * tests and future explicit reset points; no production caller wires it.
+ *
+ * @module step-cap
+ */
+
+// ─── Types ─────────────────────────────────────────────────────────────
+
+/** Default step budget when routing.yml omits max_steps for an agent. */
+export const DEFAULT_MAX_STEPS = 25
+
+// ─── Stop instruction ──────────────────────────────────────────────────
+
+/**
+ * The forced summarize-and-stop instruction injected into a prompt when an
+ * agent's step count reaches max_steps.
+ */
+export function buildStopInstruction(agent: string, maxSteps: number): string {
+  return (
+    `\n\n[STEP CAP REACHED — ${agent} at ${maxSteps} steps] ` +
+    `You have reached the maximum step budget for this delegation. ` +
+    `STOP working immediately and summarize what was accomplished (and ` +
+    `what remains, if any) as your final message. Do not start new work.`
+  )
+}
+
+/**
+ * The text returned when a delegation is skipped because the agent is
+ * already at its step cap — marks the delegation as capped and asks for a
+ * summary of prior results instead of starting new work.
+ */
+export function cappedSummary(agent: string, maxSteps: number): string {
+  return (
+    `[STEP CAP REACHED] ${agent} has reached its max_steps budget (${maxSteps}). ` +
+    `Delegation skipped — no new work was started. ` +
+    `Summarize prior results and stop.`
+  )
+}
+
+// ─── Tracker ───────────────────────────────────────────────────────────
+
+/**
+ * Per-agent step counters with a max_steps budget. Keyed by lowercase agent
+ * name (matching is case-insensitive). Agents without a configured budget
+ * are never capped.
+ */
+export class StepCapTracker {
+  private readonly steps = new Map<string, number>()
+  readonly maxStepsByAgent: Readonly<Record<string, number>>
+
+  constructor(maxStepsByAgent: Readonly<Record<string, number>> = {}) {
+    this.maxStepsByAgent = maxStepsByAgent
+  }
+
+  /** The configured budget for an agent, or undefined when uncapped. */
+  maxStepsFor(agent: string): number | undefined {
+    return this.maxStepsByAgent[agent.toLowerCase()]
+  }
+
+  /** Current step count for an agent. */
+  stepCount(agent: string): number {
+    return this.steps.get(agent.toLowerCase()) ?? 0
+  }
+
+  /** Whether the agent has reached (or exceeded) its max_steps budget. */
+  isCapped(agent: string): boolean {
+    const max = this.maxStepsFor(agent)
+    if (max === undefined) return false
+    return this.stepCount(agent) >= max
+  }
+
+  /**
+   * Record one step for an agent. Returns the new count and whether this
+   * step hit the cap (capped === true exactly when steps >= maxSteps).
+   */
+  recordStep(agent: string): {
+    steps: number
+    capped: boolean
+    maxSteps: number | undefined
+  } {
+    const key = agent.toLowerCase()
+    const max = this.maxStepsFor(agent)
+    const steps = (this.steps.get(key) ?? 0) + 1
+    this.steps.set(key, steps)
+    return { steps, capped: max !== undefined && steps >= max, maxSteps: max }
+  }
+
+  /**
+   * Reset an agent's step count.
+   *
+   * Intentionally NOT wired in production: the tracker is permanent-per-
+   * process (see module docstring) so agents cannot exceed their process
+   * budget via resets. Exists for tests and future explicit reset points.
+   */
+  reset(agent: string): void {
+    this.steps.delete(agent.toLowerCase())
+  }
+}

package/src/pantheon/tui-version-check.ts

@@ -0,0 +1,72 @@
+/**
+ * tui-version-check.ts — Runtime staleness check for the TUI plugin copy
+ *
+ * Compares the version in the user's copied TUI plugin package.json against
+ * the version of the installed pantheon-opencode package. If mismatched,
+ * logs a one-time warning. Does NOT auto-sync (safety first).
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url))
+const ROOT = join(__dirname, '..', '..')
+
+/**
+ * Detect the user's OpenCode config directory (same logic as sync-tui.mjs).
+ * Priority: $XDG_CONFIG_HOME/opencode → ~/.opencode → null
+ */
+function resolveConfigDir(): string | null {
+  const xdgConfig = process.env.XDG_CONFIG_HOME || join(homedir(), '.config')
+  const xdgDir = join(xdgConfig, 'opencode')
+  if (existsSync(xdgDir)) return xdgDir
+
+  const homeDir = join(homedir(), '.opencode')
+  if (existsSync(homeDir)) return homeDir
+
+  return null
+}
+
+/**
+ * Read the `version` field from a package.json, or null on failure.
+ */
+function readVersion(pkgPath: string): string | null {
+  try {
+    return JSON.parse(readFileSync(pkgPath, 'utf8')).version || null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Run the TUI version staleness check. Call once at plugin init.
+ *
+ * @param logger - Logging function (defaults to console.warn)
+ */
+export function checkTuiVersionStaleness(
+  logger: (msg: string) => void = console.warn,
+): void {
+  try {
+    const configDir = resolveConfigDir()
+    if (!configDir) return // Not initialized — nothing to check
+
+    const tuiCopyDir = join(configDir, 'plugins', 'pantheon-tui')
+    if (!existsSync(tuiCopyDir)) return // TUI not installed
+
+    const copyVersion = readVersion(join(tuiCopyDir, 'package.json'))
+    if (!copyVersion) return // Can't read version — skip
+
+    // Read the installed package version from the repo root's package.json
+    const currentVersion = readVersion(join(ROOT, 'package.json'))
+    if (!currentVersion) return // Can't determine current version — skip
+
+    if (copyVersion !== currentVersion) {
+      logger(
+        `⚠️  TUI plugin v${copyVersion} is outdated. Current: v${currentVersion}. Run: npx pantheon-opencode init`,
+      )
+    }
+  } catch {
+    // Fail-open — version check must never block plugin initialization
+  }
+}

package/src/pantheon/vision.ts

@@ -7,7 +7,12 @@ import { fileURLToPath } from 'node:url'
 import type { Hooks, PluginInput } from '@opencode-ai/plugin'
 import type { FilePart, Part, TextPart, UserMessage } from '@opencode-ai/sdk'
 import type { ResolvedPreset } from './presets.mjs'
-import { CAPABILITY_TABLE, hasVision, resolveActivePreset, visionBrokenOnGateway } from './presets.mjs'
+import {
+  CAPABILITY_TABLE,
+  hasVision,
+  resolveActivePreset,
+  visionBrokenOnGateway,
+} from './presets.mjs'
 
 // ─── Constants ────────────────────────────────────────────────────────────
 
@@ -136,10 +141,7 @@ export function providerIsTextOnly(providerID: string): boolean {
 }
 
 /** Return whether OpenCode's current model is known to accept image input. */
-export function modelAcceptsImages(
-  model: ModelInfo | undefined,
-  providerID?: string,
-): boolean {
+export function modelAcceptsImages(model: ModelInfo | undefined, providerID?: string): boolean {
   if (!model) {
     // Fail-closed for known text-only providers
     if (providerID && providerIsTextOnly(providerID)) return false

package/src/pantheon/zeus-delegate-with-retry.ts

@@ -39,8 +39,7 @@
 
 import type { BackgroundJobBoard } from './background-job-board.ts'
 import type { DelegationClient } from './delegation-finalize.ts'
-import { readDelegationReport } from './delegation-finalize.ts'
-import { DELEGATION_DEFAULTS } from './delegation-finalize.ts'
+import { DELEGATION_DEFAULTS, readDelegationReport } from './delegation-finalize.ts'
 import {
   createDispatchGuard,
   type DispatchClassification,
@@ -49,6 +48,11 @@ import {
   type DispatchResultLike,
 } from './dispatch-guard.ts'
 import { createPantheonLogger } from './logger.ts'
+import {
+  type ProviderCooldownTracker,
+  type RetryPolicy,
+  RetryPolicyEngine,
+} from './retry-policy.ts'
 import { safeSessionPath } from './session-guard.ts'
 
 const log = createPantheonLogger({ module: 'pantheon-zeus-retry' })
@@ -74,6 +78,12 @@ export interface ZeusDelegateWithRetryOptions {
   readTimeoutMs?: number
   /** Retry on empty results. Default: true */
   retryOnEmpty?: boolean
+  /** R1: per-error-type retry policy (routing.yml `retry_policy`). */
+  retryPolicy?: RetryPolicy
+  /** R1: provider cooldown tracker (routing.yml `cooldown`). */
+  cooldown?: ProviderCooldownTracker
+  /** R1: provider name for cooldown tracking (default "default"). */
+  provider?: string
   /** Injectable logger. Default: file log (PANTHEON_HOOKS_LOG gate). */
   logger?: { warn: (message: string) => void; info?: (message: string) => void }
   /** Output dir for delegation reports. Default: DELEGATION_DEFAULTS.outputDir */
@@ -143,20 +153,76 @@ export interface ZeusRetryHelper {
   }>
 }
 
-export function createZeusRetryHelper(
-  options?: DispatchGuardOptions,
-): ZeusRetryHelper {
+export interface ZeusRetryHelperOptions extends DispatchGuardOptions {
+  /**
+   * R1: per-error-type retry policy. When provided, error-type retries with
+   * exponential backoff apply (auth → 0, rate_limit → N, ...); when absent
+   * the legacy hard-cap-1 empty-result retry applies.
+   */
+  retryPolicy?: RetryPolicy
+  /** R1: provider cooldown tracker (shared across helpers for global cooldown). */
+  cooldown?: ProviderCooldownTracker
+  /** R1: provider name for cooldown tracking (default "default"). */
+  provider?: string
+  /** R1: injectable sleep for tests (default: setTimeout promise). */
+  sleep?: (ms: number) => Promise<void>
+}
+
+export function createZeusRetryHelper(options?: ZeusRetryHelperOptions): ZeusRetryHelper {
   const guard = createDispatchGuard(options)
+  const engine =
+    options?.retryPolicy !== undefined
+      ? new RetryPolicyEngine(options.retryPolicy, options.cooldown)
+      : undefined
+  const provider = options?.provider ?? 'default'
+  const sleep =
+    options?.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)))
   return {
     guard,
     async executeWithRetry(first, redispatch) {
-      const out = await guard.maybeRetry(first, redispatch)
-      const escalate = out.classification !== 'content'
-      return {
-        result: out.result,
-        classification: out.classification,
-        retried: out.retried,
-        escalate,
+      if (engine === undefined) {
+        // Legacy path (unchanged): hard cap 1 on empty results.
+        const out = await guard.maybeRetry(first, redispatch)
+        const escalate = out.classification !== 'content'
+        return {
+          result: out.result,
+          classification: out.classification,
+          retried: out.retried,
+          escalate,
+        }
+      }
+      // R1 path: classify the failure, apply the per-error-type policy with
+      // exponential backoff, and track provider cooldown. A content result
+      // records success (resets the provider's failure counter); an
+      // exhausted budget records failure (feeds the cooldown tracker).
+      let result = first
+      let attemptsUsed = 0
+      let retried = false
+      let classification = guard.classifyResult(result)
+      let lastError: unknown =
+        result.error ??
+        (classification === 'content' ? undefined : new Error('empty dispatch result'))
+      for (;;) {
+        if (classification === 'content') {
+          engine.recordSuccess(provider)
+          return { result, classification, retried, escalate: false }
+        }
+        lastError = result.error ?? lastError
+        const decision = engine.decide(provider, lastError, attemptsUsed)
+        if (!decision.shouldRetry) {
+          engine.recordFailure(provider, lastError)
+          return { result, classification, retried, escalate: true }
+        }
+        retried = true
+        attemptsUsed += 1
+        await sleep(decision.delayMs)
+        try {
+          result = await redispatch()
+          lastError = undefined
+        } catch (err: unknown) {
+          lastError = err
+        }
+        classification = guard.classifyResult(result)
       }
     },
   }
@@ -193,6 +259,9 @@ export async function zeusDelegateWithRetry(
   const retryHelper = createZeusRetryHelper({
     retryOnEmpty: opts.retryOnEmpty ?? true,
     logger,
+    ...(opts.retryPolicy !== undefined ? { retryPolicy: opts.retryPolicy } : {}),
+    ...(opts.cooldown !== undefined ? { cooldown: opts.cooldown } : {}),
+    ...(opts.provider !== undefined ? { provider: opts.provider } : {}),
   })
 
   // One delegate+read attempt. Factored so maybeRetry can invoke a second

package/src/plugin.ts

@@ -1,5 +1,7 @@
 import type { Plugin, PluginInput } from '@opencode-ai/plugin'
 import type { PluginConfig } from 'opencode'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
 import { BackgroundJobBoard } from './pantheon/background-job-board.ts'
 import { reassertAfterCompaction } from './pantheon/compaction-assert.ts'
 import { createCostCommand } from './pantheon/cost-command.ts'
@@ -9,6 +11,7 @@ import {
   type DelegationClient,
   resolveDelegationBudgets,
   resolveDelegationTimeoutMs,
+  startIdleChildScan,
 } from './pantheon/delegation.ts'
 import { buildCompactionContext } from './pantheon/delegation-compaction.ts'
 import {
@@ -24,9 +27,15 @@ import { createReadEnhancer } from './pantheon/hashline/read-enhancer.ts'
 import { createHashlineEditTool } from './pantheon/hashline/tool.ts'
 import { createIdleDispatcher } from './pantheon/idle-continuation.ts'
 import { createPantheonLogger } from './pantheon/logger.ts'
-import { safeSessionPath } from './pantheon/session-guard.ts'
 import { pantheonPluginOnce } from './pantheon/plugin-once.ts'
-import { applyActivePresetToConfig, loadRoutingAgentModels } from './pantheon/presets.mjs'
+import {
+  applyActivePresetToConfig,
+  loadRoutingAgentModels,
+  loadRoutingMaxSteps,
+  loadRoutingPermissionTask,
+} from './pantheon/presets.mjs'
+import { safeSessionPath } from './pantheon/session-guard.ts'
+import { StepCapTracker } from './pantheon/step-cap.ts'
 import {
   TODO_ENFORCER_DEFAULTS,
   TodoEnforcer,
@@ -34,6 +43,7 @@ import {
   todoEnforcerEnabledFromEnv,
 } from './pantheon/todo-enforcer.ts'
 import { TodoPreserver } from './pantheon/todo-preserve.ts'
+import { checkTuiVersionStaleness } from './pantheon/tui-version-check.ts'
 import { activePresetCandidates, createVisionHandler } from './pantheon/vision.ts'
 
 // ─── Background Job Board Singleton ────────────────────────────────────
@@ -55,6 +65,17 @@ const log = createPantheonLogger({ module: 'pantheon-plugin' })
 // plugin never throws at startup.
 const routingAgentModels = loadRoutingAgentModels({ logger: log })
 
+// R4: per-agent step caps from routing.yml `agents.<name>.max_steps`
+// (fail-open → {} = no agent capped). R1 retry_policy/cooldown are NOT
+// wired here — the plugin has no retry path (opencode cannot intercept task
+// completion); zeus waves load them via presets.mjs loaders and pass them
+// to zeusDelegateWithRetry explicitly.
+const stepCapTracker = new StepCapTracker(loadRoutingMaxSteps({ logger: log }))
+
+// O5: permission.task glob rules from routing.yml `permission.task`
+// (fail-open → undefined = existing runtime matrix only).
+const routingPermissionTask = loadRoutingPermissionTask({ logger: log })
+
 const board = new BackgroundJobBoard({
   maxConcurrentPerAgent: 3,
   signalDir: '.pantheon/deepwork/board-signals',
@@ -202,7 +223,13 @@ function adaptDelegationClient(client: PluginInput['client']): DelegationClient
         }
         const result = await client.session.promptAsync({
           path: path.path,
-          body: { agent: input.body.agent, parts: input.body.parts },
+          body: {
+            agent: input.body.agent,
+            ...(input.body.model !== undefined
+              ? { model: { providerID: input.body.model.providerID, modelID: input.body.model.id } }
+              : {}),
+            parts: input.body.parts,
+          },
         })
         if (result.error) throw new Error(sdkErrorMessage(result.error))
         return result.data
@@ -311,6 +338,9 @@ const plugin: Plugin = async (input: PluginInput) => {
   if (pantheonPluginOnce('pantheon:plugin')) {
     return {}
   }
+  // Runtime TUI version staleness check — warns if the copied TUI plugin
+  // is older than the installed package. Runs once, fail-open, no auto-sync.
+  checkTuiVersionStaleness((msg) => log.warn(msg))
   const vision = createVisionHandler(input)
   // Phase 2/3: background delegation toolset + the bound finalize lifecycle
   // hook. Completion is observed through the event hook below
@@ -334,10 +364,34 @@ const plugin: Plugin = async (input: PluginInput) => {
       readOnlyAgents: new Set(['apollo', 'gaia']),
       agentModels: routingAgentModels,
       delegationBudgets,
+      stepCapTracker,
+      ...(routingPermissionTask != null ? { permissionTask: routingPermissionTask } : {}),
       ...(wallClockTimeoutMs !== undefined ? { wallClockTimeoutMs } : {}),
     },
   })
 
+  // Proactive idle-child scan (Fix 2): finalize children that are idle on the
+  // board but have no MD report on disk — eliminates the phantom "running"
+  // window. Runs every 30s (configurable via PANTHEON_IDLE_SCAN_INTERVAL_MS),
+  // unref'd so it never holds the process open. Fail-open by design.
+  const idleScanIntervalMs = Number(process.env.PANTHEON_IDLE_SCAN_INTERVAL_MS) || undefined
+  startIdleChildScan(
+    {
+      board,
+      finalize: (childSessionID, opts) => delegation.finalizeDelegation(childSessionID, opts),
+      hasReport: (job) => {
+        try {
+          const filePath = join('.pantheon/delegations', job.parentSessionID, `${job.alias}.md`)
+          return existsSync(filePath)
+        } catch {
+          return false
+        }
+      },
+      logger: log,
+    },
+    idleScanIntervalMs,
+  )
+
   // Wave 1 (PR #46): TODO continuation enforcer for root/non-board sessions.
   // Mirrors routing.yml `todo_enforcer` (plugin scope has no routing.yml
   // access — COMPACTION_MAX_ITEMS pattern). The event hook routes non-board