@bastani/atomic 0.9.12 → 0.9.13-alpha.1

package/dist/builtin/workflows/README.md

@@ -7,6 +7,8 @@
 
 Default to workflows for non-trivial work and requests with inherent structure plus a verifiable objective; reserve direct chat for tiny deterministic low-risk work. Workflow-first is not builtin-only or monolithic: Atomic can author custom TypeScript `workflow({...})` definitions inline, import reusable project/package workflows or builtins from `@bastani/workflows/builtin`, and nest them with `ctx.workflow(...)`. Imported children may nest further workflows within `maxDepth`, so compose proven research, implementation, design, verification, and approval graphs rather than copying them. Custom parents can also use runtime classification, dynamic fan-out and synthesis, adversarial verification, candidate tournaments, HIL gates, and bounded convergence.
 
+Workflow stage sessions are created in process and receive a typed stage policy rather than inheriting subagent environment flags. Resource reload never mutates `process.env`; stage options carry the subagent management/fanout policy directly, so concurrent stage creation is race-free while existing tool allowlists and orchestration depth limits remain authoritative. Legacy child environment keys are only a compatibility path for older hosts.
+
 <p align="center">
   <a href="#authoring-api">Authoring API</a>
   &nbsp;·&nbsp;
@@ -43,19 +45,27 @@ After Atomic is running, use `/workflow reload` or the workflow tool's `reload`
 
 ### Workflow lifecycle notifications
 
-Workflow lifecycle notices are enabled by default. They send steer prompts into the main chat/model context when a run completes, fails, or ends blocked. Awaiting-input prompts are tracked for dedupe/restore, but they do not wake the main chat agent. Configure lifecycle tracking in the same extension config file:
+Workflow lifecycle notices are enabled by default. They send steer prompts into the main chat/model context when a run completes, fails, or ends blocked, and when a user starts, pauses, quits, or resumes one. Awaiting-input prompts are tracked for dedupe/restore, but they do not wake the main chat agent. Configure lifecycle tracking in the same extension config file:
 
 ```json
 {
   "workflowNotifications": {
     "enabled": true,
-    "notifyOn": ["completed", "failed", "blocked", "awaiting_input"]
+    "notifyOn": ["started", "completed", "failed", "blocked", "awaiting_input", "paused", "quit", "resumed"]
   }
 }
 ```
 
 Set `enabled` to `false` to disable all lifecycle notices, or narrow `notifyOn` to a non-empty list of selected events. Completion, failure, and blocked lifecycle notices are emitted for top-level workflow runs, use steer delivery, and wake an idle model so the lifecycle update enters the model context when it happens. When a fulfilled workflow body leaves admitted tool failures, the engine promotes the first admission and persists that exact tool origin for the failed notice. Ordinary body rejections retain their original error and failed graph nodes without claiming a tool origin because transparent native promises do not expose the source promise; this prevents a caught tool rejection from being misattributed when body code later throws the same object or primitive. Nested child workflow completion/failure is reflected inside the expanded parent graph instead of producing separate top-level completion cards. Awaiting-input states are tracked for dedupe/restore, but workflows do not enqueue main-chat `/workflow connect` cards for them; prompt state remains visible through workflow status/connect surfaces, avoiding stale actionable cards if a prompt resolves while the main chat is streaming.
 
