yaml-flow 5.1.0 → 5.2.1

package/dist/cli/board-live-cards-cli.cjs

@@ -102,15 +102,30 @@ function groupTasksByProvides(candidateTaskNames, tasks) {
 }
 
 // src/event-graph/task-transitions.ts
-function applyTaskStart(state, taskName) {
+function applyTaskStart(state, taskName, graph) {
   const existingTask = state.tasks[taskName] ?? createDefaultGraphEngineStore();
+  const startConsumedHashes = {};
+  if (graph) {
+    const taskConfig = graph.tasks[taskName];
+    const requires = getRequires(taskConfig);
+    for (const token of requires) {
+      for (const [otherName, otherConfig] of Object.entries(graph.tasks)) {
+        if (getProvides(otherConfig).includes(token)) {
+          const otherState = state.tasks[otherName];
+          if (otherState?.lastDataHash) startConsumedHashes[token] = otherState.lastDataHash;
+          break;
+        }
+      }
+    }
+  }
   const updatedTask = {
     ...existingTask,
     status: "running",
     startedAt: (/* @__PURE__ */ new Date()).toISOString(),
     lastUpdated: (/* @__PURE__ */ new Date()).toISOString(),
     progress: 0,
-    error: void 0
+    error: void 0,
+    startConsumedHashes
   };
   return {
     ...state,
@@ -130,16 +145,18 @@ function applyTaskCompletion(state, graph, taskName, result, dataHash, data) {
   } else {
     outputTokens = getProvides(taskConfig);
   }
-  const lastConsumedHashes = { ...existingTask.lastConsumedHashes };
-  const requires = taskConfig.requires ?? [];
-  for (const token of requires) {
-    for (const [otherName, otherConfig] of Object.entries(graph.tasks)) {
-      if (getProvides(otherConfig).includes(token)) {
-        const otherState = state.tasks[otherName];
-        if (otherState?.lastDataHash) {
-          lastConsumedHashes[token] = otherState.lastDataHash;
+  const lastConsumedHashes = existingTask.startConsumedHashes ? { ...existingTask.startConsumedHashes } : { ...existingTask.lastConsumedHashes };
+  if (!existingTask.startConsumedHashes) {
+    const requires = taskConfig.requires ?? [];
+    for (const token of requires) {
+      for (const [otherName, otherConfig] of Object.entries(graph.tasks)) {
+        if (getProvides(otherConfig).includes(token)) {
+          const otherState = state.tasks[otherName];
+          if (otherState?.lastDataHash) {
+            lastConsumedHashes[token] = otherState.lastDataHash;
+          }
+          break;
         }
-        break;
       }
     }
   }
@@ -284,7 +301,7 @@ function applyEvent(live, event) {
   switch (event.type) {
     // --- Execution state transitions ---
     case "task-started":
-      return { config, state: applyTaskStart(state, event.taskName) };
+      return { config, state: applyTaskStart(state, event.taskName, config) };
     case "task-completed":
       return { config, state: applyTaskCompletion(state, config, event.taskName, event.result, event.dataHash, event.data) };
     case "task-failed":
@@ -1112,13 +1129,29 @@ function validateNode(node) {
     if (!Array.isArray(n.sources)) {
       errors.push("sources: must be an array");
     } else {
+      const bindTos = /* @__PURE__ */ new Set();
+      const outputFiles = /* @__PURE__ */ new Set();
       n.sources.forEach((src, i) => {
         if (!src || typeof src !== "object" || Array.isArray(src)) {
           errors.push(`sources[${i}]: must be an object`);
         } else {
           const s = src;
-          if (typeof s.bindTo !== "string" || !s.bindTo) errors.push(`sources[${i}]: missing required "bindTo" property`);
-          if (s.outputFile != null && typeof s.outputFile !== "string") errors.push(`sources[${i}]: outputFile must be a string`);
+          if (typeof s.bindTo !== "string" || !s.bindTo) {
+            errors.push(`sources[${i}]: missing required "bindTo" property`);
+          } else {
+            if (bindTos.has(s.bindTo)) {
+              errors.push(`sources[${i}]: bindTo "${s.bindTo}" is not unique across sources`);
+            }
+            bindTos.add(s.bindTo);
+          }
+          if (typeof s.outputFile !== "string" || !s.outputFile) {
+            errors.push(`sources[${i}]: missing required "outputFile" property`);
+          } else {
+            if (outputFiles.has(s.outputFile)) {
+              errors.push(`sources[${i}]: outputFile "${s.outputFile}" is not unique across sources`);
+            }
+            outputFiles.add(s.outputFile);
+          }
           if (s.optionalForCompletionGating != null && typeof s.optionalForCompletionGating !== "boolean") {
             errors.push(`sources[${i}]: optionalForCompletionGating must be a boolean`);
           }
@@ -1176,12 +1209,15 @@ var CardCompute = {
 var BOARD_FILE = "board-graph.json";
 var JOURNAL_FILE = "board-journal.jsonl";
 var TASK_EXECUTOR_LOG_FILE = "task-executor.jsonl";
+var INFERENCE_ADAPTER_LOG_FILE = "inference-adapter.jsonl";
 var INVENTORY_FILE = "cards-inventory.jsonl";
 var RUNTIME_OUT_FILE = ".runtime-out";
 var DEFAULT_RUNTIME_OUT_DIR = "runtime-out";
 var RUNTIME_STATUS_FILE = "board-livegraph-status.json";
 var RUNTIME_CARDS_DIR = "cards";
 var RUNTIME_DATA_OBJECTS_DIR = "data-objects";
+var INFERENCE_ADAPTER_FILE = ".inference-adapter";
+var DEFAULT_TASK_COMPLETION_RULE = "all_required_sources_fetched";
 var EMPTY_CONFIG = { settings: { completion: "manual", refreshStrategy: "data-changed" }, tasks: {} };
 var BoardJournal = class {
   journalPath;
@@ -1389,6 +1425,39 @@ function decodeSourceToken(token) {
     return null;
   }
 }
+function markRequested(entry, requestedAt) {
+  entry.lastRequestedAt = requestedAt;
+}
+function markFetchFailed(entry, reason) {
+  entry.lastError = reason;
+  delete entry.lastFetchedAt;
+}
+function markFetchCompleted(entry, fetchedAt) {
+  entry.lastFetchedAt = fetchedAt;
+  delete entry.lastError;
+}
+function isSourceInFlight(entry) {
+  if (!entry?.lastRequestedAt) return false;
+  return !entry.lastFetchedAt || entry.lastFetchedAt < entry.lastRequestedAt;
+}
+function decideSourceAction(entry, queueRequestedAt) {
+  if (!entry?.lastRequestedAt) return "dispatch";
+  const inFlight = isSourceInFlight(entry);
+  if (inFlight) return "in-flight";
+  if (!entry.lastFetchedAt) return "dispatch";
+  if (entry.lastFetchedAt < queueRequestedAt) return "dispatch";
+  return "idle";
+}
+function nextEntryAfterFetchDelivery(entry, fetchedAt) {
+  const next = { ...entry };
+  markFetchCompleted(next, fetchedAt);
+  return next;
+}
+function nextEntryAfterFetchFailure(entry, reason) {
+  const next = { ...entry };
+  markFetchFailed(next, reason);
+  return next;
+}
 function runtimePath(boardDir, cardId) {
   return path__namespace.join(boardDir, `${cardId}.runtime.json`);
 }
@@ -1543,6 +1612,15 @@ function splitCommandLine(command) {
   if (current) tokens.push(current);
   return tokens;
 }
+function resolveCommandInvocation(rawCmd, rawArgs) {
+  if (/^(node|node\.exe)$/i.test(rawCmd)) {
+    return { cmd: process.execPath, args: rawArgs };
+  }
+  if (/\.m?js$/i.test(rawCmd)) {
+    return { cmd: process.execPath, args: [rawCmd, ...rawArgs] };
+  }
+  return { cmd: rawCmd, args: rawArgs };
+}
 function spawnDetachedProcessAccumulatedWorker(boardDir) {
   const { cmd, args: cliArgs } = getCliInvocation("process-accumulated-events", ["--rg", boardDir, "--inline-loop"]);
   try {
@@ -1618,7 +1696,18 @@ function getCliInvocation(command, args) {
   return { cmd: npxCmd, args: ["tsx", tsPath, command, ...args] };
 }
 function invokeRunSources(boardDir, cardPath, callbackToken, callback) {
-  const { cmd, args } = getCliInvocation("run-sources-internal", ["--card", cardPath, "--token", callbackToken, "--rg", boardDir]);
+  const args = ["--card", cardPath, "--token", callbackToken, "--rg", boardDir];
+  const { cmd, args: cmdArgs } = getCliInvocation("run-sources-internal", args);
+  try {
+    spawnDetachedCommand(cmd, cmdArgs);
+    callback(null);
+  } catch (err) {
+    callback(err instanceof Error ? err : new Error(String(err)));
+  }
+}
+function invokeRunInference(boardDir, cardId, inputFile, callbackToken, checksum, callback) {
+  const inferenceToken = encodeSourceToken({ cbk: callbackToken, rg: boardDir, cid: cardId, b: "", d: "", cs: checksum });
+  const { cmd, args } = getCliInvocation("run-inference-internal", ["--in", inputFile, "--token", inferenceToken]);
   try {
     spawnDetachedCommand(cmd, args);
     callback(null);
@@ -1626,10 +1715,11 @@ function invokeRunSources(boardDir, cardPath, callbackToken, callback) {
     callback(err instanceof Error ? err : new Error(String(err)));
   }
 }
-function appendTaskExecutorLog(boardDir, hydratedSource) {
+function appendTaskExecutorLog(boardDir, hydratedSource, mode) {
   try {
     const entry = {
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      mode,
       hydratedSource
     };
     fs__namespace.appendFileSync(path__namespace.join(boardDir, TASK_EXECUTOR_LOG_FILE), JSON.stringify(entry) + "\n", "utf-8");
@@ -1637,6 +1727,18 @@ function appendTaskExecutorLog(boardDir, hydratedSource) {
     console.error(`[task-executor-log] append failed: ${logErr instanceof Error ? logErr.message : String(logErr)}`);
   }
 }
+function appendInferenceAdapterLog(boardDir, cardId, payload) {
+  try {
+    const entry = {
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      cardId,
+      payload
+    };
+    fs__namespace.appendFileSync(path__namespace.join(boardDir, INFERENCE_ADAPTER_LOG_FILE), JSON.stringify(entry) + "\n", "utf-8");
+  } catch (logErr) {
+    console.error(`[inference-adapter-log] append failed: ${logErr instanceof Error ? logErr.message : String(logErr)}`);
+  }
+}
 function invokeSourceDataFetched(sourceToken, tmpFile, callback) {
   const { cmd, args } = getCliInvocation("source-data-fetched", ["--tmp", tmpFile, "--token", sourceToken]);
   execCommandAsync(cmd, args, (err, stdout, stderr) => {
@@ -1665,22 +1767,33 @@ function createBoardReactiveGraph(boardDir) {
       const requiredSources = allSources.filter((s) => s.optionalForCompletionGating !== true);
       const runtime = readRuntimeState(boardDir, cardId);
       let runtimeDirty = false;
+      const currentExecutionCount = input.taskState?.executionCount ?? 0;
+      if (typeof runtime._lastExecutionCount === "number" && runtime._lastExecutionCount !== currentExecutionCount) {
+        runtime._sources = {};
+        runtime._inferenceEntry = void 0;
+      }
+      if (runtime._lastExecutionCount !== currentExecutionCount) {
+        runtime._lastExecutionCount = currentExecutionCount;
+        runtimeDirty = true;
+      }
       if (input.update) {
         const u = input.update;
-        const bindTo = u.bindTo;
-        if (!runtime._sources[bindTo]) runtime._sources[bindTo] = {};
-        if (u.failure) {
-          runtime._sources[bindTo].lastError = u.reason ?? "unknown";
-          delete runtime._sources[bindTo].lastFetchedAt;
-          runtimeDirty = true;
-          console.log(`[card-handler] source "${bindTo}" fetch failed: ${runtime._sources[bindTo].lastError}`);
-        } else {
-          runtime._sources[bindTo].lastFetchedAt = u.fetchedAt ?? (/* @__PURE__ */ new Date()).toISOString();
-          delete runtime._sources[bindTo].lastError;
-          runtimeDirty = true;
-          console.log(`[card-handler] source "${bindTo}" delivered \u2192 ${u.dest}`);
+        const outputFile = u.outputFile;
+        if (outputFile) {
+          if (!runtime._sources[outputFile]) runtime._sources[outputFile] = {};
+          const entry = runtime._sources[outputFile];
+          if (u.failure) {
+            runtime._sources[outputFile] = nextEntryAfterFetchFailure(entry, u.reason ?? "unknown");
+            runtimeDirty = true;
+          } else {
+            runtime._sources[outputFile] = nextEntryAfterFetchDelivery(
+              entry,
+              u.fetchedAt ?? (/* @__PURE__ */ new Date()).toISOString()
+            );
+            runtimeDirty = true;
+          }
+          if (runtimeDirty) writeRuntimeState(boardDir, cardId, runtime);
         }
-        if (runtimeDirty) writeRuntimeState(boardDir, cardId, runtime);
       }
       const sourcesData = {};
       for (const src of allSources) {
@@ -1722,40 +1835,57 @@ function createBoardReactiveGraph(boardDir) {
         card_id: cardId,
         computed_values: computeNode.computed_values ?? {}
       });
+      const enrichedCard = { ...card };
+      const enrichedSources = CardCompute.enrichSources(
+        Array.isArray(card.sources) ? card.sources : void 0,
+        {
+          requires,
+          sourcesData,
+          computed_values: computeNode.computed_values
+        }
+      );
+      const sourceCwd = path__namespace.dirname(cardPath);
+      enrichedCard.sources = Array.isArray(enrichedSources) ? enrichedSources.map((src) => ({
+        ...src,
+        cwd: typeof src.cwd === "string" && src.cwd ? src.cwd : sourceCwd,
+        boardDir: typeof src.boardDir === "string" && src.boardDir ? src.boardDir : boardDir
+      })) : enrichedSources;
+      const enrichedByOutput = /* @__PURE__ */ new Map();
+      for (const src of Array.isArray(enrichedCard.sources) ? enrichedCard.sources : []) {
+        const outputFile = src.outputFile;
+        if (typeof outputFile === "string" && outputFile) {
+          enrichedByOutput.set(outputFile, src);
+        }
+      }
       const now = (/* @__PURE__ */ new Date()).toISOString();
+      const runQueuedAt = input.update ? void 0 : now;
       const undeliveredRequired = requiredSources.filter((s) => {
-        if (!s.outputFile) return false;
-        const entry = runtime._sources[s.bindTo];
-        if (!entry?.lastRequestedAt) return true;
-        if (!entry.lastFetchedAt) return true;
-        return entry.lastFetchedAt <= entry.lastRequestedAt;
+        const outputFile = s.outputFile;
+        if (typeof outputFile !== "string" || !outputFile) return true;
+        if (!runtime._sources[outputFile]) runtime._sources[outputFile] = {};
+        const entry = runtime._sources[outputFile];
+        if (runQueuedAt) {
+          entry.queueRequestedAt = runQueuedAt;
+          runtimeDirty = true;
+        }
+        const qrt = entry.queueRequestedAt ?? entry.lastRequestedAt ?? now;
+        const action = decideSourceAction(entry, qrt);
+        if (action === "in-flight") return false;
+        return action === "dispatch";
       });
+      if (runtimeDirty) writeRuntimeState(boardDir, cardId, runtime);
       if (undeliveredRequired.length > 0) {
         let stampedAny = false;
         for (const src of undeliveredRequired) {
-          const entry = runtime._sources[src.bindTo] ?? {};
-          if (!entry.lastRequestedAt || entry.lastFetchedAt && entry.lastFetchedAt >= entry.lastRequestedAt) {
-            entry.lastRequestedAt = now;
-            runtime._sources[src.bindTo] = entry;
-            stampedAny = true;
-          }
+          const outputFile = src.outputFile;
+          if (typeof outputFile !== "string" || !outputFile) continue;
+          const entry = runtime._sources[outputFile] ?? {};
+          markRequested(entry, now);
+          runtime._sources[outputFile] = entry;
+          stampedAny = true;
         }
         if (stampedAny) writeRuntimeState(boardDir, cardId, runtime);
-        const enrichedCard = { ...card };
-        const enrichedSources = CardCompute.enrichSources(
-          Array.isArray(card.sources) ? card.sources : void 0,
-          {
-            requires,
-            sourcesData,
-            computed_values: computeNode.computed_values
-          }
-        );
-        const sourceCwd = path__namespace.dirname(cardPath);
-        enrichedCard.sources = Array.isArray(enrichedSources) ? enrichedSources.map((src) => ({
-          ...src,
-          cwd: typeof src.cwd === "string" && src.cwd ? src.cwd : sourceCwd,
-          boardDir: typeof src.boardDir === "string" && src.boardDir ? src.boardDir : boardDir
-        })) : enrichedSources;
+        if (!stampedAny) return "task-initiated";
         const enrichedCardPath = path__namespace.join(os__namespace.tmpdir(), `card-enriched-${cardId}-${Date.now()}.json`);
         fs__namespace.writeFileSync(enrichedCardPath, JSON.stringify(enrichedCard, null, 2), "utf-8");
         invokeRunSources(boardDir, enrichedCardPath, input.callbackToken, (err) => {
@@ -1774,10 +1904,79 @@ function createBoardReactiveGraph(boardDir) {
       for (const { bindTo, src } of providesBindings) {
         data[bindTo] = CardCompute.resolve(computeNode, src);
       }
+      const completionRule = typeof card.when_is_task_completed === "string" && card.when_is_task_completed.trim() ? card.when_is_task_completed.trim() : DEFAULT_TASK_COMPLETION_RULE;
+      const cardData = card.card_data;
+      const llmCompletion = cardData?.llm_task_completion_inference ?? {};
+      const isLlmTaskCompleted = llmCompletion.isTaskCompleted === true;
+      const inferenceEntry = runtime._inferenceEntry ?? {};
+      const inferenceRequestedAt = typeof inferenceEntry.lastRequestedAt === "string" ? inferenceEntry.lastRequestedAt : void 0;
+      const inferenceCompletedAt = typeof llmCompletion.inferenceCompletedAt === "string" ? llmCompletion.inferenceCompletedAt : void 0;
+      const inferencePending = !!inferenceRequestedAt && (!inferenceCompletedAt || inferenceCompletedAt < inferenceRequestedAt);
+      const latestRequiredSourceFetchedAt = requiredSources.reduce((latest, src) => {
+        const fetchedAt = runtime._sources[src.outputFile]?.lastFetchedAt;
+        if (typeof fetchedAt !== "string") return latest;
+        if (!latest || fetchedAt > latest) return fetchedAt;
+        return latest;
+      }, void 0);
+      const shouldRequestInference = !inferenceRequestedAt || !inferenceCompletedAt || !!latestRequiredSourceFetchedAt && latestRequiredSourceFetchedAt > inferenceCompletedAt;
+      if (completionRule !== DEFAULT_TASK_COMPLETION_RULE) {
+        if (isLlmTaskCompleted) ; else if (inferencePending) {
+          return "task-initiated";
+        } else if (!shouldRequestInference) {
+          return "task-initiated";
+        } else {
+          const now2 = (/* @__PURE__ */ new Date()).toISOString();
+          const inferencePayload = {
+            cardId,
+            taskName: input.nodeId,
+            completionRule,
+            context: {
+              requires,
+              sourcesData,
+              computed_values: computeNode.computed_values ?? {},
+              provides: data,
+              card_data: computeNode.card_data ?? {}
+            }
+          };
+          if (runQueuedAt) {
+            inferenceEntry.queueRequestedAt = runQueuedAt;
+            runtimeDirty = true;
+          }
+          const inferenceQrt = inferenceEntry.queueRequestedAt ?? inferenceEntry.lastRequestedAt ?? now2;
+          const inferenceAction = decideSourceAction(inferenceEntry, inferenceQrt);
+          if (inferenceAction === "in-flight") {
+            runtime._inferenceEntry = inferenceEntry;
+            if (runtimeDirty) writeRuntimeState(boardDir, cardId, runtime);
+            return "task-initiated";
+          }
+          if (inferenceAction === "idle") {
+            return "task-initiated";
+          }
+          const inferenceInFile = path__namespace.join(os__namespace.tmpdir(), `card-inference-${cardId}-${Date.now()}.json`);
+          fs__namespace.writeFileSync(inferenceInFile, JSON.stringify(inferencePayload, null, 2), "utf-8");
+          appendInferenceAdapterLog(boardDir, cardId, inferencePayload);
+          markRequested(inferenceEntry, now2);
+          runtime._inferenceEntry = inferenceEntry;
+          runtimeDirty = true;
+          invokeRunInference(boardDir, cardId, inferenceInFile, input.callbackToken, void 0, (err) => {
+            if (err) {
+              console.error(`[card-handler] ${input.nodeId}:`, err.message);
+              const failedAt = (/* @__PURE__ */ new Date()).toISOString();
+              appendEventToJournal(boardDir, {
+                type: "task-failed",
+                taskName: input.nodeId,
+                error: err.message,
+                timestamp: failedAt
+              });
+            }
+          });
+          return "task-initiated";
+        }
+      }
       writeRuntimeDataObjects(boardDir, data);
       const undeliveredOptional = allSources.filter((s) => {
-        if (s.optionalForCompletionGating !== true || !s.outputFile) return false;
-        const entry = runtime._sources[s.bindTo];
+        if (s.optionalForCompletionGating !== true) return false;
+        const entry = runtime._sources[s.outputFile];
         if (!entry?.lastRequestedAt) return true;
         if (!entry.lastFetchedAt) return true;
         return entry.lastFetchedAt <= entry.lastRequestedAt;
@@ -1871,16 +2070,18 @@ function cmdAddCards(args) {
 function cmdInit(args) {
   const dir = args[0];
   if (!dir) {
-    throw new Error("Usage: board-live-cards init <dir> [--task-executor <script>] [--chat-handler <script>] [--runtime-out <dir>]");
+    throw new Error("Usage: board-live-cards init <dir> [--task-executor <script>] [--chat-handler <script>] [--inference-adapter <script>] [--runtime-out <dir>]");
   }
   const teIdx = args.indexOf("--task-executor");
   const taskExecutor = teIdx !== -1 ? args[teIdx + 1] : void 0;
   const chIdx = args.indexOf("--chat-handler");
   const chatHandler = chIdx !== -1 ? args[chIdx + 1] : void 0;
+  const iaIdx = args.indexOf("--inference-adapter");
+  const inferenceAdapter = iaIdx !== -1 ? args[iaIdx + 1] : void 0;
   const roIdx = args.indexOf("--runtime-out");
   const runtimeOut = roIdx !== -1 ? args[roIdx + 1] : void 0;
   if (roIdx !== -1 && !runtimeOut) {
-    throw new Error("Usage: board-live-cards init <dir> [--task-executor <script>] [--chat-handler <script>] [--runtime-out <dir>]");
+    throw new Error("Usage: board-live-cards init <dir> [--task-executor <script>] [--chat-handler <script>] [--inference-adapter <script>] [--runtime-out <dir>]");
   }
   const result = initBoard(dir);
   if (taskExecutor) {
@@ -1889,6 +2090,9 @@ function cmdInit(args) {
   if (chatHandler) {
     fs__namespace.writeFileSync(path__namespace.join(dir, ".chat-handler"), chatHandler, "utf-8");
   }
+  if (inferenceAdapter) {
+    fs__namespace.writeFileSync(path__namespace.join(dir, INFERENCE_ADAPTER_FILE), inferenceAdapter, "utf-8");
+  }
   const runtimeOutDir = configureRuntimeOutDir(dir, runtimeOut);
   const live = loadBoard(dir);
   writeJsonAtomic(resolveStatusSnapshotPath(dir), buildBoardStatusObject(dir, live));
@@ -2124,7 +2328,7 @@ function cmdSourceDataFetched(args) {
     console.error("Invalid source token");
     process.exit(1);
   }
-  const { cbk, rg, cid, b, d } = payload;
+  const { cbk, rg, cid, b, d, cs } = payload;
   const destPath = path__namespace.join(rg, d);
   fs__namespace.mkdirSync(path__namespace.dirname(destPath), { recursive: true });
   fs__namespace.renameSync(tmpFile, destPath);
@@ -2138,7 +2342,7 @@ function cmdSourceDataFetched(args) {
   appendEventToJournal(rg, {
     type: "task-progress",
     taskName: cbkDecoded.taskName,
-    update: { bindTo: b, fetchedAt, dest: d },
+    update: { bindTo: b, outputFile: d, fetchedAt, sourceChecksum: cs },
     timestamp: fetchedAt
   });
   void processAccumulatedEventsInfinitePass(rg);
@@ -2157,7 +2361,7 @@ function cmdSourceDataFetchFailure(args) {
     console.error("Invalid source token");
     process.exit(1);
   }
-  const { cbk, rg, cid, b } = payload;
+  const { cbk, rg, cid, b, d, cs } = payload;
   console.log(`[source-data-fetch-failure] ${cid}.${b}: ${reason}`);
   const cbkDecoded = decodeCallbackToken2(cbk);
   if (!cbkDecoded) {
@@ -2168,7 +2372,7 @@ function cmdSourceDataFetchFailure(args) {
   appendEventToJournal(rg, {
     type: "task-progress",
     taskName: cbkDecoded.taskName,
-    update: { bindTo: b, failure: true, reason },
+    update: { bindTo: b, outputFile: d, failure: true, reason, sourceChecksum: cs },
     timestamp
   });
   void processAccumulatedEventsInfinitePass(rg);
@@ -2177,11 +2381,14 @@ function cmdRunSources(args) {
   const cardIdx = args.indexOf("--card");
   const tokenIdx = args.indexOf("--token");
   const rgIdx = args.indexOf("--rg");
+  const sourceChecksumsIdx = args.indexOf("--source-checksums");
   const cardFilePath = cardIdx !== -1 ? args[cardIdx + 1] : void 0;
   const callbackToken = tokenIdx !== -1 ? args[tokenIdx + 1] : void 0;
   const boardDir = rgIdx !== -1 ? args[rgIdx + 1] : void 0;
+  const sourceChecksumsJson = sourceChecksumsIdx !== -1 ? args[sourceChecksumsIdx + 1] : void 0;
+  const sourceChecksums = sourceChecksumsJson ? JSON.parse(sourceChecksumsJson) : void 0;
   if (!cardFilePath || !callbackToken || !boardDir) {
-    console.error("Usage: board-live-cards run-sources-internal --card <path> --token <token> --rg <dir>");
+    console.error("Usage: board-live-cards run-sources-internal --card <path> --token <token> --rg <dir> [--source-checksums <json>]");
     process.exit(1);
   }
   const card = JSON.parse(fs__namespace.readFileSync(cardFilePath, "utf-8"));
@@ -2195,12 +2402,14 @@ function cmdRunSources(args) {
   const executorFile = path__namespace.join(boardDir, ".task-executor");
   const taskExecutor = fs__namespace.existsSync(executorFile) ? fs__namespace.readFileSync(executorFile, "utf-8").trim() : void 0;
   function runSource(src) {
+    const sourceChecksumForInvoke = src.outputFile ? sourceChecksums?.[src.outputFile] : void 0;
     const sourceToken = encodeSourceToken({
       cbk: callbackToken,
       rg: boardDir,
       cid: card.id,
       b: src.bindTo,
-      d: src.outputFile ?? ""
+      d: src.outputFile ?? "",
+      cs: sourceChecksumForInvoke
     });
     function reportFailure(reason) {
       invokeSourceDataFetchFailure(sourceToken, reason, (err) => {
@@ -2224,7 +2433,7 @@ function cmdRunSources(args) {
         cwd: typeof src.cwd === "string" && src.cwd ? src.cwd : path__namespace.dirname(cardFilePath || ""),
         boardDir: typeof src.boardDir === "string" && src.boardDir ? src.boardDir : boardDir
       };
-      appendTaskExecutorLog(boardDir, sourceForExecutor);
+      appendTaskExecutorLog(boardDir, sourceForExecutor, "external-task-executor");
       fs__namespace.writeFileSync(inFile, JSON.stringify(sourceForExecutor, null, 2), "utf-8");
       console.log(`[run-sources-internal] task-executor: ${taskExecutor} run-source-fetch --in ${inFile} --out ${outFile2} --err ${errFile}`);
       try {
@@ -2262,6 +2471,12 @@ function cmdRunSources(args) {
     const timeout = src.timeout ?? 12e4;
     const sourceCwd = typeof src.cwd === "string" ? src.cwd : path__namespace.dirname(cardFilePath || "");
     const sourceBoardDir = typeof src.boardDir === "string" ? src.boardDir : boardDir;
+    const sourceForBuiltInExecutor = {
+      ...src,
+      cwd: sourceCwd,
+      boardDir: sourceBoardDir
+    };
+    appendTaskExecutorLog(boardDir, sourceForBuiltInExecutor, "built-in-run-source-fetch");
     const cmdParts = splitCommandLine(src.cli);
     if (cmdParts.length === 0) {
       const errMsg = "source.cli command is empty";
@@ -2270,8 +2485,7 @@ function cmdRunSources(args) {
       return;
     }
     const rawCmd = cmdParts[0];
-    const cmd = /^(node|node\.exe)$/i.test(rawCmd) ? process.execPath : rawCmd;
-    const cliArgs = cmdParts.slice(1);
+    const { cmd, args: cliArgs } = resolveCommandInvocation(rawCmd, cmdParts.slice(1));
     let stdout;
     try {
       stdout = execCommandSync(cmd, cliArgs, {
@@ -2298,6 +2512,181 @@ function cmdRunSources(args) {
     runSource(src);
   }
 }
+function cmdTaskProgress(args) {
+  const rgIdx = args.indexOf("--rg");
+  const tokenIdx = args.indexOf("--token");
+  const updateIdx = args.indexOf("--update");
+  const dir = rgIdx !== -1 ? args[rgIdx + 1] : void 0;
+  const token = tokenIdx !== -1 ? args[tokenIdx + 1] : void 0;
+  const updateJson = updateIdx !== -1 ? args[updateIdx + 1] : "{}";
+  if (!dir || !token) {
+    console.error("Usage: board-live-cards task-progress --rg <dir> --token <token> [--update <json>]");
+    process.exit(1);
+  }
+  const decoded = decodeCallbackToken2(token);
+  if (!decoded) {
+    console.error("Invalid callback token");
+    process.exit(1);
+  }
+  const update = updateJson ? JSON.parse(updateJson) : {};
+  appendEventToJournal(dir, {
+    type: "task-progress",
+    taskName: decoded.taskName,
+    update,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  });
+  void processAccumulatedEventsInfinitePass(dir);
+}
+function cmdRunInference(args) {
+  const inIdx = args.indexOf("--in");
+  const tokenIdx = args.indexOf("--token");
+  const inFile = inIdx !== -1 ? args[inIdx + 1] : void 0;
+  const inferenceToken = tokenIdx !== -1 ? args[tokenIdx + 1] : void 0;
+  if (!inFile || !inferenceToken) {
+    console.error("Usage: board-live-cards run-inference-internal --in <input.json> --token <inference-token>");
+    process.exit(1);
+  }
+  const decodedToken = decodeSourceToken(inferenceToken);
+  if (!decodedToken) {
+    console.error("Invalid inference token");
+    process.exit(1);
+  }
+  const callbackToken = decodedToken.cbk;
+  const boardDir = decodedToken.rg;
+  const cbkDecoded = decodeCallbackToken2(callbackToken);
+  if (!cbkDecoded) {
+    console.error("Invalid callback token embedded in inference token");
+    process.exit(1);
+  }
+  function spawnInferenceDone(tmpFile) {
+    const { cmd, args: cliArgs } = getCliInvocation("inference-done", ["--tmp", tmpFile, "--token", inferenceToken]);
+    spawnDetachedCommand(cmd, cliArgs);
+  }
+  function spawnInferenceDoneError(reason) {
+    const tmpFile = path__namespace.join(os__namespace.tmpdir(), `card-inference-err-${Date.now()}.json`);
+    fs__namespace.writeFileSync(tmpFile, JSON.stringify({ isTaskCompleted: false, reason }), "utf-8");
+    spawnInferenceDone(tmpFile);
+  }
+  if (!fs__namespace.existsSync(inFile)) {
+    spawnInferenceDoneError(`inference input not found: ${inFile}`);
+    return;
+  }
+  const adapterFile = path__namespace.join(boardDir, INFERENCE_ADAPTER_FILE);
+  const inferenceAdapter = fs__namespace.existsSync(adapterFile) ? fs__namespace.readFileSync(adapterFile, "utf-8").trim() : void 0;
+  if (!inferenceAdapter) {
+    spawnInferenceDoneError(`inference adapter is not configured (${INFERENCE_ADAPTER_FILE})`);
+    return;
+  }
+  const outFile = path__namespace.join(os__namespace.tmpdir(), `card-inference-out-${Date.now()}.json`);
+  const errFile = path__namespace.join(os__namespace.tmpdir(), `card-inference-err-${Date.now()}.txt`);
+  const adapterParts = splitCommandLine(inferenceAdapter);
+  if (adapterParts.length === 0) {
+    spawnInferenceDoneError("inference adapter command is empty");
+    return;
+  }
+  const adapterRawCmd = adapterParts[0];
+  const adapterRawArgs = adapterParts.slice(1);
+  const { cmd: adapterCmd, args: adapterArgsPrefix } = resolveCommandInvocation(adapterRawCmd, adapterRawArgs);
+  const adapterArgs = [...adapterArgsPrefix, "run-inference", "--in", inFile, "--out", outFile, "--err", errFile];
+  try {
+    execCommandSync(adapterCmd, adapterArgs, {
+      shell: false,
+      timeout: 12e4,
+      cwd: boardDir,
+      env: {
+        ...process.env,
+        BOARD_DIR: boardDir
+      }
+    });
+  } catch (err) {
+    const reason = err.message ?? String(err);
+    spawnInferenceDoneError(reason);
+    return;
+  }
+  if (!fs__namespace.existsSync(outFile)) {
+    const errMsg = fs__namespace.existsSync(errFile) ? fs__namespace.readFileSync(errFile, "utf-8").trim() : "inference adapter produced no output file";
+    spawnInferenceDoneError(errMsg);
+    return;
+  }
+  spawnInferenceDone(outFile);
+}
+function cmdInferenceDone(args) {
+  const tmpIdx = args.indexOf("--tmp");
+  const tokenIdx = args.indexOf("--token");
+  const tmpFile = tmpIdx !== -1 ? args[tmpIdx + 1] : void 0;
+  const inferenceToken = tokenIdx !== -1 ? args[tokenIdx + 1] : void 0;
+  if (!tmpFile || !inferenceToken) {
+    console.error("Usage: board-live-cards inference-done --tmp <result.json> --token <inference-token>");
+    process.exit(1);
+  }
+  const decodedToken = decodeSourceToken(inferenceToken);
+  if (!decodedToken) {
+    console.error("Invalid inference token");
+    process.exit(1);
+  }
+  const { cbk: callbackToken, rg: dir, cs: inputChecksum } = decodedToken;
+  const decoded = decodeCallbackToken2(callbackToken);
+  if (!decoded) {
+    console.error("Invalid callback token embedded in inference token");
+    process.exit(1);
+  }
+  const taskName = decoded.taskName;
+  const cardPath = lookupCardPath(dir, taskName);
+  if (!cardPath) {
+    console.error(`Card file for task "${taskName}" not found in inventory`);
+    process.exit(1);
+  }
+  let result = {};
+  if (fs__namespace.existsSync(tmpFile)) {
+    try {
+      result = JSON.parse(fs__namespace.readFileSync(tmpFile, "utf-8").trim());
+    } catch (err) {
+      result = { isTaskCompleted: false, reason: `failed to parse inference result: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    try {
+      fs__namespace.unlinkSync(tmpFile);
+    } catch {
+    }
+  } else {
+    result = { isTaskCompleted: false, reason: `inference result file not found: ${tmpFile}` };
+  }
+  const isTaskCompletedFlag = result.isTaskCompleted === true;
+  const inferenceCompletedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const card = JSON.parse(fs__namespace.readFileSync(cardPath, "utf-8"));
+  if (!card.card_data) card.card_data = {};
+  const cardData = card.card_data;
+  const existingInference = cardData.llm_task_completion_inference && typeof cardData.llm_task_completion_inference === "object" ? cardData.llm_task_completion_inference : {};
+  cardData.llm_task_completion_inference = {
+    ...existingInference,
+    isTaskCompleted: isTaskCompletedFlag,
+    reason: typeof result.reason === "string" ? result.reason : "",
+    evidence: typeof result.evidence === "string" ? result.evidence : "",
+    inferenceCompletedAt
+  };
+  fs__namespace.writeFileSync(cardPath, JSON.stringify(card, null, 2), "utf-8");
+  const runtimePath2 = path__namespace.join(dir, `${taskName}.runtime.json`);
+  let runtime = { _sources: {} };
+  if (fs__namespace.existsSync(runtimePath2)) {
+    try {
+      runtime = JSON.parse(fs__namespace.readFileSync(runtimePath2, "utf-8"));
+    } catch {
+    }
+  }
+  const inferenceEntry = runtime._inferenceEntry ?? {};
+  runtime._inferenceEntry = nextEntryAfterFetchDelivery(inferenceEntry, inferenceCompletedAt);
+  fs__namespace.writeFileSync(runtimePath2, JSON.stringify(runtime, null, 2), "utf-8");
+  appendEventToJournal(dir, {
+    type: "task-progress",
+    taskName,
+    update: {
+      kind: "inference-done",
+      isTaskCompleted: isTaskCompletedFlag,
+      inputChecksum
+    },
+    timestamp: inferenceCompletedAt
+  });
+  void processAccumulatedEventsInfinitePass(dir);
+}
 function cmdRunSourceFetch(args) {
   const inIdx = args.indexOf("--in");
   const outIdx = args.indexOf("--out");
@@ -2343,8 +2732,7 @@ function cmdRunSourceFetch(args) {
     process.exit(1);
   }
   const rawCmd = cmdParts[0];
-  const cmd = /^(node|node\.exe)$/i.test(rawCmd) ? process.execPath : rawCmd;
-  const cliArgs = cmdParts.slice(1);
+  const { cmd, args: cliArgs } = resolveCommandInvocation(rawCmd, cmdParts.slice(1));
   let stdout;
   try {
     stdout = execCommandSync(cmd, cliArgs, {
@@ -2576,20 +2964,183 @@ async function cli(argv) {
       return cmdTaskCompleted(rest);
     case "task-failed":
       return cmdTaskFailed(rest);
+    case "task-progress":
+      return cmdTaskProgress(rest);
     case "source-data-fetched":
       return cmdSourceDataFetched(rest);
     case "source-data-fetch-failure":
       return cmdSourceDataFetchFailure(rest);
     case "run-sources-internal":
       return cmdRunSources(rest);
+    case "run-inference-internal":
+      return cmdRunInference(rest);
+    case "inference-done":
+      return cmdInferenceDone(rest);
     case "run-source-fetch":
       return cmdRunSourceFetch(rest);
+    case "probe-source":
+      return await cmdProbeSource(rest);
     case "process-accumulated-events":
       return await cmdTryDrain(rest);
     default:
       throw new Error(`Unknown command: ${cmd ?? "(none)"}`);
   }
 }
+async function cmdProbeSource(args) {
+  const cardIdx = args.indexOf("--card");
+  const sourceIdxArg = args.indexOf("--source-idx");
+  const sourceBindArg = args.indexOf("--source-bind");
+  const mockReqIdx = args.indexOf("--mock-requires");
+  const rgIdx = args.indexOf("--rg");
+  const outIdx = args.indexOf("--out");
+  const cardFilePath = cardIdx !== -1 ? args[cardIdx + 1] : void 0;
+  const sourceIdxVal = sourceIdxArg !== -1 ? parseInt(args[sourceIdxArg + 1], 10) : 0;
+  const sourceBindVal = sourceBindArg !== -1 ? args[sourceBindArg + 1] : void 0;
+  const mockReqRaw = mockReqIdx !== -1 ? args[mockReqIdx + 1] : void 0;
+  const boardDirArg = rgIdx !== -1 ? args[rgIdx + 1] : void 0;
+  const outFile = outIdx !== -1 ? args[outIdx + 1] : void 0;
+  if (!cardFilePath) {
+    console.error("Usage: board-live-cards probe-source --card <card.json> [--source-idx <n>] [--source-bind <name>] [--mock-requires <json>] [--rg <boardDir>] [--out <result.json>]");
+    process.exit(1);
+  }
+  let card;
+  try {
+    card = JSON.parse(fs__namespace.readFileSync(path__namespace.resolve(cardFilePath), "utf-8"));
+  } catch (e) {
+    console.error(`[probe-source] Cannot read card: ${e.message}`);
+    process.exit(1);
+  }
+  const sources = card.sources ?? [];
+  if (sources.length === 0) {
+    console.error(`[probe-source] Card "${card.id}" has no sources`);
+    process.exit(1);
+  }
+  let sourceIdx;
+  if (sourceBindVal) {
+    sourceIdx = sources.findIndex((s) => s.bindTo === sourceBindVal);
+    if (sourceIdx === -1) {
+      console.error(`[probe-source] No source with bindTo="${sourceBindVal}" in card "${card.id}"`);
+      process.exit(1);
+    }
+  } else {
+    sourceIdx = sourceIdxVal;
+    if (isNaN(sourceIdx) || sourceIdx < 0 || sourceIdx >= sources.length) {
+      console.error(`[probe-source] --source-idx ${sourceIdxVal} out of range (card has ${sources.length} source(s))`);
+      process.exit(1);
+    }
+  }
+  const sourceDef = sources[sourceIdx];
+  const cardDir = path__namespace.resolve(path__namespace.dirname(cardFilePath));
+  const boardDir = boardDirArg ? path__namespace.resolve(boardDirArg) : cardDir;
+  let mockRequires = {};
+  if (mockReqRaw) {
+    const raw = mockReqRaw.startsWith("@") ? fs__namespace.readFileSync(path__namespace.resolve(mockReqRaw.slice(1)), "utf-8") : mockReqRaw;
+    try {
+      mockRequires = JSON.parse(raw);
+    } catch (e) {
+      console.error(`[probe-source] --mock-requires is not valid JSON: ${e.message}`);
+      process.exit(1);
+    }
+  }
+  const executorFile = path__namespace.join(boardDir, ".task-executor");
+  const taskExecutor = fs__namespace.existsSync(executorFile) ? fs__namespace.readFileSync(executorFile, "utf-8").trim() : void 0;
+  const inPayload = {
+    ...sourceDef,
+    cwd: typeof sourceDef.cwd === "string" && sourceDef.cwd ? sourceDef.cwd : cardDir,
+    boardDir: typeof sourceDef.boardDir === "string" && sourceDef.boardDir ? sourceDef.boardDir : boardDir,
+    _requires: mockRequires,
+    _sourcesData: {},
+    _computed_values: {}
+  };
+  const sourceKind = sourceDef.chartApi ? "chartApi" : sourceDef.http ? "http" : sourceDef.copilot || sourceDef.prompt_template ? "copilot" : sourceDef.cli ? "cli" : "mock";
+  console.log(`[probe-source] card:        ${card.id}`);
+  console.log(`[probe-source] source[${sourceIdx}]:  bindTo="${sourceDef.bindTo}" kind=${sourceKind}`);
+  console.log(`[probe-source] _requires:   ${JSON.stringify(mockRequires)}`);
+  console.log(`[probe-source] executor:    ${taskExecutor ?? "built-in (source.cli only)"}`);
+  console.log(`[probe-source] running fetch...`);
+  const ts = Date.now();
+  const inFile = path__namespace.join(os__namespace.tmpdir(), `probe-in-${sourceDef.bindTo}-${ts}.json`);
+  const tmpOut = path__namespace.join(os__namespace.tmpdir(), `probe-out-${sourceDef.bindTo}-${ts}.json`);
+  const errFile = path__namespace.join(os__namespace.tmpdir(), `probe-err-${sourceDef.bindTo}-${ts}.txt`);
+  fs__namespace.writeFileSync(inFile, JSON.stringify(inPayload, null, 2), "utf-8");
+  let passed = false;
+  let errorMsg;
+  let resultRaw;
+  try {
+    if (taskExecutor) {
+      execCommandSync(taskExecutor, ["run-source-fetch", "--in", inFile, "--out", tmpOut, "--err", errFile], {
+        shell: true,
+        timeout: sourceDef.timeout ?? 3e4
+      });
+    } else {
+      if (!inPayload.cli) {
+        throw new Error("No task-executor registered and source has no cli field \u2014 cannot probe with built-in executor");
+      }
+      const cmdParts = splitCommandLine(inPayload.cli);
+      const rawCmd = cmdParts[0];
+      const { cmd, args: cliArgs } = resolveCommandInvocation(rawCmd, cmdParts.slice(1));
+      const stdout = execCommandSync(cmd, cliArgs, {
+        shell: false,
+        encoding: "utf-8",
+        timeout: sourceDef.timeout ?? 3e4,
+        cwd: inPayload.cwd
+      });
+      fs__namespace.writeFileSync(tmpOut, stdout.trim(), "utf-8");
+    }
+    passed = fs__namespace.existsSync(tmpOut);
+    if (passed) {
+      resultRaw = fs__namespace.readFileSync(tmpOut, "utf-8");
+    } else {
+      errorMsg = fs__namespace.existsSync(errFile) ? fs__namespace.readFileSync(errFile, "utf-8").trim() : "executor produced no output file";
+    }
+  } catch (e) {
+    errorMsg = e.message ?? String(e);
+    if (!errorMsg && fs__namespace.existsSync(errFile)) {
+      errorMsg = fs__namespace.readFileSync(errFile, "utf-8").trim();
+    }
+  }
+  for (const f of [inFile, errFile]) {
+    try {
+      fs__namespace.unlinkSync(f);
+    } catch {
+    }
+  }
+  if (passed && resultRaw !== void 0) {
+    const resultSize = resultRaw.length;
+    const sample = resultRaw.slice(0, 300);
+    console.log(`[probe-source] STATUS:      PROBE_PASS`);
+    console.log(`[probe-source] result size: ${resultSize} bytes`);
+    console.log(`[probe-source] sample:      ${sample}${resultSize > 300 ? "..." : ""}`);
+    if (outFile) {
+      fs__namespace.writeFileSync(path__namespace.resolve(outFile), resultRaw);
+      console.log(`[probe-source] result written to: ${outFile}`);
+    } else {
+      try {
+        fs__namespace.unlinkSync(tmpOut);
+      } catch {
+      }
+    }
+  } else {
+    console.log(`[probe-source] STATUS:      PROBE_FAIL`);
+    if (errorMsg) console.log(`[probe-source] error:       ${errorMsg}`);
+    try {
+      if (fs__namespace.existsSync(tmpOut)) fs__namespace.unlinkSync(tmpOut);
+    } catch {
+    }
+  }
+  const summary = {
+    status: passed ? "PROBE_PASS" : "PROBE_FAIL",
+    cardId: card.id,
+    sourceIdx,
+    bindTo: sourceDef.bindTo,
+    sourceKind,
+    mockRequiresKeys: Object.keys(mockRequires),
+    resultSizeBytes: resultRaw !== void 0 ? resultRaw.length : 0,
+    error: errorMsg ?? void 0
+  };
+  console.log(`[probe-source:result] ${JSON.stringify(summary)}`);
+  process.exit(passed ? 0 : 1);
+}
 function cmdHelp() {
   console.log(`
 board-live-cards-cli \u2014 LiveCards board CLI
@@ -2598,14 +3149,16 @@ USAGE
   board-live-cards-cli <command> [options]
 
 BOARD MANAGEMENT
-  init <dir> [--task-executor <script>] [--runtime-out <dir>]
+  init <dir> [--task-executor <script>] [--chat-handler <script>] [--inference-adapter <script>] [--runtime-out <dir>]
     Create a new board in <dir>.
     If --task-executor is given, writes <dir>/.task-executor with the script path.
+    If --chat-handler is given, writes <dir>/.chat-handler with the script path.
+    If --inference-adapter is given, writes <dir>/.inference-adapter with the script path.
     Writes <dir>/.runtime-out (default: <dir>/runtime-out).
     Published runtime files:
       <runtime-out>/board-livegraph-status.json
       <runtime-out>/cards/<card-id>.computed.json
-    Re-running init on an existing board is safe; --task-executor updates the registration.
+    Re-running init on an existing board is safe; handler registrations are updated.
 
   status --rg <dir> [--json]
     Read and print the published status snapshot from <runtime-out>/board-livegraph-status.json.
@@ -2645,13 +3198,16 @@ TASK CALLBACKS  (called by task executor scripts)
   task-failed --token <callbackToken> [--error <message>]
     Signal task failure with an optional error message.
 
+  task-progress --rg <dir> --token <callbackToken> [--update <json>]
+    Signal task progress with optional update payload (for waiting on more evidence, etc.).
+
 SOURCE CALLBACKS  (called internally by run-sources-internal)
   source-data-fetched --tmp <file> --token <sourceToken>
     Atomically rename <file> into the outputFile destination and record delivery
-    in runtime.json. Appends a task-progress event to re-invoke the card handler.
+    via journal events. Appends a task-progress event to re-invoke the card handler.
 
   source-data-fetch-failure --token <sourceToken> [--reason <message>]
-    Record a source fetch failure in runtime.json and append a task-progress event.
+    Record a source fetch failure via journal events and append a task-progress event.
 
 INTERNAL COMMANDS
   process-accumulated-events --rg <dir>
@@ -2666,7 +3222,7 @@ INTERNAL COMMANDS
     3) lock stays healthy,
     4) event production eventually quiesces.
 
-  run-sources-internal-internal --card <card.json> --token <callbackToken> --rg <dir>
+  run-sources-internal --card <card.json> --token <callbackToken> --rg <dir>
     Execute all source[] entries for a card, then report delivery or failure.
     (Internal command \u2014 invoked by the card-handler. Not intended for direct use.)
 
@@ -2679,6 +3235,34 @@ INTERNAL COMMANDS
     Execute a source definition. Board-live-cards reads source.cli and executes it.
     Writes result to --out. Presence of --out after exit indicates success.
 
+  probe-source --card <card.json> [--source-idx <n>] [--source-bind <name>]
+               [--mock-requires <json>] [--rg <boardDir>] [--out <result.json>]
+    Validate that a card source can be fetched successfully.
+    Reads the card file, extracts the chosen source (default: index 0), builds the
+    run-source-fetch --in payload with the supplied _requires data, invokes the
+    registered task-executor (or built-in executor for source.cli), and reports pass/fail.
+    --mock-requires: JSON string (or @file.json) providing the _requires token values
+                     the source needs.  Craft the minimal payload that exercises the
+                     source \u2014 e.g. '{"holdings":[{"ticker":"AAPL","quantity":10}]}'.
+                     If omitted, _requires is passed as empty ({}).
+    --source-idx:    0-based index into card.sources[]. Default: 0.
+    --source-bind:   Select source by its bindTo name instead of index.
+    --rg:            Board directory used to find .task-executor. Defaults to the
+                     directory containing the card file.
+    --out:           Optional path to write the raw fetch result JSON.
+    Prints a structured report ending with a [probe-source:result] JSON line.
+    Exits 0 on PROBE_PASS, 1 on PROBE_FAIL.
+
+  run-inference-internal --in <input.json> --token <inferenceToken>
+    Execute inference via registered .inference-adapter and forward result to inference-done.
+    inferenceToken encodes boardDir (rg), cardId (cid), callbackToken (cbk), checksum (cs).
+    (Internal command \u2014 invoked by the card-handler when custom completion rule is used.)
+
+  inference-done --tmp <result.json> --token <inferenceToken>
+    Persist llm_task_completion_inference on the card and append a task-progress event.
+    Reads boardDir/callbackToken/checksum from decoded inferenceToken; deletes --tmp file after reading.
+    (Internal command \u2014 invoked by run-inference-internal.)
+
 RUN-SOURCE-FETCH PROTOCOL
   External task-executors implement:
     <executor> run-source-fetch --in <source.json> --out <result.json> [--err <error.txt>]
@@ -2715,6 +3299,7 @@ EXAMPLES
   board-live-cards-cli add-cards --rg ./my-board --card cards/prices.json
   board-live-cards-cli status --rg ./my-board
   board-live-cards-cli retrigger --rg ./my-board --task price-fetch
+  board-live-cards-cli probe-source --card cards/card-market-prices.json --source-idx 0 --rg ./my-board --mock-requires '{"holdings":[{"ticker":"AAPL","quantity":10}]}'
 `.trimStart());
 }
 var isMain = process.argv[1] && path__namespace.resolve(process.argv[1]) === path__namespace.resolve(new URL((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('board-live-cards-cli.cjs', document.baseURI).href))).pathname.replace(/^\/([A-Z]:)/, "$1"));
@@ -2732,14 +3317,18 @@ exports.appendEventToJournal = appendEventToJournal;
 exports.buildCardInventoryIndex = buildCardInventoryIndex;
 exports.cli = cli;
 exports.createBoardReactiveGraph = createBoardReactiveGraph;
+exports.decideSourceAction = decideSourceAction;
 exports.decodeSourceToken = decodeSourceToken;
 exports.encodeSourceToken = encodeSourceToken;
 exports.getUndrainedEntries = getUndrainedEntries;
 exports.initBoard = initBoard;
+exports.isSourceInFlight = isSourceInFlight;
 exports.liveCardToTaskConfig = liveCardToTaskConfig;
 exports.loadBoard = loadBoard;
 exports.loadBoardEnvelope = loadBoardEnvelope;
 exports.lookupCardPath = lookupCardPath;
+exports.nextEntryAfterFetchDelivery = nextEntryAfterFetchDelivery;
+exports.nextEntryAfterFetchFailure = nextEntryAfterFetchFailure;
 exports.processAccumulatedEvents = processAccumulatedEvents;
 exports.processAccumulatedEventsForced = processAccumulatedEventsForced;
 exports.processAccumulatedEventsInfinitePass = processAccumulatedEventsInfinitePass;