pantheon-opencode 1.3.2 → 1.3.4

package/src/agents/zeus.md

@@ -144,6 +144,34 @@ task_status(task_id="ses_xxx", wait=true)
   -> bloqueia ate completar: { state: "completed", task_result: "..." }
 ```
 
+### Pantheon Delegation Tools (plugin) — 3-tool API
+
+O plugin Pantheon adiciona 3 tools de delegacao gerenciada pelo BackgroundJobBoard:
+
+```
+pantheon_delegate({prompt, agent, description?, read_only?})
+  -> cria sessao filha, registra no board, retorna alias: [apo-1]
+pantheon_delegation_read({id: "apo-1"})
+  -> BLOQUEIA ate o job terminar, retorna o report markdown, marca reconciled
+  -> durante a espera, mostra o que o agente esta fazendo: seccao final "## Agent Activity"
+     (amostra as messages do child a cada ~2s; tool calls + args truncados / texto)
+pantheon_delegation_list()
+  -> lista jobs da sessao, com [unread] para jobs terminados nao lidos
+  -> jobs RUNNING mostram "last activity:" (ultima acao visivel do child)
+  -> fail-open: sem suporte a messages, formato atual inalterado
+```
+
+- **Read-only enforcement:** agentes read-only (apollo, gaia — `read_only_agents` no routing.yml) tem `edit`, `write`, `bash`, `task` NEGADOS dentro da sessao delegada (o guard de `tool.execute.before` THROW com mensagem acionavel). Use `read_only: true` no delegate para qualquer agente de investigacao.
+- **Depth-2 hard-enforced:** sessao read-only NAO cria subagentes (`task` bloqueado) — investigacao nunca vira arvore.
+- **Compactacao:** jobs em voo (running + unread terminal) sao injetados no contexto de compactacao via `experimental.session.compacting` — delegacao em andamento nao se perde ao compactar.
+
+### DELEGATION_RULES (plugin path)
+
+1. **NUNCA** polle `pantheon_delegation_list` para checar se um job terminou.
+2. Voce NAO recebe notificacao injetada no chat — politica do usuario: ZERO `task-notification` no transcript. Visibilidade de conclusao: marcador `[unread]` em `pantheon_delegation_list`, `pantheon_delegation_read({id})`, toasts TUI (pantheon-hooks) e carry-forward de compactacao.
+3. Use `pantheon_delegation_read({id})` APENAS para fan-in explicito / recuperacao de resultado sob demanda (bloqueia ate o fim).
+4. `pantheon_delegation_list` e para diagnostico, nao para polling.
+
 ### Background (sempre usar)
 - **Apollo, Hermes, Aphrodite, Demeter, Hephaestus, Prometheus**
 - Dispare em waves paralelas: ate 5 concorrentes
@@ -256,3 +284,55 @@ Wave: dispare N, colete com tolerancia a falha
     catch:
       r = retry(agente, prompt_alternativo)
 ```
