pantheon-opencode 1.5.0-beta.2 → 1.5.0-beta.20

package/src/pantheon/delegation-classifier.ts

@@ -1,307 +0,0 @@
-/**
- * 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-finalize.ts

@@ -1,374 +0,0 @@
-/**
- * Delegation finalize — PULL output from a child session and persist the
- * delegation report (markdown) + the terminal board transition.
- *
- * Completion is NOT pushed: the event hook observes `session.idle` on the
- * child session, then calls `finalizeDelegation()` which pulls the child's
- * messages via `client.session.messages()`, writes the report atomically
- * (tmp + rename) to `.pantheon/delegations/<rootSessionID>/<alias>.md`, and
- * moves the job to a terminal board state (persist-before-notify: the report
- * file exists before `board.updateStatus` resolves waiters).
- *
- * Pure TypeScript — zero runtime dependencies beyond Node.js builtins and the
- * BackgroundJobBoard. The client is a STRUCTURAL interface (fake-client
- * friendly) so this module is testable standalone, without the opencode SDK.
- *
- * @module delegation-finalize
- */
-
-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 ─────────────────────────────────────────────────────────────
-
-/** A minimal structural view of one message bundle from session.messages(). */
-export interface DelegationMessageBundle {
-  info?: { role?: string; finish?: string; error?: unknown }
-  parts?: Array<{
-    type?: string
-    text?: string
-    /** Tool name on `tool` parts — used by the activity sampler. */
-    tool?: string
-    /** Tool input on `tool` parts (opencode SDK ToolPart.metadata). */
-    metadata?: { input?: unknown }
-  }>
-}
-
-/** Minimal structural view of the opencode SDK session client we use. */
-export interface DelegationClientSession {
-  create(input: {
-    body: { parentID: string; title?: string; model?: { id: string; providerID: string } }
-  }): Promise<{ id: string }>
-  promptAsync(input: {
-    path: { id: 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>>
-  /** 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. */
-export interface DelegationClient {
-  session: DelegationClientSession
-}
-
-/** Tunables for the delegation core (all optional — see DELEGATION_DEFAULTS). */
-export interface DelegationOptions {
-  /** Job timeout before the delegation is finalized as error/timedOut. */
-  timeoutMs?: number
-  /** Caller-side cap for pantheon_delegation_read's waitForTerminal. */
-  readTimeoutMs?: number
-  /** Base directory for delegation reports (default `.pantheon/delegations`). */
-  outputDir?: string
-  /** Explicit root-session allowlist for the depth guard. */
-  rootSessions?: ReadonlySet<string>
-  /** Custom depth-guard predicate — overrides rootSessions and the default. */
-  isRootSession?: (sessionID: string) => boolean
-  /** SDK-backed child predicate; authoritative when supplied by the plugin. */
-  isChildSession?: (sessionID: string) => boolean
-  /**
-   * Enforce the runtime B2 delegation matrix; createDelegationTools defaults
-   * this to true. Set false only for an explicitly legacy host that cannot
-   * provide ToolContext.agent.
-   */
-  enforceRuntimeMatrix?: boolean
-  /** Record a child returned by the SDK session.create call. */
-  registerChildSession?: (sessionID: string, parentID: string) => void
-  /**
-   * Agents whose delegated child sessions are registered as read-only
-   * (Phase 4 enforcement). Mirrors routing.yml
-   * background_delegation.read_only_agents. Matching is case-insensitive.
-   */
-  readOnlyAgents?: ReadonlySet<string>
-  /**
-   * Per-agent model overrides for delegated child sessions, keyed by agent
-   * name (lowercase, e.g. `apollo`). Values are opencode model IDs in
-   * `provider/model` form (e.g. `opencode/deepseek-v4-flash-free`), sourced
-   * from routing.yml agent entries. Higher priority than the active preset.
-   */
-  agentModels?: Readonly<Record<string, string>>
-  /**
-   * Fase B3: Per-exception delegation budgets. Keys use
-   * `<parent-agent>-><target-agent>` (for example `athena->apollo`). The
-   * count is tracked per parent session for this process. It is intentionally
-   * not persisted across restart because this layer has no reliable store.
-   * An absent key has no budget limit.
-   */
-  delegationBudgets?: ReadonlyMap<string, number>
-  /**
-   * Fase B3: Wall-clock timeout (ms) for individual delegation sessions.
-   * The plugin resolves `PANTHEON_DELEGATION_TIMEOUT_MS` into this option;
-   * direct callers may provide it here instead.
-   */
-  wallClockTimeoutMs?: number
-  /**
-   * Env override for the active-preset resolution (see resolveActivePreset).
-   * Defaults to process.env. Primarily for tests.
-   */
-  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. */
-export interface DelegationDeps {
-  board: BackgroundJobBoard
-  client: DelegationClient
-  options: DelegationOptions
-}
-
-/** Terminal transition requested by the finalize path. */
-export interface FinalizeInput {
-  state: 'completed' | 'error' | 'startup_failed' | 'startup_unknown' | 'cancelled'
-  error?: string
-  timedOut?: boolean
-}
-
-/** Defaults matching routing.yml background_delegation (timeout_ms 900000). */
-export const DELEGATION_DEFAULTS = {
-  timeoutMs: 900_000,
-  readTimeoutMs: 900_000,
-  outputDir: '.pantheon/delegations',
-} as const
-
-// ─── Output pulling ────────────────────────────────────────────────────
-
-interface PulledOutput {
-  text: string
-  /** True only when the child produced an assistant message or tool activity. */
-  hasWork: boolean
-}
-
-/** Pull visible text and structurally identify real child work. */
-async function pullOutput(client: DelegationClient, childSessionID: string): Promise<PulledOutput> {
-  if (typeof client.session.messages !== 'function')
-    return { text: '(child session messages API unavailable)', hasWork: false }
-  try {
-    const bundles = await client.session.messages({ path: { id: childSessionID } })
-    const lines: string[] = []
-    let hasWork = false
-    for (const bundle of bundles) {
-      const hasToolPart = (bundle.parts ?? []).some((part) => part.type === 'tool')
-      const hasTextPart = (bundle.parts ?? []).some(
-        (part) => part.type === 'text' && typeof part.text === 'string' && part.text.trim() !== '',
-      )
-      if (
-        bundle.info?.role === 'assistant' &&
-        bundle.info.error === undefined &&
-        (hasToolPart || hasTextPart)
-      ) {
-        hasWork = true
-      }
-      for (const part of bundle.parts ?? []) {
-        if (
-          part.type === 'tool' &&
-          bundle.info?.role === 'assistant' &&
-          bundle.info.error === undefined
-        )
-          hasWork = true
-        if (part.type === 'text' && typeof part.text === 'string' && part.text.trim() !== '') {
-          lines.push(part.text)
-        }
-      }
-    }
-    return { text: lines.join('\n\n'), hasWork }
-  } catch (err: unknown) {
-    const reason = err instanceof Error ? err.message : String(err)
-    return { text: `(failed to pull child session output: ${reason})`, hasWork: false }
-  }
-}
-
-// ─── Markdown rendering ────────────────────────────────────────────────
-
-/** Render the delegation report body. Public for tests/Phase 3 reuse. */
-export function renderDelegationMarkdown(
-  job: BackgroundJobRecord,
-  output: string,
-  opts: FinalizeInput & { at?: number },
-): string {
-  const at = opts.at ?? Date.now()
-  const lines = [
-    `# Delegation Report — ${job.alias}`,
-    '',
-    `- **Task ID**: \`${job.taskID}\``,
-    `- **Agent**: ${job.agent}`,
-    `- **Description**: ${job.description}`,
-    `- **State**: ${opts.state}`,
-    `- **Timed out**: ${opts.timedOut === true ? 'true' : 'false'}`,
-    `- **Started**: ${new Date(job.launchedAt).toISOString()}`,
-    `- **Finalized**: ${new Date(at).toISOString()}`,
-    '',
-    '## Output',
-    '',
-    output.trim() !== '' ? output : '_No output captured._',
-  ]
-  if (opts.error !== undefined) {
-    lines.push('', `**Error**: ${opts.error}`)
-  }
-  if (opts.timedOut === true) {
-    lines.push('', '[TIMEOUT REACHED]')
-  }
-  return `${lines.join('\n')}\n`
-}
-
-/** One-line result summary from the pulled output (for the board record). */
-function summarizeOutput(output: string): string {
-  const firstLine = output
-    .split('\n')
-    .map((l) => l.trim())
-    .find((l) => l !== '')
-  if (firstLine === undefined) return 'No output captured'
-  return firstLine.length > 120 ? `${firstLine.slice(0, 120)}…` : firstLine
-}
-
-// ─── Report persistence ────────────────────────────────────────────────
-
-/**
- * Reject session IDs that could escape the delegation output directory.
- * `parentSessionID` is embedded in the report path
- * `<outputDir>/<parentSessionID>/<alias>.md` — `path.join` does NOT strip
- * `..`, so a traversing ID would write outside the sandbox. Called BEFORE any
- * path construction (F1 — path traversal hardening).
- *
- * @throws {Error} When the ID contains `..`, `/`, or `\`.
- */
-export function assertSafeParentSessionID(parentSessionID: string): void {
-  if (
-    parentSessionID.includes('..') ||
-    parentSessionID.includes('/') ||
-    parentSessionID.includes('\\')
-  ) {
-    throw new Error(`Invalid parentSessionID: ${parentSessionID}`)
-  }
-}
-
-/** Atomic write (tmp + rename) of the report under <outputDir>/<parent>/<alias>.md. */
-async function writeDelegationReport(
-  outputDir: string,
-  job: BackgroundJobRecord,
-  md: string,
-): Promise<string> {
-  assertSafeParentSessionID(job.parentSessionID)
-  const dir = join(outputDir, job.parentSessionID)
-  const filePath = join(dir, `${job.alias}.md`)
-  const tmpPath = join(dir, `${job.alias}.md.tmp`)
-  await mkdir(dir, { recursive: true })
-  await writeFile(tmpPath, md, 'utf-8')
-  await rename(tmpPath, filePath)
-  return filePath
-}
-
-/** Read a previously written report; undefined when the file does not exist. */
-export async function readDelegationReport(
-  outputDir: string,
-  job: BackgroundJobRecord,
-): Promise<string | undefined> {
-  assertSafeParentSessionID(job.parentSessionID)
-  const filePath = join(outputDir, job.parentSessionID, `${job.alias}.md`)
-  try {
-    return await readFile(filePath, 'utf-8')
-  } catch (err: unknown) {
-    if (err instanceof Error && 'code' in err && (err as NodeJS.ErrnoException).code === 'ENOENT') {
-      return undefined
-    }
-    throw err
-  }
-}
-
-// ─── Finalize ──────────────────────────────────────────────────────────
-
-/**
- * Finalize a delegation for a child session: pull output, write the report
- * atomically, then move the board job to the requested terminal state.
- *
- * The board transition is guarded: only `running` → terminal, or an
- * idempotent same-terminal re-notify, are applied. A finalize that races a
- * timeout (already `error`) never overwrites the terminal state — the report
- * file is still (re)written, so the marker reflects the latest observation.
- *
- * @returns The updated job record, or undefined when the session is unknown.
- */
-export async function finalizeDelegation(
-  deps: DelegationDeps,
-  childSessionID: string,
-  opts: FinalizeInput,
-): Promise<BackgroundJobRecord | undefined> {
-  const job = deps.board.get(childSessionID)
-  if (!job) return undefined
-
-  const pulled = await pullOutput(deps.client, childSessionID)
-  const output = pulled.text
-  const effectiveOpts: FinalizeInput =
-    opts.state === 'completed' && !pulled.hasWork
-      ? {
-          state: 'error',
-          error: opts.error ?? 'Child session produced no assistant or tool output',
-          ...(opts.timedOut !== undefined ? { timedOut: opts.timedOut } : {}),
-        }
-      : opts
-  const outputDir = deps.options.outputDir ?? DELEGATION_DEFAULTS.outputDir
-  await writeDelegationReport(outputDir, job, renderDelegationMarkdown(job, output, effectiveOpts))
-
-  const status: {
-    taskID: string
-    state: 'completed' | 'error' | 'startup_failed' | 'startup_unknown' | 'cancelled'
-    error?: string
-    timedOut?: boolean
-    resultSummary?: string
-  } = {
-    taskID: childSessionID,
-    state: effectiveOpts.state,
-    resultSummary: summarizeOutput(output),
-  }
-  if (effectiveOpts.error !== undefined) status.error = effectiveOpts.error
-  if (effectiveOpts.timedOut !== undefined) status.timedOut = effectiveOpts.timedOut
-
-  const current = deps.board.get(childSessionID)
-  if (current !== undefined) {
-    if (current.state === 'running' || current.state === effectiveOpts.state) {
-      await deps.board.updateStatus(status)
-    }
-    // Terminal in a DIFFERENT state (e.g. timeout already recorded) — the
-    // report above still captures this finalize; the board state stands.
-  }
-  return deps.board.get(childSessionID) ?? job
-}