@smithers-orchestrator/scheduler 0.25.0 → 0.25.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smithers-orchestrator/scheduler",
-  "version": "0.25.0",
+  "version": "0.25.1",
   "description": "Pure decision engine: session, scheduler, and task state management for Smithers workflows",
   "type": "module",
   "sideEffects": false,
@@ -176,8 +176,8 @@
   ],
   "dependencies": {
     "effect": "^3.21.1",
-    "@smithers-orchestrator/errors": "0.25.0",
-    "@smithers-orchestrator/graph": "0.25.0"
+    "@smithers-orchestrator/errors": "0.25.1",
+    "@smithers-orchestrator/graph": "0.25.1"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/RunResult.ts

@@ -13,4 +13,20 @@ export type RunResult = {
   readonly output?: unknown;
   readonly error?: unknown;
   readonly nextRunId?: string;
+  /**
+   * Number of tasks that ended in a `failed` state yet did not fail the run —
+   * "masked" child failures the run-level status cannot express. Present (and
+   * `> 0`) only on a `finished` result that tolerated at least one failure
+   * (a {@link https://smithers.sh/components/task `continueOnFail`} task, or an
+   * agent task that failed transiently: rate limit, timeout, abort). A binary
+   * `finished` status would otherwise read as a clean success. See
+   * `docs/runtime/run-state.mdx`.
+   */
+  readonly failedChildren?: number;
+  /**
+   * Task state keys (`nodeId::iteration`) of the tasks counted by
+   * {@link failedChildren}. The iteration disambiguates the same `nodeId` failing
+   * across loop/Ralph iterations.
+   */
+  readonly failedChildKeys?: readonly string[];
 };

package/src/index.d.ts

@@ -138,6 +138,22 @@ type RunResult$1 = {
     readonly output?: unknown;
     readonly error?: unknown;
     readonly nextRunId?: string;
+    /**
+     * Number of tasks that ended in a `failed` state yet did not fail the run —
+     * "masked" child failures the run-level status cannot express. Present (and
+     * `> 0`) only on a `finished` result that tolerated at least one failure
+     * (a {@link https://smithers.sh/components/task `continueOnFail`} task, or an
+     * agent task that failed transiently: rate limit, timeout, abort). A binary
+     * `finished` status would otherwise read as a clean success. See
+     * `docs/runtime/run-state.mdx`.
+     */
+    readonly failedChildren?: number;
+    /**
+     * Task state keys (`nodeId::iteration`) of the tasks counted by
+     * {@link failedChildren}. The iteration disambiguates the same `nodeId` failing
+     * across loop/Ralph iterations.
+     */
+    readonly failedChildKeys?: readonly string[];
 };
 
 type WaitReason$1 = {

package/src/makeWorkflowSession.js

@@ -353,14 +353,37 @@ export function makeWorkflowSession(options = {}) {
    * @returns {EngineDecision}
    */
     function finishedResult(status = "finished") {
-        return {
-            _tag: "Finished",
-            result: {
-                runId: state.runId,
-                status,
-                output: [...state.outputs.values()].at(-1)?.output,
-            },
+        /** @type {RunResult} */
+        const result = {
+            runId: state.runId,
+            status,
+            output: [...state.outputs.values()].at(-1)?.output,
         };
+        if (status === "finished") {
+            // At a `finished` terminal, any task still in `failed` state is a
+            // *tolerated* failure — an unhandled one would have produced a `Failed`
+            // decision via unhandledFailureDecision() and never reached here. Those
+            // are exactly the masked children (continueOnFail tasks, transient agent
+            // failures) the binary run status cannot express. Surface them so callers
+            // can detect a run that "succeeded" while children failed. See issue #295
+            // and docs/runtime/run-state.mdx.
+            //
+            // Keys are the canonical task state keys (`nodeId::iteration`), not bare
+            // node ids: a looped/Ralph workflow can fail the same nodeId across
+            // iterations, and the iteration is what disambiguates which child to
+            // inspect.
+            const failedChildKeys = [];
+            for (const [key, taskState] of state.states) {
+                if (taskState === "failed") {
+                    failedChildKeys.push(key);
+                }
+            }
+            if (failedChildKeys.length > 0) {
+                result.failedChildren = failedChildKeys.length;
+                result.failedChildKeys = failedChildKeys;
+            }
+        }
+        return { _tag: "Finished", result };
     }
     /**
    * @returns {ScheduleResult}