pantheon-opencode 1.4.3 → 1.5.0-beta.2

package/src/pantheon/delegation-finalize.ts

@@ -0,0 +1,374 @@
+/**
+ * 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
+}

package/src/pantheon/delegation-notify.ts

@@ -0,0 +1,212 @@
+/**
+ * Delegation event wiring — observe background-job lifecycle events and
+ * route them to finalize. This module is the `event`-hook complement of the
+ * board: `session.idle`/`session.error` on a child session that is a board
+ * job → `finalizeDelegation` (Phase 2), which transitions the board and
+ * fires `onTerminal`.
+ *
+ * NOT a notification channel. The user policy is ZERO delegation
+ * notifications in the chat transcript — no `<task-notification>` block is
+ * ever injected into a `chat.message` output, and no queued delivery path
+ * exists. Completion visibility lives in the legitimate channels only:
+ * the board `[unread]` marker (`pantheon_delegation_list`),
+ * `pantheon_delegation_read`, TUI toasts (pantheon-hooks, PANTHEON_TOASTS
+ * gate), and compaction carry-forward. The plugin's `onTerminal` listener
+ * writes a file-only log line for the on-disk audit trail.
+ *
+ * `handleDelegationEvent` wires the `event` hook: `session.idle`/`session.error`
+ * on a child session that is a board job → `finalizeDelegation` (Phase 2),
+ * which transitions the board and fires `onTerminal`. Finalize never notifies
+ * directly, and `markReconciled` does not re-fire onTerminal (reconcile is an
+ * acknowledgment, not a completion), so every job gets exactly ONE terminal
+ * transition — never a reconciled echo. Unknown sessions are ignored.
+ *
+ * `finalizeIdleChildrenWithoutMd` proactively finalizes children confirmed
+ * idle by the V1 session-status API but with no MD report on disk — eliminates
+ * the phantom "running" window during `pullOutput` without treating a board
+ * record's `running` state as proof that the child is idle. 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
+ * observed `session.error` error shapes (string, { message }). The opencode SDK
+ * MAY expose other shapes (e.g. Error-like with non-string `message`) — if a
+ * real session.error ever carries one, the extraction degrades to the generic
+ * "session error" label. No code change: there is no evidence any other shape
+ * occurs in practice; revisit if a session.error shows an unexpected payload.
+ *
+ * @module delegation-notify
+ */
+
+import type { BackgroundJobRecord } from './background-job-board.ts'
+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. */
+export interface DelegationEventLike {
+  type?: string
+  properties?: Record<string, unknown>
+}
+
+/** Dependencies threaded to handleDelegationEvent (board lookup + finalize). */
+export interface DelegationEventDeps {
+  /** Look up a board job by session ID (child session IDs are task IDs). */
+  board: { get(taskID: string): BackgroundJobRecord | undefined }
+  /** Bound Phase 2 finalize — clears the timeout timer + writes the report. */
+  finalize: (childSessionID: string, opts: FinalizeInput) => Promise<unknown>
+}
+
+// ─── Event → finalize wiring ───────────────────────────────────────────
+
+function extractErrorMessage(error: unknown): string {
+  if (typeof error === 'string' && error.trim() !== '') return error
+  if (error && typeof error === 'object' && 'message' in error) {
+    const message = (error as { message: unknown }).message
+    if (typeof message === 'string' && message.trim() !== '') return message
+  }
+  return 'session error'
+}
+
+/**
+ * Handle a lifecycle event for background delegations:
+ *  - `session.idle` on a board job → finalize as completed;
+ *  - `session.error` on a board job → finalize as error (message extracted);
+ *  - any other event, a missing session ID, or an unknown session → no-op.
+ *
+ * Finalize transitions the board, which fires `onTerminal` (the plugin's
+ * file-only audit log — no chat delivery; see module header). The board's
+ * same-terminal idempotency makes repeated idles harmless (finalize rewrites
+ * the report but never transitions a terminal job to a different state).
+ *
+ * @returns True when the event named a board job (handled).
+ */
+export async function handleDelegationEvent(
+  ev: DelegationEventLike,
+  deps: DelegationEventDeps,
+): Promise<boolean> {
+  const type = ev?.type
+  if (type !== 'session.idle' && type !== 'session.error') return false
+  const sessionID = ev.properties?.sessionID
+  if (typeof sessionID !== 'string' || sessionID === '') return false
+  if (deps.board.get(sessionID) === undefined) return false
+
+  if (type === 'session.idle') {
+    await deps.finalize(sessionID, { state: 'completed' })
+  } else {
+    await deps.finalize(sessionID, {
+      state: 'error',
+      error: extractErrorMessage(ev.properties?.error),
+    })
+  }
+  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>
+  /**
+   * Confirm the child's native V1 session status. `undefined` means the
+   * status is unavailable and MUST NOT be treated as idle.
+   */
+  isIdle?: (childSessionID: string) => Promise<boolean | undefined>
+  /**
+   * 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 V1 session status is confirmed
+ * 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).
+ *
+ * A missing status probe is an explicit unknown state, not an idle signal, so
+ * legacy embedders without the V1 API fail closed. 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 (deps.isIdle === undefined) {
+        deps.logger?.warn?.(
+          `[delegation-notify] idle status unknown for ${job.taskID}; proactive finalize skipped`,
+        )
+        continue
+      }
+      const idle = await deps.isIdle(job.taskID)
+      if (idle !== true) {
+        if (idle === undefined) {
+          deps.logger?.warn?.(
+            `[delegation-notify] idle status unknown for ${job.taskID}; proactive finalize skipped`,
+          )
+        }
+        continue
+      }
+      // 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
+}

package/src/pantheon/delegation-toast.ts

@@ -0,0 +1,73 @@
+import type { BackgroundJobRecord } from './background-job-board.ts'
+
+type ToastCategory = 'errors' | 'delegations' | 'council'
+
+const toastMode = (process.env.PANTHEON_TOASTS ?? '').trim().toLowerCase()
+const enabledToastCategories: ReadonlySet<ToastCategory> = (() => {
+  switch (toastMode) {
+    case 'off':
+      return new Set()
+    case 'errors':
+      return new Set(['errors'])
+    case 'council':
+      return new Set(['errors', 'council'])
+    case 'all':
+      return new Set(['errors', 'delegations', 'council'])
+    default:
+      return new Set(['errors', 'delegations', 'council'])
+  }
+})()
+const terminalToastsShown = new Set<string>()
+const terminalStates = new Set(['completed', 'error', 'cancelled'])
+
+/** Match the lifecycle toast gate used by pantheon-hooks. */
+export function delegationToastEnabled(): boolean {
+  return enabledToastCategories.has('delegations')
+}
+
+export type ToastClient = {
+  tui?: {
+    showToast?: (input: {
+      body: {
+        title?: string
+        message: string
+        variant: 'info' | 'success' | 'warning' | 'error'
+        duration: number
+      }
+    }) => Promise<unknown>
+  }
+}
+
+/** Best-effort visual completion signal; never affects board finalization. */
+export async function showDelegationTerminalToast(
+  client: ToastClient,
+  job: Pick<BackgroundJobRecord, 'taskID' | 'alias' | 'agent' | 'state' | 'timedOut'>,
+): Promise<void> {
+  try {
+    if (!delegationToastEnabled()) return
+    const isTerminal = job.timedOut || terminalStates.has(job.state)
+    if (isTerminal) {
+      if (terminalToastsShown.has(job.taskID)) return
+      terminalToastsShown.add(job.taskID)
+    }
+    const showToast = client.tui?.showToast
+    if (typeof showToast !== 'function') return
+    const state = job.timedOut ? 'timeout' : job.state
+    const variant =
+      state === 'completed'
+        ? 'success'
+        : state === 'error' || state === 'timeout'
+          ? 'error'
+          : 'warning'
+    await showToast({
+      body: {
+        title: 'Delegação concluída',
+        message: `${job.alias} (${job.agent}) — ${state}`,
+        variant,
+        duration: 4000,
+      },
+    })
+  } catch {
+    // TUI is optional (and may disappear during shutdown); completion is durable.
+  }
+}