@bastani/atomic 0.9.9 → 0.9.10

package/dist/builtin/subagents/src/runs/foreground/subagent-executor-parallel-task.ts

@@ -20,6 +20,7 @@ import {
 import type { ExtensionContext } from "@bastani/atomic";
 import type { SubagentExecutorRuntimeDeps, TaskParam } from "./subagent-executor-types.ts";
 import { resolveParallelTaskCwd } from "./subagent-executor-worktree.ts";
+import { inheritedIntercomGroup, resolveChildIntercomGroup } from "../shared/intercom-group.ts";
 
 interface ForegroundParallelRunInput {
 	tasks: TaskParam[];
@@ -47,6 +48,8 @@ interface ForegroundParallelRunInput {
 	onControlEvent?: (event: ControlEvent) => void;
 	childIntercomTarget?: (agent: string, index: number) => string | undefined;
 	orchestratorIntercomTarget?: string;
+	setIntercomGroup?: string | true;
+	sharedAutoIntercomGroup?: string;
 	foregroundControl?: SubagentState["foregroundControls"] extends Map<string, infer T> ? T : never;
 	concurrencyLimit: number;
 	liveResults: (SingleResult | undefined)[];
@@ -58,7 +61,18 @@ interface ForegroundParallelRunInput {
 }
 
 export async function runForegroundParallelTasks(input: ForegroundParallelRunInput): Promise<SingleResult[]> {
+	const intercomDetachController = new AbortController();
 	return mapConcurrent(input.tasks, input.concurrencyLimit, async (task, index) => {
+		if (intercomDetachController.signal.aborted) {
+			return {
+				agent: task.agent,
+				task: input.taskTexts[index] ?? task.task,
+				exitCode: -1,
+				messages: [],
+				usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 },
+				error: "Skipped after foreground group detached for intercom coordination",
+			};
+		}
 		const behavior = input.behaviors[index];
 		const effectiveSkills = behavior?.skills;
 		const taskCwd = resolveParallelTaskCwd(task, input.paramsCwd, input.worktreeSetup, index);
@@ -111,7 +125,14 @@ export async function runForegroundParallelTasks(input: ForegroundParallelRunInp
 			onControlEvent: input.onControlEvent,
 			intercomSessionName: input.childIntercomTarget?.(task.agent, index),
 			orchestratorIntercomTarget: input.orchestratorIntercomTarget,
+			intercomGroup: resolveChildIntercomGroup(
+				task.group ?? input.setIntercomGroup,
+				inheritedIntercomGroup(input.ctx),
+				input.sharedAutoIntercomGroup,
+			),
 			onDetachedExit: (result) => input.onDetachedExit?.(index, result),
+			intercomDetachSignal: intercomDetachController.signal,
+			onIntercomDetachCommit: () => intercomDetachController.abort(),
 			nestedRoute: input.foregroundControl?.nestedRoute,
 			modelOverride: input.modelOverrides[index],
 			availableModels: input.availableModels,

package/dist/builtin/subagents/src/runs/foreground/subagent-executor-parallel.ts

@@ -2,6 +2,7 @@ import { resolveModelCandidate } from "../shared/model-fallback.ts";
 import { collectKnownModelProviders, toModelInfo, type ModelInfo } from "../../shared/model-info.ts";
 import { normalizeSkillInput } from "../../agents/skills.ts";
 import { aggregateParallelOutputs } from "../shared/parallel-utils.ts";
+import { sharedAutoGroupForSet } from "../shared/intercom-group.ts";
 import { recordRun } from "../shared/run-history.ts";
 import {
 	resolveStepBehavior,
@@ -43,6 +44,7 @@ import {
 	resolveParallelTaskCwd,
 } from "./subagent-executor-worktree.ts";
 import { createForegroundControlNotifier, maybeBuildForegroundIntercomReceipt, rememberForegroundRun, replaceForegroundRunChild } from "./subagent-executor-status.ts";
+import { createDetachedCleanupBarrier } from "./detached-cleanup-barrier.ts";
 
 export async function runParallelPath(data: ExecutionContextData, deps: ResolvedExecutorDeps): Promise<SubagentToolResult> {
 	const {
@@ -132,6 +134,12 @@ export async function runParallelPath(data: ExecutionContextData, deps: Resolved
 		deps.config.worktreeSetupHook,
 		deps.config.worktreeSetupHookTimeoutMs,
 	);
+	let worktreeCleanupDeferred = false;
+	const detachedCleanup = createDetachedCleanupBarrier(() => {
+		if (!worktreeSetup) return;
+		buildParallelWorktreeSuffix(worktreeSetup, artifactsDir, tasks as TaskParam[]);
+		cleanupWorktrees(worktreeSetup);
+	});
 	if (errorResult) return errorResult;
 
 	try {
@@ -160,7 +168,13 @@ export async function runParallelPath(data: ExecutionContextData, deps: Resolved
 		}
 
 		const results = await runForegroundParallelTasks({
-			onDetachedExit: (index, result) => replaceForegroundRunChild(deps.state, runId, index, result),
+			onDetachedExit: (index, result) => {
+				try {
+					replaceForegroundRunChild(deps.state, runId, index, result);
+				} finally {
+					detachedCleanup.recover(index);
+				}
+			},
 			tasks,
 			taskTexts,
 			agents,
@@ -185,6 +199,8 @@ export async function runParallelPath(data: ExecutionContextData, deps: Resolved
 			onControlEvent,
 			childIntercomTarget: childIntercomTarget ? (agent, index) => childIntercomTarget(runId, agent, index) : undefined,
 			orchestratorIntercomTarget: data.intercomBridge.active ? data.intercomBridge.orchestratorTarget : undefined,
+			setIntercomGroup: params.group,
+			sharedAutoIntercomGroup: sharedAutoGroupForSet(params.group, tasks),
 			foregroundControl,
 			concurrencyLimit: parallelConcurrency,
 			maxSubagentDepths,
@@ -221,6 +237,9 @@ export async function runParallelPath(data: ExecutionContextData, deps: Resolved
 		}
 		const detachedIndex = results.findIndex((result) => result.detached);
 		const detached = detachedIndex >= 0 ? results[detachedIndex] : undefined;
+		worktreeCleanupDeferred = detachedCleanup.defer(
+			results.flatMap((result, index) => result.detached ? [index] : []),
+		);
 		if (detached) {
 			return {
 				content: [{ type: "text", text: `Parallel run detached for intercom coordination (${detached.agent}). Reply to the supervisor request first. After the child exits, start a fresh follow-up if needed.` }],
@@ -266,6 +285,6 @@ export async function runParallelPath(data: ExecutionContextData, deps: Resolved
 			details,
 		};
 	} finally {
-		if (worktreeSetup) cleanupWorktrees(worktreeSetup);
+		if (worktreeSetup && !worktreeCleanupDeferred) cleanupWorktrees(worktreeSetup);
 	}
 }

package/dist/builtin/subagents/src/runs/foreground/subagent-executor-resume.ts

@@ -25,6 +25,7 @@ import {
 	resolveIntercomSessionTarget,
 	resolveSubagentIntercomTarget,
 } from "../../intercom/intercom-bridge.ts";
+import { requestSupervisorAuthorization } from "../../intercom/supervisor-authorization.ts";
 import { resolveCurrentSessionId } from "../../shared/session-identity.ts";
 import { resolveExecutionAgentScope } from "../../agents/agent-scope.ts";
 import {
@@ -415,6 +416,10 @@ export async function resumeAsyncRun(input: {
 	}
 
 	const runId = randomUUID().slice(0, 8);
+	const revivedTarget = intercomBridge.active
+		? resolveSubagentIntercomTarget(runId, target.agent, 0)
+		: undefined;
+	const supervisorAuthorization = await requestSupervisorAuthorization(input.deps.pi.events, revivedTarget);
 	const artifactConfig: ArtifactConfig = { ...DEFAULT_ARTIFACT_CONFIG, enabled: input.params.artifacts !== false };
 	const availableModels = input.ctx.modelRegistry.getAvailable().map(toModelInfo);
 	const result = input.deps.runtime.executeAsyncSingle(runId, {
@@ -444,12 +449,12 @@ export async function resumeAsyncRun(input: {
 		controlConfig: resolveControlConfig(input.deps.config.control, input.params.control),
 		controlIntercomTarget: intercomBridge.active ? intercomBridge.orchestratorTarget : undefined,
 		childIntercomTarget: intercomBridge.active ? (agent, index) => resolveSubagentIntercomTarget(runId, agent, index) : undefined,
+		supervisorAuthorization,
 		availableModels,
 	});
 	if (result.isError) return result;
 
 	const revivedId = result.details.asyncId ?? runId;
-	const revivedTarget = intercomBridge.active ? resolveSubagentIntercomTarget(revivedId, target.agent, 0) : undefined;
 	const sourceLabel = target.source;
 	const lines = [
 		`Revived ${sourceLabel} subagent from ${target.runId}.`,

package/dist/builtin/subagents/src/runs/foreground/subagent-executor-single.ts

@@ -7,6 +7,7 @@ import { injectSingleProgressInstruction, resolveSingleProgress, writeInitialPro
 import { recordRun } from "../shared/run-history.ts";
 import { getSingleResultOutput, compactForegroundDetails } from "../../shared/utils.ts";
 import { updateForegroundNestedProjection } from "../shared/nested-events.ts";
+import { inheritedIntercomGroup, resolveChildIntercomGroup } from "../shared/intercom-group.ts";
 import {
 	INTERCOM_BRIDGE_MARKER,
 	resolveSubagentIntercomTarget,
@@ -186,6 +187,7 @@ export async function runSinglePath(data: ExecutionContextData, deps: ResolvedEx
 			onControlEvent,
 			intercomSessionName: childIntercomTarget,
 			orchestratorIntercomTarget: data.intercomBridge.active ? data.intercomBridge.orchestratorTarget : undefined,
+			intercomGroup: resolveChildIntercomGroup(params.group, inheritedIntercomGroup(ctx), undefined),
 			nestedRoute: foregroundControl?.nestedRoute,
 			onDetachedExit: (result) => {
 				cleanupTransientProgress(progressDir, artifactConfig.enabled);

package/dist/builtin/subagents/src/runs/foreground/subagent-executor-types.ts

@@ -18,6 +18,7 @@ export interface TaskParam {
 	progress?: boolean;
 	model?: string;
 	skill?: string | string[] | boolean;
+	group?: string | true;
 }
 
 export interface SubagentParamsLike {
@@ -46,6 +47,7 @@ export interface SubagentParamsLike {
 	includeProgress?: boolean;
 	model?: string;
 	skill?: string | string[] | boolean;
+	group?: string | true;
 	output?: string | boolean;
 	outputMode?: "inline" | "file-only";
 	reads?: string[] | false;

package/dist/builtin/subagents/src/runs/foreground/subagent-executor.ts

@@ -227,7 +227,7 @@ export function createSubagentExecutor(rawDeps: ExecutorDeps): {
 		const prepared = built.prepared!;
 		let nestedForegroundStarted = false;
 		try {
-			const asyncResult = runAsyncPath(prepared.execData, deps);
+			const asyncResult = await runAsyncPath(prepared.execData, deps);
 			if (asyncResult) return withForkContext(asyncResult, prepared.effectiveParams.context);
 			if (prepared.foregroundControl) {
 				prepared.writeNestedForegroundEvent("subagent.nested.started");

package/dist/builtin/subagents/src/runs/shared/intercom-group.ts

@@ -0,0 +1,50 @@
+import { randomUUID } from "node:crypto";
+
+interface OrchestrationCarrier {
+	orchestrationContext?: { intercomGroup?: string } | undefined;
+}
+
+/** Normalize agent-serialized auto-group sentinels without changing real group names. */
+export function normalizeAutoGroupSentinel(group: string | true | undefined): string | true | undefined {
+	if (group === undefined || group === true) return group;
+	const sentinel = group.trim().toLowerCase();
+	return sentinel === "true" || sentinel === "auto" ? true : group;
+}
+
+/** Read the inherited stage/session intercom group from the extension context (never from process.env). */
+export function inheritedIntercomGroup(ctx: OrchestrationCarrier | undefined): string | undefined {
+	const group = ctx?.orchestrationContext?.intercomGroup;
+	return typeof group === "string" && group.trim().length > 0 ? group.trim() : undefined;
+}
+
+/**
+ * Resolve the intercom group for a spawned subagent child. Precedence:
+ * explicit task/parallel/chain group > inherited current-session (stage) group.
+ * `true` resolves to `sharedAutoGroup` (a single UUID minted once per parallel
+ * set) so every child in the set shares one isolated group. Returns undefined
+ * when nothing applies, so the child inherits env/config/default itself.
+ */
+export function resolveChildIntercomGroup(
+	explicit: string | true | undefined,
+	inherited: string | undefined,
+	sharedAutoGroup: string | undefined,
+): string | undefined {
+	const normalized = normalizeAutoGroupSentinel(explicit);
+	if (normalized === true) return sharedAutoGroup ?? randomUUID();
+	if (typeof normalized === "string" && normalized.trim().length > 0) return normalized.trim();
+	return inherited;
+}
+
+/**
+ * Mint one shared auto-group UUID for a set when the set-level group or any item
+ * requested `true`; otherwise undefined. Ensures all `true` items in one parallel
+ * set land in the SAME group.
+ */
+export function sharedAutoGroupForSet(
+	setGroup: string | true | undefined,
+	items: ReadonlyArray<{ group?: string | true }>,
+): string | undefined {
+	const needsAuto = normalizeAutoGroupSentinel(setGroup) === true
+		|| items.some((item) => normalizeAutoGroupSentinel(item.group) === true);
+	return needsAuto ? randomUUID() : undefined;
+}

package/dist/builtin/subagents/src/runs/shared/pi-args.ts

@@ -40,6 +40,10 @@ export const SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV = `${ENV_PREFIX}_SUBAGENT_PARE
 export const SUBAGENT_INHERIT_PROJECT_CONTEXT_ENV = `${ENV_PREFIX}_SUBAGENT_INHERIT_PROJECT_CONTEXT`;
 export const SUBAGENT_INHERIT_SKILLS_ENV = `${ENV_PREFIX}_SUBAGENT_INHERIT_SKILLS`;
 export const SUBAGENT_INTERCOM_SESSION_NAME_ENV = `${ENV_PREFIX}_SUBAGENT_INTERCOM_SESSION_NAME`;
+export const SUBAGENT_SUPERVISOR_CAPABILITY_ENV = `${ENV_PREFIX}_SUBAGENT_SUPERVISOR_CAPABILITY`;
+export const SUBAGENT_SUPERVISOR_SESSION_ID_ENV = `${ENV_PREFIX}_SUBAGENT_SUPERVISOR_SESSION_ID`;
+/** Intercom home-group env key (not a _SUBAGENT_ key); resolves ATOMIC_/PI_ variants. */
+export const INTERCOM_GROUP_ENV = `${ENV_PREFIX}_INTERCOM_GROUP`;
 const STRUCTURED_OUTPUT_TOOL_NAME = "structured_output";
 
 interface BuildPiArgsInput {
@@ -61,6 +65,8 @@ interface BuildPiArgsInput {
 	promptFileStem?: string;
 	intercomSessionName?: string;
 	orchestratorIntercomTarget?: string;
+	intercomGroup?: string;
+	supervisorAuthorization?: { capability: string; supervisorSessionId: string };
 	runId?: string;
 	childAgentName?: string;
 	childIndex?: number;
@@ -262,6 +268,16 @@ export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
 	if (input.orchestratorIntercomTarget) {
 		env[SUBAGENT_ORCHESTRATOR_TARGET_ENV] = input.orchestratorIntercomTarget;
 	}
+	// Always override inherited capability metadata: a child must never pass its
+	// own supervisor authority to a descendant that lacks a freshly issued grant.
+	env[SUBAGENT_SUPERVISOR_CAPABILITY_ENV] = input.supervisorAuthorization?.capability ?? "";
+	env[SUBAGENT_SUPERVISOR_SESSION_ID_ENV] = input.supervisorAuthorization?.supervisorSessionId ?? "";
+	// Only assign an intercom group when the child actually has intercom access
+	// (peer intercom session name OR contact_supervisor orchestrator target).
+	const hasIntercomAccess = Boolean(input.intercomSessionName || input.orchestratorIntercomTarget);
+	if (input.intercomGroup && hasIntercomAccess) {
+		env[INTERCOM_GROUP_ENV] = input.intercomGroup;
+	}
 	if (input.runId) {
 		env[SUBAGENT_RUN_ID_ENV] = input.runId;
 	}

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

@@ -0,0 +1,75 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export interface WorktreeGitResult { stdout: string; stderr: string; status: number | null }
+export type WorktreeGitRunner = (cwd: string, args: string[]) => WorktreeGitResult;
+
+function tracked(runGit: WorktreeGitRunner, repo: string, relativePath: string): boolean {
+	return runGit(repo, ["ls-files", "--error-unmatch", "--", relativePath]).status === 0;
+}
+function hasTrackedPathComponent(runGit: WorktreeGitRunner, 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.stdout.split(/\r?\n/).some((line) => line.slice(line.indexOf("\t") + 1) === candidate)) return true;
+	}
+	return false;
+}
+function copySettings(runGit: WorktreeGitRunner, 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(runGit, worktreeRoot, relativePath)) return false;
+	fs.mkdirSync(path.dirname(destination), { recursive: true });
+	fs.copyFileSync(source, destination);
+	return true;
+}
+function configureHooks(runGit: WorktreeGitRunner, mainRoot: string): void {
+	const husky = path.join(mainRoot, ".husky");
+	const ordinary = path.join(mainRoot, ".git", "hooks");
+	let desired: string | undefined;
+	try { if (fs.statSync(husky).isDirectory()) desired = husky; } catch { /* continue */ }
+	if (!desired) {
+		try {
+			if (fs.readdirSync(ordinary, { withFileTypes: true }).some((entry) => entry.isFile() && !entry.name.endsWith(".sample"))) desired = ordinary;
+		} catch { /* no hooks */ }
+	}
+	if (!desired) return;
+	const current = runGit(mainRoot, ["config", "--get", "core.hooksPath"]);
+	if (current.status === 0 && path.resolve(mainRoot, current.stdout.trim()) === desired) return;
+	const result = runGit(mainRoot, ["config", "core.hooksPath", desired]);
+	if (result.status !== 0) throw new Error(result.stderr.trim() || "failed to configure shared core.hooksPath");
+}
+function copyIncludes(runGit: WorktreeGitRunner, 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(runGit, 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 { /* concurrent removal */ }
+	}
+}
+export function performPostCreationSetup(runGit: WorktreeGitRunner, mainRoot: string, worktreeRoot: string): string[] {
+	const synthetic: string[] = [];
+	if (copySettings(runGit, mainRoot, worktreeRoot, ".atomic/settings.local.json")) synthetic.push(".atomic/settings.local.json");
+	if (!tracked(runGit, mainRoot, ".atomic/settings.json") && copySettings(runGit, mainRoot, worktreeRoot, ".atomic/settings.json")) {
+		synthetic.push(".atomic/settings.json");
+	}
+	configureHooks(runGit, mainRoot);
+	const source = path.join(mainRoot, "node_modules");
+	const destination = path.join(worktreeRoot, "node_modules");
+	if (fs.existsSync(source) && !fs.existsSync(destination) && !tracked(runGit, worktreeRoot, "node_modules")) {
+		try { fs.symlinkSync(source, destination, process.platform === "win32" ? "junction" : undefined); synthetic.push("node_modules"); } catch { /* optional */ }
+	}
+	copyIncludes(runGit, mainRoot, worktreeRoot);
+	return synthetic;
+}

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

@@ -0,0 +1,51 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+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; }
+}
+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 { /* walk */ }
+		const parent = path.dirname(current);
+		if (parent === current) return undefined;
+		current = parent;
+	}
+}
+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 contents = readText(gitEntry);
+	if (contents === undefined || !contents.startsWith("gitdir:")) return undefined;
+	const pointer = contents.slice("gitdir:".length).trim();
+	if (!pointer) return undefined;
+	const gitDir = path.resolve(repoRoot, pointer);
+	if (path.basename(path.dirname(gitDir)) !== "worktrees") return undefined;
+	const commonGitDir = path.dirname(path.dirname(gitDir));
+	if (path.basename(commonGitDir) !== ".git") return undefined;
+	const back = readText(path.join(gitDir, "gitdir"))?.trim();
+	const common = readText(path.join(gitDir, "commondir"))?.trim();
+	if (!back || !common) return undefined;
+	if (!samePath(path.resolve(gitDir, back), gitEntry)) return undefined;
+	if (!samePath(path.resolve(gitDir, common), 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/subagents/src/runs/shared/worktree.ts

@@ -2,7 +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, createGitEnvironment } from "@bastani/atomic";
+import { createGitEnvironment } from "@bastani/atomic";
+import { performPostCreationSetup } from "./worktree-post-create.js";
+import { findCanonicalGitRoot } from "./worktree-root.js";
 export interface WorktreeSetup {
 	cwd: string;
 	worktrees: WorktreeInfo[];
@@ -63,9 +65,10 @@ interface GitResult {
 	status: number | null;
 }
 interface RepoState {
-	toplevel: string;
+	mainRoot: string;
 	cwdRelative: string;
 	baseCommit: string;
+	baseRef: string;
 }
 const DEFAULT_WORKTREE_SETUP_HOOK_TIMEOUT_MS = 30000;
 function runGit(cwd: string, args: string[]): GitResult {
@@ -85,15 +88,30 @@ function runGitChecked(cwd: string, args: string[]): string {
 	}
 	return result.stdout;
 }
+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
+		&& runGit(mainRoot, ["fetch", "origin", `${branch}:${remoteRef}`]).status !== 0) return undefined;
+	return `origin/${branch}`;
+}
 function resolveRepoState(cwd: string): RepoState {
 	const cwdRelative = resolveRepoCwdRelative(cwd);
-	const toplevel = runGitChecked(cwd, ["rev-parse", "--show-toplevel"]).trim();
-	const status = runGitChecked(toplevel, ["status", "--porcelain"]);
-	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 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", "--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 baseRef = originDefaultBranch(mainRoot) || "HEAD";
+	const baseCommit = runGitChecked(mainRoot, ["rev-parse", baseRef]).trim();
+	return { mainRoot, cwdRelative, baseCommit, baseRef };
 }
 function normalizeComparableCwd(cwd: string): string {
 	const resolved = path.resolve(cwd);
@@ -126,11 +144,19 @@ export function formatWorktreeTaskCwdConflict(
 function safePatchAgentName(agent: string): string {
 	return agent.replace(/[^\w.-]/g, "_");
 }
+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 root = path.join(mainRoot, ".atomic", "worktrees");
+	fs.mkdirSync(root, { recursive: true });
+	fs.writeFileSync(path.join(root, ".gitignore"), "*\n", "utf8");
 }
 function resolveRepoCwdRelative(cwd: string): string {
 	const repoCheck = runGit(cwd, ["rev-parse", "--is-inside-work-tree"]);
@@ -145,20 +171,12 @@ 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 {
-		return false;
-	}
-}
 function parseHookTimeout(timeoutMs: number | undefined): number {
 	if (timeoutMs === undefined) return DEFAULT_WORKTREE_SETUP_HOOK_TIMEOUT_MS;
 	if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
@@ -270,53 +288,46 @@ 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 { /* idempotent */ }
+	waitForGitLockRelease();
+	try { runGitChecked(repoCwd, ["branch", "-D", worktree.branch]); } catch { /* idempotent */ }
+}
 function createSingleWorktree(
-	toplevel: string,
+	mainRoot: string,
 	cwdRelative: string,
 	runId: string,
 	index: number,
+	baseRef: string,
 	baseCommit: 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(runGit, mainRoot, worktreePath);
 		if (setupHook) {
-			const hookSyntheticPaths = runWorktreeSetupHook(setupHook, {
-				version: 1,
-				repoRoot: toplevel,
-				worktreePath,
-				agentCwd,
-				branch,
-				index,
-				runId,
-				baseCommit,
-				agent,
-			});
-			syntheticPaths.push(...hookSyntheticPaths);
+			syntheticPaths.push(...runWorktreeSetupHook(setupHook, {
+				version: 1, repoRoot: mainRoot, worktreePath, agentCwd, branch, index, runId, baseCommit, agent,
+			}));
 		}
 		return {
-			path: worktreePath,
-			agentCwd,
-			branch,
-			index,
-			nodeModulesLinked,
-			syntheticPaths,
+			path: worktreePath, agentCwd, branch, index,
+			nodeModulesLinked: syntheticPaths.includes("node_modules"), syntheticPaths,
 		};
 	} catch (error) {
-		try { runGitChecked(toplevel, ["worktree", "remove", "--force", worktreePath]); } catch {
-		}
-		try { runGitChecked(toplevel, ["branch", "-D", branch]); } catch {
-		}
+		cleanupSingleWorktree(mainRoot, { path: worktreePath, branch });
 		throw error;
 	}
 }
@@ -415,44 +426,27 @@ function writeEmptyPatch(patchPath: string): void {
 	} catch {
 	}
 }
-function cleanupSingleWorktree(repoCwd: string, worktree: WorktreeInfo): void {
-	try { runGitChecked(repoCwd, ["worktree", "remove", "--force", worktree.path]); } catch {
-	}
-	try { runGitChecked(repoCwd, ["branch", "-D", worktree.branch]); } catch {
-	}
-}
+
 function hasWorktreeChanges(diff: WorktreeDiff): boolean {
 	return diff.filesChanged > 0 || diff.insertions > 0 || diff.deletions > 0 || diff.diffStat.trim().length > 0;
 }
 export function createWorktrees(cwd: string, runId: string, count: number, options?: CreateWorktreesOptions): WorktreeSetup {
 	const repo = resolveRepoState(cwd);
-	const setupHook = resolveWorktreeSetupHook(repo.toplevel, options?.setupHook);
+	ensureWorktreeIgnore(repo.mainRoot);
+	const setupHook = resolveWorktreeSetupHook(repo.mainRoot, options?.setupHook);
 	const worktrees: WorktreeInfo[] = [];
 	try {
 		for (let index = 0; index < count; index++) {
 			worktrees.push(createSingleWorktree(
-				repo.toplevel,
-				repo.cwdRelative,
-				runId,
-				index,
-				repo.baseCommit,
-				setupHook,
-				options?.agents?.[index],
+				repo.mainRoot, repo.cwdRelative, runId, index, repo.baseRef, repo.baseCommit,
+				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 diffWorktrees(setup: WorktreeSetup, agents: string[], diffsDir: string): WorktreeDiff[] {
 	try {
@@ -478,8 +472,6 @@ 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 {
-	}
 }
 export function formatWorktreeDiffSummary(diffs: WorktreeDiff[]): string {
 	const changed = diffs.filter(hasWorktreeChanges);