+Control notices report deliberate actions on a top-level run: `/workflow <name>` produces a `WORKFLOW STARTED` card (`▶`), `/workflow pause` a `WORKFLOW PAUSED` card (`⏸`, warning tone), `/workflow quit` a `WORKFLOW QUIT` card (`⏹`, warning tone, plus a `resumable` field), and `/workflow resume` a `WORKFLOW RESUMED` card (`▶`). All four travel the same steer delivery, capped-backoff retry, and card path as the failure notice. The paused and quit text says the stop was deliberate and user-requested and instructs the model not to resume the run or take the work over unless asked, hinting `/workflow resume <run-id>`; the resumed text does not, since the run is progressing again.
+
+Only user actions notify. The matching `workflow({ action: "run" | "pause" | "quit" | "resume" })` tool calls stay silent, because the tool result already reports them to the agent, and `/workflow interrupt` raises nothing. Engine-internal transitions stay silent too — a notice exists only when a control path named an actor — which is what keeps answering a human-in-the-loop prompt, per-stage control, and the resume-acknowledgement pass from flooding the chat.
+
+Each notice carries two attributions. *Origin* is who launched the run and renders on every kind as "which you started" or "which the user started"; it is recorded once at dispatch, persisted through session restore and durable resume, and inherited by a continuation from the run it continues. *Actor* is who performed this one event ("The user paused"). A run with no recorded origin omits the clause rather than guessing one.
+
+One request produces one notice. A whole-run pause or resume reports at run scope; a stage-scoped pause or resume that leaves siblings paused reports at stage scope, and one that stops or restarts the whole run reports the run instead. A quit reports the quit alone, never the pause it publishes on the way. Because control actions are reversible, they are deduplicated by run id together with the occurrence timestamp (`pausedAt`/`quitAt`/`resumedAt`), so pause → resume → pause → resume notifies four times while repeated snapshot invalidations at one unchanged state notify once. Resuming reports a resume and never a start, whoever asked for it. Resuming a failed or blocked run launches a continuation under a fresh run id and its notice names both; resuming a quit run reuses the original workflow id so durable checkpoints replay, so that notice names the one id. A run already started, paused, or quit when notifications install (restore, replay, `/reload`, session-preserving reinstall) is seeded as delivered and stays silent, and nested child runs never notify at top level.
+
 When a stage human-in-the-loop prompt is answered from the workflow TUI/stage chat, workflows also emits a separate display-only `workflows:hil-answer-notice` custom message. It records the answer for user-visible audit, but it does not wake the main agent, enter LLM context, or authorize answering later workflow prompts. Answers sent by the main-chat `workflow` tool do not emit this notice because the tool result already tells the main agent what happened.
 
 ---