+
+### Plugin Enforcer (auto — session.idle hook)
+O plugin re-injeta "Continue: pending todos remain — review and proceed." em sessões root/não-board que
+vão a idle com todos incompletos. Guards (todos no `src/pantheon/todo-enforcer.ts`):
+- **User-activity (30s)** — após uma mensagem do usuário (`chat.message` hook),
+  a injeção é suprimida por `user_activity_quiet_ms: 30000`.
+- **Board-running** — sessão com job background do nosso board em running → skip.
+- **Native-children (2 min)** — children de `task(background=true)` do opencode
+  NÃO estão no nosso board; o enforcer consulta `session.children()` e pula se
+  algum child tiver `time.updated` mais novo que `child_active_ms: 120000`
+  (background task nativo ainda rodando). API indisponível → fail-open (log + injeta).
+- **Kill-switch**: `PANTHEON_TODO_ENFORCER=off` desativa o enforcer por completo
+  (lido na construção do plugin). routing.yml é espelho de documentação — o env
+  var é o switch real (precedente COMPACTION_MAX_ITEMS).
+
+## Wave 4 (PR #46): Empty-Result Retry + /cost + Themis Tier
+
+### Empty-Result Retry (dispatch-guard — MANUAL orchestration)
+OpenCode 1.18.x NAO permite interceptar a conclusao de `task()` via hooks,
+entao o `src/pantheon/dispatch-guard.ts` e uma lib pura usada POR VOCE na
+orquestracao (NAO esta wired no plugin):
+
+```
+import { createDispatchGuard } from '.../src/pantheon/dispatch-guard.ts'  # via code-mode ou subagente
+
+guard = createDispatchGuard({ retryOnEmpty: true, logger: { warn: console.warn } })
+
+# classificar resultado de task_status/wait:
+#   'content'      → tem texto, pronto
+#   'empty-mode1'  → SEM texto E SEM tokens (nada voltou)      → RETRY 1x
+#   'empty-mode2'  → SEM texto, MAS tokens (raciocinou, perdeu a parte de texto;
+#                    assinatura da falha themis Wave-2)         → RETRY 1x
+
+out = await guard.maybeRetry(result, async () => { ...task() de novo... })
+# out.retried=true se redisparou; CAP DURO de 1 retry — nunca 2x.
+# Se o retry voltar vazio, `out.retried=false` — NAO tente de novo: escale.
+```
+Regra: retry 1x APENAS em `empty-mode1`/`empty-mode2`. Resultado com conteudo
+nunca redispara. Apos 1 retry vazio → escalate (mesma regra do TODO Enforcer).
+
+### /cost — pantheon_cost tool (WIRED no plugin)
+`pantheon_cost({ days?: number })` le o `opencode.db` READ-ONLY (node:sqlite;
+fallback `scripts/cost.mjs`) e devolve tabela markdown de custo + tokens por
+agente nos ultimos N dias (default 7). Uso: quando Nyx pedir visibilidade de
+custo, ou antes de escalar tier — decida se o batch valeu o preco.
+
+### Themis Tier Policy (routing.yml go-deepseek)
+Revisoes de FASE do themis rodam em `opencode/deepseek-v4-flash`
+(review rapido, barato — evita a assinatura empty-mode2 de retorno vazio).
+O tier PRO (`deepseek-v4-pro`) fica RESERVADO para o FINAL GATE (auditoria
+final apos tudo aprovado) — override manual na hora. Athena NAO muda:
+planner continua em pro.

package/src/pantheon/background-job-board.ts

@@ -11,17 +11,19 @@
  */
 
 import { mkdir, rename, writeFile } from 'node:fs/promises'
-import { join, dirname } from 'node:path'
+import { dirname, join } from 'node:path'
+
+import { createPantheonLogger } from './logger.ts'
+
+// Silence-by-default TUI policy (pantheon-hooks L42-58): console output in a
+// plugin renders into the opencode TUI — the "lixo". Board internals log to
+// .pantheon/logs/hooks.log; console echo is opt-in via PANTHEON_HOOKS_LOG=1.
+const log = createPantheonLogger({ module: 'BackgroundJobBoard' })
 
 // ─── Types ─────────────────────────────────────────────────────────────
 
 /** Valid states for a background job. */
