shadow backfill: name the stop reason when a scope retires early

A scope that stops with items remaining previously reported only a bare
count; a stall (provider failure/timeout hitting the no-progress guard)
was indistinguishable from an unembeddable-item bug and cost a diagnosis
cycle. Retirement now records drained vs stalled_no_progress, logs the
stall with its usual cause and the resume path, and the manual --shadow
script prints an explicit resume note.

Author: ualtinok

packages/plugin/scripts/backfill-embeddings.ts

@@ -23,6 +23,7 @@ import {
     flushShadowEmbeddingBacklog,
     getProjectEmbeddingSnapshot,
     getShadowBackfillRemaining,
+    getShadowBackfillStopReason,
     registerProjectEmbedding,
     registerProjectShadowEmbedding,
 } from "../src/features/magic-context/memory/embedding";
@@ -104,6 +105,17 @@ async function runShadowBackfill(
         `Done. Embedded ${before.memory - after.memory} memories, ${before.commit - after.commit} commits, ${before.chunk - after.chunk} chunks. ` +
             `Remaining: ${after.memory} memories, ${after.commit} commits, ${after.chunk} chunks.`,
     );
+    // A nonzero remaining count with a stalled stop reason is honest backlog the
+    // provider failed to serve this run, not an unembeddable class — say so, and
+    // say what to do, instead of leaving a bare number that reads like a bug.
+    for (const scope of ["memory", "commit", "chunk"] as const) {
+        if (after[scope] > 0 && getShadowBackfillStopReason(projectIdentity, scope) === "stalled_no_progress") {
+            console.log(
+                `  note: ${scope} stopped early after a no-progress batch (provider failure/timeout). ` +
+                    `Re-run --shadow to resume; progress is banked per item.`,
+            );
+        }
+    }
 }
 
 async function main() {

packages/plugin/src/features/magic-context/project-embedding-registry.ts

@@ -196,6 +196,17 @@ const pendingShadowBackfills = new Map<string, Set<ShadowScope>>();
  * that cannot succeed. Any real progress changes the set and clears the stall.
  */
 const shadowBackfillLastIds = new Map<string, string>();
+/** Why a (project:scope) backfill stopped: "drained" or "stalled_no_progress". */
+const shadowBackfillStopReasons = new Map<string, ShadowBackfillStopReason>();
+export type ShadowBackfillStopReason = "drained" | "stalled_no_progress";
+
+/** Stop reason for a scope's last backfill retirement, for status surfaces. */
+export function getShadowBackfillStopReason(
+    projectIdentity: string,
+    scope: "memory" | "commit" | "chunk",
+): ShadowBackfillStopReason | undefined {
+    return shadowBackfillStopReasons.get(`${projectIdentity}:${scope}`);
+}
 
 const loadUnembeddedMemoriesStatements = new WeakMap<Database, PreparedStatement>();
 const upsertActiveIdentityStatements = new WeakMap<Database, PreparedStatement>();
@@ -1301,13 +1312,25 @@ function pumpShadowBackfill(): void {
                 SHADOW_MAX_ITEMS_PER_TICK,
             );
             if (ids.length === 0) {
+                shadowBackfillStopReasons.set(stallKey, "drained");
                 scopes.delete(scope);
                 shadowBackfillLastIds.delete(stallKey);
                 continue;
             }
             const signature = ids.join(",");
             if (shadowBackfillLastIds.get(stallKey) === signature) {
                 // No progress since the last pump for this scope; stop retrying.
+                // Record WHY so status surfaces can distinguish "honest backlog,
+                // provider was failing" from "nothing left" — a bare remaining
+                // count after a silent stop reads as an unembeddable-item bug and
+                // costs a diagnosis cycle (2026-07-24: 437 chunks, transient
+                // provider timeouts under load, zero recorded reason).
+                shadowBackfillStopReasons.set(stallKey, "stalled_no_progress");
+                log(
+                    `[shadow] backfill scope ${scope} for ${projectIdentity} retired without progress — ` +
+                        `the last batch produced no writes (provider failure or timeout is the usual cause); ` +
+                        `${ids.length}+ items remain and retry on the next registration or manual --shadow run`,
+                );
                 scopes.delete(scope);
                 shadowBackfillLastIds.delete(stallKey);
                 continue;