@bastani/atomic 0.9.8 → 0.9.9-alpha.2

package/dist/builtin/workflows/src/runs/foreground/executor-direct.ts

@@ -13,6 +13,7 @@ import type { RunOpts } from "./executor-types.js";
 import { run } from "./executor-run.js";
 import {
   cleanupPreparedWorktrees,
+  createGitWorktreeSetupCache,
   collectWorktreeDiffs,
   defineDirectWorkflow,
   directModelRequestsFromChain,
@@ -23,8 +24,9 @@ import {
   prepareDirectWorktrees,
   validateDirectModels,
   workflowDetailsFromRun,
-  writeDirectOutput,
+  type GitWorktreeSetupCache,
 } from "./executor-direct-helpers.js";
+import { writeDirectOutput } from "./executor-direct-output.js";
 import {
   directTaskPrompt,
   directTaskToStep,
@@ -57,27 +59,36 @@ export async function runTask(
   } catch (err) {
     return failedDirectDetails("single", runId, 1, err, options);
   }
-  const prepared = prepareDirectWorktrees([taskWithDefaults], options, runId, "single");
+  const workflowInvocationCwd = runOptions.cwd ?? process.cwd();
+  const prepared = prepareDirectWorktrees([taskWithDefaults], options, runId, "single", workflowInvocationCwd);
   const preparedTask = prepared.tasks[0]!;
+  const gitWorktreeSetupCache = createGitWorktreeSetupCache();
   const direct = defineDirectWorkflow("direct-task", async (ctx) => {
+    const rawResult = await ctx.task(preparedTask.name, directTaskToStep(preparedTask));
+    const { result, artifact } = await writeDirectOutput(
+      preparedTask, rawResult, workflowInvocationCwd, prepared.outputIsolations?.[0], gitWorktreeSetupCache,
+    );
+    const worktreeDiffs = collectWorktreeDiffs(prepared, options.artifacts !== false);
+    return {
+      results: [result],
+      text: result.text,
+      artifacts: [
+        ...worktreeDiffs.artifacts,
+        ...(artifact === undefined ? [] : [artifact]),
+      ],
+      ...(worktreeDiffs.summary === undefined ? {} : { worktreeSummary: worktreeDiffs.summary }),
+    };
+  });
+  let runResult;
+  try {
+    runResult = await run(direct, {}, { ...runOptions, runId, gitWorktreeSetupCache });
+  } finally {
     try {
-      const rawResult = await ctx.task(preparedTask.name, directTaskToStep(preparedTask));
-      const { result, artifact } = await writeDirectOutput(preparedTask, rawResult);
-      const worktreeDiffs = collectWorktreeDiffs(prepared, options.artifacts !== false);
-      return {
-        results: [result],
-        text: result.text,
-        artifacts: [
-          ...worktreeDiffs.artifacts,
-          ...(artifact === undefined ? [] : [artifact]),
-        ],
-        ...(worktreeDiffs.summary === undefined ? {} : { worktreeSummary: worktreeDiffs.summary }),
-      };
+      gitWorktreeSetupCache.dispose();
     } finally {
       cleanupPreparedWorktrees(prepared);
     }
-  });
-  const runResult = await run(direct, {}, { ...runOptions, runId });
+  }
   const results = (runResult.result?.["results"] ?? []) as WorkflowTaskResult[];
   return workflowDetailsFromRun("single", runResult, results, options, validationWarnings);
 }
@@ -96,35 +107,44 @@ export async function runParallel(
   } catch (err) {
     return failedDirectDetails("parallel", runId, expanded.length, err, options);
   }
