@bastani/atomic 0.9.19-alpha.5 → 0.9.19-alpha.7

package/dist/builtin/workflows/src/extension/index.bundle.mjs

@@ -76420,6 +76420,7 @@ class StageUiBroker {
     };
   }
   requestCustomUi(runId, stageId, factory, options, signal) {
+    signal = options?.signal ? signal ? AbortSignal.any([signal, options.signal]) : options.signal : signal;
     if (signal?.aborted) {
       return Promise.reject(signal.reason ?? new Error("atomic-workflows: stage UI request aborted"));
     }
@@ -82123,6 +82124,108 @@ function collectDefinitionName(tokens, localValues, workflowNames) {
   }
   return;
 }
+function discoveryField(object) {
+  if (object?.[0]?.value !== "{" || object.at(-1)?.value !== "}")
+    return;
+  let value2;
+  for (const field of arrayElements(object)) {
+    let key = field;
+    while (["get", "set", "async", "*"].includes(key[0]?.value ?? ""))
+      key = key.slice(1);
+    if (key[0]?.value === "[" || key !== field && key[0]?.value === "possibleStageNames")
+      return;
+    if (field[0]?.value === ".") {
+      if (value2 !== undefined)
+        return;
+      continue;
+    }
+    if (field[0]?.value !== "possibleStageNames")
+      continue;
+    if (value2 !== undefined || field[1]?.value !== ":")
+      return;
+    value2 = field.slice(2);
+  }
+  return value2;
+}
+function literalDiscoveryNames(value2) {
+  if (value2?.[0]?.value !== "[" || value2.at(-1)?.value !== "]")
+    return;
+  const names = [];
+  for (const element of arrayElements(value2)) {
+    if (element.length !== 1 || element[0]?.kind !== "string")
+      return;
+    names.push(element[0].value);
+  }
+  return names.length > 0 ? names : undefined;
+}
+function discoveryHelpers(tokens) {
+  const helpers = [];
+  for (let index = 0;index < tokens.length; index += 1) {
+    if (tokens[index]?.value !== "function" || tokens[index + 1]?.kind !== "ident")
+      continue;
+    let open = index + 2;
+    if (tokens[open]?.value === "<")
+      open = (matchBracket(tokens, open, "<", ">") ?? tokens.length) + 1;
+    if (tokens[open]?.value !== "(")
+      continue;
+    const close = matchBracket(tokens, open, "(", ")");
+    if (close === undefined)
+      continue;
+    let bodyOpen = close + 1;
+    while (bodyOpen < tokens.length && tokens[bodyOpen]?.value !== "{")
+      bodyOpen += 1;
+    const bodyClose = matchBracket(tokens, bodyOpen, "{", "}");
+    if (bodyClose === undefined)
+      continue;
+    const preceding = tokens[index - (tokens[index - 1]?.value === "async" ? 2 : 1)]?.value;
+    helpers.push({
+      name: tokens[index + 1].value,
+      nameIndex: index + 1,
+      params: splitTopLevelArguments({ method: "parallel", argsOpen: open }, tokens),
+      bodyOpen,
+      bodyClose,
+      declaration: preceding === undefined || ["export", ";", "{", "}"].includes(preceding)
+    });
+  }
+  return helpers;
+}
+function hasDiscoveryDestructuringWrite(tokens, parameter) {
+  for (let index = 0;index < tokens.length; index += 1) {
+    const open = tokens[index]?.value;
+    if (open !== "[" && open !== "{")
+      continue;
+    const close = matchBracket(tokens, index, open, open === "[" ? "]" : "}");
+    if (close === undefined || !["=", "of", "in"].includes(tokens[close + 1]?.value ?? ""))
+      continue;
+    if (tokens.slice(index + 1, close).some((token) => token.kind === "ident" && token.value === parameter))
+      return true;
+  }
+  return false;
+}
+function discoveryCalls(tokens, name, declaration) {
+  const calls = [];
+  for (let index = 0;index < tokens.length; index += 1) {
+    if (tokens[index]?.value === "import") {
+      while (index < tokens.length && tokens[index]?.kind !== "string")
+        index += 1;
+      continue;
+    }
+    if (tokens[index]?.value === "export" && tokens[index + 1]?.value === "{") {
+      const close = matchBracket(tokens, index + 1, "{", "}") ?? tokens.length;
+      const exported = tokens.slice(index + 2, close);
+      if (exported.some((token, offset) => token.value === name && (declaration === undefined || exported[offset + 1]?.value === "as")))
+        return;
+      index = close;
+      continue;
+    }
+    if (tokens[index]?.kind !== "ident" || tokens[index]?.value !== name || index === declaration)
+      continue;
+    if (tokens[index + 1]?.value !== "(" || [".", "?.", "function"].includes(tokens[index - 1]?.value ?? ""))
+      return;
+    calls.push(index + 1);
+  }
+  return calls;
+}
 
 class PossibleStagesScanner {
   stages = new Set;
@@ -82131,6 +82234,7 @@ class PossibleStagesScanner {
   maxDepth;
   units = new Map;
   aliasPool = new Set;
+  closure = [];
   constructor(maxDepth) {
     this.maxDepth = maxDepth;
   }
@@ -82166,11 +82270,17 @@ class PossibleStagesScanner {
         this.aliasPool.add(alias);
       }
     }
-    for (const path of ordered) {
-      const unit = this.units.get(path);
-      if (unit === undefined)
-        continue;
-      this.scanUnit(unit, path, boundaryPrefix, depth, ancestorStack);
+    const previousClosure = this.closure;
+    this.closure = ordered;
+    try {
+      for (const path of ordered) {
+        const unit = this.units.get(path);
+        if (unit === undefined)
+          continue;
+        this.scanUnit(unit, path, boundaryPrefix, depth, ancestorStack);
+      }
+    } finally {
+      this.closure = previousClosure;
     }
   }
   unitFor(path) {
@@ -82284,7 +82394,127 @@ class PossibleStagesScanner {
     }
     return resolveRelativeSpecifier(specifier, importingFile);
   }
+  hasDataOnlyDiscoveryOptions(argument) {
+    if (argument?.[0]?.value !== "{" || argument.at(-1)?.value !== "}")
+      return false;
+    return arrayElements(argument).every((field) => (field[0]?.kind === "ident" || field[0]?.kind === "string") && field[0].value !== "__proto__" && field[1]?.value === ":");
+  }
+  discoveryNames(call, unit, path) {
+    if (call.method !== "parallel")
+      return;
+    const value2 = discoveryField(splitTopLevelArguments(call, unit.tokens)[1]);
+    const literal = literalDiscoveryNames(value2);
+    if (literal !== undefined)
+      return literal;
+    if (value2?.length !== 3 || value2[0]?.kind !== "ident" || value2[1]?.value !== "." || value2[2]?.value !== "possibleStageNames")
+      return;
+    const owner = discoveryHelpers(unit.tokens).filter((helper) => helper.bodyOpen < call.argsOpen && helper.bodyClose > call.argsOpen).at(-1);
+    if (owner === undefined || !owner.declaration)
+      return;
+    const parameter = owner.params.findIndex((param) => param[0]?.value === value2[0]?.value);
+    if (parameter < 0)
+      return;
+    for (const param of owner.params) {
+      if (param[0]?.kind !== "ident")
+        return;
+      const assignment = param.findIndex((token) => token.value === "=");
+      if (assignment < 0)
+        continue;
+      const initial = param.slice(assignment + 1);
+      const emptyObject = initial.length === 2 && initial[0]?.value === "{" && initial[1]?.value === "}";
+      const scalar = initial.length === 1 && (initial[0]?.kind === "string" || ["true", "false", "null", "undefined"].includes(initial[0]?.value ?? ""));
+      if (!emptyObject && !scalar)
+        return;
+    }
+    const body = unit.tokens.slice(owner.bodyOpen, owner.bodyClose);
+    if (body.some((token) => token.kind === "ident" && token.value === "arguments"))
+      return;
+    if (hasDiscoveryDestructuringWrite(body, value2[0].value))
+      return;
+    const forwarded = new Set;
+    const spreadOptions = new Set;
+    for (let index = 0;index < body.length; index += 1) {
+      const parallel = matchCtxCall(body, index, this.aliasPool);
+      if (parallel?.method !== "parallel")
+        continue;
+      const parallelOptions = splitTopLevelArguments(parallel, body)[1];
+      const field = discoveryField(parallelOptions);
+      if (parallelOptions?.[0]?.value === "{") {
+        for (const entry of arrayElements(parallelOptions)) {
+          if (entry.length === 4 && entry.slice(0, 3).every((token) => token.value === "."))
+            spreadOptions.add(entry[3]);
+        }
+      }
+      if (field?.length === 3 && field[0]?.value === value2[0].value && field[1]?.value === "." && field[2]?.value === "possibleStageNames")
+        forwarded.add(field[0]);
+    }
+    for (let index = 0;index < body.length; index += 1) {
+      if (body[index]?.value !== value2[0]?.value)
+        continue;
+      if (body[index + 2]?.value === "possibleStageNames" && !forwarded.has(body[index]))
+        return;
+      const destructured = body[index - 2]?.value === "}" && body[index - 1]?.value === "=" && body[index + 1]?.value === ";";
+      if (destructured) {
+        let matched = false;
+        for (let open = 0;open < index - 2; open += 1) {
+          if (body[open]?.value !== "{" || matchBracket(body, open, "{", "}") !== index - 2)
+            continue;
+          if (body[open - 1]?.value !== "const")
+            return;
+          matched = true;
+          for (const entry of arrayElements(body.slice(open, index - 1))) {
+            if (entry.length === 1 && entry[0]?.kind === "ident" && entry[0].value !== "possibleStageNames")
+              continue;
+            if (entry.length !== 4 || !entry.slice(0, 3).every((token) => token.value === ".") || entry[3]?.kind !== "ident")
+              return;
+            const rest = entry[3];
+            for (let use = 0;use < body.length; use += 1) {
+              const token = body[use];
+              if (token?.kind !== "ident" || token.value !== rest.value || token === rest)
+                continue;
+              if (spreadOptions.has(token))
+                continue;
+              if (body[use - 3]?.value === "const" && body[use - 2]?.kind === "ident" && body[use - 1]?.value === "=" && body[use + 1]?.value === "." && body[use + 2]?.value === "concurrency" && body[use + 3]?.value === ";")
+                continue;
+              return;
+            }
+          }
+        }
+        if (!matched)
+          return;
+      }
+      if (!destructured && !forwarded.has(body[index]))
+        return;
+    }
+    const names = [];
+    for (const callerPath of this.closure) {
+      const caller = this.units.get(callerPath);
+      if (caller === undefined)
+        continue;
+      if ([...caller.imports.values()].some((binding) => binding.importedName === undefined && resolveRelativeSpecifier(binding.specifier, callerPath) === path))
+        return;
+      const references = callerPath === path ? [owner.name] : [...caller.imports].filter(([, binding]) => binding.importedName === owner.name && resolveRelativeSpecifier(binding.specifier, callerPath) === path).map(([local]) => local);
+      for (const reference of references) {
+        const calls = discoveryCalls(caller.tokens, reference, callerPath === path ? owner.nameIndex : undefined);
+        if (calls === undefined)
+          return;
+        for (const argsOpen of calls) {
+          const argument = splitTopLevelArguments({ method: "parallel", argsOpen }, caller.tokens)[parameter];
+          if (!this.hasDataOnlyDiscoveryOptions(argument))
+            return;
+          const declared = literalDiscoveryNames(discoveryField(argument));
+          if (declared === undefined)
+            return;
+          names.push(...declared);
+        }
+      }
+    }
+    return names.length > 0 || this.closure[0] !== path ? names : undefined;
+  }
   stepNamesForStepsCall(call, unit, path) {
+    const declared = this.discoveryNames(call, unit, path);
+    if (declared !== undefined)
+      return declared;
     const first = firstArgumentTokens(call, unit.tokens);
     if (first === undefined || first.length === 0)
       return [];
@@ -90858,7 +91088,8 @@ async function warm_first_fan_out(ctx, steps, prefixKeyOf, options = {}) {
       const warmResults = await ctx.parallel(warmSteps, {
         ...parallelOptions,
         concurrency: boundedConcurrency(warmSteps.length, warmConcurrency ?? DEFAULT_WARM_CONCURRENCY, inheritedConcurrency),
-        failFast: false
+        failFast: false,
+        possibleStageNames: options.possibleStageNames
       });
       for (const [resultIndex, result] of warmResults.entries()) {
         const originalIndex = warmIndices[resultIndex];
@@ -90873,7 +91104,8 @@ async function warm_first_fan_out(ctx, steps, prefixKeyOf, options = {}) {
     const restSteps = restIndices.map((index) => steps[index]);
     const restResults = await ctx.parallel(restSteps, {
       ...parallelOptions,
-      concurrency: boundedConcurrency(restSteps.length, undefined, inheritedConcurrency)
+      concurrency: boundedConcurrency(restSteps.length, undefined, inheritedConcurrency),
+      possibleStageNames: options.possibleStageNames
     });
     for (const [resultIndex, result] of restResults.entries()) {
       const originalIndex = restIndices[resultIndex];
@@ -91082,7 +91314,7 @@ async function runAdversarialVerification(ctx) {
     const runWave = async (pending, reaskWave) => {
       if (pending.length === 0)
         return { valid: [], invalid: [], results: [] };
-      const reports = await warm_first_fan_out(ctx, pending.map((cell) => scoreStep(cell, reaskWave, scoringHead, criteriaPath)), () => scoringHead, { concurrency: Math.min(pending.length, 4), failFast: false });
+      const reports = await warm_first_fan_out(ctx, pending.map((cell) => scoreStep(cell, reaskWave, scoringHead, criteriaPath)), () => scoringHead, { concurrency: Math.min(pending.length, 4), failFast: false, possibleStageNames: ["verifier-*-*-*", "verifier-*-*-*-reask-*"] });
       const byName = new Map;
       for (const report of reports) {
         const name = report.name ?? report.stageName;
@@ -96470,7 +96702,7 @@ async function runTournament(ctx) {
     if (stages.length === 0)
       return { preferences: [], results: [] };
     executed += stages.length;
-    const results = await warm_first_fan_out(ctx, stages.map((stage) => stage.step), (_step, index) => `${stages[index].slot1}:${stages[index].slot2}`, { concurrency: maxConcurrency, failFast: false });
+    const results = await warm_first_fan_out(ctx, stages.map((stage) => stage.step), (_step, index) => `${stages[index].slot1}:${stages[index].slot2}`, { concurrency: maxConcurrency, failFast: false, possibleStageNames: ["judge-*-*-*-r*"] });
     const phaseResults = [...results];
     for (const stage of stages) {
       let report = judgeReport(resultFor(results, stage.name)?.structured);
@@ -104255,21 +104487,17 @@ function throwFinalizationError(error) {
 function createTrackedStageCaller(input) {
   const { runtime } = input;
   const readinessGateEnabled = runtime.opts.confirmStageReadiness !== undefined || runtime.opts.usePromptNodesForUi === true;
-  const confirmReadiness = async () => {
-    try {
-      if (runtime.opts.confirmStageReadiness !== undefined) {
-        const ready = await runtime.opts.confirmStageReadiness({
-          runId: runtime.runId,
-          stageId: runtime.stageId,
-          stageName: runtime.name,
-          signal: runtime.signal
-        });
-        return ready ? { action: "advance" } : { action: "stay" };
-      }
-      return await askReadinessViaStageBroker(runtime.runId, runtime.stageId, runtime.signal);
-    } catch {
-      return { action: "advance" };
-    }
+  const confirmReadiness = async (signal) => {
+    if (runtime.opts.confirmStageReadiness !== undefined) {
+      const ready = await raceAbort(runtime.opts.confirmStageReadiness({
+        runId: runtime.runId,
+        stageId: runtime.stageId,
+        stageName: runtime.name,
+        signal
+      }), signal);
+      return ready ? { action: "advance" } : { action: "stay" };
+    }
+    return await askReadinessViaStageBroker(runtime.runId, runtime.stageId, signal);
   };
   const suppressReadinessForCurrentTurn = () => {
     runtime.state.askUserQuestionObservedThisTurn = false;
@@ -104423,9 +104651,35 @@ function createTrackedStageCaller(input) {
           });
           try {
             while (runtime.state.askUserQuestionObservedThisTurn || repeatReadinessAfterChatTurn) {
-              const decision = await confirmReadiness();
+              runtime.signal.throwIfAborted();
+              if (runtime.stageSnapshot.status === "paused" || runtime.stageSnapshot.status === "blocked") {
+                await runtime.scheduler.waitForStageRelease(runtime.stageId, runtime.releaseLiveHandle);
+                continue;
+              }
+              const controller = new AbortController;
+              runtime.state.readinessController = controller;
+              let decision;
+              try {
+                decision = await confirmReadiness(AbortSignal.any([runtime.signal, controller.signal]));
+                if (decision.action === "advance" || decision.message !== undefined) {
+                  await runtime.scheduler.waitForStageRelease(runtime.stageId, runtime.releaseLiveHandle);
+                }
+                runtime.signal.throwIfAborted();
+                if (controller.signal.aborted) {
+                  await runtime.scheduler.waitForStageRelease(runtime.stageId, runtime.releaseLiveHandle);
+                  continue;
+                }
+              } catch (error) {
+                runtime.signal.throwIfAborted();
+                if (controller.signal.aborted) {
+                  await runtime.scheduler.waitForStageRelease(runtime.stageId, runtime.releaseLiveHandle);
+                  continue;
+                }
+                throw error;
+              }
               if (decision.action === "advance")
                 break;
+              delete runtime.state.readinessController;
               if (runtime.signal.aborted)
                 break;
               runtime.state.askUserQuestionObservedThisTurn = false;
@@ -104568,9 +104822,17 @@ function createTrackedStageCaller(input) {
           const failure = runtime.classifyExecutorFailure(durableCheckpointError.error);
           applyTerminalStageState = () => applyFailureToStage(runtime.stageSnapshot, failure);
         }
-        if (!runtime.state.stageFinalized)
-          applyTerminalStageState?.();
         try {
+          if (terminalStateIsSuccess && runtime.state.readinessController !== undefined) {
+            let pauseVersion;
+            do {
+              pauseVersion = runtime.state.readinessPauseVersion;
+              await runtime.scheduler.waitForStageRelease(runtime.stageId, runtime.releaseLiveHandle);
+            } while (pauseVersion !== runtime.state.readinessPauseVersion);
+            runtime.signal.throwIfAborted();
+          }
+          if (!runtime.state.stageFinalized)
+            applyTerminalStageState?.();
           await runtime.finalizeStageSnapshot();
         } catch (err) {
           finalizationError ??= { thrown: true, error: err };
@@ -104588,6 +104850,9 @@ function createTrackedStageCaller(input) {
       input.limiter.release();
       if (finalizationError !== undefined)
         throwFinalizationError(finalizationError.error);
+      delete runtime.state.readinessController;
+      if (terminalStateIsSuccess && readinessGateEnabled)
+        runtime.signal.throwIfAborted();
     }
   };
 }
@@ -104908,12 +105173,26 @@ function createStageControlHandle(runtime) {
     async pause() {
       runtime.throwIfStageMutationBlocked();
       const statusBeforePause = runtime.stageSnapshot.status;
+      let readinessPauseVersion;
+      if (runtime.state.readinessController !== undefined) {
+        runtime.scheduler.ensureReleaseBarrier(runtime.stageId);
+        readinessPauseVersion = (runtime.state.readinessPauseVersion ?? 0) + 1;
+        runtime.state.readinessPauseVersion = readinessPauseVersion;
+      }
       if (statusBeforePause === "pending" || statusBeforePause === "running" || runtime.innerCtx.isStreaming) {
-        await runtime.innerCtx.__requestPause();
+        try {
+          await runtime.innerCtx.__requestPause();
+        } catch (error) {
+          if (readinessPauseVersion !== undefined && runtime.state.readinessPauseVersion === readinessPauseVersion && runtime.stageSnapshot.status !== "paused" && runtime.stageSnapshot.status !== "blocked" && !runtime.scheduler.hasCascadePauseOwners(runtime.stageId)) {
+            runtime.scheduler.releaseStageBarrier(runtime.stageId);
+          }
+          throw error;
+        }
       }
       const changed = runtime.activeStore.recordStagePaused(runtime.runId, runtime.stageId);
       if (changed) {
         runtime.scheduler.ensureReleaseBarrier(runtime.stageId);
+        runtime.state.readinessController?.abort(new Error("atomic-workflows: readiness paused"));
         await runtime.scheduler.cascadePauseFrom(runtime.stageId);
         const run = runtime.activeStore.runs().find((candidate) => candidate.id === runtime.runId);
         const stillActive = run?.stages.some((stage) => stage.status === "running" && stage.id !== runtime.stageId) ?? false;
@@ -112462,21 +112741,24 @@ function registerPendingStageIntercomBridge(pi, activeStore) {
     pi.events?.emit?.(PENDING_STAGE_UNDELIVERABLE_EVENT, payload);
     return payload.handled && await payload.completion === true;
   };
+  const announcedRoutes = new Map;
   const announceRoutes = () => {
     if (disposed)
       return;
+    const ownedRunIds = new Set;
     const runs = activeStore.runs();
     for (const run of runs) {
       const rootRunId = durableRootRunIdForRun(runs, run.id);
       if (rootRunId === undefined)
         continue;
+      ownedRunIds.add(run.id);
       const parentRun = runs.find((candidate) => candidate.id === run.parentRunId);
       const boundary = parentRun?.stages.find((stage) => stage.id === run.parentStageId);
       const parent = parentRun === undefined || boundary === undefined ? undefined : {
         runId: parentRun.id,
         stageKeys: [boundary.id, boundary.name].filter((key) => resolveChildRun(runs, parentRun, key)?.id === run.id)
       };
-      pi.events?.emit?.(PENDING_STAGE_ROUTE_EVENT, {
+      const announcement = {
         runId: run.id,
         group: workflowInvocationIntercomGroup(rootRunId),
         capability: workflowPendingStageRouteCapability(activeStore, run.id),
@@ -112501,7 +112783,32 @@ function registerPendingStageIntercomBridge(pi, activeStore) {
           }))
         ],
         ...run.id === rootRunId ? { possibleStages: possibleStageRows(runs, rootRunId, run) } : {}
-      });
+      };
+      const signature = JSON.stringify(announcement);
+      if (announcedRoutes.get(run.id)?.signature === signature)
+        continue;
+      const entry = { signature };
+      announcedRoutes.set(run.id, entry);
+      try {
+        pi.events?.emit?.(PENDING_STAGE_ROUTE_EVENT, announcement);
+      } catch (error) {
+        if (announcedRoutes.get(run.id) === entry)
+          announcedRoutes.delete(run.id);
+        throw error;
+      }
+      const completion = announcement.completion;
+      if (completion === undefined) {
+        announcedRoutes.delete(run.id);
+      } else {
+        completion.catch(() => {
+          if (announcedRoutes.get(run.id) === entry)
+            announcedRoutes.delete(run.id);
+        });
+      }
+    }
+    for (const runId of announcedRoutes.keys()) {
+      if (!ownedRunIds.has(runId))
+        announcedRoutes.delete(runId);
     }
     sweepPromise = sweepPromise.then(() => settleUndeliverablePendingStageMessages(activeStore, notifyUndeliverable)).then(() => {
       return;
@@ -112586,6 +112893,7 @@ function registerPendingStageIntercomBridge(pi, activeStore) {
       subscription();
     if (typeof stickySubscription === "function")
       stickySubscription();
+    announcedRoutes.clear();
   };
   pi.on?.("session_shutdown", dispose);
   return dispose;
@@ -117150,7 +117458,7 @@ var DEFAULT_PROMPT_GUIDANCE = [
   - After creating and reloading a newly authored custom workflow, close the loop by stating the folder containing the workflow file just written, for example \`.atomic/workflows/\`, in this shape: \`Custom workflow created. You can inspect its code at: <workflow-folder-path>\`. Do this only for newly created custom workflows, never builtin or pre-existing workflows.
   - Keep a small, readable workflow in one entry file and write it for human maintainers. Keep the graph and control flow visible in the top-level workflow entry file, use stage names that state each stage's responsibility, and make its inputs, outputs, evidence, and success contract explicit. A developer reading the entry file from top to bottom should be able to identify the graph, branches, gates, artifacts, and stop conditions. Avoid both monolithic prompt blobs and gratuitous fragmentation. Do not split short one-use prompts, create one file per stage, add wrapper-only modules, hide the graph across files, or use line counts alone as a module boundary.
   - When a meaningful source boundary improves clarity, reuse, ownership, or testability, keep the graph and control flow in the top-level workflow entry file and extract cohesive concerns such as long or reused prompt builders, shared TypeBox schemas and workflow-specific types, model-policy constants shared by several stages, deterministic helpers with their own testable behavior, or reusable child workflow definitions into a subdirectory below the top-level discovery directory — either one owned by a single workflow or a shared support directory. Project and user discovery scans only top-level \`.ts\`/\`.js\`/\`.mjs\`/\`.cjs\` files in the workflow directory, so those support modules are not scanned as extra top-level workflow candidates; use \`.js\` import extensions from TypeScript source.
-  - Evaluate Atomic extension hooks when a workflow needs fine-grained, cross-cutting tool or session event control. Workflow TypeScript owns the inspectable DAG, stages, handoffs, durable \`ctx.tool\` side effects, and gates; extension hooks own cross-cutting session and model-tool policy such as \`tool_call\` interception, input mutation, or blocking, \`tool_result\` transformation, context and provider hooks, lifecycle observation, or reusable custom tools. Use hooks only when cross-stage or cross-workflow event control is materially clearer than embedding the policy in each stage; do not prescribe a companion extension for ordinary workflow logic. Consult \`packages/coding-agent/docs/extensions.md#events\` for the authoritative hook contracts.
+  - Evaluate Atomic extension hooks when a workflow needs fine-grained, cross-cutting tool or session event control. Workflow TypeScript owns the inspectable DAG, stages, handoffs, durable \`ctx.tool\` side effects, and gates; extension hooks own cross-cutting session and model-tool policy such as \`tool_call\` interception, input mutation, or blocking, \`tool_result\` transformation, context and provider hooks, lifecycle observation, or reusable custom tools. Use hooks only when cross-stage or cross-workflow event control is materially clearer than embedding the policy in each stage; do not prescribe a companion extension for ordinary workflow logic. Consult \`packages/coding-agent/docs/extensions/events.md#events\` for the authoritative hook contracts.
   - When a workflow depends on a companion extension, make the dependency explicit, package and document it with the workflow, include any extension-provided custom tools in stage \`tools\` allowlists, and document hook-driven behavior so the workflow remains inspectable.
   - When creating or editing a workflow that pins an explicit stage \`model\` or \`fallbackModels\`, consult \`packages/coding-agent/docs/models/model-selection.md\` for role-based recommendations and \`packages/coding-agent/docs/models/evals.md\` for the measured per-evaluation scores behind them (its task-type picker maps each stage type to the eval that measures it), treating benchmark thinking levels as measurement configurations rather than universal workflow defaults, then call \`workflow({ action: "models" })\` to see the models actually present in the user's configured catalog. Use only the catalog's returned \`fullId\` values as model strings, and append a thinking suffix only when that exact level appears in the entry's \`availableThinkingLevels\`; apply the stage role and failure-cost policy independently to the primary and every fallback; treat an absent or empty \`availableThinkingLevels\` as no suffix support rather than inferring one. If a guide-recommended model for the role is unavailable, try another guide-recommended model that is present in the catalog. If the selected model does not support the role's level, choose another catalog model that does or leave the stage unpinned rather than inventing or silently promoting a level. An explicit user request for a level overrides the role default, but never fabricate an unsupported catalog level. If no recommendation intersects with the catalog, leave the stage unpinned rather than inventing a substitute, and mention the limitation, asking the user only if the workflow requires an explicit model choice. If the catalog is empty, continue with unpinned stages, state that no configured models were returned, and do not fabricate model IDs. Do not inspect or infer credentials, environment variables, auth files, token validity, entitlements, or the reason a model is absent; \`isCurrent\` marks the active selection, not a quality recommendation.
   - Consult docs/workflows/reliable-design.md and its starter patterns (Classify-and-act, Fan-out-and-synthesize, Adversarial verification, Generate-and-filter, Tournament, Loop until done, and Stacked implementation slices) when designing a stage graph.

package/dist/builtin/workflows/src/index.js

@@ -3156,6 +3156,7 @@ class StageUiBroker {
     };
   }
   requestCustomUi(runId, stageId, factory, options, signal) {
+    signal = options?.signal ? signal ? AbortSignal.any([signal, options.signal]) : options.signal : signal;
     if (signal?.aborted) {
       return Promise.reject(signal.reason ?? new Error("atomic-workflows: stage UI request aborted"));
     }
@@ -13429,21 +13430,17 @@ function throwFinalizationError(error) {
 function createTrackedStageCaller(input) {
   const { runtime } = input;
   const readinessGateEnabled = runtime.opts.confirmStageReadiness !== undefined || runtime.opts.usePromptNodesForUi === true;
-  const confirmReadiness = async () => {
-    try {
-      if (runtime.opts.confirmStageReadiness !== undefined) {
-        const ready = await runtime.opts.confirmStageReadiness({
-          runId: runtime.runId,
-          stageId: runtime.stageId,
-          stageName: runtime.name,
-          signal: runtime.signal
-        });
-        return ready ? { action: "advance" } : { action: "stay" };
-      }
-      return await askReadinessViaStageBroker(runtime.runId, runtime.stageId, runtime.signal);
-    } catch {
-      return { action: "advance" };
-    }
+  const confirmReadiness = async (signal) => {
+    if (runtime.opts.confirmStageReadiness !== undefined) {
+      const ready = await raceAbort(runtime.opts.confirmStageReadiness({
+        runId: runtime.runId,
+        stageId: runtime.stageId,
+        stageName: runtime.name,
+        signal
+      }), signal);
+      return ready ? { action: "advance" } : { action: "stay" };
+    }
+    return await askReadinessViaStageBroker(runtime.runId, runtime.stageId, signal);
   };
   const suppressReadinessForCurrentTurn = () => {
     runtime.state.askUserQuestionObservedThisTurn = false;
@@ -13597,9 +13594,35 @@ function createTrackedStageCaller(input) {
           });
           try {
             while (runtime.state.askUserQuestionObservedThisTurn || repeatReadinessAfterChatTurn) {
-              const decision = await confirmReadiness();
+              runtime.signal.throwIfAborted();
+              if (runtime.stageSnapshot.status === "paused" || runtime.stageSnapshot.status === "blocked") {
+                await runtime.scheduler.waitForStageRelease(runtime.stageId, runtime.releaseLiveHandle);
+                continue;
+              }
+              const controller = new AbortController;
+              runtime.state.readinessController = controller;
+              let decision;
+              try {
+                decision = await confirmReadiness(AbortSignal.any([runtime.signal, controller.signal]));
+                if (decision.action === "advance" || decision.message !== undefined) {
+                  await runtime.scheduler.waitForStageRelease(runtime.stageId, runtime.releaseLiveHandle);
+                }
+                runtime.signal.throwIfAborted();
+                if (controller.signal.aborted) {
+                  await runtime.scheduler.waitForStageRelease(runtime.stageId, runtime.releaseLiveHandle);
+                  continue;
+                }
+              } catch (error) {
+                runtime.signal.throwIfAborted();
+                if (controller.signal.aborted) {
+                  await runtime.scheduler.waitForStageRelease(runtime.stageId, runtime.releaseLiveHandle);
+                  continue;
+                }
+                throw error;
+              }
               if (decision.action === "advance")
                 break;
+              delete runtime.state.readinessController;
               if (runtime.signal.aborted)
                 break;
               runtime.state.askUserQuestionObservedThisTurn = false;
@@ -13742,9 +13765,17 @@ function createTrackedStageCaller(input) {
           const failure = runtime.classifyExecutorFailure(durableCheckpointError.error);
           applyTerminalStageState = () => applyFailureToStage(runtime.stageSnapshot, failure);
         }
-        if (!runtime.state.stageFinalized)
-          applyTerminalStageState?.();
         try {
+          if (terminalStateIsSuccess && runtime.state.readinessController !== undefined) {
+            let pauseVersion;
+            do {
+              pauseVersion = runtime.state.readinessPauseVersion;
+              await runtime.scheduler.waitForStageRelease(runtime.stageId, runtime.releaseLiveHandle);
+            } while (pauseVersion !== runtime.state.readinessPauseVersion);
+            runtime.signal.throwIfAborted();
+          }
+          if (!runtime.state.stageFinalized)
+            applyTerminalStageState?.();
           await runtime.finalizeStageSnapshot();
         } catch (err) {
           finalizationError ??= { thrown: true, error: err };
@@ -13762,6 +13793,9 @@ function createTrackedStageCaller(input) {
       input.limiter.release();
       if (finalizationError !== undefined)
         throwFinalizationError(finalizationError.error);
+      delete runtime.state.readinessController;
+      if (terminalStateIsSuccess && readinessGateEnabled)
+        runtime.signal.throwIfAborted();
     }
   };
 }
@@ -14122,12 +14156,26 @@ function createStageControlHandle(runtime) {
     async pause() {
       runtime.throwIfStageMutationBlocked();
       const statusBeforePause = runtime.stageSnapshot.status;
+      let readinessPauseVersion;
+      if (runtime.state.readinessController !== undefined) {
+        runtime.scheduler.ensureReleaseBarrier(runtime.stageId);
+        readinessPauseVersion = (runtime.state.readinessPauseVersion ?? 0) + 1;
+        runtime.state.readinessPauseVersion = readinessPauseVersion;
+      }
       if (statusBeforePause === "pending" || statusBeforePause === "running" || runtime.innerCtx.isStreaming) {
-        await runtime.innerCtx.__requestPause();
+        try {
+          await runtime.innerCtx.__requestPause();
+        } catch (error) {
+          if (readinessPauseVersion !== undefined && runtime.state.readinessPauseVersion === readinessPauseVersion && runtime.stageSnapshot.status !== "paused" && runtime.stageSnapshot.status !== "blocked" && !runtime.scheduler.hasCascadePauseOwners(runtime.stageId)) {
+            runtime.scheduler.releaseStageBarrier(runtime.stageId);
+          }
+          throw error;
+        }
       }
       const changed = runtime.activeStore.recordStagePaused(runtime.runId, runtime.stageId);
       if (changed) {
         runtime.scheduler.ensureReleaseBarrier(runtime.stageId);
+        runtime.state.readinessController?.abort(new Error("atomic-workflows: readiness paused"));
         await runtime.scheduler.cascadePauseFrom(runtime.stageId);
         const run = runtime.activeStore.runs().find((candidate) => candidate.id === runtime.runId);
         const stillActive = run?.stages.some((stage) => stage.status === "running" && stage.id !== runtime.stageId) ?? false;

package/dist/builtin/workflows/src/shared/authoring-contract-stage.d.ts

@@ -358,6 +358,8 @@ export interface WorkflowChainOptions extends WorkflowSharedTaskDefaults {
 export interface WorkflowParallelOptions extends WorkflowSharedTaskDefaults {
     readonly concurrency?: number;
     readonly failFast?: boolean;
+    /** Static discovery only: literal conservative stage names/globs for an otherwise opaque step array. */
+    readonly possibleStageNames?: readonly string[];
 }
 export type WorkflowTaskSessionOptions = StageOptions & WorkflowTaskSessionFields;
 export interface WorkflowRunChildOptions<TInputs extends WorkflowInputValues = WorkflowInputValues> {