pantheon-opencode 1.3.5 → 1.3.7

package/src/pantheon/delegation-classifier.ts

@@ -0,0 +1,307 @@
+/**
+ * Delegation Classifier — stuck-agent detection for delegation results.
+ *
+ * Classifies delegation results into actionable statuses:
+ *   - `content` / `success` — agent returned usable output
+ *   - `empty` (empty-mode1 / empty-mode2) — no or near-no output; retryable
+ *   - `budget-exhausted` — agent hit max_steps; partial result available
+ *   - `timeout` (timeout-with-partial / timeout-empty / timeout-exhausted)
+ *   - `error` — provider or infrastructure failure
+ *
+ * Integrates with the existing `dispatch-guard.ts` classification for
+ * empty-response detection and provides a structured `DelegationResult`
+ * that replaces raw-text returns.
+ *
+ * @module delegation-classifier
+ */
+
+// ─── Types ─────────────────────────────────────────────────────────────
+
+/** Empty-response mode classification (matches dispatch-guard). */
+export type EmptyMode = 'empty-mode1' | 'empty-mode2'
+
+/** Timeout sub-type based on partial output and retry history. */
+export type TimeoutSubType = 'timeout-with-partial' | 'timeout-empty' | 'timeout-exhausted'
+
+/** Structured delegation result replacing raw-text returns. */
+export interface DelegationResult {
+  status:
+    | 'success'
+    | 'empty'
+    | 'budget-exhausted'
+    | 'timeout'
+    | 'error'
+    | 'startup_failed'
+    | 'bootstrap_unknown'
+  content: string
+  retryCount: number
+  /** When status is 'empty', which empty mode was detected. */
+  classification?: EmptyMode | undefined
+  /** When status is 'timeout', the timeout sub-type. */
+  subType?: TimeoutSubType | undefined
+  /** Available when budget-exhausted or timeout-with-partial. */
+  partialResult?: string | undefined
+  /** Actionable recommendation for the orchestrator. */
+  recommendation?: string | undefined
+}
+
+/** Result of empty-response classification. */
+export interface EmptyClassification {
+  mode: EmptyMode | 'content'
+  hasContent: boolean
+  hasTokens: boolean
+}
+
+/** Timeout classification input. */
+export interface TimeoutClassifyInput {
+  /** Report markdown (undefined if no report was written). */
+  report: string | undefined
+  /** Whether the child session had any messages at all. */
+  hasMessages: boolean
+  /** How many retries have already been attempted (0 or 1). */
+  retryCount: number
+}
+
+/** Result of stuck-agent classification. */
+export interface StuckClassification {
+  status: 'success' | 'budget-exhausted' | 'empty'
+  partialResult?: string | undefined
+  recommendation?: string | undefined
+}
+
+// ─── Patterns ──────────────────────────────────────────────────────────
+
+/** Matches budget-exhausted messages from the agent or step-cap system. */
+const BUDGET_EXHAUSTED_RE =
+  /maximum\s+(?:steps?|step\s*budget)\s+(?:for\s+this\s+agent\s+)?(?:has|have)\s+been\s+reached|step\s*budget\s+(?:was\s+)?exhausted/i
+
+/** Output-captured marker in delegation reports. */
+const NO_OUTPUT_RE = /_No output captured\._/i
+
+// ─── Empty-Response Classification ────────────────────────────────────
+
+/**
+ * Classify whether a response is empty, empty-with-tokens, or has content.
+ * Matches the dispatch-guard classification (empty-mode1, empty-mode2).
+ *
+ * @param text The response text (may be null/undefined).
+ * @param tokens Optional token counts for mode2 detection.
+ */
+export function classifyEmptyResponse(
+  text: string | null | undefined,
+  tokens?: { tokensInput?: number; tokensOutput?: number },
+): EmptyClassification {
+  const hasContent = typeof text === 'string' && text.trim() !== ''
+  if (hasContent) {
+    return { mode: 'content', hasContent: true, hasTokens: hasTokens(tokens) }
+  }
+  const hasT = hasTokens(tokens)
+  return {
+    mode: hasT ? 'empty-mode2' : 'empty-mode1',
+    hasContent: false,
+    hasTokens: hasT,
+  }
+}
+
+/** Whether token counts indicate the model actually ran. */
+function hasTokens(tokens?: { tokensInput?: number; tokensOutput?: number }): boolean {
+  if (tokens === undefined) return false
+  return (tokens.tokensInput ?? 0) > 0 || (tokens.tokensOutput ?? 0) > 0
+}
+
+// ─── Stuck-Agent Detection ────────────────────────────────────────────
+
+/**
+ * Classify a report as success, budget-exhausted, or empty.
+ * Detects max-steps patterns in the report text.
+ *
+ * @param report The delegation report markdown.
+ */
+export function classifyStuckAgent(report: string): StuckClassification {
+  const trimmed = report.trim()
+
+  // Empty output
+  if (NO_OUTPUT_RE.test(trimmed) || trimmed === '') {
+    return { status: 'empty' }
+  }
+
+  // Budget-exhausted: extract content before the marker as partialResult
+  if (BUDGET_EXHAUSTED_RE.test(trimmed)) {
+    const outputSection = extractOutputSection(trimmed)
+    const partialResult =
+      outputSection !== undefined && !NO_OUTPUT_RE.test(outputSection) ? outputSection : undefined
+
+    return {
+      status: 'budget-exhausted',
+      partialResult,
+      recommendation:
+        'Agent hit step budget; partial result available. ' +
+        'Consider resuming with task_id or dispatching with larger budget.',
+    }
+  }
+
+  return { status: 'success' }
+}
+
+/** Extract the text after "## Output" in a delegation report, or undefined. */
+function extractOutputSection(report: string): string | undefined {
+  const marker = '## Output'
+  const idx = report.indexOf(marker)
+  if (idx === -1) return undefined
+  const afterMarker = report.slice(idx + marker.length)
+  // Skip the newline after "## Output"
+  const content = afterMarker.replace(/^\n+/, '')
+  // Stop at the next section (## or **Error**)
+  const endIdx = content.search(/\n(?:##|\*\*Error\*\*|\[TIMEOUT)/)
+  return endIdx === -1 ? content.trim() : content.slice(0, endIdx).trim()
+}
+
+// ─── Timeout Classification ───────────────────────────────────────────
+
+/**
+ * Classify a timeout based on available output and retry history.
+ *
+ * - timeout-empty: no report, no messages, not yet retried → retryable
+ * - timeout-with-partial: has report or messages → return partial
+ * - timeout-exhausted: already retried → escalate
+ *
+ * @param input Report availability, message presence, and retry count.
+ */
+export function classifyTimeout(input: TimeoutClassifyInput): DelegationResult {
+  const { report, hasMessages, retryCount } = input
+  const hasPartial =
+    (report !== undefined && report.trim() !== '' && !NO_OUTPUT_RE.test(report)) || hasMessages
+
+  // Already retried → exhausted, no more retries
+  if (retryCount >= 1) {
+    return {
+      status: 'timeout',
+      content: report ?? '',
+      retryCount,
+      subType: 'timeout-exhausted',
+      partialResult: hasPartial ? (report ?? '') : undefined,
+      recommendation:
+        'Agent timed out after retry. Options: ' +
+        '(a) try different agent, (b) simplify scope, (c) manual intervention.',
+    }
+  }
+
+  // Has partial output → return it
+  if (hasPartial) {
+    return {
+      status: 'timeout',
+      content: report ?? '',
+      retryCount,
+      subType: 'timeout-with-partial',
+      partialResult: report ?? '',
+      recommendation:
+        'Agent timed out but partial work exists. ' + 'Partial result is available above.',
+    }
+  }
+
+  // No output at all → retryable
+  return {
+    status: 'timeout',
+    content: report ?? '',
+    retryCount,
+    subType: 'timeout-empty',
+    recommendation: 'Agent timed out with no output. Will retry once with rephrased prompt.',
+  }
+}
+
+// ─── Result Helpers ───────────────────────────────────────────────────
+
+/**
+ * Whether a delegation result is retryable (empty + retryCount < 1,
+ * or timeout-empty + retryCount < 1).
+ */
+export function isRetryableResult(result: DelegationResult): boolean {
+  if (result.retryCount >= 1) return false
+  if (result.status === 'empty') return true
+  if (result.status === 'timeout' && result.subType === 'timeout-empty') return true
+  return false
+}
+
+/**
+ * Format a DelegationResult into a human-readable string for the orchestrator.
+ * Success results are returned as-is (the raw content). Non-success results
+ * get a structured status message.
+ */
+export function formatDelegationResult(result: DelegationResult): string {
+  if (result.status === 'success') {
+    return result.content
+  }
+
+  const parts: string[] = []
+
+  // Status header
+  switch (result.status) {
+    case 'empty': {
+      const modeLabel =
+        result.classification === 'empty-mode2'
+          ? 'empty-mode2 (reasoning tokens present but no text output)'
+          : 'empty-mode1 (no tokens generated)'
+      parts.push(`[EMPTY RESULT — ${modeLabel}]`)
+      if (result.retryCount === 0) {
+        parts.push(
+          'The agent returned an empty response. ' +
+            'A retry with a rephrased prompt has been triggered automatically.',
+        )
+      } else {
+        parts.push(
+          'The agent returned an empty response even after retry. ' +
+            'Options: (a) try different agent, (b) simplify scope, (c) manual intervention.',
+        )
+      }
+      break
+    }
+    case 'budget-exhausted':
+      parts.push('[BUDGET EXHAUSTED]')
+      if (result.partialResult) {
+        parts.push('Partial result:')
+        parts.push(result.partialResult)
+      }
+      parts.push(result.recommendation ?? '')
+      break
+    case 'timeout': {
+      const subLabel =
+        result.subType === 'timeout-with-partial'
+          ? 'with partial output'
+          : result.subType === 'timeout-exhausted'
+            ? 'exhausted after retry'
+            : 'no output'
+      parts.push(`[TIMEOUT — ${subLabel}]`)
+      if (result.partialResult) {
+        parts.push('Partial result:')
+        parts.push(result.partialResult)
+      }
+      parts.push(result.recommendation ?? '')
+      break
+    }
+    case 'error':
+      parts.push('[ERROR]')
+      parts.push(result.content)
+      break
+    case 'startup_failed':
+      parts.push('[STARTUP FAILED]')
+      parts.push(result.content)
+      parts.push(
+        result.recommendation ??
+          'Retry once or inspect the child session before dispatching again.',
+      )
+      break
+    case 'bootstrap_unknown':
+      parts.push('[BOOTSTRAP UNKNOWN]')
+      parts.push(result.content)
+      parts.push(
+        result.recommendation ?? 'The host did not expose enough session state to verify startup.',
+      )
+      break
+  }
+
+  // Structured fields for non-success results
+  parts.push(`status: ${result.status}`)
+  parts.push(`retryCount: ${result.retryCount}`)
+
+  return parts.filter((p) => p !== '').join('\n')
+}

package/src/pantheon/delegation-enforce.ts

@@ -30,6 +30,8 @@
 
 // ─── Types ─────────────────────────────────────────────────────────────
 
+import { isAgentAllowed, type PermissionTaskConfig } from './permission-globs.ts'
+
 /** Why a session is read-only. */
 export interface ReadOnlyEntry {
   /** Agent name the session was delegated to (e.g. "apollo"). */
@@ -123,11 +125,21 @@ export function normalizeDelegationAgent(agent: unknown): string | undefined {
   return normalized === '' ? undefined : normalized
 }
 
-/** Runtime delegation matrix from Fase B2. */
-export function isDelegationAllowed(callerAgent: unknown, targetAgent: unknown): boolean {
+/**
+ * Runtime delegation matrix from Fase B2, gated by the O5 permission.task
+ * glob rules when provided. The glob rules run FIRST (last-match-wins; a
+ * deny blocks the target regardless of the matrix), then the static matrix
+ * (zeus → anyone; athena/hermes → apollo only).
+ */
+export function isDelegationAllowed(
+  callerAgent: unknown,
+  targetAgent: unknown,
+  permissionTask?: PermissionTaskConfig,
+): boolean {
   const caller = normalizeDelegationAgent(callerAgent)
   const target = normalizeDelegationAgent(targetAgent)
   if (caller === undefined || target === undefined) return false
+  if (permissionTask !== undefined && !isAgentAllowed(permissionTask, target)) return false
   if (caller === 'zeus') return true
   return (caller === 'athena' || caller === 'hermes') && target === 'apollo'
 }
@@ -154,6 +166,8 @@ export interface EnforcementGuardOptions {
   isRootSession?: (sessionID: string) => boolean
   /** SDK-backed child check used to prevent native task() depth escalation. */
   isChildSession?: (sessionID: string) => boolean
+  /** O5 permission.task glob rules — deny removes the target entirely. */
+  permissionTask?: PermissionTaskConfig
   /** Audit sink for denied runtime delegation attempts. */
   logger?: { warn?: (message: string) => void }
 }
@@ -176,22 +190,14 @@ export const DEFAULT_BLOCKED_TOOLS: ReadonlySet<string> = new Set([
  * codebase reads to @apollo to avoid context bloat and enforce separation
  * of concerns.
  */
-export const ZEUS_READ_DENY_PATTERNS: ReadonlyArray<RegExp> = [
-  /^src\//,
-  /^tests?\//,
-  /^scripts?\//,
-]
+export const ZEUS_READ_DENY_PATTERNS: ReadonlyArray<RegExp> = [/^src\//, /^tests?\//, /^scripts?\//]
 
 /**
  * Path exceptions that Zeus MAY read even if they match a deny pattern.
  * Markdown files, .pantheon/ configs, and memories/ are operational context
  * that Zeus legitimately needs.
  */
-export const ALLOWED_PATHS: ReadonlyArray<RegExp> = [
-  /\.md$/,
-  /\.pantheon\//,
-  /memories\//,
-]
+export const ALLOWED_PATHS: ReadonlyArray<RegExp> = [/\.md$/, /\.pantheon\//, /memories\//]
 
 /**
  * Zeus read guard. When the active agent is Zeus, deny read/glob/grep calls
@@ -202,11 +208,7 @@ export const ALLOWED_PATHS: ReadonlyArray<RegExp> = [
  *
  * @throws {Error} when Zeus attempts a denied read
  */
-export function zeusReadGuard(
-  tool: string,
-  args: unknown,
-  agent: string | undefined,
-): void {
+export function zeusReadGuard(tool: string, args: unknown, agent: string | undefined): void {
   if (agent !== 'zeus') return
   if (tool !== 'read' && tool !== 'glob' && tool !== 'grep') return
 
@@ -226,9 +228,7 @@ export function zeusReadGuard(
       for (const allowed of ALLOWED_PATHS) {
         if (allowed.test(filePath)) return
       }
-      throw new Error(
-        `Zeus cannot read ${filePath} — delegate to @apollo`,
-      )
+      throw new Error(`Zeus cannot read ${filePath} — delegate to @apollo`)
     }
   }
 }
@@ -317,7 +317,7 @@ export function createEnforcementGuard(input: {
         )
         throw new Error(`${prefix}: session ${hook.sessionID} is not an authorized root session`)
       }
-      if (!isDelegationAllowed(caller, target)) {
+      if (!isDelegationAllowed(caller, target, input.options?.permissionTask)) {
         const reason =
           caller === undefined ? 'caller agent is unavailable' : 'agent/target is not allowed'
         input.options.logger?.warn?.(

package/src/pantheon/delegation-finalize.ts

@@ -20,6 +20,8 @@ import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 
 import type { BackgroundJobBoard, BackgroundJobRecord } from './background-job-board.ts'
+import type { PermissionTaskConfig } from './permission-globs.ts'
+import type { StepCapTracker } from './step-cap.ts'
 
 // ─── Types ─────────────────────────────────────────────────────────────
 
@@ -43,9 +45,17 @@ export interface DelegationClientSession {
   }): Promise<{ id: string }>
   promptAsync(input: {
     path: { id: string }
-    body: { agent: string; parts: Array<{ type: 'text'; text: string }> }
+    body: {
+      agent: string
+      model?: { id: string; providerID: string }
+      parts: Array<{ type: 'text'; text: string }>
+    }
+    /** Request cancellation for hosts that support AbortSignal. */
+    signal?: AbortSignal
   }): Promise<unknown>
-  messages(input: { path: { id: string } }): Promise<Array<DelegationMessageBundle>>
+  messages?(input: { path: { id: string } }): Promise<Array<DelegationMessageBundle>>
+  /** Optional session metadata endpoint (older hosts do not expose it). */
+  get?(input: { path: { id: string } }): Promise<unknown>
 }
 
 /** The client surface used by the delegation core. */
@@ -109,6 +119,34 @@ export interface DelegationOptions {
   presetEnv?: Record<string, string | undefined>
   /** Warning sink for the no-model fallback (defaults to console). */
   logger?: { warn?: (msg: string) => void }
+  /**
+   * R4: per-agent step-cap tracker (routing.yml `agents.<name>.max_steps`).
+   * When an agent reaches max_steps the delegation is forced to
+   * summarize-and-stop: skipped with a capped summary when already at the
+   * cap, or the prompt is appended with a stop instruction when the cap is
+   * hit by this dispatch.
+   */
+  stepCapTracker?: StepCapTracker
+  /**
+   * O5: permission.task glob rules controlling which subagents may be
+   * invoked. Denied agents are removed from the delegate tool description
+   * entirely (not just blocked at call time).
+   */
+  permissionTask?: PermissionTaskConfig
+  /**
+   * O5: candidate agent names for the delegate tool description. Defaults
+   * to the canonical 14-agent roster.
+   */
+  agentNames?: readonly string[]
+  /** Bounded post-prompt bootstrap watchdog window. */
+  bootstrapTimeoutMs?: number
+  /** Timeout for the promptAsync request itself (including AbortSignal). */
+  promptTimeoutMs?: number
+  /** Poll interval used by the bootstrap watchdog. */
+  bootstrapPollIntervalMs?: number
+  /** Injectable clock/sleeper for deterministic watchdog tests. */
+  now?: () => number
+  sleep?: (ms: number) => Promise<void>
 }
 
 /** Dependencies threaded to the finalize path. */
@@ -120,7 +158,7 @@ export interface DelegationDeps {
 
 /** Terminal transition requested by the finalize path. */
 export interface FinalizeInput {
-  state: 'completed' | 'error' | 'cancelled'
+  state: 'completed' | 'error' | 'startup_failed' | 'startup_unknown' | 'cancelled'
   error?: string
   timedOut?: boolean
 }
@@ -136,6 +174,8 @@ export const DELEGATION_DEFAULTS = {
 
 /** Concatenate every non-empty text part across the child's messages. */
 async function pullOutput(client: DelegationClient, childSessionID: string): Promise<string> {
+  if (typeof client.session.messages !== 'function')
+    return '(child session messages API unavailable)'
   try {
     const bundles = await client.session.messages({ path: { id: childSessionID } })
     const lines: string[] = []
@@ -277,7 +317,7 @@ export async function finalizeDelegation(
 
   const status: {
     taskID: string
-    state: 'completed' | 'error' | 'cancelled'
+    state: 'completed' | 'error' | 'startup_failed' | 'startup_unknown' | 'cancelled'
     error?: string
     timedOut?: boolean
     resultSummary?: string

package/src/pantheon/delegation-notify.ts

@@ -21,6 +21,11 @@
  * acknowledgment, not a completion), so every job gets exactly ONE terminal
  * transition — never a reconciled echo. Unknown sessions are ignored.
  *
+ * `finalizeIdleChildrenWithoutMd` proactively finalizes children that are
+ * idle on the board but have no MD report on disk — eliminates the phantom
+ * "running" window during `pullOutput` (Fix 2 for the TUI stale-running bug).
+ * Wired into a periodic scan via `startIdleChildScan` (default 30 s cadence).
+ *
  * Pure TypeScript — zero runtime dependencies beyond the board types.
  *
  * Follow-up (Themis review, Phase 5): `extractErrorMessage` handles the two
@@ -38,6 +43,9 @@ import type { FinalizeInput } from './delegation-finalize.ts'
 
 export type { FinalizeInput } from './delegation-finalize.ts'
 
+/** Default cadence for the proactive idle-child scan (30 s). */
+export const IDLE_SCAN_INTERVAL_MS = 30_000
+
 // ─── Types ─────────────────────────────────────────────────────────────
 
 /** Structural view of the event payload the `event` hook receives. */
@@ -98,3 +106,92 @@ export async function handleDelegationEvent(
   }
   return true
 }
+
+// ─── Proactive finalize (Fix 2) ────────────────────────────────────────
+
+/** Dependencies for idle-child scanning. */
+export interface IdleChildScanDeps {
+  /** Look up a board job by session ID (child session IDs are task IDs). */
+  board: {
+    get(taskID: string): BackgroundJobRecord | undefined
+    list(parentSessionID?: string): BackgroundJobRecord[]
+  }
+  /** Bound Phase 2 finalize — clears the timeout timer + writes the report. */
+  finalize: (childSessionID: string, opts: FinalizeInput) => Promise<unknown>
+  /**
+   * Check whether an MD report exists for the given board job.
+   * Receives the full job record so the caller can construct the report
+   * path from `job.parentSessionID` + `job.alias`.
+   * If the function throws, the scan skips that child (fail-open).
+   */
+  hasReport: (job: BackgroundJobRecord) => boolean
+  /** Optional logger for diagnostic messages. */
+  logger?: { info?: (msg: string) => void; warn?: (msg: string) => void }
+}
+
+/**
+ * Scan running board jobs for children whose sessions are idle but have no MD
+ * report on disk, and proactively finalize them. This eliminates the phantom
+ * "running" window that occurs between `session.idle` firing and the
+ * `pullOutput`→`writeDelegationReport` cycle completing.
+ *
+ * Called from the periodic idle-child scan (`startIdleChildScan`, default 30 s).
+ * The scan is O(N) where N = number of running jobs (typically < 10).
+ *
+ * Each child is finalized exactly once — the board's same-terminal idempotency
+ * ensures repeated scans are harmless. Errors are caught per-child so one
+ * failure never blocks the rest.
+ *
+ * @returns Number of children finalized (for diagnostics).
+ */
+export async function finalizeIdleChildrenWithoutMd(
+  deps: IdleChildScanDeps,
+): Promise<number> {
+  const runningJobs = deps.board
+    .list()
+    .filter((j: BackgroundJobRecord) => j.state === 'running')
+
+  let finalized = 0
+  for (const job of runningJobs) {
+    try {
+      // If the child already has an MD report, finalize was already handled
+      // by handleDelegationEvent — skip.
+      if (deps.hasReport(job)) continue
+      // Child is idle on the board but has no report — proactively finalize.
+      await deps.finalize(job.taskID, { state: 'completed' })
+      finalized++
+    } catch (err) {
+      deps.logger?.warn?.(
+        `[delegation-notify] proactive finalize failed for ${job.taskID}: ${err}`,
+      )
+    }
+  }
+  return finalized
+}
+
+// ─── Periodic scan launcher ─────────────────────────────────────────────
+
+/**
+ * Start a periodic scan that proactively finalizes idle board children
+ * without MD reports. The scan runs every `intervalMs` (default 30 s) and
+ * is **unref'd** so it never holds the process open on its own.
+ *
+ * The timer is idempotent — calling this function multiple times is safe
+ * (each call creates an independent timer, but the underlying finalize
+ * operation is itself idempotent due to the board's same-terminal guard).
+ *
+ * @returns A `NodeJS.Timeout` handle that can be cleared with
+ *   `clearInterval(handle)` to stop the scan.
+ */
+export function startIdleChildScan(
+  deps: IdleChildScanDeps,
+  intervalMs: number = IDLE_SCAN_INTERVAL_MS,
+): NodeJS.Timeout {
+  const timer = setInterval(() => {
+    void finalizeIdleChildrenWithoutMd(deps).catch((err) => {
+      deps.logger?.warn?.(`[delegation-notify] periodic idle scan failed: ${err}`)
+    })
+  }, intervalMs)
+  timer.unref()
+  return timer
+}