-  const prepared = prepareDirectWorktrees(expanded, options, runId, "parallel");
+  const workflowInvocationCwd = runOptions.cwd ?? process.cwd();
+  const prepared = prepareDirectWorktrees(expanded, options, runId, "parallel", workflowInvocationCwd);
+  const gitWorktreeSetupCache = createGitWorktreeSetupCache();
   const direct = defineDirectWorkflow("direct-parallel", async (ctx) => {
+    const steps = prepared.tasks.map((task) => directTaskToStep(task));
+    const rawResults = await ctx.parallel(steps, {
+      task: options.task,
+      concurrency: options.concurrency,
+      failFast: options.failFast,
+    });
+    const persisted = await Promise.all(
+      rawResults.map((result, index) => writeDirectOutput(
+        prepared.tasks[index]!, result, workflowInvocationCwd, prepared.outputIsolations?.[index], gitWorktreeSetupCache,
+      )),
+    );
+    const results = persisted.map((item) => item.result);
+    const worktreeDiffs = collectWorktreeDiffs(prepared, options.artifacts !== false);
+    const artifacts = [
+      ...worktreeDiffs.artifacts,
+      ...persisted.flatMap((item) => item.artifact === undefined ? [] : [item.artifact]),
+    ];
+    return {
+      results,
+      count: results.length,
+      artifacts,
+      ...(worktreeDiffs.summary === undefined ? {} : { worktreeSummary: worktreeDiffs.summary }),
+    };
+  });
+  let runResult;
+  try {
+    runResult = await run(direct, {}, { ...runOptions, runId, gitWorktreeSetupCache });
+  } finally {
     try {
-      const steps = prepared.tasks.map((task) => directTaskToStep(task));
-      const rawResults = await ctx.parallel(steps, {
-        task: options.task,
-        concurrency: options.concurrency,
-        failFast: options.failFast,
-      });
-      const persisted = await Promise.all(
-        rawResults.map((result, index) => writeDirectOutput(prepared.tasks[index]!, result)),
-      );
-      const results = persisted.map((item) => item.result);
-      const worktreeDiffs = collectWorktreeDiffs(prepared, options.artifacts !== false);
-      const artifacts = [
-        ...worktreeDiffs.artifacts,
-        ...persisted.flatMap((item) => item.artifact === undefined ? [] : [item.artifact]),
-      ];
-      return {
-        results,
-        count: results.length,
-        artifacts,
-        ...(worktreeDiffs.summary === undefined ? {} : { worktreeSummary: worktreeDiffs.summary }),
-      };
+      gitWorktreeSetupCache.dispose();
     } finally {
       cleanupPreparedWorktrees(prepared);
     }
-  });
-  const runResult = await run(direct, {}, { ...runOptions, runId });
+  }
   const results = (runResult.result?.["results"] ?? []) as WorkflowTaskResult[];
   return workflowDetailsFromRun("parallel", runResult, results, options, validationWarnings);
 }