-export type BackgroundJobState =
-  | 'running'
-  | 'completed'
-  | 'error'
-  | 'cancelled'
-  | 'reconciled'
+export type BackgroundJobState = 'running' | 'completed' | 'error' | 'cancelled' | 'reconciled'
 
 /** Terminal states that can transition to reconciled. */
 const TERMINAL_STATES: ReadonlySet<BackgroundJobState> = new Set([
@@ -35,10 +37,7 @@ const TERMINAL_STATES: ReadonlySet<BackgroundJobState> = new Set([
  * Each entry defines which target states are reachable from the current state.
  * Only running → terminal, or same-terminal → same-terminal (idempotent re-notify).
  */
-const UPDATE_TRANSITIONS: Record<
-  BackgroundJobState,
-  ReadonlySet<BackgroundJobState>
-> = {
+const UPDATE_TRANSITIONS: Record<BackgroundJobState, ReadonlySet<BackgroundJobState>> = {
   running: new Set(['completed', 'error', 'cancelled']),
   completed: new Set(['completed']),
   error: new Set(['error']),
@@ -129,6 +128,13 @@ export interface PersistenceAdapter {
   deleteJob(taskID: string): Promise<void>
 }
 
+/** A pending `waitForTerminal()` registration for a taskID. */
+interface TerminalWaiter {
+  resolve: (job: BackgroundJobRecord) => void
+  reject: (err: Error) => void
+  timer: NodeJS.Timeout
+}
+
 // ─── Agent Prefix Mapping ──────────────────────────────────────────────
 
 const AGENT_PREFIXES: Record<string, string> = {
@@ -171,6 +177,7 @@ export class BackgroundJobBoard {
    */
   private readonly aliasCounters: Map<string, Map<string, number>> = new Map()
   private readonly terminalListeners: Set<(taskID: string) => void> = new Set()
+  private readonly terminalWaiters: Map<string, TerminalWaiter[]> = new Map()
   private readonly options: Required<BoardOptions>
   private persistence: PersistenceAdapter | null = null
 
@@ -363,6 +370,13 @@ export class BackgroundJobBoard {
    * Valid: only `completed`, `error`, or `cancelled` → `reconciled`.
    * Idempotent: already-reconciled jobs are returned as-is.
    * Rejected: `running` → `reconciled`.
+   *
+   * Reconcile is an ACKNOWLEDGMENT, not a completion event: it does NOT fire
+   * the terminal listeners (onTerminal) and does NOT resolve waiters — the
+   * terminal transition already did both. Firing them here produced a second
+   * `<task-notification>` per job (completed + reconciled) in the parent
+   * transcript; waiters are covered by `waitForTerminal` resolving immediately
+   * for already-terminal/reconciled jobs.
    */
   async markReconciled(taskID: string): Promise<BackgroundJobRecord | undefined> {
     const job = this.jobs.get(taskID)
@@ -378,7 +392,6 @@ export class BackgroundJobBoard {
       )
     }
 
-    const wasTerminalUnreconciled = job.terminalUnreconciled
     job.state = 'reconciled'
     job.updatedAt = Date.now()
     job.terminalUnreconciled = false
@@ -386,10 +399,6 @@ export class BackgroundJobBoard {
     await this.persistRecord(job)
     await this.writeSignal(job)
 
-    if (wasTerminalUnreconciled) {
-      this.notifyTerminal(job.taskID)
-    }
-
     return job
   }
 
@@ -407,17 +416,14 @@ export class BackgroundJobBoard {
   list(parentSessionID?: string): BackgroundJobRecord[] {
     const all = Array.from(this.jobs.values())
     if (!parentSessionID) return [...all]
-    return all.filter(j => j.parentSessionID === parentSessionID)
+    return all.filter((j) => j.parentSessionID === parentSessionID)
   }
 
   /**
    * Resolve a job by either taskID or alias within a parent session.
    * Checks exact taskID first, then falls back to alias matching.
    */
-  resolve(
-    parentSessionID: string,
-    taskIDOrAlias: string,
-  ): BackgroundJobRecord | undefined {
+  resolve(parentSessionID: string, taskIDOrAlias: string): BackgroundJobRecord | undefined {
     // Exact taskID match (session-scoped)
     const byID = this.jobs.get(taskIDOrAlias)
     if (byID?.parentSessionID === parentSessionID) return byID
@@ -460,6 +466,65 @@ export class BackgroundJobBoard {
     this.terminalListeners.delete(listener)
   }
 
+  /**
+   * Resolve with the job record once the job reaches a terminal state
+   * (`completed`, `error`, `cancelled`, or `reconciled`), or reject with a
+   * timeout error if `timeoutMs` elapses first.
+   *
+   * Resolves immediately when the job is already terminal at call time.
+   * Multiple concurrent waiters for the same taskID all resolve.
+   */
+  waitForTerminal(taskID: string, timeoutMs: number): Promise<BackgroundJobRecord> {
+    const existing = this.jobs.get(taskID)
+    if (existing && (TERMINAL_STATES.has(existing.state) || existing.state === 'reconciled')) {
+      return Promise.resolve(existing)
+    }
+
+    return new Promise<BackgroundJobRecord>((resolve, reject) => {
+      const waiter: TerminalWaiter = {
+        resolve,
+        reject,
+        timer: setTimeout(() => {
+          this.removeTerminalWaiter(taskID, waiter)
+          reject(
+            new Error(
+              `Timed out after ${timeoutMs}ms waiting for job ${taskID} to reach a terminal state`,
+            ),
+          )
+        }, timeoutMs),
+      }
+      const waiters = this.terminalWaiters.get(taskID) ?? []
+      waiters.push(waiter)
+      this.terminalWaiters.set(taskID, waiters)
+    })
+  }
+
+  private removeTerminalWaiter(taskID: string, waiter: TerminalWaiter): void {
+    const waiters = this.terminalWaiters.get(taskID)
+    if (!waiters) return
+    const idx = waiters.indexOf(waiter)
+    if (idx < 0) return
+    waiters.splice(idx, 1)
+    if (waiters.length === 0) {
+      this.terminalWaiters.delete(taskID)
+    }
+  }
+
+  private resolveTerminalWaiters(taskID: string): void {
+    const waiters = this.terminalWaiters.get(taskID)
+    if (!waiters) return
+    this.terminalWaiters.delete(taskID)
+    const job = this.jobs.get(taskID)
+    for (const waiter of waiters) {
+      clearTimeout(waiter.timer)
+      if (job) {
+        waiter.resolve(job)
+      } else {
+        waiter.reject(new Error(`Job ${taskID} was removed before reaching a terminal state`))
+      }
+    }
+  }
+
   // ─── Prompt Integration ──────────────────────────────────────────────
 
   /**
@@ -471,7 +536,7 @@ export class BackgroundJobBoard {
     const jobs = this.list(parentSessionID)
     if (jobs.length === 0) return undefined
 
-    const lines = jobs.map(j => {
+    const lines = jobs.map((j) => {
       const status =
         j.state === 'completed'
           ? 'OK'
@@ -491,16 +556,25 @@ export class BackgroundJobBoard {
   // ─── Cleanup ─────────────────────────────────────────────────────────
 
   /**
-   * Remove jobs whose `updatedAt` is older than `ttlMs` milliseconds
-   * from the current time.
+   * Remove jobs whose `updatedAt` is older than `ttlMs` milliseconds.
+   *
+   * Only TERMINAL (completed/error/cancelled) and reconciled jobs are pruned —
+   * running jobs are never pruned. Each pruned job is also removed from the
+   * persistence adapter so it doesn't resurface after a restart.
    */
-  pruneExpired(ttlMs: number): void {
+  async pruneExpired(ttlMs: number): Promise<void> {
     const now = Date.now()
-    for (const [taskID, job] of this.jobs) {
-      if (now - job.updatedAt > ttlMs) {
-        this.jobs.delete(taskID)
+    const expired: BackgroundJobRecord[] = []
+    for (const job of this.jobs.values()) {
+      const isDone = TERMINAL_STATES.has(job.state) || job.state === 'reconciled'
+      if (isDone && now - job.updatedAt > ttlMs) {
+        expired.push(job)
       }
     }
+    for (const job of expired) {
+      this.jobs.delete(job.taskID)
+      await this.deletePersisted(job.taskID)
+    }
   }
 
   /** Remove all jobs belonging to a parent session. */
@@ -519,10 +593,16 @@ export class BackgroundJobBoard {
     try {
       await this.persistence.saveJob(record)
     } catch (err) {
-      console.error(
-        `[BackgroundJobBoard] Failed to persist job ${record.taskID}:`,
-        err,
-      )
+      log.error(`[BackgroundJobBoard] Failed to persist job ${record.taskID}:`, err)
+    }
+  }
+
+  private async deletePersisted(taskID: string): Promise<void> {
+    if (!this.persistence) return
+    try {
+      await this.persistence.deleteJob(taskID)
+    } catch (err) {
+      log.error(`[BackgroundJobBoard] Failed to delete persisted job ${taskID}:`, err)
     }
   }
 
@@ -531,12 +611,10 @@ export class BackgroundJobBoard {
       try {
         listener(taskID)
       } catch (err) {
-        console.error(
-          `[BackgroundJobBoard] Terminal listener error for ${taskID}:`,
-          err,
-        )
+        log.error(`[BackgroundJobBoard] Terminal listener error for ${taskID}:`, err)
       }
     }
+    this.resolveTerminalWaiters(taskID)
   }
 
   private async writeSignal(record: BackgroundJobRecord): Promise<void> {
@@ -559,10 +637,7 @@ export class BackgroundJobBoard {
       await writeFile(tmpPath, content, 'utf-8')
       await rename(tmpPath, signalPath)
     } catch (err) {
-      console.error(
-        `[BackgroundJobBoard] Failed to write signal for ${record.alias}:`,
-        err,
-      )
+      log.error(`[BackgroundJobBoard] Failed to write signal for ${record.alias}:`, err)
     }
   }
 }

package/src/pantheon/chat-reminders.ts

@@ -0,0 +1,79 @@
+/**
+ * Chat Reminders (release-134 Phase 4) — the SHARED <system-reminder> buffer.
+ *
+ * WHY a shared module (not owned by pantheon-hooks.ts):
+ *   1. opencode's legacy plugin loader (verified in the 1.18.16 source,
+ *      packages/opencode/src/plugin/index.ts getLegacyPlugins) does
+ *      `Object.values(mod)` and treats EVERY export as a plugin factory —
+ *      a non-function export throws `TypeError("Plugin export is not a
+ *      function")` and a function export is invoked with a PluginInput.
+ *      pantheon-hooks.ts therefore cannot EXPORT the enqueue API.
+ *   2. src/plugin.ts (a separate plugin file) must ENQUEUE into the SAME
+ *      buffer the pantheon-hooks `chat.message` hook drains — a local copy
+ *      would enqueue into a buffer that is never delivered.
+ *   3. opencode loads plugins via plain `await import(entry)` (PluginLoader),
+ *      so both plugin files importing this module resolve to ONE module
+ *      instance (Bun/Node module cache) → one shared buffer.
+ *
+ * release-134 Phase 4 uses this buffer for the post-compaction state
+ * re-assertion: `reassertAfterCompaction` (compaction-assert.ts) enqueues a
+ * fresh-state block here, and the existing chat.message delivery path
+ * (pantheon-hooks.ts) injects it as a <system-reminder> into the session's
+ * next message. Zero new delivery code — the P0 messageID guard already
+ * protects subagent promptAsync fires.
+ *
+ * Bounded: at most CHAT_REMINDER_MAX entries, each expiring
+ * CHAT_REMINDER_TTL_MS after enqueue. Full-buffer enqueues are SKIPPED,
+ * never unbounded. No background timers — expiry is only checked on enqueue
+ * and on delivery (drainFreshChatReminders).
+ *
+ * @module chat-reminders
+ */
+
+/**
+ * Hard cap on queued reminder entries (anti-spam philosophy, matching the
+ * "throttled signals are skipped, never backlogged" rule).
+ */
+export const CHAT_REMINDER_MAX = 10
+
+/** How long a queued reminder stays deliverable (pruned after ~60s). */
+export const CHAT_REMINDER_TTL_MS = 60_000
+
+/** One queued reminder: the text plus its enqueue timestamp. */
+export interface ChatReminderEntry {
+  text: string
+  at: number
+}
+
+/** The shared buffer — module-level state, consumed by the chat.message hook. */
+export const pendingChatReminders: ChatReminderEntry[] = []
+
+/**
+ * Queue one chat-reminder entry, pruning expired entries first. Never throws.
+ * A full buffer skips the push (bounded, never backlogged).
+ */
+export function enqueueChatReminder(text: string): void {
+  const now = Date.now()
+  for (let i = pendingChatReminders.length - 1; i >= 0; i--) {
+    const r = pendingChatReminders[i]
+    if (r !== undefined && now - r.at > CHAT_REMINDER_TTL_MS) pendingChatReminders.splice(i, 1)
+  }
+  if (pendingChatReminders.length >= CHAT_REMINDER_MAX) return
+  pendingChatReminders.push({ text, at: now })
+}
+
+/**
+ * Deliver (drain) every FRESH reminder as one joined block: expired entries
+ * are dropped, the buffer is cleared in all cases (no leak). Returns
+ * undefined when nothing fresh remains — the caller skips injection.
+ *
+ * This is the delivery helper the pantheon-hooks `chat.message` hook calls
+ * AFTER its P0 messageID guard (empty messageID → early return, buffer kept).
+ */
+export function drainFreshChatReminders(): string | undefined {
+  const now = Date.now()
+  const fresh = pendingChatReminders.filter((r) => now - r.at <= CHAT_REMINDER_TTL_MS)
+  pendingChatReminders.length = 0
+  if (fresh.length === 0) return undefined
+  return fresh.map((r) => r.text).join('\n')
+}

package/src/pantheon/compaction-assert.ts

@@ -0,0 +1,160 @@
+/**
+ * Compaction Re-Assert (release-134 Phase 4) — re-inject fresh state after
+ * compaction.
+ *
+ * WHY: after a session is compacted, the system state may have changed since
+ * the summary was built (new background delegations launched, results
+ * delivered, goals updated). The compacted session's context is frozen at
+ * summary time — the model would operate on stale state.
+ *
+ * HOW: the `session.compacted` event hook calls `reassertAfterCompaction`,
+ * which builds a COMPACT fresh-state block (running + unread delegations from
+ * the board, active goals from the GoalStore — same gating as Phase 2) and
+ * enqueues it into the SHARED chat-reminder buffer (chat-reminders.ts). The
+ * existing pantheon-hooks `chat.message` hook delivers it as a
+ * <system-reminder> into the session's next message — zero new delivery
+ * code, and the P0 messageID guard already protects subagent fires.
+ *
+ * Deliberately NOT `session.promptAsync({noReply:true})`: the sprint 4+7
+ * spike refuted noReply as a push mechanism on this opencode build (nothing
+ * is delivered to the parent).
+ *
+ * FAIL-OPEN: every source (board list, goals list, enqueue) is wrapped —
+ * a failure logs a warn via the silence-by-default logger and the hook never
+ * throws. A session with NO fresh state (nothing running/unread/goals) is a
+ * SILENT skip (no warn, no reminder). The block is capped at
+ * REASSERT_MAX_LINES item lines (1 header) so it stays compact.
+ *
+ * Pure TypeScript — zero runtime deps beyond the board/goal types and the
+ * shared reminder buffer.
+ *
+ * @module compaction-assert
+ */
+import type { BackgroundJobBoard } from './background-job-board.ts'
+import { enqueueChatReminder } from './chat-reminders.ts'
+import type { CompactionGoalSource } from './delegation-compaction.ts'
+import { createPantheonLogger } from './logger.ts'
+
+// Silence-by-default TUI policy (pantheon-hooks L42-58): console echo is
+// opt-in via PANTHEON_HOOKS_LOG=1. `deps.logger` injection stays for tests.
+const log = createPantheonLogger({ module: 'pantheon-compaction' })
+
+// ─── Constants ─────────────────────────────────────────────────────────
+
+/** Max fresh-state item lines (running + unread + goals) in the block. */
+export const REASSERT_MAX_LINES = 10
+
+/** Header line — tells the model the summary may be stale. */
+export const REASSERT_HEADER = 'State re-assertion after compaction — the summary may be stale:'
+
+// ─── Types ─────────────────────────────────────────────────────────────
+
+/** Dependencies threaded to reassertAfterCompaction (wired from plugin.ts). */
+export interface CompactionAssertDeps {
+  /** The compacted session whose next message receives the reminder. */
+  sessionID: string
+  /** Board query surface — `list` is all the re-assertion needs. */
+  board: Pick<BackgroundJobBoard, 'list'>
+  /** Goal source for the goals block (optional — same gating as Phase 2). */
+  goals?: CompactionGoalSource
+  /** Injectable enqueue (testable). Defaults to the shared chat buffer. */
+  enqueue?: (text: string) => void
+  /** Injectable warn logger (testable). Defaults to silence-by-default. */
+  logger?: { warn: (message: string) => void }
+}
+
+// ─── Formatting ────────────────────────────────────────────────────────
+
+/** One-line terminal status label, mirroring formatForPrompt. */
+function terminalLabel(state: string): string {
+  switch (state) {
+    case 'completed':
+      return 'OK'
+    case 'error':
+      return 'ERR'
+    case 'cancelled':
+      return 'CAN'
+    default:
+      return state.toUpperCase()
+  }
+}
+
+/** Collapse whitespace and truncate a description/objective. */
+function truncate(text: string, max = 80): string {
+  const flat = text.trim().replace(/\s+/g, ' ')
+  return flat.length <= max ? flat : `${flat.slice(0, max)}…`
+}
+
+// ─── Build ─────────────────────────────────────────────────────────────
+
+/**
+ * Build the compact fresh-state lines: running delegations first (active work
+ * is the freshest signal), then unread terminal delegations, then active
+ * goals (only while the line budget allows). Returns undefined when there is
+ * nothing to assert (silent skip) or a source failed (warn + skip).
+ */
+async function buildStateLines(
+  deps: CompactionAssertDeps,
+  warn: (message: string) => void,
+): Promise<string[] | undefined> {
+  const lines: string[] = []
+  try {
+    const jobs = deps.board.list(deps.sessionID)
+    const running = jobs
+      .filter((j) => j.state === 'running')
+      .sort((a, b) => a.launchedAt - b.launchedAt)
+    const unread = jobs
+      .filter((j) => j.terminalUnreconciled)
+      .sort((a, b) => b.updatedAt - a.updatedAt)
+
+    for (const job of running) {
+      if (lines.length >= REASSERT_MAX_LINES) break
+      lines.push(`  running [${job.alias}] ${job.agent} — ${truncate(job.description)}`)
+    }
+    for (const job of unread) {
+      if (lines.length >= REASSERT_MAX_LINES) break
+      lines.push(
+        `  unread [${job.alias}] ${job.agent} — ${truncate(job.description)} — ${terminalLabel(job.state)}`,
+      )
+    }
+
+    const source = deps.goals
+    if (lines.length < REASSERT_MAX_LINES && source !== undefined && source.enabled) {
+      const goals = await source.list(deps.sessionID)
+      for (const goal of goals.filter((g) => g.status !== 'done')) {
+        if (lines.length >= REASSERT_MAX_LINES) break
+        lines.push(`  goal [${goal.id}] ${truncate(goal.objective)} — ${goal.status}`)
+      }
+    }
+  } catch (err: unknown) {
+    const reason = err instanceof Error ? err.message : String(err)
+    warn(`compaction re-assert failed for session ${deps.sessionID}: ${reason}`)
+    return undefined
+  }
+  return lines.length === 0 ? undefined : lines
+}
+
+/**
+ * Re-assert fresh state for a compacted session: build the compact block and
+ * enqueue it as a chat reminder (delivered on the session's next message).
+ *
+ * Returns true when a reminder was enqueued; false when there was nothing to
+ * assert (silent skip) or a source failed (warned). NEVER throws — the event
+ * hook must never break the session.
+ */
+export async function reassertAfterCompaction(deps: CompactionAssertDeps): Promise<boolean> {
+  // Silence-by-default logger: file-only warn, console echo opt-in via
+  // PANTHEON_HOOKS_LOG=1 (TUI pollution policy, pantheon-hooks L42-58).
+  const warn = deps.logger?.warn ?? ((message: string) => log.warn(message))
+  try {
+    const lines = await buildStateLines(deps, warn)
+    if (lines === undefined) return false
+    const enqueue = deps.enqueue ?? enqueueChatReminder
+    enqueue(`${REASSERT_HEADER}\n${lines.join('\n')}`)
+    return true
+  } catch (err: unknown) {
+    const reason = err instanceof Error ? err.message : String(err)
+    warn(`compaction re-assert failed for session ${deps.sessionID}: ${reason}`)
+    return false
+  }
+}