@zokizuan/satori-mcp 6.2.0 → 6.3.0

package/README.md

@@ -7,12 +7,18 @@ Most users should install Satori through `@zokizuan/satori-cli`. The installer w
 ## Install
 
 ```bash
-npx -y @zokizuan/satori-cli@latest install --client all --runtime offline
-npx -y @zokizuan/satori-cli@latest doctor
+npm install -g @zokizuan/satori-cli@latest
+satori install --client all
+satori doctor
 ```
 
 The local Potion runtime currently supports Linux x64, including Windows through WSL2. Connected Voyage and explicit local Ollama configurations are also available. See the [main README](https://github.com/ham-zax/satori#quick-start) for runtime choices.
 
+When installed through the CLI, compatible offline Potion + LanceDB clients
+share one private local host, provider/LanceDB state, and one Potion worker. Each
+client remains an independent MCP session. Direct `npx @zokizuan/satori-mcp`
+execution is still isolated and does not join the managed host.
+
 Direct package execution is intended for inspection and custom harnesses:
 
 ```bash
@@ -64,6 +70,9 @@ In a fresh two-task OpenCode comparison where both arms answered correctly, Sato
 - Inbound call-graph evidence is advisory and should be verified before blast-radius edits.
 - Provider, model, dimensions, projection, and vector backend are persisted compatibility identities; changing them requires a reindex.
 - Multiple incompatible live Satori runtimes are blocked from mutating the same publication.
+- Managed offline Potion + LanceDB clients on Linux x64/WSL2 share one private
+  local host. Connected providers, Milvus, and explicit Ollama runtimes keep
+  the direct per-client lifecycle.
 - Offline neural reranking is not shipped today. The candidate boundary permits a future complete-set local scorer to fail back atomically to exact + BM25 + single-vector ordering.
 
 ## Development

package/dist/core/canonical-symbol-identity.js

@@ -8,6 +8,25 @@ export function buildCanonicalSymbolRegistryView(symbols) {
     }
     return symbolsByKey;
 }
+function spanContains(parent, child) {
+    if (parent.file !== child.file) {
+        return false;
+    }
+    if (parent.span.startByte !== undefined
+        && parent.span.endByte !== undefined
+        && child.span.startByte !== undefined
+        && child.span.endByte !== undefined) {
+        return parent.span.startByte <= child.span.startByte
+            && child.span.endByte <= parent.span.endByte;
+    }
+    return parent.span.startLine <= child.span.startLine
+        && child.span.endLine <= parent.span.endLine;
+}
+function spanSize(symbol, useBytes) {
+    return useBytes
+        ? Math.max(0, symbol.span.endByte - symbol.span.startByte)
+        : Math.max(0, symbol.span.endLine - symbol.span.startLine);
+}
 function resolveParent(input) {
     const { symbol } = input;
     if (!symbol.parentKey) {
@@ -17,17 +36,26 @@ function resolveParent(input) {
                 : "missing",
         };
     }
-    const candidates = (input.registry.get(symbol.parentKey) || [])
-        .filter((candidate) => candidate.symbolInstanceId !== symbol.symbolInstanceId);
-    if (candidates.length === 0) {
+    const containingCandidates = (input.registry.get(symbol.parentKey) || [])
+        .filter((candidate) => (candidate.symbolInstanceId !== symbol.symbolInstanceId
+        && spanContains(candidate, symbol)));
+    if (containingCandidates.length === 0) {
         return { state: "missing" };
     }
-    if (candidates.length > 1) {
+    const byteCandidates = containingCandidates.filter((candidate) => (candidate.span.startByte !== undefined
+        && candidate.span.endByte !== undefined
+        && symbol.span.startByte !== undefined
+        && symbol.span.endByte !== undefined));
+    const candidates = byteCandidates.length > 0 ? byteCandidates : containingCandidates;
+    const useBytes = byteCandidates.length > 0;
+    const innermostSize = Math.min(...candidates.map((candidate) => spanSize(candidate, useBytes)));
+    const innermost = candidates.filter((candidate) => spanSize(candidate, useBytes) === innermostSize);
+    if (innermost.length !== 1) {
         return { state: "ambiguous" };
     }
     return {
         state: "resolved",
-        parentSymbolId: candidates[0].symbolInstanceId,
+        parentSymbolId: innermost[0].symbolInstanceId,
     };
 }
 export function projectCanonicalSymbolIdentity(input) {

package/dist/core/manage-indexing-handlers.js

@@ -868,6 +868,13 @@ export class ManageIndexingHandlers {
             }
             else {
                 const operation = persistOperation("blocked");
+                if (result.reason === "repair_proof_limit") {
+                    return this.host.manageResponse("repair", absolutePath, "blocked", result.message, {
+                        reason: "repair_proof_limit",
+                        repairProof: result.proof,
+                        ...(operation ? { operation } : {}),
+                    });
+                }
                 const createHint = this.host.buildCreateHint(absolutePath);
                 return this.host.manageResponse("repair", absolutePath, "blocked", result.message, {
                     reason: result.reason || "needs_create",

package/dist/core/manage-types.d.ts

@@ -7,7 +7,7 @@ export type ManageIndexAction = (typeof MANAGE_INDEX_ACTIONS)[number];
 export type ManageIndexStatus = "ok" | "not_ready" | "not_indexed" | "requires_reindex" | "blocked" | "error";
 export declare const MANAGE_INDEX_STATUS_DETAILS: readonly ["summary", "capabilities", "diagnostics", "full"];
 export type ManageIndexStatusDetail = (typeof MANAGE_INDEX_STATUS_DETAILS)[number];
-export type ManageIndexReason = "indexing" | "not_indexed" | "requires_reindex" | "unnecessary_reindex_ignore_only" | "preflight_unknown" | "backend_timeout" | "remote_delete_pending" | "missing_provider_config" | "vector_backend_unavailable" | "runtime_owner_conflict" | "mutation_in_progress" | "needs_create";
+export type ManageIndexReason = "indexing" | "not_indexed" | "requires_reindex" | "unnecessary_reindex_ignore_only" | "preflight_unknown" | "backend_timeout" | "remote_delete_pending" | "missing_provider_config" | "vector_backend_unavailable" | "runtime_owner_conflict" | "mutation_in_progress" | "needs_create" | "repair_proof_limit";
 export type VectorBackendResponseCode = "ZILLIZ_CLUSTER_STOPPED" | "VECTOR_BACKEND_AUTH_FAILED" | "VECTOR_BACKEND_UNREACHABLE" | "VECTOR_BACKEND_TIMEOUT" | "VECTOR_BACKEND_CONNECTION_CLOSED";
 export type ManageReindexPreflightOutcome = "reindex_required" | "reindex_unnecessary_ignore_only" | "unknown" | "probe_failed";
 export interface ManageIndexToolHint {

package/dist/core/relationship-backed-call-graph.js

@@ -1,7 +1,7 @@
 import { compareContractStrings, getGraphNeighbors, getRelationshipsForSymbol, isTestOrFixturePath, } from "@zokizuan/satori-core";
 import { DEFAULT_CALL_GRAPH_TEST_REFERENCE_LIMIT } from "./call-graph.js";
 import { buildSourceBackedPythonCalleeFallback, buildSourceBackedPythonCallerFallback, } from "./python-call-fallback.js";
-import { buildInboundNotesOnlySearchQuery } from "./search-response-helpers.js";
+import { buildInboundVerificationSearchQuery } from "./search-response-helpers.js";
 function compareNullableNumbersAsc(a, b) {
     const left = typeof a === "number" ? a : Number.POSITIVE_INFINITY;
     const right = typeof b === "number" ? b : Number.POSITIVE_INFINITY;
@@ -28,7 +28,7 @@ export function uniqueInboundCallerSiteFile(notes) {
             continue;
         }
         const file = typeof note.file === "string" ? note.file.trim() : "";
-        if (!file) {
+        if (!file || file === "(aggregate)") {
             continue;
         }
         allSites.add(file);
@@ -43,6 +43,7 @@ export function uniqueInboundCallerSiteFile(notes) {
     return [...preferred][0];
 }
 const MAX_DETAILED_TEST_SUPPRESSED_CALLER_NOTES = 3;
+const INBOUND_COVERAGE_PARTIAL_WARNING = "CALL_GRAPH_INBOUND_COVERAGE_PARTIAL";
 /**
  * Production suppressed callers first; collapse excess test/fixture caller notes into one summary.
  */
@@ -408,11 +409,13 @@ export class RelationshipBackedCallGraph {
             ...combinedEdges.flatMap((edge) => [edge.srcSymbolId, edge.dstSymbolId]),
         ]);
         const combinedNodes = this.sortNodes([...nodeById.values()].filter((node) => referencedNodeIds.has(node.symbolId)));
+        const hasNoInboundEdges = (input.direction === "callers" || input.direction === "both") && !combinedEdges.some((edge) => (edge.dstSymbolId === input.resolvedSymbol.symbolInstanceId));
         const warnings = [...new Set([
                 ...neighbors.warnings,
                 ...(droppedEdgesOutsideSourceSpan > 0 ? [`CALL_GRAPH_EDGE_OUTSIDE_SOURCE_SPAN:${droppedEdgesOutsideSourceSpan}`] : []),
                 ...(addedDynamicCalleeEdges.length > 0 ? [`SOURCE_BACKED_DYNAMIC_CALLEES:${addedDynamicCalleeEdges.length}`] : []),
                 ...(addedDynamicCallerEdges.length > 0 ? [`SOURCE_BACKED_DYNAMIC_CALLERS:${addedDynamicCallerEdges.length}`] : []),
+                ...(hasNoInboundEdges ? [INBOUND_COVERAGE_PARTIAL_WARNING] : []),
             ])].sort(compareContractStrings);
         // Sort first for determinism within bands, then production-first inbound note priority.
         const combinedNotes = prioritizeInboundSuppressedNotes(this.sortNotes([
@@ -420,17 +423,13 @@ export class RelationshipBackedCallGraph {
             ...(addedDynamicCalleeEdges.length > 0 ? dynamicCalleeFallback.notes : []),
             ...(addedDynamicCallerEdges.length > 0 ? dynamicCallerFallback.notes : []),
         ]));
-        const wantsInbound = input.direction === "callers" || input.direction === "both";
-        const inboundEdgeCount = combinedEdges.filter((edge) => (edge.dstSymbolId === input.resolvedSymbol.symbolInstanceId)).length;
-        const hasInboundSuppressedNotes = combinedNotes.some((note) => (note.type === "suppressed_edge"
-            && typeof note.detail === "string"
-            && note.detail.includes("caller candidate")));
-        // Notes-only inbound: promote executable must: identifier search (no fake edges).
-        // path: uses unique suppressed *caller site* file when available — prefer production
-        // over test/fixture sites (never the callee defining file alone).
+        // Empty inbound traversal: disclose advisory coverage and promote executable
+        // must: identifier search without fabricating an edge. path: uses a unique
+        // suppressed caller site when proven, never the callee defining file alone.
         let hints;
-        if (wantsInbound && inboundEdgeCount === 0 && hasInboundSuppressedNotes) {
-            const constructed = buildInboundNotesOnlySearchQuery({
+        if (hasNoInboundEdges) {
+            const constructed = buildInboundVerificationSearchQuery({
+                symbolName: input.resolvedSymbol.name,
                 symbolLabel: input.resolvedSymbol.label,
                 symbolId: input.resolvedSymbol.symbolInstanceId,
                 file: uniqueInboundCallerSiteFile(combinedNotes),
@@ -446,7 +445,7 @@ export class RelationshipBackedCallGraph {
                                 scope: "runtime",
                                 resultMode: "grouped",
                             },
-                            reason: "Inbound graph edges were suppressed as low-confidence or incomplete; use deterministic must: search to find production call sites.",
+                            reason: "Inbound graph coverage is partial and returned no callers; use deterministic must: search to verify production call sites.",
                         },
                     ],
                 };

package/dist/core/search-debug-helpers.js

@@ -95,6 +95,7 @@ export function buildChangedCodeDebug(input) {
     const symbols = changedSymbols.slice(0, input.maxSymbols);
     const cappedDirectCallers = directCallers.slice(0, input.maxDirectCallers);
     return {
+        basis: "git_tracked_worktree",
         files,
         symbols,
         directCallers: cappedDirectCallers,

package/dist/core/search-response-helpers.d.ts

@@ -20,10 +20,11 @@ export declare function buildSearchGroupRecommendedAction(codebaseRoot: string,
 export declare function buildTopRecommendedSearchAction(codebaseRoot: string, results: SearchGroupResult[]): SearchRecommendedNextAction | undefined;
 export declare function buildTopRecommendedRawSearchAction(codebaseRoot: string, results: SearchChunkResult[]): SearchRecommendedNextAction | undefined;
 /**
- * Build a must: identifier query for notes-only inbound graph recovery (M7/C1).
+ * Build a must: identifier query for empty inbound graph verification.
  * Never feeds raw multi-token labels into must: (operator tokenizer is whitespace-based).
  */
-export declare function buildInboundNotesOnlySearchQuery(input: {
+export declare function buildInboundVerificationSearchQuery(input: {
+    symbolName?: string;
     symbolLabel?: string;
     symbolId?: string;
     file?: string;

package/dist/core/search-response-helpers.js

@@ -377,11 +377,13 @@ export function buildTopRecommendedRawSearchAction(codebaseRoot, results) {
     };
 }
 /**
- * Build a must: identifier query for notes-only inbound graph recovery (M7/C1).
+ * Build a must: identifier query for empty inbound graph verification.
  * Never feeds raw multi-token labels into must: (operator tokenizer is whitespace-based).
  */
-export function buildInboundNotesOnlySearchQuery(input) {
-    const identifier = extractIdentifierFromSymbolLabel(input.symbolLabel)
+export function buildInboundVerificationSearchQuery(input) {
+    const symbolName = input.symbolName?.trim();
+    const identifier = (symbolName && !/\s/.test(symbolName) ? symbolName : undefined)
+        || extractIdentifierFromSymbolLabel(input.symbolLabel)
         || extractIdentifierFromSymbolLabel(input.symbolId);
     if (!identifier) {
         return { query: "", pathFilterIncluded: false };

package/dist/core/search-types.d.ts

@@ -398,6 +398,7 @@ export interface SearchDebugHint {
         boostedCandidates: number;
     };
     changedCode?: {
+        basis: "git_tracked_worktree";
         files: string[];
         symbols: Array<{
             file: string;

package/dist/core/sync.d.ts

@@ -10,6 +10,7 @@ interface SyncManagerOptions {
     mutationLeaseCoordinator?: MutationLeaseCoordinator;
     crossProcessJoinTimeoutMs?: number;
     crossProcessJoinPollMs?: number;
+    onLifecycleActivityChanged?: () => void;
 }
 export type FreshnessDecisionMode = 'synced' | 'skipped_recent' | 'skipped_source_unchanged' | 'coalesced' | 'skipped_indexing' | 'skipped_requires_reindex' | 'skipped_source_checkpoint_unavailable' | 'skipped_mutation_in_progress' | 'skipped_missing_path' | 'reconciled_ignore_change' | 'ignore_reload_failed';
 export interface FreshnessDecision {
@@ -100,6 +101,8 @@ export declare class SyncManager {
     private activeSyncs;
     private lastSyncTimes;
     private backgroundSyncTimer;
+    private backgroundSyncEnabled;
+    private backgroundSyncFlight;
     private watcherModeStarted;
     private watchEnabled;
     private watchDebounceMs;
@@ -112,6 +115,7 @@ export declare class SyncManager {
     private ignoreRulesVersions;
     private pendingIgnoreChangeEdits;
     private activeIgnoreReconciles;
+    private activeWatcherSyncs;
     private freshnessEpochs;
     private sourceCheckpointObservations;
     private sourceCheckpointStatuses;
@@ -120,6 +124,7 @@ export declare class SyncManager {
     private readonly mutationLeaseCoordinator?;
     private readonly crossProcessJoinTimeoutMs;
     private readonly crossProcessJoinPollMs;
+    private readonly onLifecycleActivityChanged?;
     constructor(context: Context, snapshotManager: SnapshotManager, options?: SyncManagerOptions);
     private bumpFreshnessEpoch;
     getPreparedReadObservation(codebasePath: string): PreparedReadObservationResult;
@@ -140,7 +145,15 @@ export declare class SyncManager {
     private joinCrossProcessSync;
     handleSyncIndex(): Promise<void>;
     startBackgroundSync(): void;
+    private scheduleBackgroundSync;
+    private runBackgroundSync;
     stopBackgroundSync(): void;
+    /**
+     * Stops new provider-owned synchronization work and joins every lifecycle
+     * flight that may still hold mutation or backend authority.
+     */
+    stopAndDrainLifecycle(): Promise<void>;
+    getActiveLifecycleOperationCount(): number;
     getWatchDebounceMs(): number;
     private canScheduleWatchSync;
     private getIgnoreRuleVersion;

package/dist/core/sync.js

@@ -42,6 +42,8 @@ export class SyncManager {
         this.activeSyncs = new Map();
         this.lastSyncTimes = new Map();
         this.backgroundSyncTimer = null;
+        this.backgroundSyncEnabled = false;
+        this.backgroundSyncFlight = null;
         this.watcherModeStarted = false;
         this.watchedCodebases = new Set();
         this.watchers = new Map();
@@ -52,6 +54,7 @@ export class SyncManager {
         this.ignoreRulesVersions = new Map();
         this.pendingIgnoreChangeEdits = new Map();
         this.activeIgnoreReconciles = new Map();
+        this.activeWatcherSyncs = new Set();
         this.freshnessEpochs = new Map();
         this.sourceCheckpointObservations = new Map();
         this.sourceCheckpointStatuses = new Map();
@@ -62,6 +65,7 @@ export class SyncManager {
         this.now = options.now || (() => Date.now());
         this.onSyncCompleted = options.onSyncCompleted;
         this.mutationLeaseCoordinator = options.mutationLeaseCoordinator;
+        this.onLifecycleActivityChanged = options.onLifecycleActivityChanged;
         this.crossProcessJoinTimeoutMs = Math.max(1, options.crossProcessJoinTimeoutMs ?? DEFAULT_CROSS_PROCESS_JOIN_TIMEOUT_MS);
         this.crossProcessJoinPollMs = Math.max(1, options.crossProcessJoinPollMs ?? DEFAULT_CROSS_PROCESS_JOIN_POLL_MS);
     }
@@ -167,20 +171,22 @@ export class SyncManager {
             if (previousObservation && previousObservation !== checkpointEvidence.observationToken) {
                 this.bumpFreshnessEpoch(codebasePath);
             }
-            return null;
+            return { checkpoint: checkpointEvidence };
         }
         if (!checkpointEvidence)
-            return null;
+            return { checkpoint: null };
         this.sourceCheckpointStatuses.set(codebasePath, checkpointEvidence.status);
         this.sourceCheckpointObservations.delete(codebasePath);
         this.lastSyncTimes.delete(codebasePath);
         this.bumpFreshnessEpoch(codebasePath);
         return {
-            mode: 'skipped_source_checkpoint_unavailable',
-            checkedAt,
-            thresholdMs,
-            checkpointStatus: checkpointEvidence.status,
-            errorMessage: checkpointEvidence.message,
+            failure: {
+                mode: 'skipped_source_checkpoint_unavailable',
+                checkedAt,
+                thresholdMs,
+                checkpointStatus: checkpointEvidence.status,
+                errorMessage: checkpointEvidence.message,
+            },
         };
     }
     persistOwnedOperationStart(lease, ownsLease) {
@@ -278,10 +284,10 @@ export class SyncManager {
         const checkedAtMs = this.now();
         const checkedAt = new Date(checkedAtMs).toISOString();
         if (options.reason === 'ignore_change') {
-            const checkpointFailure = await this.validateSourceFreshnessCheckpoint(codebasePath, checkedAt, thresholdMs, options.preparedVectorReceipt);
-            if (checkpointFailure)
-                return checkpointFailure;
-            return this.runIgnoreReconcile(codebasePath, options.coalescedEdits, undefined, options.mutationLease);
+            const checkpointValidation = await this.validateSourceFreshnessCheckpoint(codebasePath, checkedAt, thresholdMs, options.preparedVectorReceipt);
+            if ('failure' in checkpointValidation)
+                return checkpointValidation.failure;
+            return this.runIgnoreReconcile(codebasePath, options.coalescedEdits, undefined, options.mutationLease, checkpointValidation.checkpoint?.generationReceipt);
         }
         // Join a live mutation before inspecting its checkpoint. The owner may be
         // between marker withdrawal and checkpoint publication.
@@ -307,16 +313,16 @@ export class SyncManager {
         // Source-freshness ownership is a precondition for every incremental path,
         // including ignore reconciliation. The identity comes from Core authority,
         // never from the lifecycle snapshot.
-        const checkpointFailure = await this.validateSourceFreshnessCheckpoint(codebasePath, checkedAt, thresholdMs, options.preparedVectorReceipt);
-        if (checkpointFailure)
-            return checkpointFailure;
+        const checkpointValidation = await this.validateSourceFreshnessCheckpoint(codebasePath, checkedAt, thresholdMs, options.preparedVectorReceipt);
+        if ('failure' in checkpointValidation)
+            return checkpointValidation.failure;
         let currentIgnoreControlSignature;
         if (options.skipIgnoreControlCheck !== true) {
             currentIgnoreControlSignature = await this.computeIgnoreControlSignature(codebasePath);
             const persistedIgnoreControlSignature = this.snapshotManager.getCodebaseIgnoreControlSignature?.(codebasePath);
             if (typeof persistedIgnoreControlSignature === 'string') {
                 if (persistedIgnoreControlSignature !== currentIgnoreControlSignature) {
-                    return this.runIgnoreReconcile(codebasePath, 1, currentIgnoreControlSignature, options.mutationLease);
+                    return this.runIgnoreReconcile(codebasePath, 1, currentIgnoreControlSignature, options.mutationLease, checkpointValidation.checkpoint?.generationReceipt);
                 }
             }
             else if ((this.snapshotManager.getCodebaseStatus(codebasePath) === 'indexed'
@@ -329,7 +335,7 @@ export class SyncManager {
                     ? this.context.hasSynchronizerForCodebase(codebasePath)
                     : false;
                 if (indexedPaths.length > 0 || hasSynchronizer) {
-                    return this.runIgnoreReconcile(codebasePath, 1, currentIgnoreControlSignature, options.mutationLease);
+                    return this.runIgnoreReconcile(codebasePath, 1, currentIgnoreControlSignature, options.mutationLease, checkpointValidation.checkpoint?.generationReceipt);
                 }
             }
         }
@@ -367,7 +373,7 @@ export class SyncManager {
             try {
                 return await this.syncCodebase(codebasePath, options.mutationLease, currentIgnoreControlSignature, {
                     exactSourceComparisonPaths: options.exactSourceComparisonPaths,
-                });
+                }, checkpointValidation.checkpoint?.generationReceipt);
             }
             catch (e) {
                 // Log and rethrow to allow callers to handle/see failure
@@ -409,7 +415,7 @@ export class SyncManager {
             errorMessage: outcome.errorMessage,
         };
     }
-    async runIgnoreReconcile(codebasePath, coalescedEdits = 1, nextIgnoreControlSignature, existingLease) {
+    async runIgnoreReconcile(codebasePath, coalescedEdits = 1, nextIgnoreControlSignature, existingLease, preparedVectorReceipt) {
         const reconcileKey = this.normalizeReconcileKey(codebasePath);
         const inFlight = this.activeIgnoreReconciles.get(reconcileKey);
         const checkedAtMs = this.now();
@@ -447,7 +453,7 @@ export class SyncManager {
         try {
             lastDurableOperation = this.persistOwnedOperationStart(lease, releaseLease);
             console.log(`[SYNC] 🔁 Ignore control files changed for '${codebasePath}', running reconciliation.`);
-            const promise = this.reconcileIgnoreRulesChange(codebasePath, coalescedEdits, nextIgnoreControlSignature, lease);
+            const promise = this.reconcileIgnoreRulesChange(codebasePath, coalescedEdits, nextIgnoreControlSignature, lease, preparedVectorReceipt);
             this.activeIgnoreReconciles.set(reconcileKey, promise);
             const decision = await promise;
             const phase = decision.mode === "ignore_reload_failed" ? "failed" : "completed";
@@ -478,7 +484,7 @@ export class SyncManager {
             }
         }
     }
-    async reconcileIgnoreRulesChange(codebasePath, coalescedEdits = 1, nextIgnoreControlSignature, mutationLease) {
+    async reconcileIgnoreRulesChange(codebasePath, coalescedEdits = 1, nextIgnoreControlSignature, mutationLease, preparedVectorReceipt) {
         const checkedAtMs = this.now();
         const checkedAt = new Date(checkedAtMs).toISOString();
         const startedAt = checkedAtMs;
@@ -531,9 +537,13 @@ export class SyncManager {
             }
             this.assertMutationCurrent(mutationLease);
             this.snapshotManager.saveCodebaseSnapshot();
+            // Deleting newly ignored payload invalidates ordinary live proof.
+            // Carry the pre-delete receipt so Core can revalidate that exact
+            // source generation after the mutation lease is held.
             const syncDecision = await this.ensureFreshness(codebasePath, 0, {
                 skipIgnoreControlCheck: true,
                 mutationLease,
+                preparedVectorReceipt,
             });
             const lastSyncAt = syncDecision.lastSyncAt;
             const lastSyncMs = lastSyncAt ? Date.parse(lastSyncAt) : undefined;
@@ -597,7 +607,7 @@ export class SyncManager {
             };
         }
     }
-    async syncCodebase(codebasePath, existingLease, currentIgnoreControlSignature, joinRequest = {}) {
+    async syncCodebase(codebasePath, existingLease, currentIgnoreControlSignature, joinRequest = {}, preparedVectorReceipt) {
         if (this.snapshotManager.getCodebaseStatus(codebasePath) === 'indexing') {
             console.log(`[SYNC] ⏭️  Skipping sync for '${codebasePath}' because indexing is active.`);
             return { mode: 'skipped_indexing' };
@@ -672,7 +682,7 @@ export class SyncManager {
                     this.mutationLeaseCoordinator.publishWhileCurrent(lease, publish);
                 }
                 : undefined;
-            const fencedCheckpoint = await this.inspectSourceFreshnessCheckpoint(codebasePath);
+            const fencedCheckpoint = await this.inspectSourceFreshnessCheckpoint(codebasePath, preparedVectorReceipt);
             if (fencedCheckpoint && fencedCheckpoint.status !== 'valid') {
                 throw new Error(`Incremental sync cannot continue because its authoritative source checkpoint is ${fencedCheckpoint.status}: ${fencedCheckpoint.message}`);
             }
@@ -980,23 +990,76 @@ export class SyncManager {
         }
     }
     startBackgroundSync() {
-        if (this.backgroundSyncTimer) {
+        if (this.backgroundSyncEnabled) {
             return;
         }
-        const run = async () => {
-            await this.handleSyncIndex();
-            // recursive schedule to prevent overlap
-            this.backgroundSyncTimer = setTimeout(run, BACKGROUND_SYNC_INTERVAL_MS);
-        };
-        // Initial delay
-        this.backgroundSyncTimer = setTimeout(run, BACKGROUND_SYNC_INITIAL_DELAY_MS);
+        this.backgroundSyncEnabled = true;
+        this.scheduleBackgroundSync(BACKGROUND_SYNC_INITIAL_DELAY_MS);
+    }
+    scheduleBackgroundSync(delayMs) {
+        if (!this.backgroundSyncEnabled)
+            return;
+        this.backgroundSyncTimer = setTimeout(() => {
+            this.backgroundSyncTimer = null;
+            void this.runBackgroundSync();
+        }, delayMs);
+    }
+    runBackgroundSync() {
+        const flight = (async () => {
+            try {
+                await this.handleSyncIndex();
+            }
+            catch (error) {
+                console.error('[SYNC] Periodic synchronization pass failed:', error);
+            }
+        })();
+        this.backgroundSyncFlight = flight;
+        this.onLifecycleActivityChanged?.();
+        void flight.finally(() => {
+            if (this.backgroundSyncFlight === flight) {
+                this.backgroundSyncFlight = null;
+                this.onLifecycleActivityChanged?.();
+            }
+            this.scheduleBackgroundSync(BACKGROUND_SYNC_INTERVAL_MS);
+        });
+        return flight;
     }
     stopBackgroundSync() {
+        this.backgroundSyncEnabled = false;
         if (this.backgroundSyncTimer) {
             clearTimeout(this.backgroundSyncTimer);
             this.backgroundSyncTimer = null;
         }
     }
+    /**
+     * Stops new provider-owned synchronization work and joins every lifecycle
+     * flight that may still hold mutation or backend authority.
+     */
+    async stopAndDrainLifecycle() {
+        this.stopBackgroundSync();
+        await this.stopWatcherMode();
+        for (;;) {
+            const pending = new Set();
+            if (this.backgroundSyncFlight) {
+                pending.add(this.backgroundSyncFlight);
+            }
+            for (const flight of this.activeWatcherSyncs) {
+                pending.add(flight);
+            }
+            for (const flight of this.activeSyncs.values()) {
+                pending.add(flight);
+            }
+            for (const flight of this.activeIgnoreReconciles.values()) {
+                pending.add(flight);
+            }
+            if (pending.size === 0)
+                return;
+            await Promise.allSettled(pending);
+        }
+    }
+    getActiveLifecycleOperationCount() {
+        return (this.backgroundSyncFlight ? 1 : 0) + this.activeWatcherSyncs.size;
+    }
     getWatchDebounceMs() {
         return this.watchDebounceMs;
     }
@@ -1144,29 +1207,38 @@ export class SyncManager {
             const current = this.pendingIgnoreChangeEdits.get(codebasePath) || 0;
             this.pendingIgnoreChangeEdits.set(codebasePath, current + 1);
         }
-        const timer = setTimeout(async () => {
+        const timer = setTimeout(() => {
             this.debounceTimers.delete(codebasePath);
-            const coalescedIgnoreEdits = this.pendingIgnoreChangeEdits.get(codebasePath) || 0;
-            this.pendingIgnoreChangeEdits.delete(codebasePath);
-            try {
-                if (coalescedIgnoreEdits > 0) {
-                    const decision = await this.ensureFreshness(codebasePath, 0, {
-                        reason: 'ignore_change',
-                        coalescedEdits: coalescedIgnoreEdits,
-                    });
-                    if (decision.mode === 'ignore_reload_failed') {
-                        console.warn(`[SYNC-WATCH] Ignore-rule reconcile failed for '${codebasePath}': ${decision.errorMessage || 'unknown_error'} (fallbackSyncExecuted=${decision.fallbackSyncExecuted === true})`);
-                    }
-                    else {
-                        console.log(`[SYNC-WATCH] Ignore-rule reconcile completed for '${codebasePath}' (version=${decision.ignoreRulesVersion ?? 'n/a'}, deleted=${decision.deletedFiles ?? 0}, added=${decision.addedFiles ?? 0}, coalesced=${decision.coalescedEdits ?? 1})`);
+            const flight = (async () => {
+                const coalescedIgnoreEdits = this.pendingIgnoreChangeEdits.get(codebasePath) || 0;
+                this.pendingIgnoreChangeEdits.delete(codebasePath);
+                try {
+                    if (coalescedIgnoreEdits > 0) {
+                        const decision = await this.ensureFreshness(codebasePath, 0, {
+                            reason: 'ignore_change',
+                            coalescedEdits: coalescedIgnoreEdits,
+                        });
+                        if (decision.mode === 'ignore_reload_failed') {
+                            console.warn(`[SYNC-WATCH] Ignore-rule reconcile failed for '${codebasePath}': ${decision.errorMessage || 'unknown_error'} (fallbackSyncExecuted=${decision.fallbackSyncExecuted === true})`);
+                        }
+                        else {
+                            console.log(`[SYNC-WATCH] Ignore-rule reconcile completed for '${codebasePath}' (version=${decision.ignoreRulesVersion ?? 'n/a'}, deleted=${decision.deletedFiles ?? 0}, added=${decision.addedFiles ?? 0}, coalesced=${decision.coalescedEdits ?? 1})`);
+                        }
+                        return;
                     }
-                    return;
+                    await this.ensureFreshness(codebasePath, 0);
                 }
-                await this.ensureFreshness(codebasePath, 0);
-            }
-            catch (error) {
-                console.error(`[SYNC-WATCH] Debounced sync failed for '${codebasePath}':`, error);
-            }
+                catch (error) {
+                    console.error(`[SYNC-WATCH] Debounced sync failed for '${codebasePath}':`, error);
+                }
+            })();
+            this.activeWatcherSyncs.add(flight);
+            this.onLifecycleActivityChanged?.();
+            void flight.finally(() => {
+                if (this.activeWatcherSyncs.delete(flight)) {
+                    this.onLifecycleActivityChanged?.();
+                }
+            });
         }, this.watchDebounceMs);
         this.debounceTimers.set(codebasePath, timer);
     }
@@ -1325,7 +1397,6 @@ export class SyncManager {
         this.debounceTimers.clear();
         this.watcherIgnoreMatchers.clear();
         this.pendingIgnoreChangeEdits.clear();
-        this.activeIgnoreReconciles.clear();
         this.lastSyncTimes.clear();
         this.ignoreRulesVersions.clear();
         this.freshnessEpochs.clear();