@bastani/atomic 0.9.9 → 0.9.10-alpha.1

package/dist/builtin/workflows/src/runs/foreground/stage-runner-options.ts

@@ -1,6 +1,7 @@
 import { SessionManager, type CreateAgentSessionOptions } from "@bastani/atomic";
 import type { StageExecutionMeta, StageOptions } from "../../shared/types.js";
 import type { AgentSessionConsumer } from "./stage-runner-types.js";
+import { resolveStageGroup, stageHasIntercomAccess } from "../../shared/intercom-group.js";
 
 function workflowSessionOptions(meta: StageExecutionMeta) {
   return {
@@ -9,14 +10,19 @@ function workflowSessionOptions(meta: StageExecutionMeta) {
   };
 }
 
-function workflowOrchestrationContext(meta: StageExecutionMeta): NonNullable<CreateAgentSessionOptions["orchestrationContext"]> {
-  return {
-    kind: "workflow-stage",
+function workflowOrchestrationContext(
+  meta: StageExecutionMeta,
+  stageOptions: StageOptions | undefined,
+): NonNullable<CreateAgentSessionOptions["orchestrationContext"]> {
+  const base = {
+    kind: "workflow-stage" as const,
     workflowRunId: meta.runId,
     workflowStageId: meta.stageId,
     workflowStageName: meta.stageName,
-    constraints: { disableWorkflowTool: true, maxSubagentDepth: 5 },
+    constraints: { disableWorkflowTool: true as const, maxSubagentDepth: 5 },
   };
+  const intercomGroup = stageHasIntercomAccess(stageOptions) ? resolveStageGroup(stageOptions) : undefined;
+  return intercomGroup ? { ...base, intercomGroup } : base;
 }
 
 export function stripWorkflowOnlyOptions(
@@ -25,7 +31,7 @@ export function stripWorkflowOnlyOptions(
   meta: StageExecutionMeta,
 ): CreateAgentSessionOptions {
   const classification = workflowSessionOptions(meta);
-  const orchestrationContext = workflowOrchestrationContext(meta);
+  const orchestrationContext = workflowOrchestrationContext(meta, options);
   if (!options) {
     return defaultSessionDir === undefined
       ? { orchestrationContext }
@@ -47,6 +53,7 @@ export function stripWorkflowOnlyOptions(
     sessionDir,
     gitWorktreeDir: _gitWorktreeDir,
     baseBranch: _baseBranch,
+    group: _group,
     ...sessionOptions
   } = options;
   if (sessionOptions.sessionManager === undefined) {

package/dist/builtin/workflows/src/runs/foreground/stage-runner-replacement.ts

@@ -0,0 +1,42 @@
+import type { AgentSession } from "@bastani/atomic";
+import type { StageSessionRuntime } from "./stage-runner-types.js";
+import { asAgentSession, disposeStageSession } from "./stage-runner-session.js";
+
+/** Keeps detached completion ownership continuous while a fallback session is replaced. */
+export class StageSessionReplacement {
+  private previous: StageSessionRuntime | undefined;
+  private readonly cleanups = new Set<Promise<void>>();
+
+  retire(session: StageSessionRuntime | undefined): void {
+    this.previous = session;
+  }
+
+  adopt(session: StageSessionRuntime): void {
+    const previous = this.previous;
+    this.previous = undefined;
+    if (!previous) return;
+    const source = asAgentSession(previous) as (AgentSession & {
+      transferWorkflowStageDeliveriesTo?(target: AgentSession): void;
+    }) | undefined;
+    const target = asAgentSession(session);
+    if (source && target) source.transferWorkflowStageDeliveriesTo?.(target);
+    const cleanup = this.disposeAfterIdle(previous);
+    this.cleanups.add(cleanup);
+    void cleanup.finally(() => this.cleanups.delete(cleanup)).catch(() => {});
+  }
+
+  async dispose(): Promise<void> {
+    const previous = this.previous;
+    this.previous = undefined;
+    await Promise.allSettled([
+      ...(previous ? [disposeStageSession(previous)] : []),
+      ...this.cleanups,
+    ]);
+  }
+
+  private async disposeAfterIdle(session: StageSessionRuntime): Promise<void> {
+    const agent = session.agent as { waitForIdle?: () => Promise<void> } | undefined;
+    if (typeof agent?.waitForIdle === "function") await agent.waitForIdle();
+    await disposeStageSession(session);
+  }
+}

package/dist/builtin/workflows/src/runs/foreground/stage-runner-send-user-message.ts

@@ -1,5 +1,52 @@
 import type { StageSendUserMessageOptions, StageUserMessageContent } from "../../shared/types.js";
-import type { StageSessionRuntime } from "./stage-runner-types.js";
+import type { StageMessageAdmission, StageMessageTurn } from "./stage-runner-message-admission.js";
+import type { StageSessionRuntime, StageUserMessageDeliveryAction } from "./stage-runner-types.js";
+
+interface PromptOwnershipObserver {
+  arm(): void;
+  observe(): void;
+  observeStreaming(): void;
+  settle(action?: StageUserMessageDeliveryAction): void;
+  dispose(): void;
+}
+
+function createLocalPromptOwnershipObserver(
+  session: StageSessionRuntime,
+  promptStarted: (() => void) | undefined,
+): PromptOwnershipObserver {
+  let armed = false;
+  let observed = false;
+  let unsubscribe: (() => void) | undefined;
+  const observe = (): void => {
+    if (observed) return;
+    observed = true;
+    unsubscribe?.();
+    unsubscribe = undefined;
+    promptStarted?.();
+  };
+  unsubscribe = session.subscribe((event) => {
+    if (armed && event.type === "agent_start") observe();
+  });
+  return {
+    arm() { armed = true; },
+    observe,
+    observeStreaming() { if (session.isStreaming) observe(); },
+    settle() {},
+    dispose() { unsubscribe?.(); },
+  };
+}
+
+function coordinatedPromptOwnershipObserver(
+  turn: StageMessageTurn,
+): PromptOwnershipObserver {
+  return {
+    arm: () => turn.arm(),
+    observe: () => turn.observe(),
+    observeStreaming: () => turn.observeStreaming(),
+    settle: (action) => turn.settle(action),
+    dispose() {},
+  };
+}
 
 function unsupportedContentError(): Error {
   return new Error("atomic-workflows: this stage session adapter does not support non-string sendUserMessage content; provide a runtime sendUserMessage implementation for text/image blocks.");
@@ -9,17 +56,62 @@ export async function sendStageUserMessage(
   activeSession: StageSessionRuntime,
   content: StageUserMessageContent,
   options?: StageSendUserMessageOptions,
-): Promise<void> {
-  const deliverAs = activeSession.isStreaming ? options?.deliverAs ?? "followUp" : options?.deliverAs;
+  beforeDelivery?: () => void,
+  promptStarted?: () => void,
+  admission?: StageMessageAdmission,
+): Promise<StageUserMessageDeliveryAction> {
+  const streaming = activeSession.isStreaming || admission?.isOwned(activeSession) === true;
+  const deliverAs = streaming ? options?.deliverAs ?? "followUp" : options?.deliverAs;
   if (activeSession.sendUserMessage !== undefined) {
-    await activeSession.sendUserMessage(content, deliverAs === undefined ? undefined : { deliverAs });
-    return;
+    beforeDelivery?.();
+    let reportedAction: StageUserMessageDeliveryAction | undefined;
+    const ownership = streaming
+      ? undefined
+      : admission === undefined
+        ? createLocalPromptOwnershipObserver(activeSession, promptStarted)
+        : coordinatedPromptOwnershipObserver(admission.startTurn(activeSession, promptStarted ?? (() => {})));
+    ownership?.arm();
+    try {
+      const delivery = activeSession.sendUserMessage(content, {
+        ...(deliverAs === undefined ? {} : { deliverAs }),
+        __workflowDelivery: {
+          promptStarted: ownership?.observe ?? promptStarted,
+          delivered(action) { reportedAction = action; },
+        },
+      });
+      ownership?.observeStreaming();
+      await delivery;
+      const action = reportedAction ?? (streaming ? deliverAs ?? "followUp" : "prompt");
+      ownership?.settle(action);
+      return action;
+    } catch (error) {
+      ownership?.settle();
+      throw error;
+    } finally {
+      ownership?.dispose();
+    }
   }
   if (typeof content !== "string") throw unsupportedContentError();
-  if (activeSession.isStreaming) {
+  beforeDelivery?.();
+  if (streaming) {
     if (deliverAs === "steer") await activeSession.steer(content);
     else await activeSession.followUp(content);
-    return;
+    return deliverAs ?? "followUp";
+  }
+  const ownership = admission === undefined
+    ? createLocalPromptOwnershipObserver(activeSession, promptStarted)
+    : coordinatedPromptOwnershipObserver(admission.startTurn(activeSession, promptStarted ?? (() => {})));
+  ownership.arm();
+  try {
+    const turn = activeSession.prompt(content);
+    ownership.observeStreaming();
+    await turn;
+    ownership.settle("prompt");
+    return "prompt";
+  } catch (error) {
+    ownership.settle();
+    throw error;
+  } finally {
+    ownership.dispose();
   }
-  await activeSession.prompt(content);
 }

package/dist/builtin/workflows/src/runs/foreground/stage-runner-session-options.ts

@@ -0,0 +1,51 @@
+import {
+  getModelDefaultContextWindow,
+  getSupportedContextWindows,
+  SessionManager,
+  type CreateAgentSessionOptions,
+} from "@bastani/atomic";
+import type { StageOptions } from "../../shared/types.js";
+import type { WorkflowResolvedModelCandidate } from "../shared/model-fallback.js";
+
+interface StageSessionOptionsInput {
+  readonly effectiveStageOptions: StageOptions | undefined;
+  readonly candidate: WorkflowResolvedModelCandidate | undefined;
+  readonly restoreSavedModel?: boolean;
+  readonly reattachSessionFile: string | undefined;
+  readonly sharedModelRegistry: CreateAgentSessionOptions["modelRegistry"];
+}
+
+export function buildStageSessionOptions(input: StageSessionOptionsInput): StageOptions | undefined {
+  const options: StageOptions = input.candidate === undefined
+    ? { ...(input.effectiveStageOptions ?? {}) }
+    : {
+        ...(input.effectiveStageOptions ?? {}),
+        model: input.candidate.value,
+        ...(input.candidate.reasoningLevel !== undefined ? { thinkingLevel: input.candidate.reasoningLevel } : {}),
+        ...(input.candidate.contextWindow !== undefined ? { contextWindow: input.candidate.contextWindow } : {}),
+        fallbackModels: undefined,
+        fallbackThinkingLevels: undefined,
+      };
+  if (input.restoreSavedModel === true) delete options.model;
+
+  if (
+    input.restoreSavedModel !== true &&
+    input.reattachSessionFile === undefined &&
+    options.contextWindow === undefined &&
+    input.candidate !== undefined &&
+    typeof input.candidate.value !== "string" &&
+    getSupportedContextWindows(input.candidate.value).length > 1
+  ) {
+    options.contextWindow = getModelDefaultContextWindow(input.candidate.value);
+  }
+  if (input.reattachSessionFile !== undefined && options.sessionManager === undefined) {
+    const cwd = options.cwd ?? process.cwd();
+    options.sessionManager = SessionManager.open(input.reattachSessionFile, options.sessionDir, cwd);
+    options.context = undefined;
+    options.forkFromSessionFile = undefined;
+  }
+  if (input.sharedModelRegistry !== undefined && options.modelRegistry === undefined) {
+    options.modelRegistry = input.sharedModelRegistry;
+  }
+  return Object.keys(options).length === 0 ? undefined : options;
+}

package/dist/builtin/workflows/src/runs/foreground/stage-runner-session.ts

@@ -53,3 +53,22 @@ export function normalizeSessionCreateResult(
   if ("session" in created) return created;
   return { session: created };
 }
+
+export function attachCreatedStageSession<T>(
+  created: StageSessionRuntime | StageSessionCreateResult,
+  disposed: boolean,
+  stageName: string,
+  attach: (result: StageSessionCreateResult) => T,
+): T | Promise<never> {
+  const result = normalizeSessionCreateResult(created);
+  if (!disposed) return attach(result);
+  return rejectDisposedCreatedSession(result, stageName);
+}
+
+async function rejectDisposedCreatedSession(
+  result: StageSessionCreateResult,
+  stageName: string,
+): Promise<never> {
+  await disposeStageSession(result.session);
+  throw new Error(`atomic-workflows: stage "${stageName}" session has been disposed`);
+}

package/dist/builtin/workflows/src/runs/foreground/stage-runner-types.ts

@@ -15,7 +15,8 @@ import type {
   WorkflowModelCatalogPort,
 } from "../../shared/types.js";
 
-export type StageSessionEvent = Parameters<AgentSession["subscribe"]>[0] extends (event: infer T) => void ? T : never;
+type AgentStageSessionEvent = Parameters<AgentSession["subscribe"]>[0] extends (event: infer T) => void ? T : never;
+export type StageSessionEvent = AgentStageSessionEvent & { readonly turnId?: string | number };
 
 export type WorkflowFastModeSettings = {
   readonly chat: boolean;
@@ -26,9 +27,24 @@ export type WorkflowFastModeSettingsManager = {
   getCodexFastModeSettings(): WorkflowFastModeSettings;
 };
 
+export type StageUserMessageDeliveryAction = "prompt" | "steer" | "followUp" | "handled";
+
+export interface StageUserMessageDeliveryHooks {
+  readonly beforeDelivery?: () => void;
+  /** Releases serialized admission once an idle prompt synchronously owns the turn. */
+  readonly promptStarted?: () => void;
+  readonly delivered?: (action: StageUserMessageDeliveryAction) => void;
+}
+
 export interface StageSessionRuntime {
   prompt(text: string, options?: PromptOptions): Promise<string | void>;
-  sendUserMessage?(content: StageUserMessageContent, options?: StageSendUserMessageOptions): Promise<void>;
+  sendUserMessage?(
+    content: StageUserMessageContent,
+    options?: StageSendUserMessageOptions & { readonly __workflowDelivery?: StageUserMessageDeliveryHooks },
+  ): Promise<void>;
+  sealWorkflowStageGeneration?(): void;
+  closeWorkflowStageGeneration?(): Promise<void>;
+  transferWorkflowStageDeliveriesTo?(target: object): void;
   steer(text: string): Promise<void>;
   followUp(text: string): Promise<void>;
   subscribe(listener: (event: StageSessionEvent) => void): () => void;
@@ -123,6 +139,16 @@ export interface InternalStageContext extends StageContext {
   __ensureSession(): Promise<void>;
   /** Internal: reopen an archived stage transcript before post-terminal follow-up. */
   __ensureSessionFromFile(sessionFile: string): Promise<void>;
+  /** Internal idle-aware delivery primitive; returns the action actually taken. */
+  __sendUserMessage(
+    content: StageUserMessageContent,
+    options?: StageSendUserMessageOptions,
+    beforeDelivery?: () => void,
+  ): Promise<StageUserMessageDeliveryAction>;
+  /** Internal: synchronously reject new detached traffic without waiting for active work. */
+  __sealGeneration(): void;
+  /** Internal: atomically stop detached traffic admission and drain admitted work. */
+  __closeGeneration(): Promise<void>;
   /** Internal: snapshot of currently-known SDK session metadata. */
   __sessionMeta(): { sessionId: string | undefined; sessionFile: string | undefined };
   /** Internal: live coding-agent session when the adapter returned one. */

package/dist/builtin/workflows/src/runs/shared/prompt-callsite.ts

@@ -5,7 +5,6 @@
  * selected frame is hashed by the executor and never persisted in raw form.
  */
 
-import { relative } from "node:path";
 import { fileURLToPath } from "node:url";
 
 export interface PromptCallsiteFrame {
@@ -37,13 +36,11 @@ export function normalizeStackPath(framePath: string): string {
     }
   }
 
+  // Keep the normalized module/file identity absolute. Relativizing against
+  // mutable process.cwd() makes the same persisted workflow callsite hash
+  // differently when a later process starts from another directory.
   normalized = normalizeSlashes(normalized).replace(/^\/([A-Za-z]:\/)/, "$1");
 
-  const cwd = normalizeSlashes(process.cwd());
-  if (normalized.startsWith(`${cwd}/`)) {
-    normalized = normalizeSlashes(relative(process.cwd(), normalized));
-  }
-
   return normalized;
 }
 
@@ -61,6 +58,7 @@ const CURRENT_WORKFLOW_RUNTIME_ROOT = currentModuleRuntimeRoot();
 
 export function isWorkflowRuntimeFrame(normalizedPath: string): boolean {
   const path = normalizeSlashes(normalizedPath);
+  if (path.startsWith("packages/workflows/src/")) return true;
   if (CURRENT_WORKFLOW_RUNTIME_ROOT !== undefined && path.startsWith(CURRENT_WORKFLOW_RUNTIME_ROOT)) {
     return true;
   }

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

@@ -0,0 +1,89 @@
+import { spawnSync } from "node:child_process";
+import { createGitEnvironment } from "@bastani/atomic";
+import type { GitResult } from "./worktree-types.js";
+
+const DISABLED_GIT_HOOKS_PATH = process.platform === "win32" ? "NUL" : "/dev/null";
+const GIT_COMMAND_TIMEOUT_MS = 60_000;
+const GIT_READ_ONLY_PROBE_TIMEOUT_ATTEMPTS = 2;
+export type GitRunner = (cwd: string, args: readonly string[]) => GitResult;
+let gitRunnerOverride: GitRunner | undefined;
+
+function gitCommandArgs(args: readonly string[]): string[] {
+	return ["-c", `core.hooksPath=${DISABLED_GIT_HOOKS_PATH}`, "-c", "core.fsmonitor=false", ...args];
+}
+function gitCommandArgv(args: readonly string[]): string[] { return ["git", ...gitCommandArgs(args)]; }
+function withDiagnostics(result: GitResult, cwd: string, args: readonly string[]): GitResult {
+	return { ...result, argv: result.argv ?? gitCommandArgv(args), cwd: result.cwd ?? cwd, timeoutMs: result.timeoutMs ?? GIT_COMMAND_TIMEOUT_MS };
+}
+function spawnGit(cwd: string, args: readonly string[], plain: boolean): GitResult {
+	const startedAt = Date.now();
+	const result = spawnSync("git", plain ? args : gitCommandArgs(args), {
+		cwd,
+		encoding: "utf-8",
+		env: createGitEnvironment({ GIT_OPTIONAL_LOCKS: "0", GIT_TERMINAL_PROMPT: "0", GCM_INTERACTIVE: "never" }),
+		timeout: GIT_COMMAND_TIMEOUT_MS,
+	});
+	return {
+		stdout: result.stdout ?? "", stderr: result.stderr ?? "", status: result.status ?? null,
+		signal: result.signal ?? null, elapsedMs: Math.max(0, Date.now() - startedAt),
+		...(result.error === undefined ? {} : { error: result.error }),
+	};
+}
+export function withGitRunnerForTest<T>(runner: GitRunner, callback: () => T): T {
+	const previous = gitRunnerOverride;
+	gitRunnerOverride = runner;
+	try { return callback(); } finally { gitRunnerOverride = previous; }
+}
+export function runGit(cwd: string, args: readonly string[]): GitResult {
+	return withDiagnostics((gitRunnerOverride ?? ((dir, values) => spawnGit(dir, values, false)))(cwd, args), cwd, args);
+}
+/** Run Git without command-line config overrides; used only for shared config. */
+export function runGitPlain(cwd: string, args: readonly string[]): GitResult {
+	const result = (gitRunnerOverride ?? ((dir, values) => spawnGit(dir, values, true)))(cwd, args);
+	return { ...withDiagnostics(result, cwd, args), argv: result.argv ?? ["git", ...args] };
+}
+export function runGitChecked(cwd: string, args: readonly string[]): string {
+	const result = runGit(cwd, args);
+	if (result.status !== 0) throw new Error(gitFailureMessage(result));
+	return result.stdout;
+}
+function gitErrorCode(error: Error): string | undefined {
+	return "code" in error ? String((error as Error & { readonly code?: unknown }).code) : undefined;
+}
+export function isGitTimeoutResult(result: GitResult): boolean {
+	if (result.error === undefined) return false;
+	const code = gitErrorCode(result.error)?.toUpperCase();
+	const message = result.error.message.toLowerCase();
+	return code === "ETIMEDOUT" || message.includes("etimedout") || message.includes("timed out");
+}
+function formatArg(value: string): string {
+	return /^[A-Za-z0-9_./:@%+=,\\-]+$/.test(value) ? value : JSON.stringify(value);
+}
+function diagnosticSuffix(result: GitResult): string {
+	const details: string[] = [];
+	if (result.argv?.length) details.push(`command: ${result.argv.map(formatArg).join(" ")}`);
+	if (result.cwd !== undefined) details.push(`cwd: ${result.cwd}`);
+	if (result.timeoutMs !== undefined) details.push(`timeout: ${result.timeoutMs}ms`);
+	if (result.elapsedMs !== undefined) details.push(`elapsed: ${result.elapsedMs}ms`);
+	details.push(`status: ${result.status === null ? "null" : result.status}`);
+	if (result.signal !== undefined) details.push(`signal: ${result.signal ?? "null"}`);
+	if (result.attempts !== undefined && result.attempts > 1) details.push(`attempts: ${result.attempts}`);
+	return ` (${details.join("; ")})`;
+}
+export function gitFailureMessage(result: GitResult): string {
+	if (result.error !== undefined) {
+		const code = gitErrorCode(result.error);
+		if (isGitTimeoutResult(result)) return `git command timed out after ${result.timeoutMs ?? GIT_COMMAND_TIMEOUT_MS}ms${code === undefined ? "" : ` (${code})`}: ${result.error.message}${diagnosticSuffix(result)}`;
+		return `${code === undefined ? result.error.message : `${code}: ${result.error.message}`}${diagnosticSuffix(result)}`;
+	}
+	return `${result.stderr.trim() || result.stdout.trim() || `git exited with status ${result.status}`}${diagnosticSuffix(result)}`;
+}
+export function runGitReadOnlyProbe(cwd: string, args: readonly string[]): GitResult {
+	let attempts = 1;
+	let result = runGit(cwd, args);
+	while (attempts < GIT_READ_ONLY_PROBE_TIMEOUT_ATTEMPTS && result.status !== 0 && isGitTimeoutResult(result)) {
+		attempts += 1;
+		result = runGit(cwd, args);
+	}
+	return attempts > 1 ? { ...result, attempts } : result;
+}

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

@@ -1,136 +1,24 @@
-import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { createGitEnvironment } from "@bastani/atomic";
 import type { GitResult, GitWorktreeSetupOptions, GitWorktreeSetupResult } from "./worktree-types.js";
 import { openGitWorktreeGenerationAnchor, type GitWorktreeGenerationAnchor } from "./worktree-generation.js";
-
-const DISABLED_GIT_HOOKS_PATH = process.platform === "win32" ? "NUL" : "/dev/null";
-const GIT_COMMAND_TIMEOUT_MS = 60_000;
-const GIT_READ_ONLY_PROBE_TIMEOUT_ATTEMPTS = 2;
-
-export type GitRunner = (cwd: string, args: readonly string[]) => GitResult;
-
-let gitRunnerOverride: GitRunner | undefined;
-
-function gitCommandArgs(args: readonly string[]): string[] {
-	return [
-		"-c",
-		`core.hooksPath=${DISABLED_GIT_HOOKS_PATH}`,
-		"-c",
-		"core.fsmonitor=false",
-		...args,
-	];
-}
-
-function gitCommandArgv(args: readonly string[]): string[] {
-	return ["git", ...gitCommandArgs(args)];
-}
-
-function withGitResultDiagnostics(result: GitResult, cwd: string, args: readonly string[]): GitResult {
-	return {
-		...result,
-		argv: result.argv ?? gitCommandArgv(args),
-		cwd: result.cwd ?? cwd,
-		timeoutMs: result.timeoutMs ?? GIT_COMMAND_TIMEOUT_MS,
-	};
-}
-
-function runGitProcess(cwd: string, args: readonly string[]): GitResult {
-	const startedAt = Date.now();
-	const result = spawnSync("git", gitCommandArgs(args), {
-		cwd,
-		encoding: "utf-8",
-		env: createGitEnvironment({
-			GIT_OPTIONAL_LOCKS: "0",
-			GIT_TERMINAL_PROMPT: "0",
-			GCM_INTERACTIVE: "never",
-		}),
-		timeout: GIT_COMMAND_TIMEOUT_MS,
-	});
-	return {
-		stdout: result.stdout ?? "",
-		stderr: result.stderr ?? "",
-		status: result.status ?? null,
-		signal: result.signal ?? null,
-		elapsedMs: Math.max(0, Date.now() - startedAt),
-		...(result.error === undefined ? {} : { error: result.error }),
-	};
-}
-
-export function withGitRunnerForTest<T>(runner: GitRunner, callback: () => T): T {
-	const previous = gitRunnerOverride;
-	gitRunnerOverride = runner;
-	try {
-		return callback();
-	} finally {
-		gitRunnerOverride = previous;
-	}
-}
-
-export function runGit(cwd: string, args: readonly string[]): GitResult {
-	return withGitResultDiagnostics((gitRunnerOverride ?? runGitProcess)(cwd, args), cwd, args);
-}
-
-export function runGitChecked(cwd: string, args: readonly string[]): string {
-	const result = runGit(cwd, args);
-	if (result.status !== 0) throw new Error(gitFailureMessage(result));
-	return result.stdout;
-}
-
-function gitErrorCode(error: Error): string | undefined {
-	return "code" in error ? String((error as Error & { readonly code?: unknown }).code) : undefined;
-}
-
-export function isGitTimeoutResult(result: GitResult): boolean {
-	const error = result.error;
-	if (error === undefined) return false;
-	const code = gitErrorCode(error)?.toUpperCase();
-	const message = error.message.toLowerCase();
-	return code === "ETIMEDOUT" || message.includes("etimedout") || message.includes("timed out");
-}
-
-function formatGitDiagnosticArg(value: string): string {
-	if (/^[A-Za-z0-9_./:@%+=,\\-]+$/.test(value)) return value;
-	return JSON.stringify(value);
-}
-
-function formatGitCommand(argv: readonly string[]): string {
-	return argv.map(formatGitDiagnosticArg).join(" ");
-}
-
-function gitDiagnosticSuffix(result: GitResult): string {
-	const details: string[] = [];
-	if (result.argv !== undefined && result.argv.length > 0) details.push(`command: ${formatGitCommand(result.argv)}`);
-	if (result.cwd !== undefined) details.push(`cwd: ${result.cwd}`);
-	if (result.timeoutMs !== undefined) details.push(`timeout: ${result.timeoutMs}ms`);
-	if (result.elapsedMs !== undefined) details.push(`elapsed: ${result.elapsedMs}ms`);
-	details.push(`status: ${result.status === null ? "null" : result.status}`);
-	if (result.signal !== undefined) details.push(`signal: ${result.signal ?? "null"}`);
-	if (result.attempts !== undefined && result.attempts > 1) details.push(`attempts: ${result.attempts}`);
-	return details.length === 0 ? "" : ` (${details.join("; ")})`;
-}
-
-export function gitFailureMessage(result: GitResult): string {
-	if (result.error !== undefined) {
-		const code = gitErrorCode(result.error);
-		if (isGitTimeoutResult(result)) {
-			return `git command timed out after ${result.timeoutMs ?? GIT_COMMAND_TIMEOUT_MS}ms${code === undefined ? "" : ` (${code})`}: ${result.error.message}${gitDiagnosticSuffix(result)}`;
-		}
-		return `${code === undefined ? result.error.message : `${code}: ${result.error.message}`}${gitDiagnosticSuffix(result)}`;
-	}
-	return `${result.stderr.trim() || result.stdout.trim() || `git exited with status ${result.status}`}${gitDiagnosticSuffix(result)}`;
-}
-
-function runGitReadOnlyProbe(cwd: string, args: readonly string[]): GitResult {
-	let attempts = 1;
-	let result = runGit(cwd, args);
-	while (attempts < GIT_READ_ONLY_PROBE_TIMEOUT_ATTEMPTS && result.status !== 0 && isGitTimeoutResult(result)) {
-		attempts += 1;
-		result = runGit(cwd, args);
-	}
-	return attempts > 1 ? { ...result, attempts } : result;
-}
+import { findCanonicalGitRoot } from "./worktree-root.js";
+import {
+	gitFailureMessage,
+	isGitTimeoutResult,
+	runGit,
+	runGitReadOnlyProbe,
+} from "./worktree-git-runner.js";
+
+export {
+	gitFailureMessage,
+	isGitTimeoutResult,
+	runGit,
+	runGitChecked,
+	runGitPlain,
+	withGitRunnerForTest,
+} from "./worktree-git-runner.js";
+export type { GitRunner } from "./worktree-git-runner.js";
 
 export interface GitWorktreeSetupCache {
 	get(options: GitWorktreeSetupOptions): GitWorktreeSetupResult;
@@ -301,7 +189,11 @@ function repositoryRootForGitWorktree(cwd: string): string {
 		}
 		throw new Error(`gitWorktreeDir requires the workflow to be invoked from inside a Git repository. Start from a Git checkout or omit gitWorktreeDir. Git reported: ${gitFailureMessage(result)}`);
 	}
-	return result.stdout.trim();
+	const normalized = gitPathFromOutput(result.stdout, cwd);
+	if (normalized === undefined) {
+		throw new Error(`gitWorktreeDir could not resolve the repository top level from ${cwd}: git returned an empty path.`);
+	}
+	return normalized;
 }
 
 export function gitTopLevelFromResult(result: GitResult, cwd: string, description: string): string | undefined {
@@ -436,6 +328,10 @@ function assertCachedGitWorktreeIdentity(cached: CachedGitWorktreeSetup, options
 
 export function setupGitWorktree(options: GitWorktreeSetupOptions): GitWorktreeSetupResult {
 	const repoRoot = repositoryRootForGitWorktree(options.cwd);
+	const mainRoot = findCanonicalGitRoot(repoRoot);
+	if (mainRoot === undefined) {
+		throw new Error(`Unable to resolve the canonical main Git repository root from ${repoRoot}.`);
+	}
 	const { relativeCwd, logicalRepoRoot } = cwdWithinGitRepository(options.cwd, repoRoot);
 	const worktreeRoot = resolveGitWorktreePath(options.gitWorktreeDir, logicalRepoRoot);
 	validateWorktreeOutsideInvokingCheckout(worktreeRoot, repoRoot);
@@ -456,11 +352,11 @@ export function setupGitWorktree(options: GitWorktreeSetupOptions): GitWorktreeS
 		throw new Error(`Failed to create parent directory for requested gitWorktreeDir ${worktreeRoot}: ${message}`);
 	}
 	const baseRef = options.baseBranch?.trim() || "HEAD";
-	const result = runGit(repoRoot, ["worktree", "add", "--detach", worktreeRoot, baseRef]);
+	const result = runGit(mainRoot, ["worktree", "add", "--detach", worktreeRoot, baseRef]);
 	if (result.status !== 0) {
 		throw new Error([
 			`Failed to create git worktree at requested gitWorktreeDir ${worktreeRoot} from ${baseRef}. Git reported: ${gitFailureMessage(result)}`,
-			`If another process just created this same-repository worktree, rerun the workflow to resume it. If this is an orphaned worktree from an interrupted run, recover or remove it with: ${worktreeRecoveryCommand(repoRoot, worktreeRoot)}`,
+			`If another process just created this same-repository worktree, rerun the workflow to resume it. If this is an orphaned worktree from an interrupted run, recover or remove it with: ${worktreeRecoveryCommand(mainRoot, worktreeRoot)}`,
 		].join("\n"));
 	}
 	try {
@@ -468,7 +364,7 @@ export function setupGitWorktree(options: GitWorktreeSetupOptions): GitWorktreeS
 		validateExistingGitWorktreeRoot(worktreeRoot, repoRoot);
 	} catch (error) {
 		// Best-effort rollback of a target that changed while Git was creating it.
-		runGit(repoRoot, ["worktree", "remove", "--force", worktreeRoot]);
+		runGit(mainRoot, ["worktree", "remove", "--force", worktreeRoot]);
 		const message = error instanceof Error ? error.message : String(error);
 		throw new Error(`Created gitWorktreeDir failed post-creation validation: ${message}`);
 	}