kibi-opencode 0.8.0 → 0.10.0

package/dist/prompt.js

@@ -1,10 +1,13 @@
 import * as path from "node:path";
 import { isPluginEnabled } from "./config.js";
+import { getInitKibiCommandCapability, } from "./init-kibi-capability.js";
 import { getSourceLinkedRequirementIds } from "./source-linked-guidance.js";
 const SENTINEL = "<!-- kibi-opencode -->";
 // ── Token budget enforcement ───────────────────────────────────────────
 const MAX_BULLETS = 5;
+const MAX_AUTO_BRIEF_BULLETS_WITH_REMINDER = 4;
 const MAX_WORDS = 117; // Reserve 3 words for sentinel so total injected prompt stays ≤ 120
+const AUTO_BRIEF_HEADER = "🧠 **Kibi briefing available**";
 const AUTHORITATIVE_POSTURES = [
     "root_active",
     "hybrid_root_plus_vendored",
@@ -15,14 +18,21 @@ function countWords(text) {
 function countBullets(lines) {
     return lines.filter((l) => l.startsWith("-")).length;
 }
-function enforceBudget(block) {
+const ENTITY_ID_RE = /\b(?:REQ|SYM|SCEN|TEST|ADR|FACT|FLAG|EVT)-[A-Za-z0-9_-]+\b/g;
+// implements REQ-opencode-file-context-guidance-v1
+function hasOverlappingEntityIds(textA, textB) {
+    const idsA = new Set(textA.match(ENTITY_ID_RE) ?? []);
+    const idsB = textB.match(ENTITY_ID_RE) ?? [];
+    return idsB.length > 0 && idsB.some((id) => idsA.has(id));
+}
+function enforceBudget(block, maxBullets = MAX_BULLETS) {
     const lines = block.split("\n");
-    if (countBullets(lines) > MAX_BULLETS || countWords(block) > MAX_WORDS) {
-        // Trim to budget: keep header + first MAX_BULLETS bullet lines
+    if (countBullets(lines) > maxBullets || countWords(block) > MAX_WORDS) {
+        // Trim to budget: keep header + first maxBullets bullet lines
         const header = [];
         const bullets = [];
         for (const line of lines) {
-            if (line.startsWith("-") && bullets.length < MAX_BULLETS) {
+            if (line.startsWith("-") && bullets.length < maxBullets) {
                 bullets.push(line);
             }
             else if (!line.startsWith("-")) {
@@ -45,6 +55,41 @@ function insertBulletAfterHeader(block, bullet) {
         return `${block}\n${bullet}`;
     return `${block.slice(0, headerEnd + 1)}${bullet}\n${block.slice(headerEnd + 1)}`;
 }
+// implements REQ-opencode-kibi-briefing-v2
+export function buildAutoBriefingGuidance(autoBriefResult, completionReminder) {
+    if (!autoBriefResult)
+        return null;
+    // Defensive: idle-brief results are persisted to .kb/briefs/, never injected into prompts.
+    // This function only handles auto-briefs from the file.edited risk-classification flow.
+    if (typeof autoBriefResult === "object" &&
+        autoBriefResult !== null &&
+        ("briefId" in autoBriefResult || "schemaVersion" in autoBriefResult)) {
+        return null;
+    }
+    if (autoBriefResult.state === "ready") {
+        const promptBlock = autoBriefResult.promptBlock.trim();
+        if (!promptBlock)
+            return null;
+        const maxBullets = completionReminder
+            ? MAX_AUTO_BRIEF_BULLETS_WITH_REMINDER
+            : MAX_BULLETS;
+        const briefingLines = promptBlock
+            .split("\n")
+            .map((line) => line.trim())
+            .filter((line) => line.startsWith("-"))
+            .slice(0, maxBullets);
+        if (briefingLines.length === 0)
+            return null;
+        return `${AUTO_BRIEF_HEADER}\n${briefingLines.join("\n")}`;
+    }
+    if (autoBriefResult.state === "tldr_fallback") {
+        const promptBlock = autoBriefResult.promptBlock.trim();
+        if (!promptBlock)
+            return null;
+        return `${AUTO_BRIEF_HEADER}\n${promptBlock}`;
+    }
+    return null;
+}
 function isAuthoritativePosture(posture) {
     return AUTHORITATIVE_POSTURES.includes(posture);
 }
@@ -52,6 +97,21 @@ function isAuthoritativePosture(posture) {
 function deriveFileBucket(pathKind) {
     return pathKind;
 }
+function getFocusEdit(context) {
+    return context.focusEdit ?? context.recentEdits[context.recentEdits.length - 1];
+}
+function buildInitKibiBootstrapReference(capability = getInitKibiCommandCapability()) {
+    if (capability.supported) {
+        return "Bootstrap existing repos: when the Kibi OpenCode plugin is active and native injection is supported, `/init-kibi` is the canonical short alias; `/kibi:init-kibi:mcp` remains the namespaced MCP fallback for the retroactive initialization (`kb_autopilot_generate`) workflow.";
+    }
+    return "Bootstrap existing repos: this host does not support native `/init-kibi` injection, so Kibi must fail closed and does not register a fake native alias; use `/kibi:init-kibi:mcp` for the retroactive initialization (`kb_autopilot_generate`) workflow.";
+}
+function buildBootstrapRequiredBody(capability = getInitKibiCommandCapability()) {
+    const commandBullet = capability.supported
+        ? "- When the Kibi OpenCode plugin is active and native injection is supported, use `/init-kibi` as the canonical short alias; `/kibi:init-kibi:mcp` remains the namespaced MCP fallback."
+        : "- This host does not support native `/init-kibi` injection. Kibi must fail closed and does not register a fake native alias; use `/kibi:init-kibi:mcp` instead.";
+    return `This repository does not appear to have Kibi initialized. Agents should:\n${commandBullet}\n- The workflow uses \`kb_autopilot_generate\` for read-only synthesis; always preview and get approval before writes.\n- Ask the user/operator to run setup or repair outside this session if bootstrap is insufficient.\n\nUse public MCP tools only: \`kb_autopilot_generate\`, \`kb_search\`, \`kb_query\`, \`kb_status\`, \`kb_find_gaps\`, \`kb_coverage\`, \`kb_graph\`, \`kb_upsert\`, \`kb_delete\`, \`kb_check\`.`;
+}
 // ── Guidance blocks by risk class ──────────────────────────────────────
 const GUIDANCE_BY_RISK = {
     safe_docs_only: null,
@@ -86,7 +146,7 @@ The Kibi knowledge base is managed through public MCP tools. Direct manual edits
 - Use kb_check to validate consistency`,
 };
 // ── Posture overrides ──────────────────────────────────────────────────
-export function postureGuidance(posture) {
+export function postureGuidance(posture, capability = getInitKibiCommandCapability()) {
     // implements REQ-opencode-prompt-injection
     switch (posture) {
         case "vendored_only":
@@ -95,12 +155,7 @@ export function postureGuidance(posture) {
         case "root_uninitialized":
             return `🔧 **Bootstrap required**
 
-This repository does not appear to have Kibi initialized. Agents should:
-- Start with \`kb_autopilot_generate\` to discover entities and bootstrap the KB (preferred workflow)
-- Use \`/init-kibi\` as the sanctioned slash command for initial repo setup
-- Ask the user/operator to run setup or repair outside this session if bootstrap is insufficient
-
-Do not run \`kibi\` CLI commands directly; use public MCP tools (kb_autopilot_generate, kb_search, kb_query, kb_status, kb_find_gaps, kb_coverage, kb_graph, kb_upsert, kb_delete, kb_check).`;
+${buildBootstrapRequiredBody(capability)}`;
         case "root_partial":
             return `⚠️  **Partial KB setup detected**
 
@@ -113,12 +168,19 @@ Root .kb/config.json exists but some configured KB targets are missing. Guidance
 /**
  * Build prompt guidance block based on posture, risk class, and cache state.
  */
-function buildContextualGuidance(context) {
+function buildContextualGuidance(context, capability = getInitKibiCommandCapability()) {
     const posture = context.posture ?? "root_active";
     const riskClass = context.riskClass;
+    const readyAutoBriefingAvailable = context.autoBriefResult?.showManualCue === false;
+    const suppressSourceLinkedBrief = context.autoBriefResult?.state === "ready" ||
+        context.autoBriefResult?.state === "tldr_fallback";
     const showDegraded = context.showDegradedAdvisory === true &&
         context.maintenanceDegraded === true &&
         context.degradedMode === "warn-once";
+    const fileOpReminder = context.fileOperationReminder;
+    const hasFileOpReminders = fileOpReminder !== undefined &&
+        (fileOpReminder.lifecycleReminder !== null ||
+            fileOpReminder.e2eReminder !== null);
     // ── Single-block priority selection ──
     // Priority order (highest wins): manual_kb_edit > posture > risk_class > safe/none
     let selectedBlock = null;
@@ -132,59 +194,71 @@ function buildContextualGuidance(context) {
     }
     // Priority 3: Posture warnings for non-active states — not cache-suppressed
     else if (posture === "root_uninitialized" || posture === "root_partial") {
-        const postureBlock = postureGuidance(posture);
+        const postureBlock = postureGuidance(posture, capability);
         if (postureBlock)
             selectedBlock = postureBlock;
     }
     else if (!context.posture && context.workspaceHealth?.needsBootstrap) {
         selectedBlock = `🔧 **Bootstrap required**
 
-This repository does not appear to have Kibi initialized. Agents should:
-- Start with \`kb_autopilot_generate\` to discover entities and bootstrap the KB (preferred workflow)
-- Use \`/init-kibi\` as the sanctioned slash command for initial repo setup
-- Ask the user/operator to run setup or repair outside this session if bootstrap is insufficient
-
-Do not run \`kibi\` CLI commands directly; use public MCP tools (kb_autopilot_generate, kb_search, kb_query, kb_status, kb_find_gaps, kb_coverage, kb_graph, kb_upsert, kb_delete, kb_check).`;
+${buildBootstrapRequiredBody(capability)}`;
         // Advisory guidance: check cache before selecting, since these blocks can be safely suppressed
     }
     else {
         // Cache check: skip repeated advisory guidance — only after critical signals are handled above
         // Allow degraded advisory to bypass cache so it is always visible
+        // File-operation reminders also bypass cache (per-path suppression handled by caller)
+        let cacheSuppressedSemantic = false;
         if (!showDegraded &&
             context.cache &&
             context.workspaceRoot &&
             context.branch &&
             riskClass) {
-            const lastEdit = context.recentEdits[context.recentEdits.length - 1];
+            const focusEdit = getFocusEdit(context);
             const key = {
                 workspaceRoot: context.workspaceRoot,
                 branch: context.branch,
                 posture,
                 riskClass,
-                fileBucket: deriveFileBucket(lastEdit?.kind ?? "unknown"),
+                fileBucket: deriveFileBucket(focusEdit?.kind ?? "unknown"),
             };
             if (context.cache.isSatisfied(key)) {
-                return SENTINEL; // skip guidance — recently satisfied
+                if (hasFileOpReminders) {
+                    cacheSuppressedSemantic = true;
+                }
+                else {
+                    return SENTINEL; // skip guidance — recently satisfied
+                }
             }
         }
         // Priority 5: Risk-class-driven guidance (for non-safe classes)
-        if (riskClass &&
+        if (!cacheSuppressedSemantic &&
+            riskClass &&
             riskClass !== "safe_docs_only" &&
             riskClass !== "safe_test_only") {
-            // For behavior/traceability with comment suggestions, use suggestion guidance
-            if ((riskClass === "behavior_candidate" ||
-                riskClass === "traceability_candidate") &&
-                context.recentCommentSuggestion) {
-                selectedBlock = buildCommentSuggestionGuidance(context.recentCommentSuggestion);
+            const autoBriefBlock = riskClass === "behavior_candidate" ||
+                riskClass === "traceability_candidate"
+                ? buildAutoBriefingGuidance(context.autoBriefResult, context.completionReminder === true)
+                : null;
+            if (autoBriefBlock) {
+                selectedBlock = autoBriefBlock;
             }
             else {
-                const block = GUIDANCE_BY_RISK[riskClass];
-                if (block)
-                    selectedBlock = block;
+                // For behavior/traceability with comment suggestions, use suggestion guidance
+                if ((riskClass === "behavior_candidate" ||
+                    riskClass === "traceability_candidate") &&
+                    context.recentCommentSuggestion) {
+                    selectedBlock = buildCommentSuggestionGuidance(context.recentCommentSuggestion);
+                }
+                else {
+                    const block = GUIDANCE_BY_RISK[riskClass];
+                    if (block)
+                        selectedBlock = block;
+                }
             }
         }
         // Priority 6: Legacy path-kind fallback (when no risk class)
-        else if (!riskClass) {
+        else if (!cacheSuppressedSemantic && !riskClass) {
             const codeEdits = context.recentEdits.filter((e) => e.kind === "code");
             const reqEdits = context.recentEdits.filter((e) => e.kind === "requirement");
             const kbDocEdits = context.recentEdits.filter((e) => [
@@ -229,7 +303,8 @@ If you're adding long explanatory comments, consider routing that knowledge to:
         (riskClass === "behavior_candidate" ||
             riskClass === "traceability_candidate") &&
         isAuthoritativePosture(posture) &&
-        !context.maintenanceDegraded) {
+        !context.maintenanceDegraded &&
+        !readyAutoBriefingAvailable) {
         selectedBlock = insertBulletAfterHeader(selectedBlock, "- Authoritative risky edit: run `/brief-kibi` before acting.");
     }
     // Source-linked micro-brief: insert after header line for code risk classes
@@ -239,11 +314,12 @@ If you're adding long explanatory comments, consider routing that knowledge to:
     if (selectedBlock &&
         (riskClass === "behavior_candidate" ||
             riskClass === "traceability_candidate") &&
-        context.workspaceRoot) {
+        context.workspaceRoot &&
+        !suppressSourceLinkedBrief) {
         try {
-            const lastEdit = context.recentEdits[context.recentEdits.length - 1];
-            if (lastEdit?.path) {
-                const editedPath = lastEdit.path;
+            const focusEdit = getFocusEdit(context);
+            if (focusEdit?.path) {
+                const editedPath = focusEdit.path;
                 const absEdited = path.isAbsolute(editedPath)
                     ? editedPath
                     : path.join(context.workspaceRoot, editedPath);
@@ -257,6 +333,41 @@ If you're adding long explanatory comments, consider routing that knowledge to:
             // Non-fatal: source-linked brief is best-effort
         }
     }
+    // ── File-operation reminder folding ─────────────────────────────────
+    // File-operation reminders bypass generic GuidanceCache suppression but
+    // are subject to prompt budget trimming. Per-path suppression is handled
+    // by the caller via file-operation-state hasShown/markShown.
+    // implements REQ-opencode-file-context-guidance-v1
+    if (hasFileOpReminders && fileOpReminder) {
+        const foBullets = [];
+        if (fileOpReminder.lifecycleReminder) {
+            // Skip lifecycleReminder if source-linked brief already shows the same IDs
+            const hasSourceLinked = selectedBlock?.includes("- Existing Kibi links:") === true;
+            const lifecycleHasEntities = fileOpReminder.lifecycleReminder.includes("Kibi entities:");
+            const overlapsSourceLinked = hasSourceLinked &&
+                lifecycleHasEntities &&
+                selectedBlock !== null &&
+                hasOverlappingEntityIds(selectedBlock, fileOpReminder.lifecycleReminder);
+            if (!overlapsSourceLinked) {
+                foBullets.push(fileOpReminder.lifecycleReminder);
+            }
+        }
+        if (fileOpReminder.e2eReminder) {
+            foBullets.push(fileOpReminder.e2eReminder);
+        }
+        if (foBullets.length > 0) {
+            if (selectedBlock) {
+                // Fold into existing semantic block
+                for (const bullet of foBullets) {
+                    selectedBlock = insertBulletAfterHeader(selectedBlock, bullet);
+                }
+            }
+            else {
+                // Create file-operation-only compact block
+                selectedBlock = `🧠 **File operation detected**\n${foBullets.join("\n")}`;
+            }
+        }
+    }
     // Inject degraded advisory block for warn-once mode
     if (showDegraded) {
         const advisory = `⚠️  **Maintenance degraded**
@@ -276,25 +387,37 @@ The Kibi workspace is in a maintenance-degraded state. Guidance remains advisory
         context.workspaceRoot &&
         context.branch &&
         riskClass) {
-        const lastEdit = context.recentEdits[context.recentEdits.length - 1];
+        const focusEdit = getFocusEdit(context);
         const key = {
             workspaceRoot: context.workspaceRoot,
             branch: context.branch,
             posture,
             riskClass,
-            fileBucket: deriveFileBucket(lastEdit?.kind ?? "unknown"),
+            fileBucket: deriveFileBucket(focusEdit?.kind ?? "unknown"),
         };
         context.cache.recordSatisfied(key, "guidance");
     }
-    // Apply budget enforcement before appending the completion reminder so the
-    // reminder bullet is never silently trimmed when bullet count exceeds MAX_BULLETS.
-    const budgeted = selectedBlock ? enforceBudget(selectedBlock) : null;
-    // Append completion reminder for risky classes when enabled
     const REMINDER_RISK_CLASSES = [
         "behavior_candidate",
         "traceability_candidate",
         "req_policy_candidate",
     ];
+    const reminderWillBeAppended = !!selectedBlock &&
+        context.completionReminder === true &&
+        !context.maintenanceDegraded &&
+        riskClass != null &&
+        REMINDER_RISK_CLASSES.includes(riskClass) &&
+        posture !== "root_uninitialized" &&
+        posture !== "root_partial";
+    const effectiveMaxBullets = reminderWillBeAppended
+        ? MAX_BULLETS - 1
+        : MAX_BULLETS;
+    // Apply budget enforcement before appending the completion reminder so the
+    // reminder bullet is never silently trimmed when bullet count exceeds MAX_BULLETS.
+    const budgeted = selectedBlock
+        ? enforceBudget(selectedBlock, effectiveMaxBullets)
+        : null;
+    // Append completion reminder for risky classes when enabled
     let finalBlock = budgeted;
     if (finalBlock &&
         context.completionReminder === true &&
@@ -360,7 +483,8 @@ Before implementing or explaining code:
 /**
  * Build the static guidance block (original behavior).
  */
-const BASE_GUIDANCE = `${SENTINEL}
+function buildBaseGuidance(capability = getInitKibiCommandCapability()) {
+    return `${SENTINEL}
 This project uses Kibi (via MCP). Prefer storing durable knowledge in Kibi over code comments.
 
 Before changing behavior: use kb_search for discovery, then kb_query by sourceFile, id, type, or tags for exact follow-up; do not rely on undocumented tools.
@@ -379,26 +503,28 @@ Dogfood note for this repo: OpenCode here uses local built \`kibi-mcp\` and \`ki
 5. **Link during work**: When creating KB entities, include relationship rows: specified_by (req→scenario), implements (symbol→req for ownership), covered_by (symbol→test for coverage), executable_for (test code→test).
 6. **Validate**: Run kb_check after KB mutations to catch violations early.
 
-**Public Kibi tools only:** kb_autopilot_generate, kb_search, kb_query, kb_status, kb_find_gaps, kb_coverage, kb_graph, kb_upsert, kb_delete, kb_check.\n\nDo not invoke Kibi CLI commands directly from the agent.\n\nBootstrap existing repos: use \`/init-kibi\` to run the retroactive initialization (\`kb_autopilot_generate\`) workflow.`;
+**Public Kibi tools only:** kb_autopilot_generate, kb_search, kb_query, kb_status, kb_find_gaps, kb_coverage, kb_graph, kb_upsert, kb_delete, kb_check.\n\nDo not invoke Kibi CLI commands directly from the agent.\n\n${buildInitKibiBootstrapReference(capability)}`;
+}
 /**
  * Build prompt with contextual guidance based on posture, risk class, and cache state.
  */
-export function buildPrompt(context) {
+export function buildPrompt(context, capability = getInitKibiCommandCapability()) {
     if (!context) {
-        return BASE_GUIDANCE.trim();
+        return buildBaseGuidance(capability).trim();
     }
-    return buildContextualGuidance(context).trim();
+    return buildContextualGuidance(context, capability).trim();
 }
 /**
  * Inject prompt guidance if not already present.
  */
-export function injectPrompt(current, config, context) {
+// implements REQ-opencode-kibi-briefing-v2
+export function injectPrompt(current, config, context, capability = getInitKibiCommandCapability()) {
     if (!config.prompt.enabled || !isPluginEnabled(config)) {
         return current;
     }
     if (current.includes(SENTINEL)) {
         return current;
     }
-    return `${current}\n\n${buildPrompt(context)}`;
+    return `${current}\n\n${buildPrompt(context, capability)}`;
 }
 export { SENTINEL };

package/dist/reconcile-engine.d.ts

@@ -0,0 +1,15 @@
+import type { AuditEntry } from "./idle-brief-audit.js";
+export interface EntityChangeItem {
+    id: string;
+    type: string;
+    title?: string;
+    source?: string;
+    textRef?: string;
+}
+export interface ReconcileResult {
+    added: EntityChangeItem[];
+    modified: EntityChangeItem[];
+    removed: EntityChangeItem[];
+    relationshipsChanged: number;
+}
+export declare function reconcileAuditEntries(entries: AuditEntry[]): ReconcileResult;

package/dist/reconcile-engine.js

@@ -0,0 +1,112 @@
+function normalizeWhitespace(value) {
+    return value.trim().replace(/\s+/g, " ");
+}
+function normalizeValue(value) {
+    if (typeof value === "string") {
+        return normalizeWhitespace(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry) => normalizeValue(entry));
+    }
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            .filter(([key]) => key !== "created_at" && key !== "updated_at")
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, entry]) => [key, normalizeValue(entry)]));
+    }
+    return value;
+}
+function fingerprintPayload(payload) {
+    return JSON.stringify(normalizeValue(payload.properties));
+}
+function isEntityPayload(payload) {
+    return payload?.kind === "entity";
+}
+function toChangeItem(payload, entityId) {
+    const title = payload.title ??
+        (typeof payload.properties.title === "string"
+            ? payload.properties.title
+            : undefined);
+    const source = payload.source ??
+        (typeof payload.properties.source === "string"
+            ? payload.properties.source
+            : undefined);
+    const textRef = payload.textRef ??
+        (typeof payload.properties.text_ref === "string"
+            ? payload.properties.text_ref
+            : undefined);
+    return {
+        id: entityId,
+        type: payload.entityType,
+        ...(title ? { title } : {}),
+        ...(source ? { source } : {}),
+        ...(textRef ? { textRef } : {}),
+    };
+}
+function compareChangeItems(left, right) {
+    return left.type.localeCompare(right.type) || left.id.localeCompare(right.id);
+}
+export function reconcileAuditEntries(
+// implements REQ-opencode-kibi-briefing-v6
+entries) {
+    const states = new Map();
+    let relationshipsChanged = 0;
+    for (const entry of [...entries].sort((left, right) => left.timestamp.localeCompare(right.timestamp))) {
+        if (entry.operation === "upsert_rel") {
+            relationshipsChanged += 1;
+            continue;
+        }
+        const state = states.get(entry.entityId) ?? {
+            sawCreate: false,
+            sawLegacyUpsert: false,
+            deleted: false,
+        };
+        if (entry.operation === "delete") {
+            state.deleted = true;
+            states.set(entry.entityId, state);
+            continue;
+        }
+        if (!isEntityPayload(entry.payload)) {
+            continue;
+        }
+        if (entry.payload.changeKind === "created") {
+            state.sawCreate = true;
+        }
+        if (!entry.payload.changeKind) {
+            state.sawLegacyUpsert = true;
+        }
+        state.lastKnown = toChangeItem(entry.payload, entry.entityId);
+        state.lastFingerprint = fingerprintPayload(entry.payload);
+        state.deleted = false;
+        states.set(entry.entityId, state);
+    }
+    const added = [];
+    const modified = [];
+    const removed = [];
+    for (const state of states.values()) {
+        if (!state.lastKnown) {
+            continue;
+        }
+        if (state.deleted) {
+            if (state.sawCreate) {
+                continue;
+            }
+            removed.push(state.lastKnown);
+            continue;
+        }
+        if (state.sawCreate || state.sawLegacyUpsert) {
+            added.push(state.lastKnown);
+            continue;
+        }
+        modified.push(state.lastKnown);
+    }
+    added.sort(compareChangeItems);
+    modified.sort(compareChangeItems);
+    removed.sort(compareChangeItems);
+    return {
+        added,
+        modified,
+        removed,
+        relationshipsChanged,
+    };
+}

package/dist/scheduler.d.ts

@@ -36,6 +36,7 @@ export interface SyncScheduler {
     scheduleSync(reason: string, filePath?: string, checkRules?: string[]): void;
     onFileEdited(filePath: string): void;
     onToolExecuteAfter(reason?: string): void;
+    flush(): Promise<void>;
     dispose(): void;
 }
 export declare function createSyncScheduler(opts: SchedulerOptions): SyncScheduler;

package/dist/scheduler.js

@@ -18,6 +18,7 @@ class WorktreeSyncScheduler {
     pending = null;
     trailing = null;
     lastFileEditedAt = 0;
+    flushWaiters = [];
     constructor(opts) {
         this.worktree = path.resolve(opts.worktree);
         this.config = opts.config;
@@ -32,7 +33,9 @@ class WorktreeSyncScheduler {
     scheduleSync(reason, filePath, checkRules) {
         if (!this.config.sync.enabled)
             return;
-        if (reason === "file.edited") {
+        // Treat file.created, file.edited, and file.deleted same relevance-wise
+        const isFileLifecycle = reason === "file.edited" || reason === "file.created" || reason === "file.deleted";
+        if (isFileLifecycle) {
             if (!filePath)
                 return;
             if (!shouldHandleFile(filePath, this.worktree))
@@ -71,11 +74,30 @@ class WorktreeSyncScheduler {
             this.scheduleSync(reason);
         }
     }
+    async flush() {
+        if (!this.config.sync.enabled)
+            return;
+        if (this.timer) {
+            this.clearTimeoutFn(this.timer);
+            this.timer = null;
+        }
+        this.flushPending();
+        if (this.isIdle()) {
+            return;
+        }
+        await new Promise((resolve) => {
+            this.flushWaiters.push(resolve);
+        });
+    }
     dispose() {
         if (this.timer) {
             this.clearTimeoutFn(this.timer);
             this.timer = null;
         }
+        const waiters = this.flushWaiters.splice(0);
+        for (const waiter of waiters) {
+            waiter();
+        }
     }
     isToolExecuteAfterEnabled() {
         if (this.explicitToolAfterHint)
@@ -147,6 +169,20 @@ class WorktreeSyncScheduler {
                         : {}),
                 });
             }
+            this.resolveFlushWaitersIfIdle();
+        }
+    }
+    isIdle() {
+        return !this.inFlight && !this.timer && !this.pending && !this.dirty && !this.trailing;
+    }
+    resolveFlushWaitersIfIdle() {
+        if (!this.isIdle())
+            return;
+        if (this.flushWaiters.length === 0)
+            return;
+        const waiters = this.flushWaiters.splice(0);
+        for (const waiter of waiters) {
+            waiter();
         }
     }
     emitCompletion(trigger, startedAt, exitCode, checkExitCode, checkRules) {

package/dist/session-edit-state.d.ts

@@ -0,0 +1,25 @@
+export type EditEventKind = string;
+export interface SessionEditEntry {
+    /** Relative file path (relative to worktree root). */
+    filePath: string;
+    /** Hash of the file content at first sight (baseline). "<deleted>" sentinel if file was missing. */
+    baselineHash: string;
+    /** Current hash at last reconciliation. */
+    currentHash: string;
+    /** Timestamp (ms) of last reconciliation pass. */
+    lastReconciledAt: number;
+}
+export interface SessionEditState {
+    recordEventHint(filePath: string, kind: EditEventKind, timestamp?: number): void;
+    reconcilePath(filePath: string): void;
+    reconcileKnownPaths(): void;
+    getSessionEdits(): SessionEditEntry[];
+    getFocusEdit(): SessionEditEntry | null;
+    hasSessionEdits(): boolean;
+    forceEdit(filePath: string, kind?: EditEventKind, timestamp?: number): void;
+}
+export declare function createSessionEditState(opts: {
+    worktree: string;
+    /** Custom clock for testing. Defaults to Date.now. */
+    now?: () => number;
+}): SessionEditState;