@bastani/atomic 0.9.9 → 0.9.10-alpha.1

package/dist/builtin/workflows/src/runs/background/durable-resume-transition.ts

@@ -0,0 +1,63 @@
+import type { DurableWorkflowBackend } from "../../durable/backend.js";
+import {
+  getLoadableDurableWorkflow,
+  transitionDurableWorkflowStatus,
+} from "../../durable/workflow-status-transition.js";
+import { getDurableBackend } from "../../durable/factory.js";
+
+const pendingRunningTransitions = new WeakMap<DurableWorkflowBackend, Set<string>>();
+
+export type DurableResumeTransitionOutcome = "transitioned" | "not_needed" | "refused";
+
+function transitionsFor(backend: DurableWorkflowBackend): Set<string> {
+  let transitions = pendingRunningTransitions.get(backend);
+  if (transitions === undefined) {
+    transitions = new Set();
+    pendingRunningTransitions.set(backend, transitions);
+  }
+  return transitions;
+}
+
+/** Whether a previous visible resume still needs its durable running write. */
+export function hasPendingDurableResumeTransition(runId: string): boolean {
+  return pendingRunningTransitions.get(getDurableBackend())?.has(runId) ?? false;
+}
+
+/** Persist and flush the root running transition after visible local resume. */
+export async function markDurableResumed(runId: string): Promise<DurableResumeTransitionOutcome> {
+  const backend = getDurableBackend();
+  const pending = transitionsFor(backend);
+  const handle = getLoadableDurableWorkflow(backend, runId);
+  if (handle === undefined) {
+    pending.delete(runId);
+    return "not_needed";
+  }
+  if (!pending.has(runId) && handle.status === "running") return "not_needed";
+  if (!pending.has(runId) && handle.status !== "paused") return "refused";
+  if (pending.has(runId) && handle.status !== "paused" && handle.status !== "running") {
+    pending.delete(runId);
+    return "refused";
+  }
+  pending.add(runId);
+  try {
+    // Reissue even when an earlier failed flush already changed the local
+    // mirror to running. Persistent backends need a new queued write to retry.
+    const transitioned = await transitionDurableWorkflowStatus(
+      backend,
+      runId,
+      pending.has(runId) ? ["paused", "running"] : ["paused"],
+      "running",
+    );
+    if (!transitioned) {
+      pending.delete(runId);
+      const authoritative = getLoadableDurableWorkflow(backend, runId);
+      return authoritative?.status === "running" ? "not_needed" : "refused";
+    }
+    await backend.flush();
+    pending.delete(runId);
+    return "transitioned";
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to persist resumed workflow ${runId}: ${detail}`);
+  }
+}

package/dist/builtin/workflows/src/runs/background/quit.ts

@@ -1,61 +1,171 @@
-import { pauseRun, type PauseResult } from "./status.js";
+import type { PauseResult } from "./status.js";
 import { store as defaultStore } from "../../shared/store.js";
 import type { Store } from "../../shared/store-public-types.js";
+import type { RunSnapshot, StageSnapshot } from "../../shared/store-types.js";
+import { expandWorkflowGraph } from "../../shared/expanded-workflow-graph.js";
 import { topLevelWorkflowRuns } from "../../shared/run-visibility.js";
-import type { StageControlRegistry } from "../foreground/stage-control-registry.js";
+import {
+  stageControlRegistry as defaultStageControlRegistry,
+  type StageControlHandle,
+  type StageControlRegistry,
+} from "../foreground/stage-control-registry.js";
 import { getDurableBackend } from "../../durable/factory.js";
+import type { DurableWorkflowBackend } from "../../durable/backend.js";
+import { recordRunTimingCheckpoint } from "../../durable/run-timing.js";
+import {
+  getLoadableDurableWorkflow,
+  transitionDurableWorkflowStatus,
+} from "../../durable/workflow-status-transition.js";
 
 export type QuitRunResult = PauseResult;
+type QuitAllRunResult = QuitRunResult | {
+  readonly ok: false;
+  readonly runId: string;
+  readonly reason: "pause_failed";
+  readonly message: string;
+};
 
 /**
- * Quit/detach a workflow UI without authoritatively killing the workflow.
+ * Gracefully quit workflow work without destructive cancellation.
  *
- * This is the graph-panel/orchestrator close affordance: it pauses any live
- * stage handles when possible, annotates the run as resumable via
- * `/workflow resume`, and deliberately does NOT abort through the cancellation
- * registry or append a terminal `workflow.run.end` entry. `/workflow kill`
- * remains the only explicit non-resumable manual kill path.
+ * This is the graceful public quit primitive: it waits for every currently
+ * controllable stage to acknowledge its pause, then annotates the run as
+ * resumable via `/workflow resume`. It deliberately does NOT abort through the
+ * cancellation registry or append a terminal `workflow.run.end` entry.
+ * Destructive cancellation remains an internal lifecycle mechanism.
  */
-export function quitRun(
+export async function quitRun(
   runId: string,
   opts?: {
     store?: Store;
     stageControlRegistry?: StageControlRegistry;
   },
-): QuitRunResult {
+): Promise<QuitRunResult> {
   const activeStore = opts?.store ?? defaultStore;
+  const registry = opts?.stageControlRegistry ?? defaultStageControlRegistry;
   const run = activeStore.runs().find((candidate) => candidate.id === runId);
   if (!run) return { ok: false, runId, reason: "not_found" };
   if (run.endedAt !== undefined) return { ok: false, runId, reason: "already_ended" };
 
-  const paused = pauseRun(runId, opts);
-  if (!paused.ok && paused.reason !== "no_active_stages") return paused;
+  const graph = expandWorkflowGraph(activeStore.snapshot(), runId);
+  const handles = controllableHandles(activeStore, registry, runId);
+  const promptStages = graph.stages.filter((stage) =>
+    stage.pendingPrompt !== undefined || stage.inputRequest !== undefined || stage.status === "awaiting_input"
+  );
+  const hasPausedState = run.status === "paused" || graph.stages.some((stage) => stage.status === "paused");
+  if (handles.length === 0 && promptStages.length === 0 && !hasPausedState) {
+    return { ok: false, runId, reason: "no_active_stages" };
+  }
+
+  const paused: StageSnapshot[] = [];
+  const pausedRunIds = new Set<string>();
+  const pausable = handles.filter(({ handle }) => handle.status !== "paused");
+  const settled = await Promise.allSettled(pausable.map(({ handle }) => handle.pause()));
+  const pauseFailures: string[] = [];
+  settled.forEach((result, index) => {
+    const target = pausable[index]!;
+    if (result.status === "rejected") {
+      const message = result.reason instanceof Error ? result.reason.message : String(result.reason);
+      pauseFailures.push(`${target.controlRunId}/${target.handle.stageId}: ${message}`);
+      return;
+    }
+    const controlRun = activeStore.runs().find((candidate) => candidate.id === target.controlRunId);
+    if (controlRun?.endedAt !== undefined) return;
+    activeStore.recordStagePaused(target.controlRunId, target.handle.stageId);
+    const stage = activeStore.runs().find((candidate) => candidate.id === target.controlRunId)
+      ?.stages.find((candidate) => candidate.id === target.handle.stageId);
+    if (stage?.status === "paused") {
+      pausedRunIds.add(target.controlRunId);
+      paused.push(structuredClone(stage));
+    }
+  });
+  if (pauseFailures.length > 0) {
+    throw new Error(`Failed to pause workflow stages: ${pauseFailures.join("; ")}`);
+  }
+
+  for (const promptStage of promptStages) {
+    const target = promptStage.workflowGraphTarget;
+    activeStore.recordStagePaused(target.runId, target.stageId);
+    pausedRunIds.add(target.runId);
+  }
+  const current = activeStore.runs().find((candidate) => candidate.id === runId);
+  if (current === undefined) return { ok: false, runId, reason: "not_found" };
+  if (current.endedAt !== undefined) return { ok: false, runId, reason: "already_ended" };
+  const durableTransition = await markDurableQuit(runId, current);
+  if (durableTransition === "refused") return { ok: false, runId, reason: "already_ended" };
+  for (const pausedRunId of pausedRunIds) activeStore.recordRunPaused(pausedRunId);
   activeStore.recordRunPaused(runId, undefined, { exitReason: "quit", resumable: true });
-  // Mark the durable handle inactive so `/workflow resume` in this or another
-  // session can discover it again. While the run stays `running` in the store
-  // and (after a fresh dispatch) in the durable backend, it is hidden from the
-  // resume selector and refused on resume; quitting flips durable to `paused`.
-  markDurableQuit(runId);
-  return paused.ok ? paused : { ok: true, runId, paused: [] };
+  return { ok: true, runId, paused };
 }
 
-function markDurableQuit(runId: string): void {
-  let backend;
+function controllableHandles(
+  activeStore: Store,
+  registry: StageControlRegistry,
+  runId: string,
+): Array<{ controlRunId: string; handle: StageControlHandle }> {
+  const graph = expandWorkflowGraph(activeStore.snapshot(), runId);
+  const controlRunIds = new Set<string>([runId]);
+  for (const stage of graph.stages) controlRunIds.add(stage.workflowGraphTarget.runId);
+  return [...controlRunIds].flatMap((controlRunId) =>
+    registry.run(controlRunId).stages()
+      .filter((handle) =>
+        handle.status === "running" || handle.status === "pending" ||
+        handle.status === "awaiting_input" || handle.status === "paused"
+      )
+      .map((handle) => ({ controlRunId, handle })),
+  );
+}
+
+async function markDurableQuit(runId: string, run: RunSnapshot): Promise<"transitioned" | "not_needed" | "refused"> {
+  const backend = discoverDurableQuitBackend(runId);
+  if (backend === undefined) return "not_needed";
+  // The workflow is durably tracked, so a failure to persist the paused
+  // transition or flush it must surface. Swallowing it here would let quitRun
+  // record a resumable pause that no future process could actually resume from.
+  const transitioned = await transitionDurableWorkflowStatus(
+    backend, runId, ["running", "paused"], "paused", undefined, true,
+  );
+  if (!transitioned) return "refused";
+  // Persist the exact accumulated run elapsed at quit time so a later durable
+  // resume seeds the total workflow duration with prior-session time.
+  recordRunTimingCheckpoint(backend, run);
+  await backend.flush();
+  return "transitioned";
+}
+
+/**
+ * Resolve the durable backend only when `runId` is durably tracked. Discovery
+ * stays best-effort for custom backends that throw on unsupported inspection;
+ * the persistence writes performed after a positive match are intentionally
+ * left to propagate so genuine durable failures are not masked.
+ */
+function discoverDurableQuitBackend(runId: string): DurableWorkflowBackend | undefined {
   try {
-    backend = getDurableBackend();
+    const backend = getDurableBackend();
+    return getLoadableDurableWorkflow(backend, runId) === undefined ? undefined : backend;
   } catch {
-    return;
-  }
-  if (backend.getWorkflow(runId) !== undefined) {
-    backend.setWorkflowStatus(runId, "paused", undefined, true);
+    return undefined;
   }
 }
 
-export function quitAllRuns(opts?: {
+export async function quitAllRuns(opts?: {
   store?: Store;
   stageControlRegistry?: StageControlRegistry;
-}): QuitRunResult[] {
+}): Promise<QuitAllRunResult[]> {
   const activeStore = opts?.store ?? defaultStore;
-  const inFlight = topLevelWorkflowRuns(activeStore.runs()).filter((r) => r.endedAt === undefined);
-  return inFlight.map((r) => quitRun(r.id, { store: activeStore, stageControlRegistry: opts?.stageControlRegistry }));
+  const inFlight = topLevelWorkflowRuns(activeStore.runs()).filter((run) => run.endedAt === undefined);
+  const attempts = inFlight.map((run) =>
+    quitRun(run.id, { store: activeStore, stageControlRegistry: opts?.stageControlRegistry })
+  );
+  const settled = await Promise.allSettled(attempts);
+  return settled.map((result, index) => {
+    if (result.status === "fulfilled") return result.value;
+    const runId = inFlight[index]!.id;
+    return {
+      ok: false,
+      runId,
+      reason: "pause_failed",
+      message: result.reason instanceof Error ? result.reason.message : String(result.reason),
+    };
+  });
 }

package/dist/builtin/workflows/src/runs/background/resume-acknowledgements.ts

@@ -0,0 +1,97 @@
+import type { Store } from "../../shared/store-public-types.js";
+import type { StageSnapshot } from "../../shared/store-types.js";
+import type { StageControlHandle } from "../foreground/stage-control-registry.js";
+
+export interface ResumeAcknowledgementTarget {
+  readonly controlRunId: string;
+  readonly handle: StageControlHandle;
+}
+
+export interface ResumeAcknowledgementResult {
+  readonly resumed: readonly StageSnapshot[];
+  readonly acknowledged: number;
+  /** Rejections whose targets are still visibly paused and therefore retryable. */
+  readonly failures: readonly string[];
+  /** Rejections reported after the target had already become visibly running. */
+  readonly lateFailures: readonly string[];
+}
+
+function targetStage(
+  store: Store,
+  target: ResumeAcknowledgementTarget,
+): StageSnapshot | undefined {
+  return store.runs()
+    .find((run) => run.id === target.controlRunId)
+    ?.stages.find((stage) => stage.id === target.handle.stageId);
+}
+
+function targetIsActuallyPaused(store: Store, target: ResumeAcknowledgementTarget): boolean {
+  const run = store.runs().find((candidate) => candidate.id === target.controlRunId);
+  const stage = targetStage(store, target);
+  if (run?.endedAt !== undefined || stage?.endedAt !== undefined) return false;
+  return stage?.status === "paused" || stage?.status === "blocked"
+    || (run?.status === "paused" && target.handle.status === "paused");
+}
+
+/** Attempt every actually-paused control, then reconcile outcomes from visible state in target order. */
+export async function settleResumeAcknowledgements(
+  store: Store,
+  targets: readonly ResumeAcknowledgementTarget[],
+  message?: string,
+): Promise<ResumeAcknowledgementResult> {
+  const attempted = targets.filter(
+    (target) => target.handle.status === "paused" && targetIsActuallyPaused(store, target),
+  );
+  const settled = await Promise.allSettled(
+    attempted.map(({ handle }) => handle.resume(message)),
+  );
+  const resumed: StageSnapshot[] = [];
+  let acknowledged = 0;
+  const failures: string[] = [];
+  const lateFailures: string[] = [];
+  const resumedRunIds = new Set<string>();
+  settled.forEach((result, index) => {
+    const target = attempted[index]!;
+    const controlRun = store.runs().find((candidate) => candidate.id === target.controlRunId);
+    const controlVisiblyRunning = target.handle.status === "running"
+      || target.handle.status === "pending"
+      || target.handle.status === "awaiting_input";
+    if (result.status === "fulfilled" || controlVisiblyRunning) acknowledged += 1;
+    if ((result.status === "fulfilled" || controlVisiblyRunning) && controlRun?.endedAt === undefined) {
+      const stage = targetStage(store, target);
+      if (stage?.status === "paused" || stage?.status === "blocked") {
+        store.recordStageResumed(target.controlRunId, target.handle.stageId);
+      }
+    }
+    const stage = targetStage(store, target);
+    const visiblyRunning = controlRun?.endedAt === undefined && stage?.status === "running";
+    if (visiblyRunning && stage !== undefined) {
+      resumedRunIds.add(target.controlRunId);
+      resumed.push(structuredClone(stage));
+    }
+    if (result.status !== "rejected") return;
+    const detail = result.reason instanceof Error ? result.reason.message : String(result.reason);
+    const qualified = `${target.controlRunId}/${target.handle.stageId}: ${detail}`;
+    if (visiblyRunning) lateFailures.push(qualified);
+    else if (controlRun?.endedAt === undefined && targetIsActuallyPaused(store, target)) failures.push(qualified);
+  });
+  for (const controlRunId of resumedRunIds) store.recordRunResumed(controlRunId);
+  return { resumed, acknowledged, failures, lateFailures };
+}
+
+/** Let immediate prompt/root finalizers settle before public resume reconciliation. */
+export async function waitForResumeReconciliation(acknowledged: number): Promise<void> {
+  if (acknowledged > 0) await new Promise<void>((resolve) => setTimeout(resolve, 0));
+}
+
+/** Existing optional message channel for a fulfilled zero-stage or terminal acknowledgement. */
+export function resumeAcknowledgementMessage(
+  acknowledged: number,
+  resumed: number,
+  runId: string,
+  current: { readonly status: string; readonly endedAt?: number },
+): string | undefined {
+  if (acknowledged === 0 || (current.endedAt === undefined && resumed > 0)) return undefined;
+  return `Resume acknowledged; workflow ${runId} ${current.endedAt !== undefined
+    ? `reached terminal status ${current.status}` : "can continue"}.`;
+}

package/dist/builtin/workflows/src/runs/background/run-inspect.ts

@@ -0,0 +1,111 @@
+/**
+ * Read-only per-run inspection surface.
+ *
+ * Extracted from `status.ts` (which stays focused on lifecycle status,
+ * cancellation, and resume helpers) so both files respect the repository
+ * file-length gate.
+ *
+ * cross-ref: spec §5.5
+ */
+
+import type { Store } from "../../shared/store.js";
+import type { RunSnapshot, RunStatus } from "../../shared/store-types.js";
+import type { WorkflowInputValues, WorkflowOutputValues } from "../../shared/types.js";
+import { store as defaultStore } from "../../shared/store.js";
+import { expandWorkflowGraph } from "../../shared/expanded-workflow-graph.js";
+import { actionableReturnedStatusText, effectiveRunStatus, structuredRecoverableWorkflowFailureText } from "../../shared/returned-run-status.js";
+
+/**
+ * Per-run detail returned by {@link inspectRun}. A read-only view over the
+ * store snapshot suitable for the "  RUN" detail surface — same data the
+ * resume snapshot carries, plus a normalised `mode` field derived from
+ * stage shape so renderers don't have to recompute it.
+ */
+export interface RunDetail {
+  readonly runId: string;
+  readonly name: string;
+  readonly status: RunStatus;
+  readonly mode: "single" | "chain";
+  readonly startedAt: number;
+  readonly endedAt?: number;
+  readonly durationMs?: number;
+  readonly pausedDurationMs?: number;
+  readonly pausedAt?: number;
+  readonly resumedAt?: number;
+  /** Elapsed ms inherited from prior sessions of a resumed durable run. */
+  readonly accumulatedDurationMs?: number;
+  readonly inputs: Readonly<WorkflowInputValues>;
+  readonly stages: readonly RunSnapshot["stages"][number][];
+  readonly result?: WorkflowOutputValues;
+  readonly error?: string;
+  readonly exited?: boolean;
+  readonly exitReason?: string;
+  readonly failureKind?: RunSnapshot["failureKind"];
+  readonly failureCode?: RunSnapshot["failureCode"];
+  readonly failureRecoverability?: RunSnapshot["failureRecoverability"];
+  readonly failureDisposition?: RunSnapshot["failureDisposition"];
+  readonly failedStageId?: string;
+  readonly resumable?: boolean;
+  readonly retryAfterMs?: number;
+  readonly blockedAt?: number;
+}
+
+export type InspectRunResult =
+  | { ok: true; runId: string; detail: RunDetail }
+  | { ok: false; runId: string; reason: "not_found" };
+
+/**
+ * Look up a single run by id (full UUID or unique prefix) and return a
+ * normalised {@link RunDetail} for the per-run text/TUI surfaces.
+ *
+ * Returns ok:false "not_found" when no run matches, "ambiguous" when a
+ * prefix matches multiple. Read-only: does not mutate the store.
+ */
+export function inspectRun(
+  runId: string,
+  opts?: { store?: Store },
+): InspectRunResult {
+  const activeStore = opts?.store ?? defaultStore;
+  const runs = activeStore.runs();
+
+  const exact = runs.find((r) => r.id === runId);
+  const candidate = exact ?? (runs.length > 0 ? runs.find((r) => r.id.startsWith(runId)) : undefined);
+
+  if (!candidate) {
+    return { ok: false, runId, reason: "not_found" };
+  }
+
+  // Deep copy so callers cannot mutate the store via the snapshot.
+  const copy = structuredClone(candidate);
+  const expandedStages = expandWorkflowGraph(activeStore.snapshot(), copy.id).stages;
+
+  const detail: RunDetail = {
+    runId: copy.id,
+    name: copy.name,
+    status: effectiveRunStatus(copy),
+    mode: expandedStages.length > 1 ? "chain" : "single",
+    startedAt: copy.startedAt,
+    endedAt: copy.endedAt,
+    durationMs: copy.durationMs,
+    pausedDurationMs: copy.pausedDurationMs,
+    pausedAt: copy.pausedAt,
+    resumedAt: copy.resumedAt,
+    accumulatedDurationMs: copy.accumulatedDurationMs,
+    inputs: copy.inputs,
+    stages: expandedStages.map((stage) => structuredClone(stage)),
+    result: copy.result,
+    error: copy.error ?? (effectiveRunStatus(copy) === copy.status ? undefined : (structuredRecoverableWorkflowFailureText(copy) ?? actionableReturnedStatusText(copy.result))),
+    exited: copy.exited,
+    exitReason: copy.exitReason,
+    failureKind: copy.failureKind,
+    failureCode: copy.failureCode,
+    failureRecoverability: copy.failureRecoverability,
+    failureDisposition: copy.failureDisposition,
+    failedStageId: copy.failedStageId,
+    resumable: copy.resumable,
+    retryAfterMs: copy.retryAfterMs,
+    blockedAt: copy.blockedAt,
+  };
+
+  return { ok: true, runId: copy.id, detail };
+}

package/dist/builtin/workflows/src/runs/background/runner.ts

@@ -54,12 +54,22 @@ export interface DetachedRunOpts
   jobs?: JobTracker;
   /** Runtime execution mode for UI/prompt policy. Defaults to interactive. */
   executionMode?: WorkflowExecutionMode;
+  /**
+   * Observes the raw executor outcome. Fulfillment includes the executor's
+   * RunResult; rejection includes the thrown setup/final-flush error. The job
+   * promise still resolves either way.
+   */
+  onRawSettled?: (ok: boolean, result: RunResult | undefined, error: unknown | undefined) => void;
 }
 
 // ---------------------------------------------------------------------------
 // Helper — build accepted result object
 // ---------------------------------------------------------------------------
 
+export function workflowConnectGuidance(runId: string): string {
+  return `Run /workflow connect ${runId} to see agents working and chat with and steer each stage.`;
+}
+
 export function buildDetachedAccepted(
   name: string,
   runId: string,
@@ -69,7 +79,7 @@ export function buildDetachedAccepted(
     name,
     runId,
     status: "running",
-    message: `Workflow "${name}" started in background (runId: ${runId}).`,
+    message: `Workflow "${name}" started in background (runId: ${runId}). ${workflowConnectGuidance(runId)}`,
     stages: [],
   };
 }
@@ -118,6 +128,7 @@ export function runDetached<
     cancellation: _cancellation,
     ui: _ui,
     store: storeOverride,
+    onRawSettled,
     ...restOpts
   } = opts;
   const store: Store = storeOverride ?? defaultStore;
@@ -131,25 +142,43 @@ export function runDetached<
     deferWorkflowStart: true,
   };
 
-  // 5. Start background promise
-  const backgroundPromise: Promise<RunResult> = syncRun(def, inputs, execOpts);
-
-  // 6. Build void promise that unregisters on settle and swallows rejections
-  const voidPromise: Promise<void> = backgroundPromise.then(
-    () => {
-      tracker.unregister(runId);
-      // CancellationRegistry.unregister called by executor in its finally block.
-    },
-    (_err: unknown) => {
-      // Reject path: executor already records failed/killed status in store.
-      // Swallow here to avoid unhandled rejection — store is source of truth.
+  // 5-7. Register the job BEFORE starting the executor, so a registration
+  //   failure can never leave a started (and now-orphaned) executor running.
+  //   The job promise settles when the executor settles; it is wired below.
+  let settleJob: () => void = () => {};
+  const voidPromise: Promise<void> = new Promise<void>((resolve) => { settleJob = resolve; });
+  try {
+    tracker.register({ runId, controller, promise: voidPromise });
+  } catch (error) {
+    controller.abort(error);
+    registry.unregister(runId);
+    settleJob();
+    throw error;
+  }
+  let backgroundPromise: Promise<RunResult>;
+  try {
+    backgroundPromise = syncRun(def, inputs, execOpts);
+  } catch (error) {
+    controller.abort(error);
+    registry.unregister(runId);
+    tracker.unregister(runId);
+    settleJob();
+    throw error;
+  }
+  const settle = (ok: boolean, result: RunResult | undefined, error: unknown | undefined): void => {
+    try {
+      onRawSettled?.(ok, result, error);
+    } finally {
+      registry.unregister(runId);
       tracker.unregister(runId);
-    },
+      settleJob();
+    }
+  };
+  void backgroundPromise.then(
+    (result) => { settle(true, result, undefined); },
+    (error: unknown) => { settle(false, undefined, error); },
   );
 
-  // 7. Register live job in tracker
-  tracker.register({ runId, controller, promise: voidPromise });
-
   // 8. Return immediate accepted result
   return buildDetachedAccepted(def.name, runId);
 }

package/dist/builtin/workflows/src/runs/background/startup-admission.ts

@@ -0,0 +1,77 @@
+import type { RunResult } from "../foreground/executor-types.js";
+import type { WorkflowDefinition, WorkflowInputValues, WorkflowOutputValues } from "../../shared/types.js";
+import { runDetached, type DetachedAccepted, type DetachedRunOpts } from "./runner.js";
+
+export type WorkflowStartupAdmission =
+  | { readonly started: true }
+  | {
+      readonly started: false;
+      readonly resultError: string | undefined;
+      readonly error: unknown | undefined;
+    };
+
+export interface WorkflowStartupObserver {
+  readonly wait: Promise<WorkflowStartupAdmission>;
+  readonly onWorkflowStartReady: () => void;
+  readonly onRawSettled: (
+    ok: boolean,
+    result: RunResult | undefined,
+    error: unknown | undefined,
+  ) => void;
+}
+
+/** Resolve startup readiness separately from later workflow-body settlement. */
+export function createWorkflowStartupObserver(
+  beforeReady?: () => void,
+): WorkflowStartupObserver {
+  const startup = Promise.withResolvers<WorkflowStartupAdmission>();
+  return {
+    wait: startup.promise,
+    onWorkflowStartReady: () => {
+      beforeReady?.();
+      startup.resolve({ started: true });
+    },
+    onRawSettled: (_ok, result, error) => {
+      startup.resolve({ started: false, resultError: result?.error, error });
+    },
+  };
+}
+export function launchDetachedUntilStartup<
+  TInputs extends WorkflowInputValues,
+  TRunInputs extends WorkflowInputValues = TInputs,
+>(
+  def: WorkflowDefinition<TInputs, WorkflowOutputValues, TRunInputs>,
+  inputs: Readonly<Record<string, unknown>>,
+  opts: DetachedRunOpts = {},
+): { readonly accepted: DetachedAccepted; readonly wait: Promise<WorkflowStartupAdmission> } {
+  const priorReady = opts.onWorkflowStartReady;
+  const priorSettled = opts.onRawSettled;
+  const startup = createWorkflowStartupObserver(priorReady);
+  const accepted = runDetached(def, inputs, {
+    ...opts,
+    onWorkflowStartReady: startup.onWorkflowStartReady,
+    onRawSettled: (ok, result, error) => {
+      try {
+        priorSettled?.(ok, result, error);
+      } finally {
+        startup.onRawSettled(ok, result, error);
+      }
+    },
+  });
+  return { accepted, wait: startup.wait };
+}
+
+export function workflowStartupFailureMessage(
+  admission: Extract<WorkflowStartupAdmission, { started: false }>,
+  snapshotError: string | undefined,
+  fallback: string,
+): string {
+  return admission.resultError
+    ?? snapshotError
+    ?? (admission.error instanceof Error
+      ? admission.error.message
+      : admission.error === undefined
+        ? undefined
+        : String(admission.error))
+    ?? fallback;
+}