@@ -137,6 +157,8 @@ async function runDirectChainStep(
   prior: WorkflowTaskResult | readonly WorkflowTaskResult[] | undefined,
   options: WorkflowDirectOptions,
   runId: string,
+  workflowInvocationCwd: string,
+  gitWorktreeSetupCache: GitWorktreeSetupCache,
 ): Promise<{ results: WorkflowTaskResult[]; artifacts: WorkflowArtifact[] }> {
   if ("parallel" in step) {
     const stepOptions = {
@@ -146,7 +168,9 @@ async function runDirectChainStep(
       ...(step.baseBranch !== undefined ? { baseBranch: step.baseBranch } : {}),
     };
     const expanded = expandedParallelTasks(step.parallel.map((item) => directTaskWithDefaults(item, stepOptions)));
-    const prepared = prepareDirectWorktrees(expanded, stepOptions, `${runId}-s${index}`, `step-${index}`);
+    const prepared = prepareDirectWorktrees(
+      expanded, stepOptions, `${runId}-s${index}`, `step-${index}`, workflowInvocationCwd,
+    );
     try {
       const steps = prepared.tasks.map((item) =>
         directTaskToStep(item, directTaskPrompt(item) ?? "{previous}", item.previous ?? prior),
@@ -159,7 +183,10 @@ async function runDirectChainStep(
       } as WorkflowParallelOptions);
       const persisted = await Promise.all(
         rawResults.map((result, taskIndex) =>
-          writeDirectOutput({ ...prepared.tasks[taskIndex]!, chainDir: options.chainDir }, result),
+          writeDirectOutput(
+            { ...prepared.tasks[taskIndex]!, chainDir: options.chainDir }, result, workflowInvocationCwd,
+            prepared.outputIsolations?.[taskIndex], gitWorktreeSetupCache,
+          ),
         ),
       );
       const worktreeDiffs = collectWorktreeDiffs(prepared, stepOptions.artifacts !== false);
@@ -176,7 +203,9 @@ async function runDirectChainStep(
   }
 
   const prompt = directTaskPrompt(step) ?? (index === 0 ? "{task}" : "{previous}");
-  const prepared = prepareDirectWorktrees([directTaskWithDefaults(step, options)], options, `${runId}-s${index}`, `step-${index}`);
+  const prepared = prepareDirectWorktrees(
+    [directTaskWithDefaults(step, options)], options, `${runId}-s${index}`, `step-${index}`, workflowInvocationCwd,
+  );
   const preparedStep = prepared.tasks[0]!;
   try {
     const rawResult = await ctx.task(
@@ -186,7 +215,10 @@ async function runDirectChainStep(
         ...(typeof options.chainDir === "string" ? { chainDir: options.chainDir } : {}),
       } as WorkflowTaskOptions,
     );
-    const { result, artifact } = await writeDirectOutput({ ...preparedStep, chainDir: options.chainDir }, rawResult);
+    const { result, artifact } = await writeDirectOutput(
+      { ...preparedStep, chainDir: options.chainDir }, rawResult, workflowInvocationCwd,
+      prepared.outputIsolations?.[0], gitWorktreeSetupCache,
+    );
     const worktreeDiffs = collectWorktreeDiffs(prepared, options.artifacts !== false);
     return {
       results: [result],
@@ -215,19 +247,36 @@ export async function runChain(
   } catch (err) {
     return failedDirectDetails("chain", runId, chain.length, err, options);
   }
+  const workflowInvocationCwd = runOptions.cwd ?? process.cwd();
+  const gitWorktreeSetupCache = createGitWorktreeSetupCache();
   const direct = defineDirectWorkflow("direct-chain", async (ctx) => {
     const results: WorkflowTaskResult[] = [];
     const artifacts: WorkflowArtifact[] = [];
     let prior: WorkflowTaskResult | readonly WorkflowTaskResult[] | undefined;
     for (let index = 0; index < chain.length; index += 1) {
-      const step = await runDirectChainStep(ctx, chain[index]!, index, options.task ?? "", prior, options, runId);
+      const step = await runDirectChainStep(
+        ctx,
+        chain[index]!,
+        index,
+        options.task ?? "",
+        prior,
+        options,
+        runId,
+        workflowInvocationCwd,
+        gitWorktreeSetupCache,
+      );
       results.push(...step.results);
       artifacts.push(...step.artifacts);
       prior = step.results.length === 1 ? step.results[0] : step.results;
     }
     return { results, count: results.length, artifacts };
   });
-  const runResult = await run(direct, {}, { ...runOptions, runId });
+  let runResult;
+  try {
+    runResult = await run(direct, {}, { ...runOptions, runId, gitWorktreeSetupCache });
+  } finally {
+    gitWorktreeSetupCache.dispose();
+  }
   const results = (runResult.result?.["results"] ?? []) as WorkflowTaskResult[];
   return workflowDetailsFromRun("chain", runResult, results, options, validationWarnings);
 }

package/dist/builtin/workflows/src/runs/foreground/executor-stage-call.ts

@@ -7,6 +7,7 @@ import { raceAbort } from "./executor-abort.js";
 import { hasExplicitFastModeCandidate } from "./executor-direct-helpers.js";
 import { applyFailureToStage } from "./executor-lifecycle.js";
 import { isTerminalStage } from "./executor-scheduler.js";
+import { rebasedStageStartedAt } from "../../shared/timing.js";
 
 export interface TrackedStageCallOptions {
   readonly eagerSession?: boolean;
@@ -110,8 +111,9 @@ export function createTrackedStageCaller(input: {
       }
     }
     if (trackStageLifecycle) {
+      const now = Date.now();
       runtime.stageSnapshot.status = "running";
-      runtime.stageSnapshot.startedAt = Date.now();
+      runtime.stageSnapshot.startedAt ??= rebasedStageStartedAt(input.options?.durableAccumulatedDurationMs, now);
       const hasNoExplicitModelConfig = input.options?.model === undefined && input.options?.fallbackModels === undefined;
       const promptAdapterHandlesInitialPrompt = input.adapters.prompt !== undefined;
       if (callOptions.eagerSession && !promptAdapterHandlesInitialPrompt && (hasNoExplicitModelConfig || await hasExplicitFastModeCandidate({

package/dist/builtin/workflows/src/runs/foreground/executor-task-prompts.ts

@@ -69,7 +69,7 @@ export function resolveWorkflowPath(filePath: string, baseDir: string | undefine
 }
 
 export function taskBaseDir(options: Pick<WorkflowTaskExecutionOptions, "chainDir" | "cwd">): string | undefined {
-  if (typeof options.chainDir === "string" && options.chainDir.length > 0) {
+  if (typeof options.chainDir === "string" && options.chainDir.trim().length > 0) {
     return resolveWorkflowPath(options.chainDir, process.cwd());
   }
   if (typeof options.cwd === "string" && options.cwd.length > 0) {

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

@@ -15,6 +15,7 @@ import type { WorkflowRegistry } from "../../workflows/registry.js";
 import type { CancellationRegistry } from "../background/cancellation-registry.js";
 import type { StageAdapters } from "./stage-runner.js";
 import type { StageControlRegistry } from "./stage-control-registry.js";
+import type { GitWorktreeSetupCache } from "../shared/worktree.js";
 
 export interface ResolvedInputs extends WorkflowInputValues {}
 
@@ -68,6 +69,8 @@ export interface RunOpts extends Omit<AuthoringContract.RunOpts, "adapters" | "s
   stageControlRegistry?: StageControlRegistry;
   /** Pre-allocated runId. */
   runId?: string;
+  /** Internal reusable-worktree cache shared with direct output persistence. */
+  gitWorktreeSetupCache?: GitWorktreeSetupCache;
   /** Replay completed stages from a failed source run, then resume at this stage. */
   continuation?: RunContinuationOpts;
   /**

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

@@ -306,7 +306,7 @@ export class StageSessionController {
     const stageOptions = this.stageOptionsForCandidate(candidate, resumeOptions);
     const created = this.opts.adapters.agentSession
       ? await this.opts.adapters.agentSession.create(
-          stripWorkflowOnlyOptions(stageOptions, this.opts.defaultSessionDir) as StageSessionCreateOptions,
+          stripWorkflowOnlyOptions(stageOptions, this.opts.defaultSessionDir, this.meta) as StageSessionCreateOptions,
           { ...this.meta, stageOptions },
         )
       : missingAdapter(consumer);

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

@@ -1,15 +1,38 @@
 import { SessionManager, type CreateAgentSessionOptions } from "@bastani/atomic";
-import type { StageOptions } from "../../shared/types.js";
+import type { StageExecutionMeta, StageOptions } from "../../shared/types.js";
 import type { AgentSessionConsumer } from "./stage-runner-types.js";
 
+function workflowSessionOptions(meta: StageExecutionMeta) {
+  return {
+    internal: true as const,
+    workflow: { runId: meta.runId, stageId: meta.stageId, stageName: meta.stageName },
+  };
+}
+
+function workflowOrchestrationContext(meta: StageExecutionMeta): NonNullable<CreateAgentSessionOptions["orchestrationContext"]> {
+  return {
+    kind: "workflow-stage",
+    workflowRunId: meta.runId,
+    workflowStageId: meta.stageId,
+    workflowStageName: meta.stageName,
+    constraints: { disableWorkflowTool: true, maxSubagentDepth: 5 },
+  };
+}
+
 export function stripWorkflowOnlyOptions(
   options: StageOptions | undefined,
-  defaultSessionDir?: string,
+  defaultSessionDir: string | undefined,
+  meta: StageExecutionMeta,
 ): CreateAgentSessionOptions {
+  const classification = workflowSessionOptions(meta);
+  const orchestrationContext = workflowOrchestrationContext(meta);
   if (!options) {
     return defaultSessionDir === undefined
-      ? {}
-      : { sessionManager: SessionManager.create(process.cwd(), defaultSessionDir) };
+      ? { orchestrationContext }
+      : {
+          orchestrationContext,
+          sessionManager: SessionManager.create(process.cwd(), defaultSessionDir, classification),
+        };
   }
   const {
     schema: _schema,
@@ -20,6 +43,7 @@ export function stripWorkflowOnlyOptions(
     forkFromSessionFile,
     resumeFromSessionFile,
     durableReplayKey: _durableReplayKey,
+    durableAccumulatedDurationMs: _durableAccumulatedDurationMs,
     sessionDir,
     gitWorktreeDir: _gitWorktreeDir,
     baseBranch: _baseBranch,
@@ -31,12 +55,17 @@ export function stripWorkflowOnlyOptions(
     if (resumeFromSessionFile !== undefined) {
       sessionOptions.sessionManager = SessionManager.open(resumeFromSessionFile, effectiveSessionDir, cwd);
     } else if (context === "fork" && forkFromSessionFile !== undefined) {
-      sessionOptions.sessionManager = SessionManager.forkFrom(forkFromSessionFile, cwd, effectiveSessionDir);
+      sessionOptions.sessionManager = SessionManager.forkFrom(
+        forkFromSessionFile,
+        cwd,
+        effectiveSessionDir,
+        classification,
+      );
     } else if (effectiveSessionDir !== undefined) {
-      sessionOptions.sessionManager = SessionManager.create(cwd, effectiveSessionDir);
+      sessionOptions.sessionManager = SessionManager.create(cwd, effectiveSessionDir, classification);
     }
   }
-  return sessionOptions as CreateAgentSessionOptions;
+  return { ...sessionOptions, orchestrationContext } as CreateAgentSessionOptions;
 }
 
 export function missingAdapter(consumer: AgentSessionConsumer): never {

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

@@ -0,0 +1,25 @@
+import { createGitWorktreeSetupCache, type GitWorktreeSetupCache } from "./worktree-git.js";
+
+export interface GitWorktreeSetupCacheOwner {
+	readonly cache: GitWorktreeSetupCache;
+	release(finalizer: () => void): void;
+}
+
+export function createGitWorktreeSetupCacheOwner(
+	suppliedCache?: GitWorktreeSetupCache,
+): GitWorktreeSetupCacheOwner {
+	const cache = suppliedCache ?? createGitWorktreeSetupCache();
+	const ownsCache = suppliedCache === undefined;
+	let released = false;
+	return {
+		cache,
+		release(finalizer) {
+			try {
+				if (!released && ownsCache) cache.dispose();
+				released = true;
+			} finally {
+				finalizer();
+			}
+		},
+	};
+}

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

@@ -0,0 +1,103 @@
+import { lstatSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import type { GitWorktreeSetupResult } from "./worktree-types.js";
+
+function relativePathWithin(root: string, candidate: string): string | undefined {
+  const path = relative(root, candidate);
+  return path === ".." || path.startsWith(`..${sep}`) || isAbsolute(path) ? undefined : path;
+}
+
+function existingRealPathThroughAncestor(path: string, description: string): string {
+  let existing = resolve(path);
+  const missing: string[] = [];
+  while (true) {
+    try {
+      return resolve(realpathSync.native(existing), ...missing);
+    } catch (error) {
+      let existingEntry: ReturnType<typeof lstatSync> | undefined;
+      try {
+        existingEntry = lstatSync(existing);
+      } catch {
+        // Missing components are resolved through their nearest existing ancestor.
+      }
+      const code = error && typeof error === "object" && "code" in error
+        ? String((error as { readonly code?: unknown }).code)
+        : undefined;
+      const parent = dirname(existing);
+      if (existingEntry?.isSymbolicLink() === true || (code !== "ENOENT" && code !== "ENOTDIR") || parent === existing) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`atomic-workflows: cannot resolve ${description} ${path}: ${message}`);
+      }
+      missing.unshift(existing.slice(parent.length + (parent.endsWith(sep) ? 0 : 1)));
+      existing = parent;
+    }
+  }
+}
+
+function existingRealPath(path: string, description: string): string {
+  try {
+    return realpathSync.native(path);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`atomic-workflows: cannot resolve ${description} ${path}: ${message}`);
+  }
+}
+
+export function resolveWorktreeStageCwd(
+  cwd: string | undefined,
+  setup: GitWorktreeSetupResult,
+): string | undefined {
+  const worktreeRoot = existingRealPath(setup.worktreeRoot, "gitWorktreeDir");
+  const repositoryRoot = existingRealPath(setup.repositoryRoot, "invoking checkout");
+  if (cwd === undefined || cwd.length === 0) return undefined;
+
+  const absoluteInput = isAbsolute(cwd);
+  const candidate = absoluteInput ? cwd : resolve(setup.cwd, cwd);
+  if (!absoluteInput && relativePathWithin(setup.worktreeRoot, candidate) === undefined) {
+    throw new Error(`atomic-workflows: relative cwd ${cwd} escapes gitWorktreeDir ${setup.worktreeRoot}; choose a cwd inside the worktree.`);
+  }
+  const candidateRealPath = existingRealPath(candidate, "cwd");
+  const worktreeRelative = relativePathWithin(worktreeRoot, candidateRealPath);
+  if (worktreeRelative !== undefined) return resolve(setup.worktreeRoot, worktreeRelative);
+  if (!isAbsolute(cwd)) {
+    throw new Error(`atomic-workflows: relative cwd ${cwd} escapes gitWorktreeDir ${setup.worktreeRoot}; choose a path that remains inside the selected worktree.`);
+  }
+  if (relativePathWithin(setup.worktreeRoot, candidate) !== undefined) {
+    throw new Error(`atomic-workflows: cwd ${cwd} resolves outside gitWorktreeDir ${setup.worktreeRoot}; remove the escaping symlink or choose a cwd inside the worktree.`);
+  }
+
+  const repositoryRelative = absoluteInput
+    ? relativePathWithin(repositoryRoot, candidateRealPath)
+    : undefined;
+  if (repositoryRelative === undefined) {
+    throw new Error(`atomic-workflows: cwd ${cwd} is outside gitWorktreeDir ${setup.worktreeRoot}; use a cwd inside the invoking repository so Atomic can remap it, or omit cwd.`);
+  }
+  const mappedCwd = resolve(setup.worktreeRoot, repositoryRelative);
+  const mappedRealPath = existingRealPath(mappedCwd, "remapped worktree cwd");
+  if (relativePathWithin(worktreeRoot, mappedRealPath) === undefined) {
+    throw new Error(`atomic-workflows: cwd ${cwd} remaps through a path that resolves outside gitWorktreeDir ${setup.worktreeRoot}; remove the escaping symlink or omit cwd.`);
+  }
+  return mappedCwd;
+}
+
+
+export function resolveContainedRelativePath(
+  root: string,
+  baseDir: string,
+  relativePath: string,
+  description: string,
+): string {
+  if (isAbsolute(relativePath) || relativePath.split(/[\\/]+/).includes("..")) {
+    throw new Error(`atomic-workflows: relative output ${relativePath} escapes ${description} ${root}; use a path without parent traversal.`);
+  }
+  const candidate = resolve(baseDir, relativePath);
+  if (relativePathWithin(resolve(root), candidate) === undefined) {
+    throw new Error(`atomic-workflows: relative output ${relativePath} escapes ${description} ${root}.`);
+  }
+  const realRoot = existingRealPath(root, description);
+  const realCandidate = existingRealPathThroughAncestor(candidate, "relative output");
+  if (relativePathWithin(realRoot, realCandidate) === undefined) {
+    throw new Error(`atomic-workflows: relative output ${relativePath} resolves outside ${description} ${root} through a symlink.`);
+  }
+  return candidate;
+}

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

@@ -0,0 +1,57 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export interface GitWorktreeGenerationAnchor {
+	assertCurrent(): void;
+	dispose(): void;
+}
+
+function sameFileIdentity(left: fs.BigIntStats, right: fs.BigIntStats): boolean {
+	return left.dev === right.dev && left.ino === right.ino;
+}
+
+function openMainCheckoutAnchor(gitDir: string): GitWorktreeGenerationAnchor {
+	let disposed = false;
+	return {
+		assertCurrent() {
+			if (disposed) throw new Error(`cached .git identity anchor is already disposed: ${gitDir}`);
+			if (!fs.lstatSync(gitDir).isDirectory()) {
+				throw new Error(`cached main-checkout .git directory is no longer current: ${gitDir}`);
+			}
+		},
+		dispose() {
+			disposed = true;
+		},
+	};
+}
+
+export function openGitWorktreeGenerationAnchor(worktreeRoot: string): GitWorktreeGenerationAnchor {
+	const gitFile = path.join(worktreeRoot, ".git");
+	if (fs.lstatSync(gitFile).isDirectory()) return openMainCheckoutAnchor(gitFile);
+	const descriptor = fs.openSync(gitFile, "r");
+	let disposed = false;
+
+	const anchor: GitWorktreeGenerationAnchor = {
+		assertCurrent() {
+			if (disposed) throw new Error(`cached .git identity anchor is already disposed: ${gitFile}`);
+			const held = fs.fstatSync(descriptor, { bigint: true });
+			const current = fs.lstatSync(gitFile, { bigint: true });
+			if (!current.isFile() || !sameFileIdentity(held, current)) {
+				throw new Error(`cached .git identity anchor no longer matches the selected checkout: ${gitFile}`);
+			}
+		},
+		dispose() {
+			if (disposed) return;
+			disposed = true;
+			fs.closeSync(descriptor);
+		},
+	};
+
+	try {
+		anchor.assertCurrent();
+		return anchor;
+	} catch (error) {
+		anchor.dispose();
+		throw error;
+	}
+}