kibi-opencode 0.10.0 → 0.11.0

package/dist/prompt.js

@@ -280,7 +280,7 @@ ${buildBootstrapRequiredBody(capability)}`;
                     selectedBlock = `📝 **Code changes detected**
 
 Before implementing or explaining code:
-1. **Discover first** - Run kb_search to find related requirements, ADRs, tests, facts, and symbols.
+1. **Discover**: Run kb_search for REQ, ADR, TEST, FACT. Decompose broad queries (e.g., "Apple Sign-In").
 2. **Follow up exactly** - Run kb_query by sourceFile, id, type, or tags once you know what you need.
 3. **Prefer Kibi over comments** - Store durable knowledge in KB entities instead of inline comments.
 4. **Add traceability** - Production code: \`implements\` (symbol→req) for ownership. Test code: \`executable_for\`. \`covered_by\` is coverage evidence only for production symbols.
@@ -473,7 +473,7 @@ This ensures behavior is documented and traceable.`;
             return `📝 **Code changes detected**
 
 Before implementing or explaining code:
-1. **Discover first** - Run kb_search to find related requirements, ADRs, tests, facts, and symbols.
+1. **Discover**: Run kb_search for REQ, ADR, TEST, FACT. Decompose broad queries (e.g., "Apple Sign-In").
 2. **Follow up exactly** - Run kb_query by sourceFile, id, type, or tags once you know what you need.
 3. **Prefer Kibi over comments** - Store durable knowledge in KB entities instead of inline comments.
 4. **Add traceability** - Production code: \`implements\` (symbol→req) for ownership. Test code: \`executable_for\`. \`covered_by\` is coverage evidence only for production symbols.`;