@@ -802,7 +812,7 @@ Config-based discovery (`~/.atomic/agent/extensions/workflow/config.json` or `.a
   },
   "workflowNotifications": {
     "enabled": true,
-    "notifyOn": ["completed", "failed", "blocked", "awaiting_input"]
+    "notifyOn": ["started", "completed", "failed", "blocked", "awaiting_input", "paused", "quit", "resumed"]
   }
 }
 ```

package/dist/builtin/workflows/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/workflows",
-  "version": "0.9.12",
+  "version": "0.9.13-alpha.1",
   "private": true,
   "description": "Atomic extension for multi-stage workflow authoring and execution.",
   "contributors": [

package/dist/builtin/workflows/src/durable/backend.ts

@@ -203,6 +203,11 @@ export class InMemoryDurableBackend implements DurableWorkflowBackend {
 				: existing?.handle.invocationCwd !== undefined
 					? { invocationCwd: existing.handle.invocationCwd }
 					: {}),
+			...(handle.origin !== undefined
+				? { origin: handle.origin }
+				: existing?.handle.origin !== undefined
+					? { origin: existing.handle.origin }
+					: {}),
 			...(handle.workflowCwd !== undefined
 				? { workflowCwd: handle.workflowCwd }
 				: existing?.handle.workflowCwd !== undefined
@@ -474,6 +479,7 @@ export class InMemoryDurableBackend implements DurableWorkflowBackend {
 			...(h.resumable !== undefined ? { resumable: h.resumable } : {}),
 			...workflowFailureFields(h),
 			...(h.invocationCwd !== undefined ? { invocationCwd: h.invocationCwd } : {}),
+			...(h.origin !== undefined ? { origin: h.origin } : {}),
 			...(h.workflowCwd !== undefined ? { workflowCwd: h.workflowCwd } : {}),
 			...(h.repositoryRoot !== undefined ? { repositoryRoot: h.repositoryRoot } : {}),
 			...(h.gitWorktreeRoot !== undefined ? { gitWorktreeRoot: h.gitWorktreeRoot } : {}),
@@ -554,6 +560,7 @@ function toResumableEntry(handle: DurableWorkflowHandle): ResumableWorkflowEntry
 		...(handle.resumable !== undefined ? { resumable: handle.resumable } : {}),
 		...workflowFailureFields(handle),
 		...(handle.invocationCwd !== undefined ? { invocationCwd: handle.invocationCwd } : {}),
+		...(handle.origin !== undefined ? { origin: handle.origin } : {}),
 		...(handle.workflowCwd !== undefined ? { workflowCwd: handle.workflowCwd } : {}),
 		...(handle.repositoryRoot !== undefined ? { repositoryRoot: handle.repositoryRoot } : {}),
 		...(handle.gitWorktreeRoot !== undefined ? { gitWorktreeRoot: handle.gitWorktreeRoot } : {}),

package/dist/builtin/workflows/src/durable/dbos-metadata.ts

@@ -1,3 +1,4 @@
+import type { WorkflowActor } from "../shared/store-types.js";
 import type { WorkflowSerializableValue } from "../shared/types.js";
 import {
 	isWorkflowFailureCode,
@@ -66,6 +67,7 @@ export function encodeMetadata(metadata: DurableWorkflowMetadata): WorkflowSeria
 				: {}),
 			...(metadata.failureDisposition !== undefined ? { failureDisposition: metadata.failureDisposition } : {}),
 			...(metadata.failedToolNodeId !== undefined ? { failedToolNodeId: metadata.failedToolNodeId } : {}),
+			...(metadata.origin !== undefined ? { origin: metadata.origin } : {}),
 			...(metadata.invocationCwd !== undefined ? { invocationCwd: metadata.invocationCwd } : {}),
 			...(metadata.workflowCwd !== undefined ? { workflowCwd: metadata.workflowCwd } : {}),
 			...(metadata.repositoryRoot !== undefined ? { repositoryRoot: metadata.repositoryRoot } : {}),
@@ -167,7 +169,15 @@ function parseDurableWorkflowMetadata(
 		(metadata.gitWorktreeRoot !== undefined && typeof metadata.gitWorktreeRoot !== "string")
 	)
 		return undefined;
-	return metadata as DurableWorkflowMetadata;
+	const { origin, ...metadataWithoutOrigin } = metadata;
+	return {
+		...metadataWithoutOrigin,
+		...(isWorkflowActor(origin) ? { origin } : {}),
+	} as DurableWorkflowMetadata;
+}
+
+function isWorkflowActor(value: WorkflowSerializableValue | undefined): value is WorkflowActor {
+	return value === "user" || value === "agent";
 }
 
 function isDurableWorkflowStatus(value: string): value is DurableWorkflowStatus {

package/dist/builtin/workflows/src/durable/resume-runtime.ts

@@ -206,6 +206,7 @@ export async function resumeDurableWorkflow(
 	const resumeRunOpts: RunOpts = {
 		...deps.baseRunOpts,
 		...(handle.invocationCwd !== undefined ? { cwd: handle.invocationCwd } : {}),
+		...(handle.origin !== undefined ? { origin: handle.origin } : {}),
 		runId: resolved.workflowId,
 		durableBackend: backend,
 	};

package/dist/builtin/workflows/src/durable/tool-primitive.ts

@@ -16,6 +16,7 @@
  */
 
 import { runCallback } from "@bastani/atomic";
+import { sleepOrAbort } from "../runs/shared/retry.js";
 import { flattenTruncatedString } from "../shared/flat-string.js";
 import type { ToolNodeSnapshot } from "../shared/store-types.js";
 import type {
@@ -26,6 +27,9 @@ import type {
 	WorkflowToolPrimitive,
 } from "../shared/types.js";
 import { field, hasProcessFailureEvidence, normalizeCode } from "../shared/workflow-failures-signals.js";
+
+export { sleepOrAbort } from "../runs/shared/retry.js";
+
 import type { DurableWorkflowBackend } from "./backend.js";
 import { durableHash } from "./backend.js";
 import { recordThrowingToolFailure } from "./tool-failure-checkpoint.js";
@@ -660,34 +664,6 @@ async function executeWithRetries<T>(
 	throw lastError ?? new Error("ctx.tool: retries exhausted");
 }
 
-export function sleepOrAbort(ms: number, signal?: AbortSignal): Promise<void> {
-	if (signal?.aborted)
-		return Promise.reject(
-			signal.reason instanceof Error ? signal.reason : new Error("atomic-workflows: workflow cancelled"),
-		);
-	return new Promise((resolve, reject) => {
-		let settled = false;
-		const cleanup = (): void => signal?.removeEventListener("abort", onAbort);
-		const finish = (): void => {
-			if (settled) return;
-			settled = true;
-			cleanup();
-			resolve();
-		};
-		const fail = (err: Error): void => {
-			if (settled) return;
-			settled = true;
-			clearTimeout(timer);
-			cleanup();
-			reject(err);
-		};
-		const timer = setTimeout(finish, ms);
-		const onAbort = (): void =>
-			fail(signal?.reason instanceof Error ? signal.reason : new Error("atomic-workflows: workflow cancelled"));
-		signal?.addEventListener("abort", onAbort, { once: true });
-	});
-}
-
 /**
  * Create a monotonic checkpoint id generator for a workflow.
  */

package/dist/builtin/workflows/src/durable/types.ts

@@ -10,6 +10,7 @@
  */
 
 import type {
+	WorkflowActor,
 	WorkflowFailureCode,
 	WorkflowFailureDisposition,
 	WorkflowFailureKind,
@@ -40,6 +41,8 @@ export interface DurableWorkflowHandle {
 	readonly status: DurableWorkflowStatus;
 	/** Original invocation cwd used to resolve repo-relative workflow defaults on resume. */
 	readonly invocationCwd?: string;
+	/** Who launched this workflow, when the launcher was attributable. */
+	readonly origin?: WorkflowActor;
 	/** Resolved workflow cwd when an input-bound reusable worktree was set up. */
 	readonly workflowCwd?: string;
 	/** Invoking repository root used for reusable worktree validation. */
@@ -276,6 +279,7 @@ export interface DurableWorkflowMetadata {
 	readonly rootWorkflowId?: string;
 	readonly resumable?: boolean;
 	readonly invocationCwd?: string;
+	readonly origin?: WorkflowActor;
 	readonly workflowCwd?: string;
 	readonly repositoryRoot?: string;
 	readonly gitWorktreeRoot?: string;
@@ -301,6 +305,7 @@ export interface ResumableWorkflowEntry {
 	readonly rootWorkflowId?: string;
 	readonly resumable?: boolean;
 	readonly invocationCwd?: string;
+	readonly origin?: WorkflowActor;
 	readonly workflowCwd?: string;
 	readonly repositoryRoot?: string;
 	readonly gitWorktreeRoot?: string;

package/dist/builtin/workflows/src/engine/run.ts

@@ -164,6 +164,7 @@ export async function run<TInputs extends WorkflowInputValues, TRunInputs extend
 		opts.parentRun === undefined
 			? inheritedRunElapsedMs({ backend: durableBackend, runId, continuationSource: opts.continuation?.source })
 			: undefined;
+	const continuationOrigin = opts.continuation !== undefined ? opts.continuation.source.origin : opts.origin;
 	const runSnapshot: RunSnapshot = {
 		id: runId,
 		name: def.name,
@@ -185,6 +186,15 @@ export async function run<TInputs extends WorkflowInputValues, TRunInputs extend
 					resumeFromStageId: opts.continuation.resumeFromStageId,
 				}
 			: {}),
+		// A continuation keeps the attribution of the run it continues rather than
+		// recomputing it, so resuming an agent-started run still reads as one the
+		// agent started. Only the resume itself is attributed to its requester.
+		...(continuationOrigin !== undefined ? { origin: continuationOrigin } : {}),
+		// A resumed run reports the resume that produced it, never a fresh start —
+		// whether it continues under a new id or reclaims the original one.
+		...(opts.resumeActor !== undefined
+			? { resumeActor: opts.resumeActor, resumeSource: "run_control" as const }
+			: {}),
 		...(inheritedElapsedMs !== undefined ? { accumulatedDurationMs: inheritedElapsedMs } : {}),
 	};
 	const classifiedFailures = new Map<unknown, WorkflowFailure>();
@@ -216,6 +226,7 @@ export async function run<TInputs extends WorkflowInputValues, TRunInputs extend
 			...(runSnapshot.parentStageId !== undefined ? { parentStageId: runSnapshot.parentStageId } : {}),
 			...(runSnapshot.rootRunId !== undefined ? { rootRunId: runSnapshot.rootRunId } : {}),
 			...(runSnapshot.resumedFromRunId !== undefined ? { resumedFromRunId: runSnapshot.resumedFromRunId } : {}),
+			...(runSnapshot.origin !== undefined ? { origin: runSnapshot.origin } : {}),
 			...(runSnapshot.resumeFromStageId !== undefined ? { resumeFromStageId: runSnapshot.resumeFromStageId } : {}),
 			...(runSnapshot.accumulatedDurationMs !== undefined
 				? { accumulatedDurationMs: runSnapshot.accumulatedDurationMs }
@@ -550,7 +561,12 @@ export async function run<TInputs extends WorkflowInputValues, TRunInputs extend
 					? undefined
 					: {
 							...durableRootRegistration,
-							...workflowInvocationMetadata(inputRuntimeDefaults, workflowInvocationCwd, gitWorktreeSetupCache),
+							...workflowInvocationMetadata(
+								inputRuntimeDefaults,
+								workflowInvocationCwd,
+								gitWorktreeSetupCache,
+								runSnapshot.origin,
+							),
 						},
 		});
 		if (opts.deferWorkflowStart === true) opts.onWorkflowStartReady?.();

package/dist/builtin/workflows/src/extension/atomic-stage-session.ts

@@ -3,11 +3,13 @@ import type {
 	CreateAgentSessionOptions,
 	DefaultResourceLoaderInheritanceSnapshot,
 	PackageSource,
+	SubagentChildPolicy,
 } from "@bastani/atomic";
 import type { StageSessionRuntime } from "../runs/foreground/stage-runner.js";
 
 export interface PiSdkSettingsManager {
 	getCodexFastModeSettings(): { readonly chat: boolean; readonly workflow: boolean };
+	getRetrySettings?(): { readonly enabled: boolean; readonly maxRetries: number; readonly baseDelayMs: number };
 }
 
 export interface PiSdkResourceLoader {
@@ -45,8 +47,14 @@ export type AtomicCreateAgentSessionOptions = Omit<
 
 export interface PrepareAtomicStageSessionOptions {
 	resourceLoaderInheritanceSnapshot?: DefaultResourceLoaderInheritanceSnapshot;
+	onSettingsManager?: (settingsManager: PiSdkSettingsManager) => void;
 }
-
+const WORKFLOW_STAGE_SUBAGENT_POLICY: SubagentChildPolicy = {
+	managementActions: "full",
+	fanoutAuthorized: false,
+	inheritProjectContext: true,
+	inheritSkills: true,
+};
 function resolveSessionCwd(options: AtomicCreateAgentSessionOptions | undefined): string {
 	return options?.cwd ?? options?.sessionManager?.getCwd() ?? process.cwd();
 }
@@ -87,6 +95,7 @@ export async function prepareAtomicStageSessionOptions(
 				? undefined
 				: { projectTrusted: inheritanceSnapshot.projectTrusted },
 		);
+	prepareOptions.onSettingsManager?.(settingsManager);
 	const inheritedBuiltinPackagePaths = inheritanceSnapshot?.builtinPackagePaths;
 	const builtinPackagePaths =
 		inheritedBuiltinPackagePaths === undefined
@@ -107,6 +116,7 @@ export async function prepareAtomicStageSessionOptions(
 		...(hasAgentDirOverride ? { agentDir } : {}),
 		settingsManager,
 		resourceLoader,
+		subagentPolicy: WORKFLOW_STAGE_SUBAGENT_POLICY,
 	};
 }
 
@@ -143,47 +153,10 @@ function stageBuiltinPackagePaths(paths: readonly PackageSource[]): PackageSourc
 	});
 }
 
-const SUBAGENT_CHILD_EXTENSION_ENV_KEYS = [
-	"ATOMIC_SUBAGENT_CHILD",
-	"ATOMIC_SUBAGENT_FANOUT_CHILD",
-	"PI_SUBAGENT_CHILD",
-	"PI_SUBAGENT_FANOUT_CHILD",
-] as const;
-
 let workflowStageResourceReloadQueue: Promise<void> = Promise.resolve();
 
 async function reloadWorkflowStageResources(resourceLoader: PiSdkResourceLoader): Promise<void> {
-	const queuedReload = workflowStageResourceReloadQueue.then(() =>
-		reloadWorkflowStageResourcesWithEnvIsolation(resourceLoader),
-	);
+	const queuedReload = workflowStageResourceReloadQueue.then(() => resourceLoader.reload());
 	workflowStageResourceReloadQueue = queuedReload.catch(() => undefined);
 	return queuedReload;
 }
-
-async function reloadWorkflowStageResourcesWithEnvIsolation(resourceLoader: PiSdkResourceLoader): Promise<void> {
-	// Workflow stage sessions are already governed by an orchestration context
-	// that disables recursive workflow tools and caps nested subagent depth. When
-	// a workflow itself runs inside a subagent child process, inherited subagent
-	// child env flags would otherwise make the bundled subagents extension skip
-	// registering its `subagent` tool before the stage session exists. Isolate
-	// extension discovery from those parent-process flags so an explicit
-	// `tools: ["subagent"]` allowlist works the same in workflow stages everywhere.
-	// The isolation mutates process-global env, so serialize the full
-	// save/delete/reload/restore section. Without this queue, overlapping workflow
-	// stage session creation can snapshot an already-cleared env and restore that
-	// stale snapshot after another reload restores the real parent values.
-	const previousValues = new Map<string, string | undefined>();
-	for (const key of SUBAGENT_CHILD_EXTENSION_ENV_KEYS) {
-		previousValues.set(key, process.env[key]);
-		delete process.env[key];
-	}
-	try {
-		await resourceLoader.reload();
-	} finally {
-		for (const key of SUBAGENT_CHILD_EXTENSION_ENV_KEYS) {
-			const previousValue = previousValues.get(key);
-			if (previousValue === undefined) delete process.env[key];
-			else process.env[key] = previousValue;
-		}
-	}
-}

package/dist/builtin/workflows/src/extension/config-file-loader.ts

@@ -2,6 +2,15 @@ import type { ConfigDiagnostic, WorkflowExtensionConfig } from "./config-loader.
 import { WORKFLOW_LIFECYCLE_NOTICE_KINDS, type WorkflowLifecycleNoticeKind } from "./lifecycle-notifications.js";
 
 const WORKFLOW_LIFECYCLE_NOTICE_KIND_SET = new Set<string>(WORKFLOW_LIFECYCLE_NOTICE_KINDS);
+/**
+ * Every accepted lifecycle kind, quoted for the rejection message, so adding a
+ * kind can never leave the error naming a stale subset of what validates.
+ */
+const WORKFLOW_LIFECYCLE_NOTICE_KIND_LIST = ((): string => {
+	const quoted = WORKFLOW_LIFECYCLE_NOTICE_KINDS.map((kind) => JSON.stringify(kind));
+	const last = quoted[quoted.length - 1] ?? "";
+	return quoted.length <= 1 ? last : `${quoted.slice(0, -1).join(", ")}, or ${last}`;
+})();
 
 async function tryReadFile(filePath: string): Promise<string | null> {
 	const { readFile } = await import("node:fs/promises");
@@ -73,7 +82,7 @@ function validateConfig(value: unknown): string | null {
 			}
 			for (const item of notifyOn) {
 				if (!isWorkflowLifecycleNoticeKind(item)) {
-					return `"workflowNotifications.notifyOn" entries must be "completed", "failed", "blocked", or "awaiting_input", got ${JSON.stringify(item)}`;
+					return `"workflowNotifications.notifyOn" entries must be ${WORKFLOW_LIFECYCLE_NOTICE_KIND_LIST}, got ${JSON.stringify(item)}`;
 				}
 			}
 		}

package/dist/builtin/workflows/src/extension/config-loader.ts

@@ -186,7 +186,7 @@ export const WORKFLOW_CONFIG_DEFAULTS = {
 	resumeInFlight: "ask" as const,
 	workflowNotifications: {
 		enabled: true,
-		notifyOn: ["completed", "failed", "blocked", "awaiting_input"] as const,
+		notifyOn: ["started", "completed", "failed", "blocked", "awaiting_input", "paused", "quit", "resumed"] as const,
 	},
 	worktree: {
 		symlinkDirectories: ["node_modules"] as readonly string[],

package/dist/builtin/workflows/src/extension/dispatcher.ts

@@ -16,6 +16,7 @@ import type { StageAdapters } from "../runs/foreground/stage-runner.js";
 import { effectiveRunStatus } from "../shared/returned-run-status.js";
 import { deriveInputFields, schemaIsRequired } from "../shared/schema-introspection.js";
 import { store as defaultStore, type Store } from "../shared/store.js";
+import type { WorkflowActor } from "../shared/store-types.js";
 import {
 	INTERACTIVE_WORKFLOW_POLICY,
 	type WorkflowExecutionPolicy,
@@ -82,6 +83,8 @@ export interface DispatcherOpts {
 	models?: WorkflowModelCatalogPort;
 	/** Runtime-derived interaction policy for this dispatch. */
 	policy?: WorkflowExecutionPolicy;
+	/** Who launched this run. Omitted when the launcher is not attributable. */
+	origin?: WorkflowActor;
 	/** Invocation cwd used for workflow execution. */
 	cwd?: string;
 	/** Host-resolved non-default session directory inherited by stages without explicit sessionDir. */
@@ -187,6 +190,7 @@ export async function dispatch(args: WorkflowToolArgs, opts: DispatcherOpts): Pr
 					executionMode: policy.mode,
 					cwd: opts.cwd,
 					defaultSessionDir: opts.defaultSessionDir,
+					...(opts.origin === undefined ? {} : { origin: opts.origin }),
 					runId,
 				});
 			} catch (error) {