kibi-opencode 0.8.0 → 0.10.0

package/dist/e2e-coverage-signals.js

@@ -0,0 +1,186 @@
+// implements REQ-opencode-file-context-guidance-v1
+import { existsSync, readFileSync } from "node:fs";
+import * as path from "node:path";
+import { getFileLinkedTargetsByType } from "./file-entity-links.js";
+// ── TEST doc reader ──────────────────────────────────────────────
+//
+// Reads a TEST-*.md file from documentation/tests/ and extracts
+// frontmatter tags, source, and body.
+function readTestDoc(worktree, testId) {
+    // Try common locations for TEST docs
+    const candidates = [
+        `documentation/tests/${testId}.md`,
+        `documentation/tests/${testId.toLowerCase()}.md`,
+    ];
+    for (const rel of candidates) {
+        const fullPath = path.join(worktree, rel);
+        if (existsSync(fullPath)) {
+            try {
+                const content = readFileSync(fullPath, "utf8");
+                return parseTestDoc(content, testId);
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    return null;
+}
+function parseTestDoc(content, id) {
+    const result = { id, title: id };
+    // Extract frontmatter
+    const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!fmMatch || fmMatch[1] === undefined) {
+        result.body = content;
+        return result;
+    }
+    const frontmatter = fmMatch[1];
+    // Parse title
+    const titleMatch = frontmatter.match(/^title:\s*(.+)$/m);
+    if (titleMatch && titleMatch[1] !== undefined) {
+        result.title = titleMatch[1].trim();
+    }
+    // Parse status
+    const statusMatch = frontmatter.match(/^status:\s*(.+)$/m);
+    if (statusMatch && statusMatch[1] !== undefined) {
+        result.status = statusMatch[1].trim();
+    }
+    // Parse source
+    const sourceMatch = frontmatter.match(/^source:\s*(.+)$/m);
+    if (sourceMatch && sourceMatch[1] !== undefined) {
+        result.source = sourceMatch[1].trim();
+    }
+    // Parse tags
+    const tagsMatch = frontmatter.match(/^tags:\s*$/m);
+    if (tagsMatch) {
+        const afterTags = frontmatter.slice(frontmatter.indexOf("tags:") + "tags:".length);
+        const tagLines = afterTags.match(/^\s+-\s+(.+)$/gm);
+        if (tagLines) {
+            result.tags = tagLines.map((l) => l.replace(/^\s+-\s+/, "").trim());
+        }
+    }
+    // Extract body (after frontmatter)
+    const bodyMatch = content.match(/^---\n[\s\S]*?\n---\n([\s\S]*)$/);
+    if (bodyMatch && bodyMatch[1] !== undefined) {
+        result.body = bodyMatch[1];
+    }
+    return result;
+}
+// ── E2e detection predicates ─────────────────────────────────────
+const E2E_SOURCE_PREFIXES = [
+    "documentation/tests/e2e/",
+    "documentation/tests/e2e/packed/",
+];
+function isExactE2eEvidence(doc) {
+    // (a) has e2e tag
+    if (doc.tags?.includes("e2e"))
+        return true;
+    // (b) source points into e2e directories
+    if (doc.source) {
+        for (const prefix of E2E_SOURCE_PREFIXES) {
+            if (doc.source.startsWith(prefix))
+                return true;
+        }
+    }
+    return false;
+}
+function isPackageLevelUmbrellaDoc(testId) {
+    // Package-level umbrella docs like TEST-opencode-kibi-plugin-v1
+    // These are broad test manifests, not file-specific e2e evidence
+    return /^TEST-opencode-.*-plugin-v\d+$/.test(testId);
+}
+function docNamesPath(doc, queryRelPath, distRelPath, srcCorrespondingPath) {
+    const body = doc.body ?? "";
+    return (body.includes(queryRelPath) ||
+        (distRelPath !== null && body.includes(distRelPath)) ||
+        (srcCorrespondingPath !== null && body.includes(srcCorrespondingPath)));
+}
+// ── Main exported function ───────────────────────────────────────
+const EXACT_REMINDER = "- This file has existing e2e coverage. Check whether the e2e tests and linked TEST entities need updates.";
+const HEURISTIC_REMINDER = "- This file may have related e2e coverage. Check the linked e2e tests if this change affects behavior.";
+// implements REQ-opencode-file-context-guidance-v1
+export function getE2eCoverageSignal(worktree, filePath) {
+    // Compute relative paths for heuristic matching
+    const srcRelPath = path
+        .relative(worktree, filePath)
+        .split(path.sep)
+        .join("/");
+    // For dist/ files, compute the matching src/ path
+    let distRelPath = null;
+    let srcCorrespondingPath = null;
+    if (srcRelPath.startsWith("packages/opencode/dist/")) {
+        distRelPath = srcRelPath;
+        // Derive the src/ path: packages/opencode/dist/toast.js → packages/opencode/src/toast.ts
+        const distSuffix = srcRelPath.slice("packages/opencode/dist/".length);
+        const baseName = distSuffix.replace(/\.js$/, ".ts");
+        srcCorrespondingPath = `packages/opencode/src/${baseName}`;
+    }
+    // Step 1: Get linked TEST-* targets via symbols.yaml relationships
+    // Try the actual file path first, then also try the src/ corresponding path for dist/ files
+    let linkedTargets = getFileLinkedTargetsByType(worktree, filePath, [
+        "covered_by",
+        "executable_for",
+    ]);
+    if (linkedTargets.length === 0 && srcCorrespondingPath) {
+        const srcAbsPath = path.join(worktree, srcCorrespondingPath);
+        linkedTargets = getFileLinkedTargetsByType(worktree, srcAbsPath, [
+            "covered_by",
+            "executable_for",
+        ]);
+    }
+    // Track exact and heuristic evidence
+    const exactEvidence = [];
+    const heuristicEvidence = [];
+    for (const targetId of linkedTargets) {
+        if (!targetId.startsWith("TEST-"))
+            continue;
+        const doc = readTestDoc(worktree, targetId);
+        if (!doc)
+            continue;
+        const isUmbrella = isPackageLevelUmbrellaDoc(targetId);
+        const hasExactE2e = isExactE2eEvidence(doc);
+        const namesPath = docNamesPath(doc, srcRelPath, distRelPath, srcCorrespondingPath);
+        if (isUmbrella) {
+            // Package-level umbrella docs are demoted to heuristic at most
+            // and only if they explicitly name the path
+            if (namesPath) {
+                heuristicEvidence.push(`${targetId} (umbrella doc names path: ${srcRelPath})`);
+            }
+            // Never exact for umbrella docs
+            continue;
+        }
+        if (hasExactE2e) {
+            exactEvidence.push(targetId);
+        }
+        else if (namesPath) {
+            // Heuristic: non-e2e doc that explicitly names the source path
+            heuristicEvidence.push(`${targetId} (doc names path: ${srcRelPath})`);
+        }
+    }
+    // Step 2: Also check heuristic path rules when no exact evidence
+    if (exactEvidence.length === 0 && heuristicEvidence.length === 0) {
+        // Narrow heuristic: file under packages/opencode/src/ and a test doc body names it
+        // This is already covered by the linked targets loop above since we check docNamesPath
+        // No additional scanning needed - we only inspect linked docs
+    }
+    // Step 3: Resolve level
+    if (exactEvidence.length > 0) {
+        return {
+            level: "exact",
+            evidence: exactEvidence,
+            reminderText: EXACT_REMINDER,
+        };
+    }
+    if (heuristicEvidence.length > 0) {
+        return {
+            level: "heuristic",
+            evidence: heuristicEvidence,
+            reminderText: HEURISTIC_REMINDER,
+        };
+    }
+    return {
+        level: "none",
+        evidence: [],
+        reminderText: null,
+    };
+}

package/dist/file-entity-links.d.ts

@@ -0,0 +1,15 @@
+export type SymbolsManifestRow = {
+    id?: string;
+    sourceFile?: string;
+    links?: string[];
+    relationships?: Array<{
+        type: string;
+        target: string;
+    }>;
+};
+export declare function parseSymbolsYaml(content: string): SymbolsManifestRow[];
+export declare function getFileLinkedEntityIds(worktree: string, filePath: string): {
+    ids: string[];
+    source: "symbols" | "doc-path" | "none";
+};
+export declare function getFileLinkedTargetsByType(worktree: string, filePath: string, relationshipTypes: string[]): string[];

package/dist/file-entity-links.js

@@ -0,0 +1,254 @@
+// implements REQ-opencode-file-context-guidance-v1
+import { existsSync, readFileSync } from "node:fs";
+import * as path from "node:path";
+import { loadKbSyncPaths } from "./file-filter.js";
+// ── Lightweight YAML parser (symbols.yaml subset) ───────────────────
+//
+// Handles:
+//   symbols:
+//     - id: SYM-xxx
+//       sourceFile: path/to/file
+//       links:
+//         - REQ-xxx
+//       relationships:
+//         - type: implements
+//           target: REQ-xxx
+//
+// And bare array format (no wrapping `symbols:` key):
+//     - id: SYM-xxx
+//       ...
+// implements REQ-opencode-file-context-guidance-v1
+export function parseSymbolsYaml(content) {
+    const entries = [];
+    const lines = content.split("\n");
+    let current = null;
+    let section = "none";
+    let pendingRel = null;
+    function flushRel() {
+        if (pendingRel?.type && pendingRel.target && current?.relationships) {
+            current.relationships.push({
+                type: pendingRel.type,
+                target: pendingRel.target,
+            });
+        }
+        pendingRel = null;
+    }
+    function flushEntry() {
+        flushRel();
+        if (current?.id && current?.sourceFile) {
+            entries.push(current);
+        }
+        current = null;
+        section = "none";
+    }
+    for (const raw of lines) {
+        if (raw.trim().startsWith("#"))
+            continue;
+        // New entry: "  - id: ..."
+        const entryMatch = raw.match(/^\s+-\s+id:\s*(.+)$/);
+        if (entryMatch) {
+            flushEntry();
+            const entryId = entryMatch[1];
+            if (entryId === undefined)
+                continue;
+            current = { id: entryId.trim(), links: [], relationships: [] };
+            section = "none";
+            continue;
+        }
+        if (!current)
+            continue;
+        // sourceFile
+        const srcMatch = raw.match(/^\s+sourceFile:\s*(.+)$/);
+        if (srcMatch) {
+            const sourceFile = srcMatch[1];
+            if (sourceFile === undefined)
+                continue;
+            current.sourceFile = sourceFile.trim();
+            section = "none";
+            continue;
+        }
+        // links section header
+        if (/^\s+links:\s*$/.test(raw)) {
+            flushRel();
+            section = "links";
+            continue;
+        }
+        // relationships section header
+        if (/^\s+relationships:\s*$/.test(raw)) {
+            flushRel();
+            section = "relationships";
+            continue;
+        }
+        // Link item: "      - REQ-xxx"
+        if (section === "links") {
+            const linkMatch = raw.match(/^\s+-\s+(REQ-[A-Za-z0-9_-]+)\s*$/);
+            if (linkMatch) {
+                const linkId = linkMatch[1];
+                if (linkId !== undefined && current.links) {
+                    current.links.push(linkId);
+                }
+                continue;
+            }
+        }
+        // Relationship type: "      - type: implements"
+        if (section === "relationships") {
+            const relTypeMatch = raw.match(/^\s+-\s+type:\s*(.+)$/);
+            if (relTypeMatch) {
+                flushRel();
+                const relationType = relTypeMatch[1];
+                if (relationType === undefined)
+                    continue;
+                pendingRel = { type: relationType.trim() };
+                continue;
+            }
+            // Relationship target: "        target: REQ-..."
+            const relTargetMatch = raw.match(/^\s+target:\s*(.+)$/);
+            if (relTargetMatch && pendingRel) {
+                const target = relTargetMatch[1];
+                if (target === undefined)
+                    continue;
+                pendingRel.target = target.trim();
+                continue;
+            }
+        }
+    }
+    flushEntry();
+    return entries;
+}
+// ── Doc-path identity mapping ───────────────────────────────────────
+const DOC_ENTITY_PATTERN = /^(REQ|SCEN|TEST|ADR|FLAG|EVT|FACT)-[A-Za-z0-9_-]+\.md$/;
+// implements REQ-opencode-file-context-guidance-v1
+function resolveDocPathIdentity(relPath, syncPaths) {
+    const basename = path.posix.basename(relPath);
+    if (!DOC_ENTITY_PATTERN.test(basename))
+        return null;
+    const entityId = basename.replace(/\.md$/, "");
+    // Check if the file lives under one of the configured doc roots
+    const docRootKeys = [
+        "requirements",
+        "scenarios",
+        "tests",
+        "adr",
+        "flags",
+        "events",
+        "facts",
+    ];
+    // Normalize the relative path for matching
+    const normalizedRel = relPath.split(path.sep).join("/");
+    for (const key of docRootKeys) {
+        const pattern = syncPaths[key];
+        if (!pattern)
+            continue;
+        // Strip glob from pattern to get the root dir prefix
+        // e.g. "documentation/requirements/**/*.md" → "documentation/requirements"
+        const rootDir = pattern.replace(/\/\*\*\/.*$/, "").replace(/\/+$/, "");
+        if (normalizedRel.startsWith(rootDir + "/")) {
+            return entityId;
+        }
+    }
+    // If no specific root matched but path starts with documentation/,
+    // still accept (covers default configuration)
+    return null;
+}
+// ── Symbols file resolution ─────────────────────────────────────────
+function readSymbolsManifest(worktree, syncPaths) {
+    const symbolsPathRaw = syncPaths.symbols;
+    if (!symbolsPathRaw)
+        return [];
+    const symbolsPath = path.isAbsolute(symbolsPathRaw)
+        ? symbolsPathRaw
+        : path.join(worktree, symbolsPathRaw);
+    if (!existsSync(symbolsPath))
+        return [];
+    const content = readFileSync(symbolsPath, "utf8");
+    return parseSymbolsYaml(content);
+}
+function normalizeFilePath(worktree, filePath) {
+    // Normalize to forward-slash relative path from worktree
+    const absPath = path.isAbsolute(filePath)
+        ? filePath
+        : path.resolve(worktree, filePath);
+    return path
+        .relative(worktree, absPath)
+        .split(path.sep)
+        .join("/");
+}
+// ── Public API ──────────────────────────────────────────────────────
+// implements REQ-opencode-file-context-guidance-v1
+export function getFileLinkedEntityIds(worktree, filePath) {
+    try {
+        const syncPaths = loadKbSyncPaths(worktree);
+        const relPath = normalizeFilePath(worktree, filePath);
+        // Check doc-path identity first
+        const docId = resolveDocPathIdentity(relPath, syncPaths);
+        if (docId) {
+            return { ids: [docId], source: "doc-path" };
+        }
+        // Try symbols manifest
+        const symbols = readSymbolsManifest(worktree, syncPaths);
+        const matchedRows = symbols.filter((s) => s.sourceFile === relPath);
+        if (matchedRows.length === 0) {
+            return { ids: [], source: "none" };
+        }
+        const seen = new Set();
+        const orderedIds = [];
+        // Priority order: implements → covered_by → executable_for
+        const relPriority = ["implements", "covered_by", "executable_for"];
+        // First pass: collect relationships grouped by priority type, preserving file order within each type
+        for (const priorityType of relPriority) {
+            for (const row of matchedRows) {
+                for (const r of row.relationships ?? []) {
+                    if (r.type === priorityType) {
+                        const id = r.target;
+                        if (!seen.has(id)) {
+                            seen.add(id);
+                            orderedIds.push(id);
+                            if (orderedIds.length >= 3)
+                                return { ids: orderedIds.slice(0, 3), source: "symbols" };
+                        }
+                    }
+                }
+            }
+        }
+        // Second pass: fall back to static links, preserving file order
+        for (const row of matchedRows) {
+            for (const l of row.links ?? []) {
+                if (!seen.has(l)) {
+                    seen.add(l);
+                    orderedIds.push(l);
+                    if (orderedIds.length >= 3)
+                        return { ids: orderedIds.slice(0, 3), source: "symbols" };
+                }
+            }
+        }
+        return { ids: orderedIds.slice(0, 3), source: "symbols" };
+    }
+    catch {
+        return { ids: [], source: "none" };
+    }
+}
+// implements REQ-opencode-file-context-guidance-v1
+export function getFileLinkedTargetsByType(worktree, filePath, relationshipTypes) {
+    try {
+        const syncPaths = loadKbSyncPaths(worktree);
+        const relPath = normalizeFilePath(worktree, filePath);
+        const symbols = readSymbolsManifest(worktree, syncPaths);
+        const matchedRows = symbols.filter((s) => s.sourceFile === relPath);
+        if (matchedRows.length === 0)
+            return [];
+        const targets = [];
+        const seen = new Set();
+        for (const row of matchedRows) {
+            for (const r of row.relationships ?? []) {
+                if (relationshipTypes.includes(r.type) && !seen.has(r.target)) {
+                    seen.add(r.target);
+                    targets.push(r.target);
+                }
+            }
+        }
+        return targets;
+    }
+    catch {
+        return [];
+    }
+}

package/dist/file-operation-reminders.d.ts

@@ -0,0 +1,24 @@
+import type { RepoPosture } from "./repo-posture.js";
+import type { PathKind } from "./path-kind.js";
+import type { RiskClass } from "./risk-classifier.js";
+import type { ReminderKind } from "./file-operation-state.js";
+import type { E2eCoverageSignal } from "./e2e-coverage-signals.js";
+export interface LinkedEntityResult {
+    ids: string[];
+    source: "symbols" | "doc-path" | "none";
+}
+export interface DeriveFileOperationReminderParams {
+    normalizedPath: string;
+    lifecycle: "created" | "edited" | "deleted";
+    pathKind: PathKind;
+    linkedEntityResult: LinkedEntityResult;
+    e2eSignal: E2eCoverageSignal;
+    currentSemanticRisk: RiskClass;
+    posture: RepoPosture;
+}
+export interface DeriveFileOperationReminderResult {
+    lifecycleReminder: string | null;
+    e2eReminder: string | null;
+    reminderKindsToMark: ReminderKind[];
+}
+export declare function deriveFileOperationReminder(params: DeriveFileOperationReminderParams): DeriveFileOperationReminderResult;

package/dist/file-operation-reminders.js

@@ -0,0 +1,55 @@
+// ── Lifecycle reminder text ─────────────────────────────────────
+const NEW_FILE_REMINDER = "- New file detected. Add or update the necessary Kibi entities and traceability before completing this task.";
+const DELETED_WITH_IDS_REMINDER = (ids) => `- Deleted file had linked Kibi entities: ${ids}. Update Kibi to keep traceability accurate.`;
+const DELETED_NO_IDS_REMINDER = "- Deleted file had no linked Kibi entities. Update Kibi if this removal changes documented behavior or traceability.";
+// ── Main exported function ────────────────────────────────────
+// implements REQ-opencode-file-context-guidance-v1
+export function deriveFileOperationReminder(params) {
+    const { lifecycle, pathKind, linkedEntityResult, e2eSignal, posture, } = params;
+    // Check if posture allows lifecycle reminders
+    const isAuthoritativePosture = posture === "root_active" || posture === "hybrid_root_plus_vendored";
+    // Derive lifecycle reminder
+    let lifecycleReminder = null;
+    const reminderKindsToMark = [];
+    if (isAuthoritativePosture) {
+        if (lifecycle === "created") {
+            // Only emit create reminder for code files (not documentation, not KB docs)
+            if (pathKind === "code") {
+                lifecycleReminder = NEW_FILE_REMINDER;
+                reminderKindsToMark.push("kibi_write");
+            }
+        }
+        else if (lifecycle === "edited") {
+            // No generic lifecycle reminder for edited files
+            // Existing semantic risk guidance remains primary
+        }
+        else if (lifecycle === "deleted") {
+            const ids = linkedEntityResult.ids;
+            if (ids.length > 0) {
+                lifecycleReminder = DELETED_WITH_IDS_REMINDER(ids.join(", "));
+                reminderKindsToMark.push("kibi_delete");
+            }
+            else {
+                lifecycleReminder = DELETED_NO_IDS_REMINDER;
+                reminderKindsToMark.push("kibi_delete");
+            }
+        }
+    }
+    // Derive e2e reminder (only when e2e signal exists)
+    // E2e reminders are NOT posture-gated - they're always relevant
+    let e2eReminder = null;
+    if (e2eSignal.level !== "none" && e2eSignal.reminderText !== null) {
+        e2eReminder = e2eSignal.reminderText;
+        if (lifecycle === "deleted") {
+            reminderKindsToMark.push("e2e_delete");
+        }
+        else {
+            reminderKindsToMark.push("e2e_write");
+        }
+    }
+    return {
+        lifecycleReminder,
+        e2eReminder,
+        reminderKindsToMark,
+    };
+}

package/dist/file-operation-state.d.ts

@@ -0,0 +1,29 @@
+export type FileLifecycle = "created" | "edited" | "deleted";
+export type ReminderKind = "kibi_write" | "kibi_delete" | "e2e_write" | "e2e_delete";
+export interface PendingLifecycleEvent {
+    /** Normalized file path (relative to worktree root). */
+    normalizedPath: string;
+    /** Coalesced lifecycle event for this path. */
+    lifecycle: FileLifecycle;
+    /** Timestamp (ms) of the lifecycle event. */
+    timestamp: number;
+}
+export interface FileOperationState {
+    /** Normalize file path relative to worktree root. */
+    normalizePath(filePath: string): string;
+    /** Record a lifecycle event for a file, coalescing with existing events. */
+    recordLifecycle(filePath: string, lifecycle: FileLifecycle, timestamp?: number): void;
+    /** Peek at pending lifecycle event, preferring specified path if available. */
+    peekPending(preferredPath?: string): PendingLifecycleEvent | null;
+    /** Consume pending lifecycle event for a specific path. */
+    consumePending(filePath: string): void;
+    /** Check if a reminder has already been shown for a path/kind combo. */
+    hasShown(filePath: string, reminderKind: ReminderKind): boolean;
+    /** Mark a reminder as shown for a path/kind combo. */
+    markShown(filePath: string, reminderKind: ReminderKind): void;
+}
+export declare function createFileOperationState(opts: {
+    worktree: string;
+    /** Custom clock for testing. Defaults to Date.now. */
+    now?: () => number;
+}): FileOperationState;

package/dist/file-operation-state.js

@@ -0,0 +1,113 @@
+import * as path from "node:path";
+// ---------------------------------------------------------------------------
+// Factory function
+// ---------------------------------------------------------------------------
+export function createFileOperationState(opts) {
+    const worktree = opts.worktree;
+    const now = opts.now ?? Date.now;
+    // ---- Per-instance state (no module globals) ----
+    /**
+     * Pending lifecycle events keyed by normalized path.
+     * Each path has at most one coalesced lifecycle state.
+     */
+    const pendingLifecycleEvents = new Map();
+    /**
+     * Reminder suppression state: (normalized path + reminder kind) -> shown flag.
+     * Keeps path-aware, kind-aware suppression separate from GuidanceCache.
+     */
+    const reminderSuppression = new Map();
+    // ---- Internal helpers ----
+    /**
+     * Coalesce lifecycle events using precedence rules:
+     * - created + edited -> created
+     * - edited + edited -> edited
+     * - created|edited + deleted -> deleted
+     * - deleted + created|edited -> deleted
+     */
+    function coalesceLifecycle(existing, incoming) {
+        if (existing === undefined) {
+            return incoming;
+        }
+        // created + edited -> created
+        if (existing === "created" && incoming === "edited") {
+            return "created";
+        }
+        // edited + edited -> edited
+        if (existing === "edited" && incoming === "edited") {
+            return "edited";
+        }
+        // created|edited + deleted -> deleted
+        if ((existing === "created" || existing === "edited") && incoming === "deleted") {
+            return "deleted";
+        }
+        // deleted + created|edited -> deleted
+        if (existing === "deleted" && (incoming === "created" || incoming === "edited")) {
+            return "deleted";
+        }
+        // Fallback: use incoming
+        return incoming;
+    }
+    function normalizeSessionPath(filePath) {
+        if (path.isAbsolute(filePath)) {
+            const relativePath = path.relative(worktree, filePath);
+            // Keep absolute path if it escapes worktree
+            return relativePath.startsWith("..") ? filePath : relativePath;
+        }
+        // Normalize leading ./ and trailing slashes
+        const normalized = path.normalize(filePath);
+        return normalized.startsWith("./") ? normalized.slice(2) : normalized;
+    }
+    function getSuppressionKey(filePath, kind) {
+        const normalized = normalizeSessionPath(filePath);
+        return `${normalized}:${kind}`;
+    }
+    // ---- Public API ----
+    function normalizePath(filePath) {
+        return normalizeSessionPath(filePath);
+    }
+    function recordLifecycle(filePath, lifecycle, timestamp) {
+        const normalized = normalizeSessionPath(filePath);
+        const existing = pendingLifecycleEvents.get(normalized);
+        const coalesced = coalesceLifecycle(existing?.lifecycle, lifecycle);
+        pendingLifecycleEvents.set(normalized, {
+            normalizedPath: normalized,
+            lifecycle: coalesced,
+            timestamp: timestamp ?? now(),
+        });
+    }
+    function peekPending(preferredPath) {
+        if (preferredPath !== undefined) {
+            const normalized = normalizeSessionPath(preferredPath);
+            const preferred = pendingLifecycleEvents.get(normalized);
+            return preferred ?? null;
+        }
+        // No preferred path specified, return most recent pending event
+        let mostRecent = null;
+        for (const event of pendingLifecycleEvents.values()) {
+            if (mostRecent === null || event.timestamp > mostRecent.timestamp) {
+                mostRecent = event;
+            }
+        }
+        return mostRecent;
+    }
+    function consumePending(filePath) {
+        const normalized = normalizeSessionPath(filePath);
+        pendingLifecycleEvents.delete(normalized);
+    }
+    function hasShown(filePath, reminderKind) {
+        const key = getSuppressionKey(filePath, reminderKind);
+        return reminderSuppression.get(key) ?? false;
+    }
+    function markShown(filePath, reminderKind) {
+        const key = getSuppressionKey(filePath, reminderKind);
+        reminderSuppression.set(key, true);
+    }
+    return {
+        normalizePath,
+        recordLifecycle,
+        peekPending,
+        consumePending,
+        hasShown,
+        markShown,
+    };
+}