@bastani/atomic 0.9.9 → 0.9.10

package/dist/builtin/workflows/src/runs/shared/worktree-post-create.ts

@@ -0,0 +1,130 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { runGit, runGitPlain } from "./worktree-git.js";
+
+function tracked(repo: string, relativePath: string): boolean {
+	const result = runGit(repo, ["ls-files", "--error-unmatch", "--", relativePath]);
+	return result.status === 0;
+}
+
+function hasTrackedPathComponent(repo: string, relativePath: string): boolean {
+	const components = relativePath.split(/[\\/]+/).filter(Boolean);
+	let candidate = "";
+	for (const component of components) {
+		candidate = candidate ? `${candidate}/${component}` : component;
+		const result = runGit(repo, ["ls-files", "--stage", "--", candidate]);
+		if (result.status !== 0) continue;
+		const exact = result.stdout.split(/\r?\n/).some((line) => line.slice(line.indexOf("\t") + 1) === candidate);
+		if (exact) return true;
+	}
+	return false;
+}
+
+function copyUntrackedFile(mainRoot: string, worktreeRoot: string, relativePath: string): boolean {
+	const source = path.join(mainRoot, relativePath);
+	const destination = path.join(worktreeRoot, relativePath);
+	if (!fs.existsSync(source) || fs.existsSync(destination) || hasTrackedPathComponent(worktreeRoot, relativePath)) return false;
+	fs.mkdirSync(path.dirname(destination), { recursive: true });
+	fs.copyFileSync(source, destination);
+	return true;
+}
+
+function propagateLocalSettings(mainRoot: string, worktreeRoot: string): string[] {
+	const copied: string[] = [];
+	if (copyUntrackedFile(mainRoot, worktreeRoot, ".atomic/settings.local.json")) copied.push(".atomic/settings.local.json");
+	if (!tracked(mainRoot, ".atomic/settings.json") && copyUntrackedFile(mainRoot, worktreeRoot, ".atomic/settings.json")) {
+		copied.push(".atomic/settings.json");
+	}
+	return copied;
+}
+
+function populatedHooksDirectory(mainRoot: string): string | undefined {
+	const husky = path.join(mainRoot, ".husky");
+	try {
+		if (fs.statSync(husky).isDirectory()) return husky;
+	} catch {
+		// Try ordinary Git hooks.
+	}
+	const hooks = path.join(mainRoot, ".git", "hooks");
+	try {
+		const populated = fs.readdirSync(hooks, { withFileTypes: true })
+			.some((entry) => entry.isFile() && !entry.name.endsWith(".sample"));
+		return populated ? hooks : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function configureSharedHooksPath(mainRoot: string): void {
+	const desired = populatedHooksDirectory(mainRoot);
+	if (desired === undefined) return;
+	const current = runGitPlain(mainRoot, ["config", "--get", "core.hooksPath"]);
+	if (current.status === 0 && path.resolve(mainRoot, current.stdout.trim()) === desired) return;
+	const configured = runGitPlain(mainRoot, ["config", "core.hooksPath", desired]);
+	if (configured.status !== 0) {
+		throw new Error(configured.stderr.trim() || "failed to configure shared core.hooksPath");
+	}
+}
+
+function normalizeSymlinkDirectory(value: string): string | undefined {
+	const trimmed = value.trim();
+	if (!trimmed || path.isAbsolute(trimmed)) return undefined;
+	const normalized = path.normalize(trimmed);
+	if (normalized === "." || normalized === ".." || normalized.startsWith(`..${path.sep}`)) return undefined;
+	return normalized;
+}
+
+function symlinkConfiguredDirectories(
+	mainRoot: string,
+	worktreeRoot: string,
+	directories: readonly string[],
+): string[] {
+	const synthetic: string[] = [];
+	for (const rawDirectory of directories) {
+		const relativePath = normalizeSymlinkDirectory(rawDirectory);
+		if (relativePath === undefined || synthetic.includes(relativePath)) continue;
+		const source = path.join(mainRoot, relativePath);
+		const destination = path.join(worktreeRoot, relativePath);
+		if (!fs.existsSync(source) || fs.existsSync(destination) || hasTrackedPathComponent(worktreeRoot, relativePath)) continue;
+		fs.mkdirSync(path.dirname(destination), { recursive: true });
+		try {
+			fs.symlinkSync(source, destination, process.platform === "win32" ? "junction" : undefined);
+			synthetic.push(relativePath);
+		} catch {
+			// Optional setup: unsupported filesystems may reject symlinks.
+		}
+	}
+	return synthetic;
+}
+
+function copyWorktreeIncludes(mainRoot: string, worktreeRoot: string): void {
+	if (!fs.existsSync(path.join(mainRoot, ".worktreeinclude"))) return;
+	const ignored = runGit(mainRoot, ["ls-files", "--others", "--ignored", "--exclude-standard"]);
+	const included = runGit(mainRoot, ["ls-files", "--others", "--ignored", "--exclude-from=.worktreeinclude"]);
+	if (ignored.status !== 0 || included.status !== 0) return;
+	const ignoredPaths = new Set(ignored.stdout.split(/\r?\n/).filter(Boolean));
+	for (const relativePath of included.stdout.split(/\r?\n/).filter(Boolean)) {
+		if (!ignoredPaths.has(relativePath) || hasTrackedPathComponent(worktreeRoot, relativePath)) continue;
+		const source = path.join(mainRoot, relativePath);
+		const destination = path.join(worktreeRoot, relativePath);
+		try {
+			if (!fs.statSync(source).isFile() || fs.existsSync(destination)) continue;
+			fs.mkdirSync(path.dirname(destination), { recursive: true });
+			fs.copyFileSync(source, destination);
+		} catch {
+			// A concurrently removed ignored file is harmless.
+		}
+	}
+}
+
+export function performPostCreationSetup(
+	mainRoot: string,
+	worktreeRoot: string,
+	symlinkDirectories: readonly string[],
+): string[] {
+	const syntheticPaths = propagateLocalSettings(mainRoot, worktreeRoot);
+	configureSharedHooksPath(mainRoot);
+	syntheticPaths.push(...symlinkConfiguredDirectories(mainRoot, worktreeRoot, symlinkDirectories));
+	copyWorktreeIncludes(mainRoot, worktreeRoot);
+	return syntheticPaths;
+}

package/dist/builtin/workflows/src/runs/shared/worktree-root.ts

@@ -0,0 +1,84 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+function pathFromPointer(contents: string, prefix: string, base: string): string | undefined {
+	if (!contents.startsWith(prefix)) return undefined;
+	const value = contents.slice(prefix.length).trim();
+	if (!value) return undefined;
+	return path.resolve(base, value);
+}
+
+function readText(file: string): string | undefined {
+	try {
+		return fs.readFileSync(file, "utf8");
+	} catch {
+		return undefined;
+	}
+}
+
+function samePath(left: string, right: string): boolean {
+	try {
+		const a = fs.realpathSync.native(left);
+		const b = fs.realpathSync.native(right);
+		return process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b;
+	} catch {
+		return false;
+	}
+}
+
+/** Find the nearest checkout root without invoking Git. */
+export function findGitRoot(cwd: string): string | undefined {
+	let current = path.resolve(cwd);
+	try {
+		if (!fs.statSync(current).isDirectory()) current = path.dirname(current);
+	} catch {
+		return undefined;
+	}
+	while (true) {
+		try {
+			const entry = fs.statSync(path.join(current, ".git"));
+			if (entry.isDirectory() || entry.isFile()) return current;
+		} catch {
+			// Continue walking.
+		}
+		const parent = path.dirname(current);
+		if (parent === current) return undefined;
+		current = parent;
+	}
+}
+
+/** Resolve only standard `git worktree add` layouts to their main checkout. */
+export function resolveMainRepoRoot(repoRoot: string): string | undefined {
+	const gitEntry = path.join(repoRoot, ".git");
+	let stats: fs.Stats;
+	try {
+		stats = fs.statSync(gitEntry);
+	} catch {
+		return undefined;
+	}
+	if (stats.isDirectory()) return path.resolve(repoRoot);
+	if (!stats.isFile()) return undefined;
+
+	const pointer = readText(gitEntry);
+	if (pointer === undefined) return undefined;
+	const gitDir = pathFromPointer(pointer, "gitdir:", repoRoot);
+	if (gitDir === undefined || path.basename(path.dirname(gitDir)) !== "worktrees") return undefined;
+	const commonGitDir = path.dirname(path.dirname(gitDir));
+	if (path.basename(commonGitDir) !== ".git") return undefined;
+
+	// A real linked-worktree admin directory points back to this checkout and
+	// declares the common directory. These checks reject crafted foreign pointers.
+	const backPointer = readText(path.join(gitDir, "gitdir"));
+	const commonPointer = readText(path.join(gitDir, "commondir"));
+	if (backPointer === undefined || commonPointer === undefined) return undefined;
+	const linkedGitEntry = path.resolve(gitDir, backPointer.trim());
+	const declaredCommonDir = path.resolve(gitDir, commonPointer.trim());
+	if (!backPointer.trim() || !commonPointer.trim()) return undefined;
+	if (!samePath(linkedGitEntry, gitEntry) || !samePath(declaredCommonDir, commonGitDir)) return undefined;
+	return path.dirname(commonGitDir);
+}
+
+export function findCanonicalGitRoot(cwd: string): string | undefined {
+	const repoRoot = findGitRoot(cwd);
+	return repoRoot === undefined ? undefined : resolveMainRepoRoot(repoRoot);
+}

package/dist/builtin/workflows/src/runs/shared/worktree-setup.ts

@@ -2,8 +2,9 @@ import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { APP_NAME } from "@bastani/atomic";
 import { runGit, runGitChecked } from "./worktree-git.js";
+import { performPostCreationSetup } from "./worktree-post-create.js";
+import { findCanonicalGitRoot } from "./worktree-root.js";
 import type {
 	CreateWorktreesOptions,
 	RepoState,
@@ -18,17 +19,37 @@ import type {
 
 const DEFAULT_WORKTREE_SETUP_HOOK_TIMEOUT_MS = 30000;
 
-function resolveRepoState(cwd: string): RepoState {
+function originDefaultBranch(mainRoot: string): string | undefined {
+	const symbolic = runGit(mainRoot, ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"]);
+	let branch = symbolic.status === 0 && symbolic.stdout.trim().startsWith("origin/")
+		? symbolic.stdout.trim().slice("origin/".length)
+		: undefined;
+	if (!branch) {
+		const remote = runGit(mainRoot, ["remote", "show", "origin"]);
+		branch = remote.status === 0 ? remote.stdout.match(/^\s*HEAD branch:\s*(\S+)\s*$/m)?.[1] : undefined;
+	}
+	if (!branch || branch === "(unknown)") return undefined;
+	const remoteRef = `refs/remotes/origin/${branch}`;
+	if (runGit(mainRoot, ["show-ref", "--verify", "--quiet", remoteRef]).status !== 0) {
+		if (runGit(mainRoot, ["fetch", "origin", `${branch}:${remoteRef}`]).status !== 0) return undefined;
+	}
+	return `origin/${branch}`;
+}
+
+function resolveRepoState(cwd: string, explicitBaseBranch?: string): RepoState {
 	const cwdRelative = resolveRepoCwdRelative(cwd);
-	const toplevel = runGitChecked(cwd, ["rev-parse", "--show-toplevel"]).trim();
+	const toplevel = path.resolve(runGitChecked(cwd, ["rev-parse", "--show-toplevel"]).trim());
+	const mainRoot = findCanonicalGitRoot(toplevel);
+	if (mainRoot === undefined) throw new Error(`unable to resolve canonical main Git repository root from ${toplevel}`);
 
-	const status = runGitChecked(toplevel, ["status", "--porcelain"]);
+	const status = runGitChecked(toplevel, ["status", "--porcelain", "--untracked-files=no"]);
 	if (status.trim().length > 0) {
 		throw new Error("worktree isolation requires a clean git working tree. Commit or stash changes first.");
 	}
 
-	const baseCommit = runGitChecked(toplevel, ["rev-parse", "HEAD"]).trim();
-	return { toplevel, cwdRelative, baseCommit };
+	const baseRef = explicitBaseBranch?.trim() || originDefaultBranch(mainRoot) || "HEAD";
+	const baseCommit = runGitChecked(mainRoot, ["rev-parse", baseRef]).trim();
+	return { toplevel, mainRoot, cwdRelative, baseCommit, baseRef };
 }
 
 function normalizeComparableCwd(cwd: string): string {
@@ -63,12 +84,22 @@ export function formatWorktreeTaskCwdConflict(
 	return `worktree isolation uses the shared cwd (${sharedCwd}); task ${conflict.index + 1} (${conflict.agent}) sets cwd to ${conflict.cwd}. Remove task-level cwd overrides or disable worktree.`;
 }
 
+function flattenedWorktreeName(runId: string, index: number): string {
+	return `${runId}-${index}`.replaceAll("/", "+");
+}
+
 function buildWorktreeBranch(runId: string, index: number): string {
-	return `${APP_NAME}-parallel-${runId}-${index}`;
+	return `worktree-${flattenedWorktreeName(runId, index)}`;
+}
+
+function buildWorktreePath(mainRoot: string, runId: string, index: number): string {
+	return path.join(mainRoot, ".atomic", "worktrees", flattenedWorktreeName(runId, index));
 }
 
-function buildWorktreePath(runId: string, index: number): string {
-	return path.join(os.tmpdir(), `${APP_NAME}-worktree-${runId}-${index}`);
+function ensureWorktreeIgnore(mainRoot: string): void {
+	const worktreesRoot = path.join(mainRoot, ".atomic", "worktrees");
+	fs.mkdirSync(worktreesRoot, { recursive: true });
+	fs.writeFileSync(path.join(worktreesRoot, ".gitignore"), "*\n", "utf8");
 }
 
 function resolveRepoCwdRelative(cwd: string): string {
@@ -85,23 +116,13 @@ function resolveRepoCwdRelative(cwd: string): string {
 
 export function resolveExpectedWorktreeAgentCwd(cwd: string, runId: string, index: number): string {
 	const cwdRelative = resolveRepoCwdRelative(cwd);
-	const worktreePath = buildWorktreePath(runId, index);
+	const toplevel = path.resolve(runGitChecked(cwd, ["rev-parse", "--show-toplevel"]).trim());
+	const mainRoot = findCanonicalGitRoot(toplevel);
+	if (mainRoot === undefined) throw new Error(`unable to resolve canonical main Git repository root from ${toplevel}`);
+	const worktreePath = buildWorktreePath(mainRoot, runId, index);
 	return cwdRelative ? path.join(worktreePath, cwdRelative) : worktreePath;
 }
 
-function linkNodeModulesIfPresent(toplevel: string, worktreePath: string): boolean {
-	const nodeModulesPath = path.join(toplevel, "node_modules");
-	const nodeModulesLinkPath = path.join(worktreePath, "node_modules");
-	if (!fs.existsSync(nodeModulesPath) || fs.existsSync(nodeModulesLinkPath)) return false;
-	try {
-		fs.symlinkSync(nodeModulesPath, nodeModulesLinkPath);
-		return true;
-	} catch {
-		// Symlink creation is optional (e.g., unsupported filesystems on CI runners).
-		return false;
-	}
-}
-
 function parseHookTimeout(timeoutMs: number | undefined): number {
 	if (timeoutMs === undefined) return DEFAULT_WORKTREE_SETUP_HOOK_TIMEOUT_MS;
 	if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
@@ -227,32 +248,47 @@ function runWorktreeSetupHook(
 	return [...uniquePaths];
 }
 
+function waitForGitLockRelease(): void {
+	Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100);
+}
+
+function cleanupSingleWorktree(repoCwd: string, worktree: Pick<WorktreeInfo, "path" | "branch">): void {
+	try { runGitChecked(repoCwd, ["worktree", "remove", "--force", worktree.path]); } catch {
+		// Cleanup is idempotent and best-effort.
+	}
+	waitForGitLockRelease();
+	try { runGitChecked(repoCwd, ["branch", "-D", worktree.branch]); } catch {
+		// Cleanup is idempotent and best-effort.
+	}
+}
+
 function createSingleWorktree(
-	toplevel: string,
+	mainRoot: string,
 	cwdRelative: string,
 	runId: string,
 	index: number,
+	baseRef: string,
 	baseCommit: string,
+	symlinkDirectories: readonly string[],
 	setupHook: ResolvedWorktreeSetupHook | undefined,
 	agent: string | undefined,
 ): WorktreeInfo {
 	const branch = buildWorktreeBranch(runId, index);
-	const worktreePath = buildWorktreePath(runId, index);
-	const add = runGit(toplevel, ["worktree", "add", worktreePath, "-b", branch, "HEAD"]);
+	const worktreePath = buildWorktreePath(mainRoot, runId, index);
+	const add = runGit(mainRoot, ["worktree", "add", "-B", branch, worktreePath, baseRef]);
 	if (add.status !== 0) {
 		const message = add.stderr.trim() || add.stdout.trim() || `failed to create worktree ${worktreePath}`;
+		cleanupSingleWorktree(mainRoot, { path: worktreePath, branch });
 		throw new Error(message);
 	}
 
 	const agentCwd = cwdRelative ? path.join(worktreePath, cwdRelative) : worktreePath;
 	try {
-		const nodeModulesLinked = linkNodeModulesIfPresent(toplevel, worktreePath);
-		const syntheticPaths = nodeModulesLinked ? ["node_modules"] : [];
-
+		const syntheticPaths = performPostCreationSetup(mainRoot, worktreePath, symlinkDirectories);
 		if (setupHook) {
 			const hookSyntheticPaths = runWorktreeSetupHook(setupHook, {
 				version: 1,
-				repoRoot: toplevel,
+				repoRoot: mainRoot,
 				worktreePath,
 				agentCwd,
 				branch,
@@ -263,73 +299,51 @@ function createSingleWorktree(
 			});
 			syntheticPaths.push(...hookSyntheticPaths);
 		}
-
 		return {
 			path: worktreePath,
 			agentCwd,
 			branch,
 			index,
-			nodeModulesLinked,
+			nodeModulesLinked: syntheticPaths.includes("node_modules"),
 			syntheticPaths,
 		};
 	} catch (error) {
-		try { runGitChecked(toplevel, ["worktree", "remove", "--force", worktreePath]); } catch {
-			// Best-effort rollback; preserve the original setup failure.
-		}
-		try { runGitChecked(toplevel, ["branch", "-D", branch]); } catch {
-			// Best-effort rollback; preserve the original setup failure.
-		}
+		cleanupSingleWorktree(mainRoot, { path: worktreePath, branch });
 		throw error;
 	}
 }
 
-function cleanupSingleWorktree(repoCwd: string, worktree: WorktreeInfo): void {
-	try { runGitChecked(repoCwd, ["worktree", "remove", "--force", worktree.path]); } catch {
-		// Cleanup is best-effort to avoid masking caller errors.
-	}
-	try { runGitChecked(repoCwd, ["branch", "-D", worktree.branch]); } catch {
-		// Cleanup is best-effort to avoid masking caller errors.
-	}
-}
-
 export function createWorktrees(cwd: string, runId: string, count: number, options?: CreateWorktreesOptions): WorktreeSetup {
-	const repo = resolveRepoState(cwd);
-	const setupHook = resolveWorktreeSetupHook(repo.toplevel, options?.setupHook);
+	const repo = resolveRepoState(cwd, options?.baseBranch);
+	ensureWorktreeIgnore(repo.mainRoot);
+	const setupHook = resolveWorktreeSetupHook(repo.mainRoot, options?.setupHook);
+	const symlinkDirectories = options?.symlinkDirectories ?? ["node_modules"];
 	const worktrees: WorktreeInfo[] = [];
 
 	try {
 		for (let index = 0; index < count; index++) {
 			worktrees.push(createSingleWorktree(
-				repo.toplevel,
+				repo.mainRoot,
 				repo.cwdRelative,
 				runId,
 				index,
+				repo.baseRef,
 				repo.baseCommit,
+				symlinkDirectories,
 				setupHook,
 				options?.agents?.[index],
 			));
 		}
 	} catch (error) {
-		cleanupWorktrees({
-			cwd: repo.toplevel,
-			worktrees,
-			baseCommit: repo.baseCommit,
-		});
+		cleanupWorktrees({ cwd: repo.mainRoot, worktrees, baseCommit: repo.baseCommit });
 		throw error;
 	}
 
-	return {
-		cwd: repo.toplevel,
-		worktrees,
-		baseCommit: repo.baseCommit,
-	};
+	return { cwd: repo.mainRoot, worktrees, baseCommit: repo.baseCommit };
 }
 
 export function cleanupWorktrees(setup: WorktreeSetup): void {
 	for (let index = setup.worktrees.length - 1; index >= 0; index--) {
 		cleanupSingleWorktree(setup.cwd, setup.worktrees[index]!);
 	}
-	try { runGitChecked(setup.cwd, ["worktree", "prune"]); } catch {
-		// Pruning is best-effort cleanup.
-	}
 }

package/dist/builtin/workflows/src/runs/shared/worktree-types.ts

@@ -38,6 +38,8 @@ export interface WorktreeSetupHookConfig {
 export interface CreateWorktreesOptions {
 	agents?: string[];
 	setupHook?: WorktreeSetupHookConfig;
+	baseBranch?: string;
+	symlinkDirectories?: readonly string[];
 }
 
 export interface ResolvedWorktreeSetupHook {
@@ -93,6 +95,8 @@ export interface GitWorktreeSetupResult {
 
 export interface RepoState {
 	toplevel: string;
+	mainRoot: string;
 	cwdRelative: string;
 	baseCommit: string;
+	baseRef: string;
 }

package/dist/builtin/workflows/src/sdk-surface.ts

@@ -26,7 +26,7 @@ export { INTERACTIVE_WORKFLOW_POLICY, NON_INTERACTIVE_WORKFLOW_POLICY } from "./
 export type { AuthoredWorkflowDefinition, AuthoredWorkflowSpec, WorkflowInputsFromSchemas, WorkflowOutputsFromSchemas, WorkflowProvidedInputsFromSchemas } from "./authoring/workflow.js";
 export type { WorkflowRegistry } from "./workflows/registry.js";
 
-export { run, runTask, runParallel, runChain, resolveInputs } from "./runs/foreground/executor.js";
+export { run, resolveInputs } from "./runs/foreground/executor.js";
 export type { RunOpts, RunResult, ResolvedInputs } from "./runs/foreground/executor.js";
 export type { AgentSessionAdapter, StageAdapters } from "./runs/foreground/stage-runner.js";
 export { GraphFrontierTracker } from "./engine/graph-inference.js";

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

@@ -24,7 +24,7 @@ export type WorkflowThinkingLevel = "off" | "minimal" | "low" | "medium" | "high
 export type WorkflowExecutionMode = "interactive" | "non_interactive";
 export type WorkflowExitStatus = "completed" | "skipped" | "cancelled" | "blocked";
 export type RunStatus = "pending" | "running" | "paused" | WorkflowExitStatus | "failed" | "killed";
-export type WorkflowDetailsMode = "named" | "single" | "parallel" | "chain" | "inspection" | "control";
+export type WorkflowDetailsMode = "named" | "inspection" | "control";
 export type WorkflowDetailsStatus = "accepted" | "running" | WorkflowExitStatus | "failed" | "killed" | "noop";
 export type WorkflowAction = "list" | "get" | "inputs" | "run" | "status" | "interrupt" | "resume";
 type WorkflowExitOutputValues<TOutputs extends WorkflowOutputValues = WorkflowOutputValues> = [keyof TOutputs] extends [never] ? Readonly<Record<string, never>> : Partial<TOutputs>;
@@ -146,6 +146,13 @@ export interface StageOptions<TSchemaDef extends TSchema | undefined = TSchema |
     readonly sessionDir?: string;
     /** @deprecated Prefer suffixing model/fallbackModels entries with `:level`; removal is deferred. */
     readonly thinkingLevel?: WorkflowThinkingLevel;
+    /**
+     * Intercom home group for this stage session. A named string joins that group;
+     * `true` auto-generates one shared UUID group per parallel set (all items in the
+     * set share it). Absent inherits per the precedence chain (ultimately "default").
+     * Only applied when the stage session actually has intercom access.
+     */
+    readonly group?: string | true;
 }
 export interface CompleteStageOpts extends WorkflowModelFallbackFields {
     readonly model?: WorkflowModelValue;
@@ -186,12 +193,31 @@ export interface WorkflowPersistencePort {
     setLabel?(entryId: string, label: string): void;
     appendCustomMessageEntry?(content: string, meta?: Record<string, unknown>): string | undefined;
 }
+/** Stable public identifier used to correlate replayed/overlapping turn lifecycle events. */
+export type StageSessionTurnId = string | number;
+/** Public lifecycle events emitted by stage session adapters for turn ownership. */
+export type StageSessionEvent = {
+    readonly type: "agent_start";
+    readonly turnId?: StageSessionTurnId;
+} | {
+    readonly type: "agent_end";
+    readonly turnId?: StageSessionTurnId;
+    readonly messages?: readonly WorkflowSerializableValue[];
+};
 export interface StageSessionRuntime {
     prompt(text: string, options?: PromptOptions): Promise<string | void>;
     sendUserMessage?(content: StageUserMessageContent, options?: StageSendUserMessageOptions): Promise<void>;
     steer(text: string): Promise<void>;
     followUp(text: string): Promise<void>;
-    subscribe(listener: (event: never) => void): () => void;
+    /**
+     * Must emit `agent_start` when a submitted user-message turn takes ownership and
+     * `agent_end` when that owned turn terminates. Registration may replay state
+     * synchronously; synchronous untagged replays are snapshots only. An adapter
+     * that can emit a later end for a replayed turn while a newer turn is active
+     * must provide the same stable `turnId` on that replayed start and its end.
+     * After registration returns, starts must represent new turns.
+     */
+    subscribe(listener: (event: StageSessionEvent) => void): () => void;
     readonly sessionFile: string | undefined;
     readonly sessionId: string;
     setModel(model: WorkflowSerializableValue): Promise<void>;
@@ -258,7 +284,7 @@ export interface StageContext<TSchemaDef extends TSchema | undefined = undefined
     sendUserMessage(content: StageUserMessageContent, options?: StageSendUserMessageOptions): Promise<void>;
     steer(text: string): Promise<void>;
     followUp(text: string): Promise<void>;
-    subscribe(listener: (event: never) => void): () => void;
+    subscribe(listener: (event: StageSessionEvent) => void): () => void;
     readonly sessionFile: string | undefined;
     readonly sessionId: string;
     setModel(model: WorkflowModelValue): Promise<void>;
@@ -338,26 +364,7 @@ export interface WorkflowParallelOptions extends WorkflowSharedTaskDefaults {
     readonly concurrency?: number;
     readonly failFast?: boolean;
 }
-export interface WorkflowDirectTaskItem extends WorkflowTaskOptions {
-    readonly name: string;
-    readonly count?: number;
-}
-export interface WorkflowParallelChainStep {
-    readonly parallel: readonly WorkflowDirectTaskItem[];
-    readonly concurrency?: number;
-    readonly failFast?: boolean;
-    readonly worktree?: boolean;
-    readonly gitWorktreeDir?: string;
-    readonly baseBranch?: string;
-}
-export type WorkflowChainStep = WorkflowDirectTaskItem | WorkflowParallelChainStep;
 export type WorkflowTaskSessionOptions = StageOptions & WorkflowTaskSessionFields;
-export interface WorkflowDirectOptions extends StageOptions, WorkflowTaskSessionFields {
-    readonly chainName?: string;
-    readonly concurrency?: number;
-    readonly failFast?: boolean;
-    readonly chainDir?: string;
-}
 export interface WorkflowRunChildOptions<TInputs extends WorkflowInputValues = WorkflowInputValues> {
     readonly inputs?: TInputs;
     readonly stageName?: string;

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

@@ -33,7 +33,7 @@ export type WorkflowThinkingLevel = "off" | "minimal" | "low" | "medium" | "high
 export type WorkflowExecutionMode = "interactive" | "non_interactive";
 export type WorkflowExitStatus = "completed" | "skipped" | "cancelled" | "blocked";
 export type RunStatus = "pending" | "running" | "paused" | WorkflowExitStatus | "failed" | "killed";
-export type WorkflowDetailsMode = "named" | "single" | "parallel" | "chain" | "inspection" | "control";
+export type WorkflowDetailsMode = "named" | "inspection" | "control";
 export type WorkflowDetailsStatus = "accepted" | "running" | WorkflowExitStatus | "failed" | "killed" | "noop";
 export type WorkflowAction = "list" | "get" | "inputs" | "run" | "status" | "interrupt" | "resume";
 
@@ -183,6 +183,13 @@ export interface StageOptions<TSchemaDef extends TSchema | undefined = TSchema |
   readonly sessionDir?: string;
   /** @deprecated Prefer suffixing model/fallbackModels entries with `:level`; removal is deferred. */
   readonly thinkingLevel?: WorkflowThinkingLevel;
+  /**
+   * Intercom home group for this stage session. A named string joins that group;
+   * `true` auto-generates one shared UUID group per parallel set (all items in the
+   * set share it). Absent inherits per the precedence chain (ultimately "default").
+   * Only applied when the stage session actually has intercom access.
+   */
+  readonly group?: string | true;
 }
 
 export interface CompleteStageOpts extends WorkflowModelFallbackFields {
@@ -233,12 +240,28 @@ export interface WorkflowPersistencePort {
   appendCustomMessageEntry?(content: string, meta?: Record<string, unknown>): string | undefined;
 }
 
+/** Stable public identifier used to correlate replayed/overlapping turn lifecycle events. */
+export type StageSessionTurnId = string | number;
+
+/** Public lifecycle events emitted by stage session adapters for turn ownership. */
+export type StageSessionEvent =
+  | { readonly type: "agent_start"; readonly turnId?: StageSessionTurnId }
+  | { readonly type: "agent_end"; readonly turnId?: StageSessionTurnId; readonly messages?: readonly WorkflowSerializableValue[] };
+
 export interface StageSessionRuntime {
   prompt(text: string, options?: PromptOptions): Promise<string | void>;
   sendUserMessage?(content: StageUserMessageContent, options?: StageSendUserMessageOptions): Promise<void>;
   steer(text: string): Promise<void>;
   followUp(text: string): Promise<void>;
-  subscribe(listener: (event: never) => void): () => void;
+  /**
+   * Must emit `agent_start` when a submitted user-message turn takes ownership and
+   * `agent_end` when that owned turn terminates. Registration may replay state
+   * synchronously; synchronous untagged replays are snapshots only. An adapter
+   * that can emit a later end for a replayed turn while a newer turn is active
+   * must provide the same stable `turnId` on that replayed start and its end.
+   * After registration returns, starts must represent new turns.
+   */
+  subscribe(listener: (event: StageSessionEvent) => void): () => void;
   readonly sessionFile: string | undefined;
   readonly sessionId: string;
   setModel(model: WorkflowSerializableValue): Promise<void>;
@@ -310,7 +333,7 @@ export interface StageContext<TSchemaDef extends TSchema | undefined = undefined
   sendUserMessage(content: StageUserMessageContent, options?: StageSendUserMessageOptions): Promise<void>;
   steer(text: string): Promise<void>;
   followUp(text: string): Promise<void>;
-  subscribe(listener: (event: never) => void): () => void;
+  subscribe(listener: (event: StageSessionEvent) => void): () => void;
   readonly sessionFile: string | undefined;
   readonly sessionId: string;
   setModel(model: WorkflowModelValue): Promise<void>;
@@ -395,29 +418,8 @@ export interface WorkflowParallelOptions extends WorkflowSharedTaskDefaults {
   readonly failFast?: boolean;
 }
 
-export interface WorkflowDirectTaskItem extends WorkflowTaskOptions {
-  readonly name: string;
-  readonly count?: number;
-}
-
-export interface WorkflowParallelChainStep {
-  readonly parallel: readonly WorkflowDirectTaskItem[];
-  readonly concurrency?: number;
-  readonly failFast?: boolean;
-  readonly worktree?: boolean;
-  readonly gitWorktreeDir?: string;
-  readonly baseBranch?: string;
-}
-
-export type WorkflowChainStep = WorkflowDirectTaskItem | WorkflowParallelChainStep;
 export type WorkflowTaskSessionOptions = StageOptions & WorkflowTaskSessionFields;
 
-export interface WorkflowDirectOptions extends StageOptions, WorkflowTaskSessionFields {
-  readonly chainName?: string;
-  readonly concurrency?: number;
-  readonly failFast?: boolean;
-  readonly chainDir?: string;
-}
 
 export interface WorkflowRunChildOptions<TInputs extends WorkflowInputValues = WorkflowInputValues> {
   readonly inputs?: TInputs;