@descix/cli 1.0.10 → 1.0.12

package/bin/descix.js

@@ -2187,6 +2187,7 @@ corpusCommand
   .option('--dry-run', 'Enumerate would-be-purged file_ids and would-be-upserted chunks without ANY Pinecone writes. Exit 0 if no drift, 1 if drift. Read-only.')
   .option('--show-walk', 'Print the resolved ref + the first 50 walked files BEFORE any Pinecone operations. Useful for verifying --ref / manifest source resolution.')
   .option('--yes', 'Skip the interactive purge confirmation in --rebuild mode. Use in scripting/CI.')
+  .option('--skip-retrieval-canary', 'Skip the post-sync retrieval canary that confirms a synced chunk actually retrieves before reporting success (measured 2026-09-17: presence in Pinecone is not the same as searchable — the index can lag ~20 minutes after a large upsert/purge). Skipping costs nothing but SAVES one credit-metered query_knowledge_base call and up to ~25s; the sync then reports success on presence only, same as before this check existed. Prefer leaving this ON for anything user-facing; use it for CI/cost-sensitive automation that will verify separately.')
   .action(async (options) => {
     try {
       const apiClient = new DeSciXApiClient();

package/bin/mcp-server.js

@@ -23,6 +23,7 @@ import { WalletFileManager } from '../lib/wallet-file.js';
 import { CLI_VERSION } from '../lib/cli-version.js';
 import { checkDevCert } from '@descix/app-sdk/dev';
 import { resolveGatewayCertContext } from '../lib/dev-cert-resolver.js';
+import { originStampFor, stampToolResult } from '../lib/mcp-origin-stamp.js';
 import * as fs from 'fs/promises';
 import * as path from 'path';
 // WS-MCP-SSOT-TIER2 (audit §5.B-1): the curated HTTP-valid core tools are the SINGLE SOURCE
@@ -153,7 +154,7 @@ try {
   // descix_doctor — local diagnostic (no backend call)
   // -------------------------------------------------------------------------
 
-  async function runDoctor(args) {
+  async function runDoctor(args, originStamp) {
     const verifyRemote = args?.verify_remote !== false;
     const report = {
       auth: { connected: false },
@@ -199,7 +200,12 @@ try {
           app_id: freshContext.appId,
           community_id: freshContext.communityId,
           kb_id: freshContext.kbId || 'General',
-          api_url: freshConfig.apiUrl || apiClient.baseUrl,
+          // ONE OWNER: `freshConfig.apiUrl` is a legacy top-level key WorkspaceConfig never
+          // populates (the real value lives at `env.apiUrl`, read via `resolveOrigin()`) — the
+          // `||` here was always falling through to `apiClient.baseUrl`. Read the resolved
+          // origin stamp directly rather than keeping a dead alternative that looked like a
+          // second source.
+          api_url: originStamp?.origin ?? apiClient.baseUrl,
           local_apps: [
             platform.appId,
             ...products.map(p => p.appId),
@@ -361,6 +367,13 @@ try {
       report.status = 'warnings';
     }
 
+    // The same origin stamp every other tool result carries (see mcp-origin-stamp.js) — doctor
+    // is the diagnostic surface, so it states the fact explicitly rather than only via the
+    // appended content block every tool gets.
+    if (originStamp) {
+      report.origin_stamp = originStamp;
+    }
+
     return report;
   }
 
@@ -407,13 +420,35 @@ try {
     const { name, arguments: args } = request.params;
     console.error(`[MCP] tools/call — ${name}`);
 
+    // Resolve the origin stamp ONCE per call, from the one owner (api-client.js's own
+    // resolution — the same baseUrl/originSource the CLI's `env:` line reports), and carry it
+    // onto EVERY result this call returns, success or error. MEASURED 2026-09-17: two sessions
+    // spent hours reading DEV through this connector while believing they were reading PROD
+    // because no tool result said where it came from — see mcp-origin-stamp.js.
+    let originStamp = null;
+    let originStampError = null;
     try {
+      await apiClient.ensureInitialized();
+      originStamp = originStampFor(apiClient);
+    } catch (err) {
+      // The origin itself failed to resolve (e.g. a configured-but-invalid origin). There is
+      // nothing valid to stamp — the error's own message already names the fix — so this call
+      // fails loud below rather than stamping a guess.
+      originStampError = err;
+    }
+    const withStamp = (result) => (originStamp ? stampToolResult(result, originStamp) : result);
+
+    try {
+      if (originStampError) {
+        throw originStampError;
+      }
+
       // descix_doctor is handled locally
       if (name === 'descix_doctor') {
-        const report = await runDoctor(args);
-        return {
+        const report = await runDoctor(args, originStamp);
+        return withStamp({
           content: [{ type: 'text', text: JSON.stringify(report, null, 2) }],
-        };
+        });
       }
 
       // Merge default context for convenience (caller can override). Only auto-fill when the
@@ -455,12 +490,12 @@ try {
       });
 
       const result = await apiClient.invoke(name, params);
-      return {
+      return withStamp({
         content: [{
           type: 'text',
           text: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
         }],
-      };
+      });
     } catch (error) {
       console.error(`[MCP] Tool error: ${error.message}`);
       // WS-HEADLESS-MVP-A3: when the backend attached structured error fields (code +
@@ -471,10 +506,10 @@ try {
       const structured = (error.code || error.data)
         ? `\n${JSON.stringify({ code: error.code, data: error.data }, null, 2)}`
         : '';
-      return {
+      return withStamp({
         content: [{ type: 'text', text: `Error: ${error.message}${structured}` }],
         isError: true,
-      };
+      });
     }
   });
 

package/lib/commands/corpus.js

@@ -32,6 +32,8 @@ import {
   isReportedCount, accumulateReportedCount, UNREPORTED_COUNT
 } from '../core/Syncer.js';
 import { lintManifestForDenyClasses, assertNoViolations } from '../core/CorpusDenyLint.js';
+import { pickCanaryChunk, runRetrievalCanary, DEFAULT_CANARY_DELAYS_MS } from '../core/RetrievalCanary.js';
+import { loadSyncState, saveSyncState, syncStatePath, syncFailureLogPath } from '../core/syncState.js';
 
 /**
  * Resolve community_id for corpus sync — same precedence as site upload / update kb:
@@ -206,35 +208,12 @@ export function renderCount(value, unknownText = 'an unreported number of') {
 }
 
 /**
- * Save sync state after a successful corpus sync.
- *
- * @param {string} appRoot - App root directory
- * @param {string} kbName - Knowledge base name
- * @param {Object} state - { last_sync_commit, sources_provenance, synced_files_count, total_chunks, timestamp }
+ * Sync state is owned by lib/core/syncState.js and keyed by the ORIGIN the sync talked to.
+ * The unscoped local helpers that used to live here are DELETED, not wrapped: they were the
+ * defect (one file per KB name, no environment anywhere in it), and a compat path that still
+ * resolved `.descix/sync-state/<KB>.json` would keep producing the silent under-sync this
+ * module exists to end. See that file's header for the measurement.
  */
-async function saveSyncState(appRoot, kbName, state) {
-  const stateDir = path.join(appRoot, '.descix', 'sync-state');
-  await fs.mkdir(stateDir, { recursive: true });
-  const statePath = path.join(stateDir, `${kbName}.json`);
-  await fs.writeFile(statePath, JSON.stringify(state, null, 2));
-}
-
-/**
- * Load sync state from a previous corpus sync.
- *
- * @param {string} appRoot - App root directory
- * @param {string} kbName - Knowledge base name
- * @returns {Promise<Object|null>} Sync state or null if no previous sync
- */
-async function loadSyncState(appRoot, kbName) {
-  const statePath = path.join(appRoot, '.descix', 'sync-state', `${kbName}.json`);
-  try {
-    const raw = await fs.readFile(statePath, 'utf-8');
-    return JSON.parse(raw);
-  } catch {
-    return null;
-  }
-}
 
 /**
  * Detect the current git branch in workspaceRoot.
@@ -397,6 +376,13 @@ export async function runCorpusSync(apiClient, options) {
 
     spinner.succeed(`Found ${manifests.length} manifest(s)`);
 
+    // THE ORIGIN THIS SYNC IS TALKING TO — resolved once, from the client that will actually
+    // carry the upserts, and used to key every sync-state read and write below. Taken from the
+    // client rather than re-derived from the workspace: a re-derivation could name a different
+    // origin than the one receiving the chunks, which is precisely the lie that state file
+    // told for months. Awaited because baseUrl is loaded lazily.
+    const syncOrigin = await apiClient.ensureBaseUrl();
+
     // Deliverable B: branch-mismatch advisory. We only emit this when:
     //   - no --ref override was supplied, AND
     //   - every loaded manifest's every source uses the default "main", AND
@@ -467,6 +453,11 @@ export async function runCorpusSync(apiClient, options) {
     let totalChunksCreated = 0;
     let totalFilesSkipped = 0;
     let totalFilesDeleted = 0;
+    // The retrieval canary's verdict per KB — a sync/rebuild does not get to report a bare
+    // success while any of these are unverified (see RetrievalCanary.js). Collected across
+    // manifests so ONE loud failure at the end names every KB still unconfirmed, rather than
+    // failing fast on the first and leaving later manifests unsynced.
+    const canaryResults = [];
 
     for (const rawManifest of manifests) {
       // ── Deliverable B: resolve --ref override (CLI > manifest > default) ──
@@ -643,7 +634,16 @@ export async function runCorpusSync(apiClient, options) {
       // Deliverable A note: in dry-run + rebuild we ALSO null previousState so
       // the count below reflects what a real rebuild would upsert (all files),
       // not what an incremental sync would upsert.
-      let previousState = await loadSyncState(appRoot, kbName);
+      // State is per-ORIGIN. The blob-SHA skip below is only sound against the origin that
+      // actually received those SHAs — see lib/core/syncState.js.
+      const loadedState = await loadSyncState(appRoot, kbName, syncOrigin);
+      let previousState = loadedState.state;
+      if (loadedState.reason === 'unkeyed-legacy' || loadedState.reason === 'origin-mismatch') {
+        // LOUD, because the consequence of not saying it is a full re-walk the operator did not
+        // ask for, and silence here is what made the original defect invisible for months.
+        console.log(chalk.yellow(`  ⚠ No sync state for ${syncOrigin} — walking the FULL corpus.`));
+        console.log(chalk.gray(`    ${loadedState.detail}`));
+      }
       if (options.rebuild) {
         previousState = null;
       }
@@ -651,9 +651,9 @@ export async function runCorpusSync(apiClient, options) {
       const previousChunkCount = readPreviousChunkCount(previousState);
 
       if (previousBlobShas.size > 0) {
-        console.log(chalk.gray(`  Previous sync: ${previousBlobShas.size} files, ${previousChunkCount ?? 'an unknown number of'} chunks`));
+        console.log(chalk.gray(`  Previous sync to ${syncOrigin}: ${previousBlobShas.size} files, ${previousChunkCount ?? 'an unknown number of'} chunks`));
       } else {
-        console.log(chalk.gray('  First sync (no previous state)'));
+        console.log(chalk.gray(`  First sync to ${syncOrigin} (no previous state for this origin)`));
       }
 
       // 3c. Compute delta — compare by blob SHA against local sync state
@@ -816,10 +816,10 @@ export async function runCorpusSync(apiClient, options) {
 
         // Write failure log to .descix if any batches failed
         if (syncFailures.length > 0) {
-          const failLogDir = path.join(appRoot, '.descix', 'sync-state');
-          await fs.mkdir(failLogDir, { recursive: true });
-          const failLogPath = path.join(failLogDir, `${kbName}-failures.json`);
+          const failLogPath = syncFailureLogPath(appRoot, kbName, syncOrigin);
+          await fs.mkdir(path.dirname(failLogPath), { recursive: true });
           await fs.writeFile(failLogPath, JSON.stringify({
+            origin: syncOrigin,
             timestamp: new Date().toISOString(),
             commit: commitSha,
             failures: syncFailures,
@@ -877,9 +877,52 @@ export async function runCorpusSync(apiClient, options) {
         }
       }
 
+      // 3f-2. RETRIEVAL CANARY (measured 2026-09-17): presence in Pinecone (reconciled above)
+      // is NOT searchability — the PROD index can take ~20 minutes to catch up after a
+      // purge+re-upsert, during which every status surface still says healthy. A sync does not
+      // get to report bare success until a chunk it just wrote actually RETRIEVES. Bounded
+      // (RetrievalCanary.js) rather than a loop: query_knowledge_base is credit-metered.
+      let retrievalCanary = null;
+      if (allChunks.length > 0 && options.skipRetrievalCanary) {
+        console.log(chalk.gray('  [canary] Skipped (--skip-retrieval-canary): searchability NOT confirmed.'));
+      } else if (allChunks.length > 0) {
+        const canaryChunk = pickCanaryChunk(allChunks, syncFailures);
+        if (canaryChunk) {
+          const canarySpinner = ora('  [canary] Confirming a synced chunk actually retrieves...').start();
+          // TEST SEAM ONLY: options._canaryDelaysMs / options._canarySleep let tests exercise
+          // this path without real wall-clock waits or a live query_knowledge_base backend.
+          // Production callers never set these — runRetrievalCanary defaults to the real
+          // bounded backoff and real timers when they are undefined.
+          const result = await runRetrievalCanary(apiClient, {
+            appId, kbName, chunk: canaryChunk,
+            ...(options._canaryDelaysMs ? { delaysMs: options._canaryDelaysMs } : {}),
+            ...(options._canarySleep ? { sleep: options._canarySleep } : {}),
+          });
+          retrievalCanary = { ...result, checked_at: new Date().toISOString() };
+          if (result.ok) {
+            canarySpinner.succeed(
+              `  [canary] Confirmed searchable after ${(result.elapsedMs / 1000).toFixed(1)}s ` +
+              `(attempt ${result.attempts}/${DEFAULT_CANARY_DELAYS_MS.length})`
+            );
+          } else {
+            canarySpinner.warn(
+              `  [canary] NOT YET SEARCHABLE after ${(result.elapsedMs / 1000).toFixed(1)}s and ` +
+              `${result.attempts} attempt(s)${result.lastError ? ` (last error: ${result.lastError})` : ''}. ` +
+              `The vectors ARE present in Pinecone (reconciled above) but the index has not caught up yet — ` +
+              `this is a known ~20-minute propagation delay after a large upsert/purge. ` +
+              `Re-run 'descix kb corpus sync -a ${appId} -k ${kbName}' later to re-check ` +
+              `(unchanged files are cheap; this canary re-runs).`
+            );
+          }
+          canaryResults.push({ kbName, ...retrievalCanary });
+        } else {
+          console.log(chalk.yellow('  [canary] Skipped: every upsert batch failed, nothing new to confirm.'));
+        }
+      }
+
       // 3g. Save sync state with blob SHAs for future delta computation
       const allSyncedBlobShas = [...localBlobShas]; // All current files
-      await saveSyncState(appRoot, kbName, {
+      await saveSyncState(appRoot, kbName, syncOrigin, {
         last_sync_commit: commitSha,
         // Per-source provenance: WHICH repo, at WHICH ref, and the RESOLVED COMMIT SHA actually
         // synced. `ref` may be a mutable branch, so the ref alone is not a record of what was
@@ -894,7 +937,10 @@ export async function runCorpusSync(apiClient, options) {
         files_unchanged: unchangedCount,
         chunks_upserted: isReportedCount(upserted) ? upserted : null,
         chunks_deleted: isReportedCount(deleted) ? deleted : null,
-        synced_blob_shas: allSyncedBlobShas
+        synced_blob_shas: allSyncedBlobShas,
+        // The retrieval canary's verdict — read this, not `total_chunks`, to know whether the
+        // last sync's content was CONFIRMED searchable or only confirmed present.
+        retrieval_canary: retrievalCanary
       });
 
       totalFilesProcessed += newOrChangedFiles.length;
@@ -935,6 +981,26 @@ export async function runCorpusSync(apiClient, options) {
     const deletedLine = `  Chunks deleted:  ${renderCount(totalFilesDeleted)}`;
     console.log(totalFilesDeleted === 0 ? chalk.gray(deletedLine) : chalk.white(deletedLine));
     console.log('');
+
+    // NEVER A BARE SUCCESS: if any KB's retrieval canary did not confirm searchability, this
+    // command fails loud here rather than letting the green summary above stand as the last
+    // word. The summary itself is left intact (it is a true report of what was written) —
+    // this is a SEPARATE fact ("can it be found yet") that gets its own loud verdict.
+    const unverified = canaryResults.filter((r) => !r.ok);
+    if (unverified.length > 0) {
+      throw new Error(
+        `Sync wrote vectors successfully, but ${unverified.length} KB(s) did NOT confirm ` +
+        `searchable within the canary window:\n` +
+        unverified.map((r) =>
+          `  - ${r.kbName}: not found after ${(r.elapsedMs / 1000).toFixed(1)}s / ${r.attempts} attempt(s)` +
+          (r.lastError ? ` (last error: ${r.lastError})` : '')
+        ).join('\n') +
+        `\nThe vectors ARE present in Pinecone (reconciled above) — this is the store's own ` +
+        `~20-minute post-upsert propagation delay, not data loss. Re-run the same sync command ` +
+        `later to re-check; unchanged files make the re-run cheap and it re-runs this canary.`
+      );
+    }
+
     return { dryRun: false };
 
   } catch (error) {
@@ -976,6 +1042,19 @@ export async function runCorpusStatus(apiClient, options) {
 
     const appRoot = appConfig.absolutePath;
 
+    // Sync state is per-ORIGIN, so status cannot report it without knowing which origin is
+    // being asked about. Resolved from the same client the sync would use — never re-derived
+    // here, which would let status describe one origin while sync wrote another.
+    if (!apiClient) {
+      spinner.fail('Origin required');
+      throw new Error(
+        'corpus status needs an API client to know WHICH origin\'s sync state to report. '
+        + 'Sync state is keyed by origin (see lib/core/syncState.js), so there is no '
+        + 'origin-independent status to print.',
+      );
+    }
+    const statusOrigin = await apiClient.ensureBaseUrl();
+
     // Load manifests
     const manifests = await loadManifests(appRoot, workspaceRoot, options.kb || null);
 
@@ -992,11 +1071,20 @@ export async function runCorpusStatus(apiClient, options) {
       const refResolution = resolveRef(rawManifest, options.ref || null);
       const manifest = refResolution.manifest;
       const kbName = manifest.kb_name;
-      const syncState = await loadSyncState(appRoot, kbName);
+      // Status reports state for ONE origin — the one this invocation is pointed at. A status
+      // that merged or guessed across origins would be the same unscoped claim the state file
+      // used to make.
+      const loadedState = await loadSyncState(appRoot, kbName, statusOrigin);
+      const syncState = loadedState.state;
 
       console.log(chalk.cyan(`\nCorpus Status: ${appId} / ${kbName}`));
       console.log(chalk.gray('─'.repeat(50)));
+      console.log(chalk.white(`  Origin:          ${statusOrigin}`));
       console.log(chalk.white(`  Resolved ref:    ${refResolution.resolvedRef} (source=${refResolution.source})`));
+      if (loadedState.reason === 'unkeyed-legacy' || loadedState.reason === 'origin-mismatch') {
+        console.log(chalk.yellow(`  ⚠ No sync state for this origin.`));
+        console.log(chalk.gray(`    ${loadedState.detail}`));
+      }
 
       // File count from a fresh walk so the operator sees the LIVE file count
       // at the resolved ref, not the count from the last sync. This is the
@@ -1017,11 +1105,32 @@ export async function runCorpusStatus(apiClient, options) {
       console.log(chalk.white(`  Last sync:       ${syncState.timestamp}`));
       console.log(chalk.white(`  Commit:          ${syncState.last_sync_commit?.substring(0, 8) || 'unknown'}`));
       console.log(chalk.white(`  Files tracked:   ${syncState.synced_files_count}`));
+      // NAME THE SOURCE OF THIS NUMBER: this is a LOCAL RECORD of what the store reported
+      // AT THE TIME OF THE LAST SYNC's reconcile — not a fresh read of the store now. It can be
+      // stale (the store's contents can change from other syncs/purges) and, even when fresh,
+      // "present" is not "searchable" (see the Retrieval line below). `descix kb doctor -a
+      // <app> -k <kb> --live` reads Pinecone directly for the current truth.
       console.log(chalk.white(
-        `  Chunks in store: ${Number.isFinite(syncState.total_chunks)
+        `  Chunks (local record, as of last sync): ${Number.isFinite(syncState.total_chunks)
           ? syncState.total_chunks
           : 'unknown (the last sync reported no live count)'}`
       ));
+      // Retrieval canary verdict from the last sync (see RetrievalCanary.js) — the only field
+      // in this file that speaks to SEARCHABILITY rather than presence.
+      const canary = syncState.retrieval_canary;
+      if (canary === undefined) {
+        console.log(chalk.gray('  Retrieval:       unknown (synced before the retrieval-canary check existed)'));
+      } else if (canary === null) {
+        console.log(chalk.gray('  Retrieval:       not checked (last sync upserted nothing new)'));
+      } else if (canary.ok) {
+        console.log(chalk.green(`  Retrieval:       CONFIRMED searchable (as of last sync, ${canary.checked_at})`));
+      } else {
+        console.log(chalk.yellow(
+          `  Retrieval:       NOT CONFIRMED as of last sync (${canary.checked_at}) — vectors were ` +
+          `present but did not retrieve within the canary window. Re-run 'descix kb corpus sync ` +
+          `-a ${appId} -k ${kbName}' to re-check.`
+        ));
+      }
 
       // Quick change detection: walk and compare blob SHAs
       if (options.verbose) {

package/lib/commands/kb.js

@@ -33,6 +33,7 @@ import * as driveADC from '../google-storage-adc.js';
 // commands' next steps are read by a developer as instructions, so they must name the live verb
 // and nothing else.
 import { CANONICAL_KB_SYNC } from './retired-kb-sync.js';
+import { loadSyncState, syncStatePath } from '../core/syncState.js';
 
 // ============ Pull Command ============
 
@@ -346,24 +347,24 @@ export async function runKbDoctor(apiClient, options) {
     }
   }
 
-  // (b) Local sync-state total_chunks
-  const syncStatePath = path.join(appRoot, '.descix', 'sync-state', `${kbName}.json`);
-  let localChunks = null;
-  let syncStateRaw = null;
-  try {
-    const raw = await fs.readFile(syncStatePath, 'utf-8');
-    syncStateRaw = JSON.parse(raw);
-    localChunks = syncStateRaw?.total_chunks;
-    if (typeof localChunks !== 'number') {
-      throw new Error(`sync-state has no total_chunks: ${syncStatePath}`);
-    }
-  } catch (err) {
-    if (err.code === 'ENOENT') {
-      console.log(chalk.yellow(`  ⚠ No local sync-state at ${syncStatePath}`));
-      console.log(chalk.gray(`    Run 'descix kb corpus sync -a ${appId} -k ${kbName}' first.`));
-      process.exit(2);
-    }
-    throw err;
+  // (b) Local sync-state total_chunks, for THIS ORIGIN.
+  //
+  // The path is resolved by its owner (lib/core/syncState.js), never rebuilt here: doctor
+  // compares a LOCAL record against a LIVE store, so reading one origin's state while querying
+  // another's store would manufacture the very drift this command exists to detect.
+  const doctorOrigin = await apiClient.ensureBaseUrl();
+  const statePathForOrigin = syncStatePath(appRoot, kbName, doctorOrigin);
+  const loadedState = await loadSyncState(appRoot, kbName, doctorOrigin);
+  const syncStateRaw = loadedState.state;
+  if (!syncStateRaw) {
+    console.log(chalk.yellow(`  ⚠ No local sync-state for ${doctorOrigin} at ${statePathForOrigin}`));
+    if (loadedState.detail) console.log(chalk.gray(`    ${loadedState.detail}`));
+    console.log(chalk.gray(`    Run 'descix kb corpus sync -a ${appId} -k ${kbName}' against this origin first.`));
+    process.exit(2);
+  }
+  const localChunks = syncStateRaw.total_chunks;
+  if (typeof localChunks !== 'number') {
+    throw new Error(`sync-state has no total_chunks: ${statePathForOrigin}`);
   }
 
   // (c) Report

package/lib/core/RetrievalCanary.js

@@ -0,0 +1,128 @@
+/**
+ * RetrievalCanary — a corpus sync does not report success until a KNOWN chunk it just
+ * wrote actually RETRIEVES from the store.
+ *
+ * MEASURED 2026-09-17: `descix kb corpus sync --rebuild` purges and re-upserts, then
+ * reports success and a reconciled live count, while the PROD search index takes ~20
+ * minutes to catch up. Every status surface said healthy over a KB that returned zero
+ * results for hours. The reconcile step (`get_kb_rag_status {reconcile:true}`, driven from
+ * `corpus.js::runCorpusSync`) counts by Pinecone ID PREFIX — presence, not searchability —
+ * so a clean reconcile is not evidence the index can answer a query yet.
+ *
+ * THE CANARY: after upserting, pick ONE chunk that was actually upserted (never one from a
+ * failed batch), run `query_knowledge_base` scoped to that chunk's own document
+ * (`file_filter`) using the chunk's own text as the query, and check the result set for a
+ * row whose metadata identifies THIS chunk (blob_sha + chunk_idx — the two fields
+ * `corpus.js::chunkCorpusFile` always writes, so this needs no second identity scheme).
+ *
+ * BOUNDED, NOT A LOOP: `query_knowledge_base` is a real, credit-metered read (WS-HEADLESS-MVP-A3
+ * flat debit per call). A canary that polled every few seconds for the full ~20-minute
+ * propagation window would multiply that cost by hundreds of calls for a single sync. This
+ * canary makes a SMALL, FIXED number of attempts (`DEFAULT_CANARY_DELAYS_MS`, 3 calls across
+ * ~25s) — enough to catch the common case where the index catches up quickly — and REFUSES to
+ * claim success if it does not, rather than waiting out the full window synchronously inside a
+ * CLI command. See corpus.js's hand-back for the case this does not close and the remedy it
+ * names when it doesn't (re-run the sync; unchanged blob SHAs make the re-run cheap and it
+ * re-runs this same canary).
+ */
+
+/** Fixed, small backoff schedule — see the module doc for why this is bounded, not a loop. */
+export const DEFAULT_CANARY_DELAYS_MS = [3000, 7000, 15000];
+
+/** Pinecone metadata budget note in chunkCorpusFile caps chunk text at 35000 bytes; a canary
+ * query only needs enough text to be a near-exact self-match, so it is truncated far below that
+ * — a long query costs more to embed for no better discrimination.
+ */
+const MAX_CANARY_QUERY_CHARS = 300;
+
+/**
+ * The query text for a canary check: the chunk's own text is guaranteed to retrieve itself
+ * with the highest similarity of anything in the index, so no second corpus of "known good"
+ * queries is needed.
+ *
+ * @param {{text: string}} chunk
+ * @returns {string}
+ */
+export function canaryQueryText(chunk) {
+    return String(chunk.text || '').trim().slice(0, MAX_CANARY_QUERY_CHARS);
+}
+
+/**
+ * Does this `query_knowledge_base` result row identify the given chunk?
+ *
+ * Matches on `blob_sha` + `chunk_idx` — the two fields `chunkCorpusFile()` always writes as
+ * Pinecone metadata, content-addressed and stable regardless of any server-side text
+ * normalization. This is the SAME identity the sync's own delta computation uses, not a
+ * second one invented for this check.
+ *
+ * @param {{metadata?: Record<string, any>}} row - one row of `query_knowledge_base`'s `results`
+ * @param {{blob_sha: string, chunk_idx: number}} chunk
+ * @returns {boolean}
+ */
+export function chunkMatchesCanary(row, chunk) {
+    const md = row?.metadata || {};
+    return md.blob_sha === chunk.blob_sha && md.chunk_idx === chunk.chunk_idx;
+}
+
+/**
+ * Pick one upserted chunk to canary-check: the first chunk that was NOT part of a batch the
+ * store reported as failed. Returns null when there is nothing safe to check (every batch
+ * failed) — the caller's existing batch-failure reporting already covers that case loudly;
+ * this module does not re-report it.
+ *
+ * @param {Array<{id: string}>} allChunks - every chunk this sync attempted to upsert
+ * @param {Array<{chunks: string[]}>} syncFailures - failed batches, each naming its chunk ids
+ * @returns {object|null}
+ */
+export function pickCanaryChunk(allChunks, syncFailures) {
+    const failedIds = new Set((syncFailures || []).flatMap((f) => f.chunks || []));
+    return allChunks.find((c) => !failedIds.has(c.id)) || null;
+}
+
+/**
+ * Run the bounded-backoff retrieval canary against a freshly-upserted chunk.
+ *
+ * @param {object} apiClient - an initialized DeSciXApiClient
+ * @param {object} args
+ * @param {string} args.appId
+ * @param {string} args.kbName
+ * @param {object} args.chunk - one entry from `allChunks` (must carry text/file_id/blob_sha/chunk_idx)
+ * @param {number[]} [args.delaysMs] - injectable for tests; production default is
+ *        DEFAULT_CANARY_DELAYS_MS
+ * @param {(ms: number) => Promise<void>} [args.sleep] - injectable for tests (real timers by default)
+ * @returns {Promise<{ok: boolean, attempts: number, elapsedMs: number, lastError: string|null}>}
+ */
+export async function runRetrievalCanary(apiClient, {
+    appId, kbName, chunk,
+    delaysMs = DEFAULT_CANARY_DELAYS_MS,
+    sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+}) {
+    const startedAt = Date.now();
+    let attempts = 0;
+    let lastError = null;
+
+    for (const delay of delaysMs) {
+        attempts++;
+        await sleep(delay);
+        try {
+            const resp = await apiClient.invoke('query_knowledge_base', {
+                app_id: appId,
+                kb_id: kbName,
+                query: canaryQueryText(chunk),
+                limit: 5,
+                file_filter: chunk.file_id,
+            }, { allowGuest: false });
+            const data = resp?.message || resp;
+            const results = data?.results || [];
+            if (results.some((row) => chunkMatchesCanary(row, chunk))) {
+                return { ok: true, attempts, elapsedMs: Date.now() - startedAt, lastError: null };
+            }
+        } catch (err) {
+            // A transient failure on ONE attempt does not end the canary early — the schedule is
+            // already bounded by delaysMs.length, so this is not an unbounded retry-on-error loop.
+            lastError = err.message;
+        }
+    }
+
+    return { ok: false, attempts, elapsedMs: Date.now() - startedAt, lastError };
+}

package/lib/core/syncState.js

@@ -0,0 +1,144 @@
+/**
+ * syncState — THE owner of where a KB's local sync state lives, and which ORIGIN it describes.
+ *
+ * ── The defect this closes (measured 2026-09-17, two apps) ───────────────────
+ * State used to live at `.descix/sync-state/<KB>.json` — one file per KB NAME, with no
+ * environment and no origin anywhere in the path or the payload. `corpus sync` skips a file
+ * when its blob SHA appears in that state, and nothing asked WHICH ORIGIN had received those
+ * SHAs. Syncing one KB to two environments therefore produced two failures from one cause:
+ *
+ *   UNDER-SYNC  the second origin skips files it never received, as "unchanged"
+ *   BLINDING    the first origin's drift becomes invisible, because the second origin's
+ *               commit was written over the shared state — a stale KB reporting healthy
+ *
+ * Measured: GodsWorld on DEV took 2 of 8 files and then reported PROD clean ("Drift: NONE")
+ * over a PROD KB two files behind. Independently, daita/General's one state file described
+ * DEV (886 chunks, matching DEV's 886 vectors) while PROD sat on a different corpus (2545
+ * vectors, 2026-05-29); a PROD dry-run against it declared 43 files "Unchanged" that PROD had
+ * never received at those SHAs.
+ *
+ * ── The fix ─────────────────────────────────────────────────────────────────
+ * State is keyed by the ORIGIN the sync actually talked to — the same fact `lib/origin.js`
+ * owns and that every MCP result is stamped with. The origin is used because it is the fact
+ * that is ALWAYS available: an env NAME is not (a workspace `env.apiUrl` or a DESCIX_API_URL
+ * carries no label), and keying on a name would also miss a repointed workspace — same label,
+ * different origin — which is the same lie one level up. The full origin is recorded INSIDE
+ * the file as well, so a slug collision is caught rather than trusted.
+ *
+ * ── Migration: an unkeyed file belongs to NOBODY ─────────────────────────────
+ * A legacy `.descix/sync-state/<KB>.json` records a sync to an origin nobody wrote down.
+ * Adopting it for whichever origin asks first would hard-code today's accident as tomorrow's
+ * truth — exactly the bug, re-created by the fix. So it is reported as UNKNOWN-ORIGIN and
+ * forces one full walk, for every origin, and is never read as state and never deleted: it is
+ * the only surviving record of what was synced before keying existed.
+ */
+
+import path from 'path';
+import fs from 'fs/promises';
+
+/** Directory holding every origin's state for an app. */
+export function syncStateRoot(appRoot) {
+  return path.join(appRoot, '.descix', 'sync-state');
+}
+
+/**
+ * A filename-safe token for an origin. ONE derivation, used for the directory name; the exact
+ * origin is recorded in the file, so this only has to be stable and readable, not injective.
+ *
+ * `https://dev.descix.net` -> `dev.descix.net`
+ * `https://localhost:4000` -> `localhost-4000`
+ *
+ * @param {string} origin an absolute http(s) origin, already normalized by lib/origin.js
+ * @returns {string}
+ * @throws {Error} on an empty or non-string origin — a state file keyed by "undefined" is
+ *   exactly the unscoped file this module exists to abolish, so it must never be writable.
+ */
+export function originKey(origin) {
+  if (typeof origin !== 'string' || origin.trim() === '') {
+    throw new Error(
+      'syncState: refusing to key sync state by an empty origin. The caller must pass the '
+      + 'origin the sync actually talked to (apiClient.baseUrl) — an unkeyed state file is the '
+      + 'defect this module exists to prevent.',
+    );
+  }
+  return origin
+    .trim()
+    .replace(/^https?:\/\//, '')
+    .replace(/\/+$/, '')
+    .replace(/[^A-Za-z0-9._-]/g, '-');
+}
+
+/** Where this origin's state for this KB lives. */
+export function syncStatePath(appRoot, kbName, origin) {
+  return path.join(syncStateRoot(appRoot), originKey(origin), `${kbName}.json`);
+}
+
+/**
+ * Where a failed-batch log for this origin lives. Keyed for the same reason the state is: a
+ * failure log named only by KB let a DEV run overwrite the record of which PROD batches failed,
+ * so the surviving file described an environment nobody could identify from it.
+ */
+export function syncFailureLogPath(appRoot, kbName, origin) {
+  return path.join(syncStateRoot(appRoot), originKey(origin), `${kbName}-failures.json`);
+}
+
+/** Where an unkeyed (pre-origin-keying) file would be. Read only to DETECT it. */
+export function legacySyncStatePath(appRoot, kbName) {
+  return path.join(syncStateRoot(appRoot), `${kbName}.json`);
+}
+
+/**
+ * Load the state for THIS origin, or report why there is none.
+ *
+ * @returns {Promise<{state: Object|null, reason: 'loaded'|'first-sync'|'unkeyed-legacy'|'origin-mismatch', detail?: string}>}
+ *   `state` is null for every reason but 'loaded'. A null state means a FULL walk, which is
+ *   always safe: it re-upserts rather than purging, and it is self-correcting.
+ */
+export async function loadSyncState(appRoot, kbName, origin) {
+  const statePath = syncStatePath(appRoot, kbName, origin);
+  try {
+    const parsed = JSON.parse(await fs.readFile(statePath, 'utf-8'));
+    // Defensive: the directory is a slug, the payload is exact. They can only disagree through
+    // a slug collision, and trusting the slug in that case would resurrect the original bug.
+    if (parsed.origin && parsed.origin !== origin) {
+      return {
+        state: null,
+        reason: 'origin-mismatch',
+        detail: `${statePath} records origin ${parsed.origin}, but this sync is talking to ${origin}. `
+          + 'Treating it as no state and walking the full corpus.',
+      };
+    }
+    return { state: parsed, reason: 'loaded' };
+  } catch {
+    // No state for this origin. Is there an unkeyed file from before keying existed?
+    const legacy = legacySyncStatePath(appRoot, kbName);
+    try {
+      await fs.access(legacy);
+      return {
+        state: null,
+        reason: 'unkeyed-legacy',
+        detail: `${legacy} was written before sync state was keyed by origin, so it does not say `
+          + `WHICH environment it describes. It is not being read — this sync walks the full corpus `
+          + `once for ${origin}, and writes its own state at ${statePath}. The old file is left `
+          + `alone as the only record of what came before.`,
+      };
+    } catch {
+      return { state: null, reason: 'first-sync' };
+    }
+  }
+}
+
+/**
+ * Persist state for THIS origin. The origin is written into the payload as well as the path.
+ *
+ * @param {string} appRoot
+ * @param {string} kbName
+ * @param {string} origin
+ * @param {Object} state the same shape as before, minus provenance this function adds
+ */
+export async function saveSyncState(appRoot, kbName, origin, state) {
+  const statePath = syncStatePath(appRoot, kbName, origin);
+  await fs.mkdir(path.dirname(statePath), { recursive: true });
+  await fs.writeFile(statePath, JSON.stringify({ origin, ...state }, null, 2));
+  return statePath;
+}

package/lib/mcp-origin-stamp.js

@@ -0,0 +1,84 @@
+/**
+ * THE ORIGIN STAMP EVERY MCP TOOL RESULT CARRIES.
+ *
+ * MEASURED 2026-09-17: two sessions spent hours investigating a knowledge base as broken.
+ * Both were reading DEV through the MCP connector while believing they were reading PROD,
+ * because tool results said nothing about where they came from. `bin/mcp-server.js` returned
+ * every result as a bare `JSON.stringify(result)` — no origin, no environment. The envelope
+ * carries `community_id`/`app_id`, which READ like provenance and are not: they say which app,
+ * never which deployment of the platform answered.
+ *
+ * By contrast the CLI prints `env: <name> (<source>) <origin>` on EVERY network-bound command,
+ * unprompted (`lib/environment-report.js` `reportEnvironment()`), sourced from the ONE owner of
+ * "which origin did this invocation resolve to" (`lib/origin.js` `resolveOrigin()`, consumed by
+ * `DeSciXApiClient.initialize()` and kept on the client as `baseUrl` + `originSource`).
+ *
+ * This module adds NO second derivation. It reads the SAME two facts the CLI already keeps on
+ * an initialized `DeSciXApiClient` and combines them with the SAME env-name owner
+ * (`environmentNameFor`) the CLI's own status line uses. There is exactly one answer to "what
+ * origin, what environment" for a given client, and every surface — the CLI's stderr line, the
+ * MCP stamp — reads it from here.
+ */
+import { environmentNameFor } from './environment-report.js';
+
+/**
+ * Build the origin stamp for an MCP tool result FROM the one owner: an already-initialized
+ * `DeSciXApiClient`'s `baseUrl` + `originSource` (set once, in `initialize()`, by
+ * `resolveOrigin()` — see `api-client.js`).
+ *
+ * @param {import('./api-client.js').DeSciXApiClient} apiClient - must already be initialized
+ *   (`ensureInitialized()` resolved) so `baseUrl`/`originSource` are populated. Calling this
+ *   before initialization is a caller defect, not a state to paper over with a guess.
+ * @returns {{origin: string, source: string, environment: string}}
+ */
+export function originStampFor(apiClient) {
+    const origin = apiClient?.baseUrl;
+    const source = apiClient?.originSource;
+    if (!origin || !source) {
+        throw new Error(
+            'originStampFor: apiClient has no resolved baseUrl/originSource — ' +
+            'call ensureInitialized() before stamping a result.',
+        );
+    }
+    return { origin, source, environment: environmentNameFor(origin) };
+}
+
+/**
+ * The ONE spelling of the human-visible stamp line. Mirrors `formatEnvLine()`
+ * (`environment-report.js`) in shape so a reader who has seen the CLI's own `env:` line
+ * recognizes this as the same fact, not a second convention.
+ *
+ * @param {{origin: string, source: string, environment: string}} stamp
+ * @returns {string}
+ */
+export function formatOriginStampLine({ origin, source, environment }) {
+    return `[DeSciX origin] env: ${environment} (${source}) ${origin}`;
+}
+
+/**
+ * Attach the origin stamp to an MCP `CallToolResult` — success or error alike.
+ *
+ * TWO PLACES, DELIBERATELY, per the same fact:
+ *   1. An appended `content` block (visible text). This is the fix for the actual measured
+ *      failure: the reader is an LLM/agent consuming the tool's TEXT output, not a program
+ *      inspecting `_meta` — a stamp only a machine can see would not have caught the two
+ *      sessions this closes. The ORIGINAL content entries are left untouched and in place, so
+ *      an existing caller's `JSON.parse(content[0].text)` keeps working exactly as before —
+ *      this only ever APPENDS a new block, never rewrites or reorders the old one.
+ *   2. `_meta.descix_origin` — the MCP-spec extension point (`CallToolResult._meta`, a sibling
+ *      of `content`, not nested inside it) for a programmatic caller that wants the fact as
+ *      structured data without re-parsing the human-readable line.
+ *
+ * @param {{content?: Array<object>, isError?: boolean, [k: string]: any}} result
+ * @param {{origin: string, source: string, environment: string}} stamp
+ * @returns {object} a NEW result object; `result` is not mutated.
+ */
+export function stampToolResult(result, stamp) {
+    const content = Array.isArray(result.content) ? [...result.content] : [];
+    content.push({ type: 'text', text: formatOriginStampLine(stamp) });
+    return {
+        ...result,
+        content,
+        _meta: { ...(result._meta || {}), descix_origin: stamp },
+    };
+}

package/lib/verb-invokes.generated.json

@@ -136,7 +136,8 @@
     "kb_delete_chunks",
     "kb_list_file_ids",
     "kb_sync_chunks",
-    "list_knowledge_bases"
+    "list_knowledge_bases",
+    "query_knowledge_base"
   ],
   "kb delete": [
     "delete_knowledge_base"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@descix/cli",
-  "version": "1.0.10",
+  "version": "1.0.12",
   "description": "DeSciX CLI and MCP Server - Unified command-line interface for DeSciX platform",
   "repository": {
     "type": "git",