pantheon-opencode 1.5.0-beta.9 → 1.5.1

package/src/pantheon/delegation-finalize.ts

@@ -1,406 +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
-  /**
-   * Max completed jobs to keep per agent after pruning (default: 10).
-   * Matches the native delegate-manager default.
-   */
-  keepCompleted?: number
-  /**
-   * Hard cap on total board entries (default: 50).
-   * Matches the native delegate-manager default.
-   */
-  maxEntries?: number
-  /** Injectable clock/sleeper for deterministic watchdog tests. */
-  now?: () => number
-  sleep?: (ms: number) => Promise<void>
-  /**
-   * Kill-switch: when false, all delegation tools (delegate/read/list) throw
-   * immediately. Mirrors `PANTHEON_DELEGATION=off` from the native manager.
-   * Defaults to true (delegation enabled) when not specified.
-   */
-  delegationEnabled?: boolean
-}
-
-/** 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.
-  }
-
-  // P1-1: Delete the auto-wake signal file to prevent leaks. The board
-  // writes .signal.json on every terminal transition, but the legacy path
-  // never called deleteSignal — only the native delegate-manager did.
-  // The consumer (auto-wake.ts consumeWakeSignals) is intentionally NOT
-  // wired in the event hook: finalizeDelegation already handles the
-  // terminal transition, so consuming signals would be redundant and risks
-  // double-processing. deleteSignal on finalize is sufficient.
-  await deps.board.deleteSignal(job.alias)
-
-  // P1-4: Prune old completed jobs and enforce the hard entry cap. The
-  // native delegate-manager called these in settle(), but the legacy
-  // finalize path omitted them, allowing unbounded board growth.
-  await deps.board.pruneCompleted(deps.options.keepCompleted ?? 10)
-  await deps.board.enforceEntryCap(deps.options.maxEntries ?? 50)
-
-  return deps.board.get(childSessionID) ?? job
-}

package/src/pantheon/delegation-notify.ts

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

@@ -1,73 +0,0 @@
-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.
-  }
-}