@@ -496,7 +496,7 @@ Run kb_check after KB mutations.
 Dogfood note for this repo: OpenCode here uses local built \`kibi-mcp\` and \`kibi-opencode\` artifacts. If you change package versions or local package wiring, run \`bun run build\` before relying on OpenCode in this workspace.
 
 **Kibi-first workflow:**
-1. **Discover**: Run kb_search to find relevant requirements, ADRs, tests, facts, and symbols.
+1. **Discover**: Run kb_search for REQ, ADR, TEST, FACT. Decompose broad queries (e.g., "Apple Sign-In").
 2. **Confirm**: Run kb_query with sourceFile, id, type, or tags once you know the exact follow-up target.
 3. **Inspect freshness**: Run kb_status when branch or stale-state confidence matters.
 4. **Document intent**: If you are about to explain code, STOP. Route that explanation to kb_upsert instead of inline comments.

package/dist/scheduler.d.ts

@@ -9,10 +9,20 @@ export interface SyncRunMetadata {
     exitCode: number;
     checkExitCode?: number;
     checkRules?: string[];
+    /** Operational sync.failed observability only. */
+    syncCommand?: string;
+    syncStdout?: string;
+    syncStderr?: string;
+    syncErrorMessage?: string;
 }
-export type SyncRunner = (worktree: string) => Promise<{
+export type SyncRunnerResult = {
     exitCode: number;
-}>;
+    syncCommand?: string;
+    syncStdout?: string;
+    syncStderr?: string;
+    syncErrorMessage?: string;
+};
+export type SyncRunner = (worktree: string) => Promise<SyncRunnerResult>;
 export type CheckRunner = (worktree: string, rules: string[]) => Promise<{
     exitCode: number;
 }>;

package/dist/scheduler.js

@@ -128,9 +128,17 @@ class WorktreeSyncScheduler {
         let syncExitCode = 0;
         let checkExitCode;
         let checkRules;
+        let syncCommand;
+        let syncStdout;
+        let syncStderr;
+        let syncErrorMessage;
         try {
             const syncResult = await this.runSync(this.worktree);
             syncExitCode = syncResult.exitCode;
+            syncCommand = syncResult.syncCommand;
+            syncStdout = syncResult.syncStdout;
+            syncStderr = syncResult.syncStderr;
+            syncErrorMessage = syncResult.syncErrorMessage;
             // Run targeted checks if sync succeeded and rules specified
             if (syncExitCode === 0 &&
                 trigger.checkRules &&
@@ -149,11 +157,11 @@ class WorktreeSyncScheduler {
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
-            logger.error(`sync.failed ${message}`);
             syncExitCode = 1;
+            syncErrorMessage = message;
         }
         finally {
-            this.emitCompletion(trigger, startedAt, syncExitCode, checkExitCode, checkRules);
+            this.emitCompletion(trigger, startedAt, syncExitCode, checkExitCode, checkRules, truncateSyncOutput(syncStdout), truncateSyncOutput(syncStderr), syncErrorMessage, syncCommand);
             this.inFlight = false;
             if (this.dirty) {
                 const trailing = this.trailing ?? { reason: "sync.trailing" };
@@ -185,7 +193,7 @@ class WorktreeSyncScheduler {
             waiter();
         }
     }
-    emitCompletion(trigger, startedAt, exitCode, checkExitCode, checkRules) {
+    emitCompletion(trigger, startedAt, exitCode, checkExitCode, checkRules, syncStdout, syncStderr, syncErrorMessage, syncCommand) {
         const durationMs = Math.max(0, this.now() - startedAt);
         const normalizedReason = trigger.reason.endsWith(".trailing")
             ? trigger.reason.slice(0, -".trailing".length)
@@ -200,6 +208,10 @@ class WorktreeSyncScheduler {
             ...(trigger.filePath !== undefined ? { filePath: trigger.filePath } : {}),
             ...(checkExitCode !== undefined ? { checkExitCode } : {}),
             ...(checkRules !== undefined ? { checkRules } : {}),
+            ...(syncStdout !== undefined ? { syncStdout } : {}),
+            ...(syncStderr !== undefined ? { syncStderr } : {}),
+            ...(syncErrorMessage !== undefined ? { syncErrorMessage } : {}),
+            ...(syncCommand !== undefined ? { syncCommand } : {}),
         };
         if (exitCode === 0) {
             logger.info(`sync.succeeded ${JSON.stringify(meta)}`);
@@ -213,11 +225,42 @@ class WorktreeSyncScheduler {
         this.onRunComplete?.(meta);
     }
 }
+const TRUNCATE_LIMIT = 4000;
+const TRUNCATE_SUFFIX = "\n...[truncated]";
+function truncateSyncOutput(value) {
+    if (!value)
+        return undefined;
+    if (value.length > TRUNCATE_LIMIT) {
+        return value.slice(0, TRUNCATE_LIMIT) + TRUNCATE_SUFFIX;
+    }
+    return value;
+}
 async function runKibiSync(worktree) {
     return new Promise((resolve) => {
-        exec("kibi sync", { cwd: worktree }, (error) => {
-            resolve({ exitCode: error ? (error.code ?? 1) : 0 });
-        });
+        try {
+            exec("kibi sync", { cwd: worktree }, (error, stdout, stderr) => {
+                if (error) {
+                    const truncatedOut = truncateSyncOutput(stdout || undefined);
+                    const truncatedErr = truncateSyncOutput(stderr || undefined);
+                    const signal = error.signal ? ` (signal: ${error.signal})` : "";
+                    const errorMessage = error.message ? `${error.message}${signal}` : signal || undefined;
+                    resolve({
+                        exitCode: error.code ?? 1,
+                        syncCommand: "kibi sync",
+                        ...(truncatedOut !== undefined ? { syncStdout: truncatedOut } : {}),
+                        ...(truncatedErr !== undefined ? { syncStderr: truncatedErr } : {}),
+                        ...(errorMessage ? { syncErrorMessage: errorMessage } : {}),
+                    });
+                }
+                else {
+                    resolve({ exitCode: 0, syncCommand: "kibi sync" });
+                }
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            resolve({ exitCode: 1, syncCommand: "kibi sync", syncErrorMessage: message });
+        }
     });
 }
 async function runKibiCheck(worktree, rules) {

package/dist/toast.d.ts

@@ -24,6 +24,8 @@ export type ToastCapableClient = {
         showToast?: (payload: {
             body: ToastPayload;
         }) => void | Promise<void>;
+        /** SDK command bridge - invoke TUI command */
+        executeCommand?: (command: string, args?: object) => void | Promise<void>;
         clearPrompt?: () => void | Promise<void>;
         submitPrompt?: () => void | Promise<void>;
     };

package/dist/tui-brief-delivery.d.ts

@@ -1,3 +1,4 @@
+import type { ToastCapableClient as SendToastCapableClient } from "./toast.js";
 import type { IdleBriefEnvelope } from "./idle-brief-store.js";
 export type ToastPayload = {
     variant?: "info" | "success" | "warning" | "error";
@@ -45,3 +46,22 @@ export type DeliverResult = {
  * @param localConfig - Local OpenCode config
  */
 export declare function deliverBriefTui(client: ToastCapableClient, envelope: IdleBriefEnvelope, sharedPolicy: SharedBriefPolicy, _localConfig: LocalBriefConfig): Promise<DeliverResult>;
+/**
+ * Client type for announcement-only TUI delivery.
+ * Extends toast capability with the SDK command bridge.
+ */
+export type AnnouncementClient = SendToastCapableClient;
+export type AnnouncementResult = {
+    toastDelivered: boolean;
+    commandPublished: boolean;
+};
+/**
+ * Announcement-only TUI delivery coordinator.
+ *
+ * Sends the summary toast and invokes the official SDK bridge
+ * (`executeCommand`) but does NOT mutate read/seen state.
+ * The caller is responsible for any state transitions after the
+ * TUI route confirms render success.
+ */
+export declare function announceBriefTui(// implements REQ-opencode-kibi-briefing-v6
+client: AnnouncementClient, envelope: IdleBriefEnvelope, sharedPolicy: SharedBriefPolicy): Promise<AnnouncementResult>;

package/dist/tui-brief-delivery.js

@@ -7,6 +7,8 @@
  * the Free Software Foundation, either version 3 of the License, or
  * (at your option) any later version.
  */
+import { sendToast } from "./toast.js";
+import { renderToastSummary } from "./brief-delivery-reasons.js";
 import * as logger from "./logger.js";
 function firstNonEmpty(...values) {
     for (const value of values) {
@@ -15,16 +17,20 @@ function firstNonEmpty(...values) {
             return trimmed;
         }
     }
-    return "Knowledge updates were recorded in this brief.";
-}
-function defaultWhyItMatters() {
-    return "This update changes how the project knowledge should be interpreted and applied.";
+    return undefined;
 }
 function buildTuiBriefMessage(envelope) {
     const lines = [];
-    const whatChanged = envelope.schemaVersion === "2.0"
-        ? envelope.briefing.changeNarrative.map((line) => line.trim()).filter(Boolean)
-        : [];
+    const briefing = envelope.briefing;
+    const deliveryReasons = briefing.deliveryReasons;
+    const renderedToast = deliveryReasons?.items?.length
+        ? renderToastSummary(deliveryReasons)
+        : undefined;
+    const whatChanged = renderedToast
+        ? [renderedToast.summary]
+        : envelope.schemaVersion === "2.0"
+            ? envelope.briefing.changeNarrative.map((line) => line.trim()).filter(Boolean).filter((line) => !line.includes(".sisyphus/"))
+            : [];
     lines.push("## What changed");
     if (whatChanged.length > 0) {
         lines.push(...whatChanged.slice(0, 2));
@@ -36,16 +42,23 @@ function buildTuiBriefMessage(envelope) {
             lines.push(`${action} ${fallbackEntity.id}: ${fallbackEntity.title ?? "Untitled"}`);
         }
         else {
-            lines.push(firstNonEmpty(envelope.summary, envelope.briefing.tldr));
+            const fallback = firstNonEmpty(envelope.summary, envelope.briefing.tldr);
+            if (fallback)
+                lines.push(fallback);
         }
     }
     else {
-        lines.push(firstNonEmpty(envelope.summary, envelope.briefing.tldr));
+        const fallback = firstNonEmpty(envelope.summary, envelope.briefing.tldr);
+        if (fallback)
+            lines.push(fallback);
     }
     lines.push("");
-    lines.push("## Why it matters");
-    lines.push(firstNonEmpty(envelope.briefing.promptBlock, defaultWhyItMatters()));
-    lines.push("");
+    const whyItMatters = firstNonEmpty(deliveryReasons?.items?.length ? renderedToast?.whyItMatters : undefined);
+    if (whyItMatters) {
+        lines.push("## Why it matters");
+        lines.push(whyItMatters);
+        lines.push("");
+    }
     const hasKnowledgeImpact = envelope.briefing.citations.length > 0 ||
         (envelope.briefing.constraints?.length ?? 0) > 0 ||
         (envelope.briefing.regressionRisks?.length ?? 0) > 0;
@@ -85,7 +98,65 @@ function buildTuiBriefMessage(envelope) {
     while (lines.length > 0 && lines[lines.length - 1] === "") {
         lines.pop();
     }
-    return lines.join("\n");
+    const result = lines.join("\n");
+    if (result === "## What changed") {
+        return undefined;
+    }
+    return result;
+}
+function buildTuiBriefToastPayload(envelope) {
+    const message = buildTuiBriefMessage(envelope);
+    if (message === undefined) {
+        return undefined;
+    }
+    return {
+        variant: envelope.type === "warning" ? "warning" : "info",
+        title: "Kibi Knowledge Update",
+        message,
+        duration: 8000,
+    };
+}
+function hasSignificantBriefingImpact(envelope) {
+    const briefing = envelope.briefing;
+    return !(briefing.citations.length === 0 &&
+        (!briefing.constraints || briefing.constraints.length === 0) &&
+        (!briefing.regressionRisks || briefing.regressionRisks.length === 0) &&
+        (!briefing.missingEvidence || briefing.missingEvidence.length === 0));
+}
+function isNoOpBriefEnvelope(envelope) {
+    const counts = envelope.counts;
+    const zeroCounts = "relationshipsChanged" in counts
+        ? counts.entitiesAdded === 0 &&
+            counts.entitiesModified === 0 &&
+            counts.entitiesRemoved === 0 &&
+            counts.relationshipsChanged === 0
+        : counts.requirementsAdded === 0 &&
+            counts.relationshipsAdded === 0 &&
+            counts.entitiesDeleted === 0;
+    const briefing = envelope.briefing;
+    const hasDeliveryReasons = (briefing.deliveryReasons?.items.length ?? 0) > 0;
+    if (hasDeliveryReasons) {
+        const toast = briefing.deliveryReasons ? renderToastSummary(briefing.deliveryReasons) : undefined;
+        if (toast === undefined)
+            return true; // all operational → no-op
+        return false;
+    }
+    // Suppress legacy (no deliveryReasons) envelopes only when all three conditions hold:
+    // zero change counts, no validation issues, and no significant briefing impact.
+    // Matching summary/tldr alone is not sufficient — a domain-specific brief may legitimately
+    // have the same value in both fields.
+    return (zeroCounts &&
+        envelope.validation.count === 0 &&
+        !hasSignificantBriefingImpact(envelope));
+}
+function getEnvelopeChangeTotal(envelope) {
+    const counts = envelope.counts;
+    return "relationshipsChanged" in counts
+        ? counts.entitiesAdded +
+            counts.entitiesModified +
+            counts.entitiesRemoved +
+            counts.relationshipsChanged
+        : counts.requirementsAdded + counts.relationshipsAdded + counts.entitiesDeleted;
 }
 /**
  * Delivers a Kibi briefing to the TUI via toast notification.
@@ -111,8 +182,14 @@ export async function deliverBriefTui(client, envelope, sharedPolicy, _localConf
     const tui = client.tui;
     // Toast is the primary delivery mechanism
     if (sharedPolicy.briefs.tui.toast && typeof tui?.showToast === "function") {
+        if (isNoOpBriefEnvelope(envelope)) {
+            return { delivered: false };
+        }
         try {
             const message = buildTuiBriefMessage(envelope);
+            if (message === undefined) {
+                return { delivered: false };
+            }
             await tui.showToast({
                 body: {
                     variant: envelope.type === "warning" ? "warning" : "info",
@@ -136,3 +213,67 @@ export async function deliverBriefTui(client, envelope, sharedPolicy, _localConf
         return { delivered: false };
     }
 }
+/**
+ * Announcement-only TUI delivery coordinator.
+ *
+ * Sends the summary toast and invokes the official SDK bridge
+ * (`executeCommand`) but does NOT mutate read/seen state.
+ * The caller is responsible for any state transitions after the
+ * TUI route confirms render success.
+ */
+export async function announceBriefTui(// implements REQ-opencode-kibi-briefing-v6
+client, envelope, sharedPolicy) {
+    if (!sharedPolicy.briefs.channels.tui) {
+        logger.info("TUI brief delivery disabled by shared policy");
+        return { toastDelivered: false, commandPublished: false };
+    }
+    const briefing = envelope.briefing;
+    if (!envelope.unread &&
+        isNoOpBriefEnvelope(envelope) &&
+        !(briefing.deliveryReasons?.items.length ?? 0)) {
+        return { toastDelivered: false, commandPublished: false };
+    }
+    const totalChanges = getEnvelopeChangeTotal(envelope);
+    const hasDeliveryReasons = (briefing.deliveryReasons?.items.length ?? 0) > 0;
+    if (!envelope.unread &&
+        totalChanges === 0 &&
+        envelope.validation.count === 0 &&
+        !hasDeliveryReasons &&
+        isNoOpBriefEnvelope(envelope)) {
+        return { toastDelivered: false, commandPublished: false };
+    }
+    let toastDelivered = false;
+    let commandPublished = false;
+    if (sharedPolicy.briefs.tui.toast) {
+        const payload = buildTuiBriefToastPayload(envelope);
+        if (payload !== undefined) {
+            const toastResult = await sendToast(client, payload);
+            if (toastResult.status === "delivered") {
+                toastDelivered = true;
+            }
+            else if (toastResult.status === "failed") {
+                logger.error("Failed to deliver brief toast", {
+                    event: "idle_brief_toast_failed",
+                    error: toastResult.error ?? toastResult.reason,
+                });
+            }
+            else {
+                logger.info("TUI showToast API unavailable, brief not delivered");
+            }
+        }
+    }
+    // Step 2: Invoke the SDK command bridge to open the brief in the TUI
+    if (typeof client.tui?.executeCommand === "function") {
+        try {
+            await client.tui.executeCommand("kibi.open_latest_brief", {});
+            commandPublished = true;
+        }
+        catch (err) {
+            logger.error("Failed to publish open_latest_brief command", {
+                event: "idle_brief_command_failed",
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return { toastDelivered, commandPublished };
+}

package/dist/tui-brief-view-model.d.ts

@@ -0,0 +1,63 @@
+import type { IdleBriefCitation, IdleBriefEnvelope, IdleBriefStatement } from "./idle-brief-store.js";
+export interface TuiBriefViewModel {
+    briefId: string;
+    schemaVersion: "1.0" | "2.0";
+    branch: string;
+    createdAt: string;
+    type: "success" | "warning";
+    unread: boolean;
+    contentHash: string;
+    /** Short human-readable title derived from the envelope */
+    title: string;
+    /** "What changed" section content */
+    whatChanged: string[];
+    /** "Why it matters" section content */
+    whyItMatters: string | undefined;
+    /** Project knowledge impact section (citations, constraints, risks) */
+    knowledgeImpact: {
+        citations: IdleBriefCitation[];
+        constraints: IdleBriefStatement[];
+        regressionRisks: IdleBriefStatement[];
+    };
+    /** Interpretation note section (validation + missing evidence) */
+    interpretationNote: {
+        validationCount: number;
+        missingEvidence: IdleBriefStatement[];
+    };
+    /** Summary counts (schema-aware) */
+    counts: {
+        schemaVersion: "1.0";
+        requirementsAdded: number;
+        relationshipsAdded: number;
+        entitiesDeleted: number;
+    } | {
+        schemaVersion: "2.0";
+        entitiesAdded: number;
+        entitiesModified: number;
+        entitiesRemoved: number;
+        relationshipsChanged: number;
+    };
+}
+/**
+ * Build a structured view model from a persisted brief envelope.
+ *
+ * Derives all route-rendering data (title, sections, citations, counts) from
+ * the envelope without regenerating any content. Supports both schema 1.0 and
+ * 2.0 during the migration window.
+ *
+ * @param envelope - The persisted brief envelope
+ * @returns A deterministic view model suitable for route rendering
+ */
+export declare function buildTuiBriefViewModel(// implements REQ-opencode-kibi-briefing-v6
+envelope: IdleBriefEnvelope): TuiBriefViewModel;
+/**
+ * Build a short summary text from a persisted brief envelope.
+ *
+ * Reuses the same section-building logic as `buildTuiBriefMessage` from
+ * `tui-brief-delivery.ts`, producing a deterministic plain-text summary
+ * suitable for TUI route rendering or server-side summary generation.
+ *
+ * @param envelope - The persisted brief envelope
+ * @returns A multi-line summary string
+ */
+export declare function buildTuiBriefSummary(envelope: IdleBriefEnvelope): string;

package/dist/tui-brief-view-model.js

@@ -0,0 +1,209 @@
+/*
+ * Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ * Copyright (C) 2026 Piotr Franczyk
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ */
+import { renderFullBriefReasons, renderToastSummary } from "./brief-delivery-reasons.js";
+// ─── Helpers ───────────────────────────────────────────────────────────────
+function firstNonEmpty(...values) {
+    for (const value of values) {
+        const trimmed = value?.trim();
+        if (trimmed) {
+            return trimmed;
+        }
+    }
+    return undefined;
+}
+function isOperationalByEntityIds(item) {
+    if (item.entityIds.length === 0)
+        return false;
+    return item.entityIds.every((id) => {
+        const dashIdx = id.indexOf("-");
+        if (dashIdx < 0)
+            return false;
+        return /\.[a-zA-Z0-9]+$/.test(id.slice(dashIdx + 1));
+    });
+}
+function isOperationalDeliveryItem(item, allItems) {
+    if (item.kind === "relationship_changed") {
+        // relationship_changed items have no entityIds; treat as operational when
+        // all entity-level items in the set are operational (they're relationship side-effects)
+        const entityItems = allItems.filter((i) => i.kind === "entity_added" || i.kind === "entity_modified" || i.kind === "entity_removed");
+        return entityItems.length > 0 && entityItems.every(isOperationalByEntityIds);
+    }
+    return isOperationalByEntityIds(item);
+}
+function deriveWhatChanged(envelope) {
+    const briefing = envelope.briefing;
+    const deliveryReasons = briefing.deliveryReasons;
+    if (deliveryReasons?.items?.length) {
+        const domainItems = deliveryReasons.items.filter((item) => !isOperationalDeliveryItem(item, deliveryReasons.items));
+        if (domainItems.length > 0) {
+            return domainItems.map((item) => item.text);
+        }
+    }
+    if (envelope.schemaVersion === "2.0") {
+        const narrative = envelope.briefing.changeNarrative
+            .map((line) => line.trim())
+            .filter(Boolean)
+            .filter((line) => !line.includes(".sisyphus/"));
+        if (narrative.length > 0) {
+            return narrative.slice(0, 2);
+        }
+        const fallbackEntity = envelope.changes.entities.modified[0] ??
+            envelope.changes.entities.added[0];
+        if (fallbackEntity) {
+            const action = envelope.changes.entities.modified[0] ? "Modified" : "Added";
+            return [
+                `${action} ${fallbackEntity.id}: ${fallbackEntity.title ?? "Untitled"}`,
+            ];
+        }
+    }
+    const fallback = firstNonEmpty(envelope.summary, envelope.briefing.tldr);
+    return fallback ? [fallback] : [];
+}
+// ─── Public API ────────────────────────────────────────────────────────────
+/**
+ * Build a structured view model from a persisted brief envelope.
+ *
+ * Derives all route-rendering data (title, sections, citations, counts) from
+ * the envelope without regenerating any content. Supports both schema 1.0 and
+ * 2.0 during the migration window.
+ *
+ * @param envelope - The persisted brief envelope
+ * @returns A deterministic view model suitable for route rendering
+ */
+export function buildTuiBriefViewModel(// implements REQ-opencode-kibi-briefing-v6
+envelope) {
+    const briefing = envelope.briefing;
+    const deliveryReasons = briefing.deliveryReasons;
+    let title = firstNonEmpty(envelope.summary, envelope.briefing.tldr);
+    if (deliveryReasons?.items?.length) {
+        const filteredToast = renderToastSummary(deliveryReasons);
+        if (filteredToast) {
+            title = filteredToast.summary;
+        }
+    }
+    else if (envelope.schemaVersion === "2.0" && envelope.briefing.changeNarrative.length > 0) {
+        title = envelope.briefing.changeNarrative[0]?.trim() ?? title;
+    }
+    const base = {
+        briefId: envelope.briefId,
+        schemaVersion: envelope.schemaVersion,
+        branch: envelope.branch,
+        createdAt: envelope.createdAt,
+        type: envelope.type,
+        unread: envelope.unread,
+        contentHash: envelope.contentHash,
+        title: title ?? "Kibi Brief",
+        whatChanged: deriveWhatChanged(envelope),
+        whyItMatters: deliveryReasons?.items?.length
+            ? renderToastSummary(deliveryReasons)?.whyItMatters || undefined
+            : undefined,
+        knowledgeImpact: {
+            citations: envelope.briefing.citations,
+            constraints: envelope.briefing.constraints ?? [],
+            regressionRisks: envelope.briefing.regressionRisks ?? [],
+        },
+        interpretationNote: {
+            validationCount: envelope.validation.count,
+            missingEvidence: envelope.briefing.missingEvidence ?? [],
+        },
+    };
+    if (envelope.schemaVersion === "2.0") {
+        return {
+            ...base,
+            counts: {
+                schemaVersion: "2.0",
+                entitiesAdded: envelope.counts.entitiesAdded,
+                entitiesModified: envelope.counts.entitiesModified,
+                entitiesRemoved: envelope.counts.entitiesRemoved,
+                relationshipsChanged: envelope.counts.relationshipsChanged,
+            },
+        };
+    }
+    return {
+        ...base,
+        counts: {
+            schemaVersion: "1.0",
+            requirementsAdded: envelope.counts.requirementsAdded,
+            relationshipsAdded: envelope.counts.relationshipsAdded,
+            entitiesDeleted: envelope.counts.entitiesDeleted,
+        },
+    };
+}
+/**
+ * Build a short summary text from a persisted brief envelope.
+ *
+ * Reuses the same section-building logic as `buildTuiBriefMessage` from
+ * `tui-brief-delivery.ts`, producing a deterministic plain-text summary
+ * suitable for TUI route rendering or server-side summary generation.
+ *
+ * @param envelope - The persisted brief envelope
+ * @returns A multi-line summary string
+ */
+export function buildTuiBriefSummary(envelope) {
+    const briefing = envelope.briefing;
+    const deliveryReasons = briefing.deliveryReasons;
+    if (deliveryReasons?.items?.length) {
+        return renderFullBriefReasons(deliveryReasons);
+    }
+    const lines = [];
+    // What changed
+    lines.push("## What changed");
+    lines.push(...deriveWhatChanged(envelope));
+    lines.push("");
+    // Why it matters
+    if (deliveryReasons?.items?.length) {
+        lines.push("## Why it matters");
+        lines.push(deliveryReasons.toast.whyItMatters || "");
+        lines.push("");
+    }
+    // Project knowledge impact
+    const hasKnowledgeImpact = envelope.briefing.citations.length > 0 ||
+        (envelope.briefing.constraints?.length ?? 0) > 0 ||
+        (envelope.briefing.regressionRisks?.length ?? 0) > 0;
+    if (hasKnowledgeImpact) {
+        lines.push("## Project knowledge impact");
+        if (envelope.briefing.citations.length > 0) {
+            for (const citation of envelope.briefing.citations) {
+                lines.push(`- **${citation.id}**${citation.title ? `: ${citation.title}` : ""}${citation.source ? ` (${citation.source})` : ""}`);
+            }
+        }
+        if ((envelope.briefing.constraints?.length ?? 0) > 0) {
+            for (const constraint of envelope.briefing.constraints ?? []) {
+                lines.push(`- ${constraint.statement}`);
+            }
+        }
+        if ((envelope.briefing.regressionRisks?.length ?? 0) > 0) {
+            for (const risk of envelope.briefing.regressionRisks ?? []) {
+                lines.push(`- ${risk.statement}`);
+            }
+        }
+        lines.push("");
+    }
+    // Interpretation note
+    const hasMissingEvidence = (envelope.briefing.missingEvidence?.length ?? 0) > 0;
+    if (envelope.validation.count > 0 || hasMissingEvidence) {
+        lines.push("## Interpretation note");
+        if (envelope.validation.count > 0) {
+            lines.push(`Validation checks reported unresolved items: ${envelope.validation.count} issue(s).`);
+        }
+        if (hasMissingEvidence) {
+            lines.push("This brief includes unresolved evidence notes:");
+            for (const item of envelope.briefing.missingEvidence ?? []) {
+                lines.push(`- ${item.statement}`);
+            }
+        }
+        lines.push("");
+    }
+    // Trim trailing blank lines
+    while (lines.length > 0 && lines[lines.length - 1] === "") {
+        lines.pop();
+    }
+    return lines.join("\n");
+}