@fitlab-ai/agent-infra 0.9.4 → 0.9.5

package/lib/agent-clients/adapters/codex-lifecycle/evidence.ts

@@ -0,0 +1,307 @@
+type CodexEvidenceSource =
+  | 'codex-hook'
+  | 'codex-app-server-thread'
+  | 'codex-app-server-settings'
+  | 'codex-app-server-turn'
+  | 'codex-app-server-reroute';
+
+type CodexLifecycleEvent =
+  | Readonly<{
+      type: 'hook-spawn';
+      sessionId: string;
+      turnId: string;
+      toolUseId: string;
+      nativeAgent: string;
+      requestedModel?: string;
+      requestedReasoningEffort?: string;
+      hookDefinitionHash: string;
+    }>
+  | Readonly<{
+      type: 'hook-child';
+      sessionId: string;
+      turnId: string;
+      childThreadId: string;
+      nativeAgent: string;
+    }>
+  | Readonly<{
+      type: 'app-thread';
+      childThreadId: string;
+      parentThreadId: string;
+      forkedFromId: string | null;
+      sourceParentThreadId: string;
+    }>
+  | Readonly<{
+      type: 'app-settings';
+      childThreadId: string;
+      model: string;
+      reasoningEffort: string;
+    }>
+  | Readonly<{
+      type: 'app-reroute';
+      childThreadId: string;
+      turnId: string;
+      fromModel: string;
+      toModel: string;
+      reason: string;
+    }>
+  | Readonly<{
+      type: 'app-terminal';
+      childThreadId: string;
+      turnId: string;
+      status: 'completed' | 'interrupted' | 'failed';
+    }>
+  | Readonly<{
+      type: 'hook-stop';
+      sessionId: string;
+      turnId: string;
+      childThreadId: string;
+      nativeAgent: string;
+    }>;
+
+type CodexStartEvidence = Readonly<{
+  schemaVersion: 1;
+  cliVersion: string;
+  parentThreadId: string;
+  parentTurnId: string;
+  spawnToolUseId: string;
+  childThreadId: string;
+  nativeAgent: string;
+  spawnMode: 'fresh';
+  actualModel: Readonly<{ value: string; source: CodexEvidenceSource }>;
+  actualReasoningEffort: Readonly<{ value: string; source: CodexEvidenceSource }>;
+  modelFallbackReason: string | null;
+  reasoningEffortFallbackReason: string | null;
+  hookDefinitionHash: string;
+}>;
+
+type CodexStopEvidence = Readonly<{
+  schemaVersion: 1;
+  childThreadId: string;
+  turnId: string;
+  terminalStatus: 'completed';
+  hookStopObserved: true;
+}>;
+
+type CodexLifecycleStatus =
+  | 'empty'
+  | 'observed-spawn'
+  | 'observed-child'
+  | 'start-ready'
+  | 'observed-terminal'
+  | 'stop-ready'
+  | 'invalid'
+  | 'expired';
+
+type CodexEvidenceError = Readonly<{ code: string; message: string }>;
+
+type CodexLifecycleState = Readonly<{
+  schemaVersion: 1;
+  cliVersion: string;
+  status: CodexLifecycleStatus;
+  spawn: Extract<CodexLifecycleEvent, { type: 'hook-spawn' }> | null;
+  child: Extract<CodexLifecycleEvent, { type: 'hook-child' }> | null;
+  thread: Extract<CodexLifecycleEvent, { type: 'app-thread' }> | null;
+  settings: Extract<CodexLifecycleEvent, { type: 'app-settings' }> | null;
+  reroute: Extract<CodexLifecycleEvent, { type: 'app-reroute' }> | null;
+  terminal: Extract<CodexLifecycleEvent, { type: 'app-terminal' }> | null;
+  stop: Extract<CodexLifecycleEvent, { type: 'hook-stop' }> | null;
+  startEvidence: CodexStartEvidence | null;
+  stopEvidence: CodexStopEvidence | null;
+  error: CodexEvidenceError | null;
+}>;
+
+function createCodexLifecycleState(cliVersion: string): CodexLifecycleState {
+  if (!cliVersion.trim()) throw new Error('Codex CLI version is required');
+  return Object.freeze({
+    schemaVersion: 1,
+    cliVersion,
+    status: 'empty',
+    spawn: null,
+    child: null,
+    thread: null,
+    settings: null,
+    reroute: null,
+    terminal: null,
+    stop: null,
+    startEvidence: null,
+    stopEvidence: null,
+    error: null
+  });
+}
+
+function invalid(state: CodexLifecycleState, code: string, message: string): CodexLifecycleState {
+  return Object.freeze({
+    ...state,
+    status: 'invalid',
+    startEvidence: null,
+    stopEvidence: null,
+    error: Object.freeze({ code, message })
+  });
+}
+
+function same(left: unknown, right: unknown): boolean {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function requiredStrings(event: CodexLifecycleEvent): boolean {
+  return Object.entries(event).every(([key, value]) =>
+    key === 'forkedFromId'
+    || (typeof value !== 'string' || value.trim() !== '')
+  );
+}
+
+function derive(state: CodexLifecycleState): CodexLifecycleState {
+  const { spawn, child, thread, settings, reroute, terminal, stop } = state;
+  if (spawn && child && (
+    spawn.sessionId !== child.sessionId
+    || spawn.nativeAgent !== child.nativeAgent
+  )) {
+    return invalid(state, 'CODEX_EVIDENCE_IDENTITY_MISMATCH', 'hook spawn and child identity do not match');
+  }
+  if (child && thread && child.childThreadId !== thread.childThreadId) {
+    return invalid(state, 'CODEX_EVIDENCE_IDENTITY_MISMATCH', 'hook and App Server child identity do not match');
+  }
+  if (spawn && thread && (
+    thread.parentThreadId !== spawn.sessionId
+    || thread.sourceParentThreadId !== spawn.sessionId
+  )) {
+    return invalid(state, 'CODEX_EVIDENCE_PARENT_MISMATCH', 'App Server parent identity does not match the spawning session');
+  }
+  if (thread?.forkedFromId !== null && thread?.forkedFromId !== undefined) {
+    return invalid(state, 'CODEX_EVIDENCE_FORK_FORBIDDEN', 'forked child threads are not fresh lifecycle evidence');
+  }
+  if (settings && child && settings.childThreadId !== child.childThreadId) {
+    return invalid(state, 'CODEX_EVIDENCE_IDENTITY_MISMATCH', 'resolved settings belong to a different child');
+  }
+  if (reroute && child && reroute.childThreadId !== child.childThreadId) {
+    return invalid(state, 'CODEX_EVIDENCE_IDENTITY_MISMATCH', 'model reroute belongs to a different child');
+  }
+  if (spawn?.requestedModel && settings && spawn.requestedModel !== settings.model) {
+    if (
+      !reroute
+      || reroute.fromModel !== spawn.requestedModel
+      || reroute.toModel !== settings.model
+      || !reroute.reason.trim()
+    ) {
+      return invalid(state, 'CODEX_EVIDENCE_MODEL_UNEXPLAINED', 'resolved model differs without a matching host reroute');
+    }
+  }
+  if (
+    spawn?.requestedReasoningEffort
+    && settings
+    && spawn.requestedReasoningEffort !== settings.reasoningEffort
+  ) {
+    return invalid(state, 'CODEX_EVIDENCE_EFFORT_UNEXPLAINED', 'resolved reasoning effort differs without structured host evidence');
+  }
+  if (terminal && terminal.status !== 'completed') {
+    return invalid(state, 'CODEX_EVIDENCE_TERMINAL_INVALID', `child turn ended as '${terminal.status}'`);
+  }
+  if (terminal && child && terminal.childThreadId !== child.childThreadId) {
+    return invalid(state, 'CODEX_EVIDENCE_IDENTITY_MISMATCH', 'terminal event belongs to a different child');
+  }
+  if (stop && child && (
+    stop.sessionId !== child.sessionId
+    || stop.turnId !== child.turnId
+    || stop.childThreadId !== child.childThreadId
+    || stop.nativeAgent !== child.nativeAgent
+  )) {
+    return invalid(state, 'CODEX_EVIDENCE_IDENTITY_MISMATCH', 'hook stop identity does not match the child');
+  }
+
+  let startEvidence: CodexStartEvidence | null = null;
+  if (spawn && child && thread && settings) {
+    startEvidence = Object.freeze({
+      schemaVersion: 1,
+      cliVersion: state.cliVersion,
+      parentThreadId: spawn.sessionId,
+      parentTurnId: spawn.turnId,
+      spawnToolUseId: spawn.toolUseId,
+      childThreadId: child.childThreadId,
+      nativeAgent: child.nativeAgent,
+      spawnMode: 'fresh',
+      actualModel: Object.freeze({ value: settings.model, source: 'codex-app-server-settings' }),
+      actualReasoningEffort: Object.freeze({ value: settings.reasoningEffort, source: 'codex-app-server-settings' }),
+      modelFallbackReason: reroute?.reason ?? null,
+      reasoningEffortFallbackReason: null,
+      hookDefinitionHash: spawn.hookDefinitionHash
+    });
+  }
+  let stopEvidence: CodexStopEvidence | null = null;
+  if (startEvidence && terminal?.status === 'completed' && stop) {
+    stopEvidence = Object.freeze({
+      schemaVersion: 1,
+      childThreadId: startEvidence.childThreadId,
+      turnId: terminal.turnId,
+      terminalStatus: 'completed',
+      hookStopObserved: true
+    });
+  }
+  const status: CodexLifecycleStatus = stopEvidence
+    ? 'stop-ready'
+    : terminal
+      ? 'observed-terminal'
+      : startEvidence
+        ? 'start-ready'
+        : child
+          ? 'observed-child'
+          : spawn
+            ? 'observed-spawn'
+            : 'empty';
+  return Object.freeze({ ...state, status, startEvidence, stopEvidence, error: null });
+}
+
+function reduceCodexLifecycleEvent(
+  state: CodexLifecycleState,
+  event: CodexLifecycleEvent
+): CodexLifecycleState {
+  if (state.status === 'invalid' || state.status === 'expired') return state;
+  if (!requiredStrings(event)) {
+    return invalid(state, 'CODEX_EVIDENCE_FIELD_MISSING', 'lifecycle event contains an empty required field');
+  }
+  const key = ({
+    'hook-spawn': 'spawn',
+    'hook-child': 'child',
+    'app-thread': 'thread',
+    'app-settings': 'settings',
+    'app-reroute': 'reroute',
+    'app-terminal': 'terminal',
+    'hook-stop': 'stop'
+  } as const)[event.type];
+  const existing = state[key];
+  if (existing) {
+    if (same(existing, event)) return state;
+    return invalid(state, 'CODEX_EVIDENCE_REPLAY_CONFLICT', `conflicting '${event.type}' event`);
+  }
+  return derive(Object.freeze({ ...state, [key]: Object.freeze({ ...event }) }));
+}
+
+function expireCodexLifecycleState(state: CodexLifecycleState): CodexLifecycleState {
+  if (!['observed-spawn', 'observed-child', 'start-ready', 'observed-terminal'].includes(state.status)) {
+    return state;
+  }
+  return Object.freeze({
+    ...state,
+    status: 'expired',
+    startEvidence: null,
+    stopEvidence: null,
+    error: Object.freeze({
+      code: 'CODEX_EVIDENCE_EXPIRED',
+      message: 'Codex lifecycle evidence expired before completion'
+    })
+  });
+}
+
+export {
+  createCodexLifecycleState,
+  expireCodexLifecycleState,
+  reduceCodexLifecycleEvent
+};
+export type {
+  CodexEvidenceError,
+  CodexEvidenceSource,
+  CodexLifecycleEvent,
+  CodexLifecycleState,
+  CodexLifecycleStatus,
+  CodexStartEvidence,
+  CodexStopEvidence
+};

package/lib/agent-clients/adapters/codex-lifecycle/store.ts

@@ -0,0 +1,250 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import {
+  createCodexLifecycleState,
+  expireCodexLifecycleState,
+  reduceCodexLifecycleEvent
+} from './evidence.ts';
+import type {
+  CodexLifecycleEvent,
+  CodexLifecycleState
+} from './evidence.ts';
+
+type StoredCodexLifecycle = Readonly<{
+  schemaVersion: 1;
+  revision: number;
+  state: CodexLifecycleState;
+  consumer: string | null;
+  consumedAt: string | null;
+  updatedAt: string;
+}>;
+
+type CodexLifecycleStoreOptions = Readonly<{
+  root?: string;
+  cliVersion: string;
+  now?: () => string;
+}>;
+
+type CodexLifecycleStoreResult = Readonly<{
+  path: string;
+  revision: number;
+  state: CodexLifecycleState;
+}>;
+
+const LOCK_RETRY_MS = 10;
+const LOCK_TIMEOUT_MS = 1_000;
+const LOCK_STALE_MS = 30_000;
+
+function digest(value: string): string {
+  return crypto.createHash('sha256').update(value).digest('hex');
+}
+
+function readRecord(file: string): StoredCodexLifecycle {
+  const value = JSON.parse(fs.readFileSync(file, 'utf8')) as StoredCodexLifecycle;
+  if (
+    value.schemaVersion !== 1
+    || !Number.isSafeInteger(value.revision)
+    || value.revision < 1
+    || !value.state
+    || value.state.schemaVersion !== 1
+  ) {
+    throw new Error(`Codex lifecycle record '${path.basename(file)}' is invalid`);
+  }
+  return value;
+}
+
+function recordFiles(root: string): string[] {
+  if (!fs.existsSync(root)) return [];
+  return fs.readdirSync(root)
+    .filter((name) => /^[a-f0-9]{64}\.json$/.test(name))
+    .map((name) => path.join(root, name));
+}
+
+function writeRecord(file: string, record: StoredCodexLifecycle, expectedRevision: number): void {
+  const temp = `${file}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  fs.writeFileSync(temp, `${JSON.stringify(record, null, 2)}\n`, {
+    encoding: 'utf8',
+    flag: 'wx',
+    mode: 0o600
+  });
+  try {
+    const actualRevision = fs.existsSync(file) ? readRecord(file).revision : 0;
+    if (actualRevision !== expectedRevision) {
+      throw new Error(`Codex lifecycle revision changed from ${expectedRevision} to ${actualRevision}`);
+    }
+    fs.renameSync(temp, file);
+    fs.chmodSync(file, 0o600);
+  } finally {
+    if (fs.existsSync(temp)) fs.unlinkSync(temp);
+  }
+}
+
+function createCodexLifecycleStore(options: CodexLifecycleStoreOptions) {
+  const root = options.root ?? path.join(process.cwd(), '.agents', 'workspace', '.runtime', 'codex-lifecycle');
+  const now = options.now ?? (() => new Date().toISOString());
+  fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+  fs.chmodSync(root, 0o700);
+
+  function withWriteLock<T>(operation: () => T): T {
+    const lock = path.join(root, '.write.lock');
+    const deadline = Date.now() + LOCK_TIMEOUT_MS;
+    let descriptor: number | null = null;
+    while (descriptor === null) {
+      try {
+        descriptor = fs.openSync(lock, 'wx', 0o600);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+        try {
+          if (Date.now() - fs.statSync(lock).mtimeMs > LOCK_STALE_MS) {
+            fs.unlinkSync(lock);
+            continue;
+          }
+        } catch (lockError) {
+          if ((lockError as NodeJS.ErrnoException).code === 'ENOENT') continue;
+          throw lockError;
+        }
+        if (Date.now() >= deadline) throw new Error('Codex lifecycle store is busy');
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, LOCK_RETRY_MS);
+      }
+    }
+    try {
+      return operation();
+    } finally {
+      fs.closeSync(descriptor);
+      fs.unlinkSync(lock);
+    }
+  }
+
+  function findByChild(childThreadId: string): string[] {
+    return recordFiles(root).filter((file) => {
+      const child = readRecord(file).state.child;
+      return child?.childThreadId === childThreadId;
+    });
+  }
+
+  function locate(event: CodexLifecycleEvent): string {
+    if (event.type === 'hook-spawn') {
+      return path.join(root, `${digest(`${event.sessionId}\0${event.turnId}\0${event.toolUseId}`)}.json`);
+    }
+    if (event.type === 'hook-child') {
+      const matches = recordFiles(root).filter((file) => {
+        const state = readRecord(file).state;
+        return state.spawn?.sessionId === event.sessionId
+          && state.spawn.nativeAgent === event.nativeAgent
+          && (!state.child || state.child.childThreadId === event.childThreadId);
+      });
+      if (matches.length !== 1) {
+        throw new Error(matches.length === 0
+          ? 'Codex lifecycle parent session and agent correlation was not found'
+          : 'Codex lifecycle parent session and agent correlation is ambiguous');
+      }
+      return matches[0]!;
+    }
+    const matches = findByChild(event.childThreadId);
+    if (matches.length !== 1) {
+      throw new Error(matches.length === 0
+        ? `Codex lifecycle child '${event.childThreadId}' was not found`
+        : `Codex lifecycle child '${event.childThreadId}' is ambiguous`);
+    }
+    return matches[0]!;
+  }
+
+  function apply(event: CodexLifecycleEvent): CodexLifecycleStoreResult {
+    return withWriteLock(() => {
+      const file = locate(event);
+      const current = fs.existsSync(file)
+        ? readRecord(file)
+        : Object.freeze({
+            schemaVersion: 1 as const,
+            revision: 0,
+            state: createCodexLifecycleState(options.cliVersion),
+            consumer: null,
+            consumedAt: null,
+            updatedAt: now()
+          });
+      if (current.consumer) throw new Error(`Codex lifecycle evidence was already consumed by '${current.consumer}'`);
+      const nextState = reduceCodexLifecycleEvent(current.state, event);
+      const next = Object.freeze({
+        schemaVersion: 1 as const,
+        revision: current.revision + 1,
+        state: nextState,
+        consumer: null,
+        consumedAt: null,
+        updatedAt: now()
+      });
+      writeRecord(file, next, current.revision);
+      return Object.freeze({ path: file, revision: next.revision, state: next.state });
+    });
+  }
+
+  function read(childThreadId: string): StoredCodexLifecycle {
+    const matches = findByChild(childThreadId);
+    if (matches.length !== 1) throw new Error(`Codex lifecycle child '${childThreadId}' was not found uniquely`);
+    return readRecord(matches[0]!);
+  }
+
+  function consume(
+    childThreadId: string,
+    consumer: string,
+    expectedHookDefinitionHash?: string
+  ): StoredCodexLifecycle {
+    if (!consumer.trim()) throw new Error('Codex lifecycle consumer is required');
+    return withWriteLock(() => {
+      const matches = findByChild(childThreadId);
+      if (matches.length !== 1) throw new Error(`Codex lifecycle child '${childThreadId}' was not found uniquely`);
+      const file = matches[0]!;
+      const current = readRecord(file);
+      if (current.consumer) throw new Error(`Codex lifecycle evidence was already consumed by '${current.consumer}'`);
+      if (current.state.status !== 'stop-ready') throw new Error('Codex lifecycle evidence is not stop-ready');
+      if (
+        expectedHookDefinitionHash
+        && current.state.startEvidence?.hookDefinitionHash !== expectedHookDefinitionHash
+      ) throw new Error('Codex lifecycle hook definition hash is stale');
+      const next = Object.freeze({
+        ...current,
+        revision: current.revision + 1,
+        consumer,
+        consumedAt: now(),
+        updatedAt: now()
+      });
+      writeRecord(file, next, current.revision);
+      return next;
+    });
+  }
+
+  function expireBefore(cutoff: string): number {
+    return withWriteLock(() => {
+      let changed = 0;
+      for (const file of recordFiles(root)) {
+        const current = readRecord(file);
+        if (current.updatedAt >= cutoff) continue;
+        if (current.consumer || ['invalid', 'expired', 'stop-ready'].includes(current.state.status)) {
+          fs.unlinkSync(file);
+          changed += 1;
+          continue;
+        }
+        const expiredState = expireCodexLifecycleState(current.state);
+        if (expiredState === current.state) continue;
+        writeRecord(file, Object.freeze({
+          ...current,
+          revision: current.revision + 1,
+          state: expiredState,
+          updatedAt: now()
+        }), current.revision);
+        changed += 1;
+      }
+      return changed;
+    });
+  }
+
+  return Object.freeze({ root, apply, consume, expireBefore, read });
+}
+
+export { createCodexLifecycleStore };
+export type {
+  CodexLifecycleStoreOptions,
+  CodexLifecycleStoreResult,
+  StoredCodexLifecycle
+};

package/lib/agent-clients/adapters/codex.ts

@@ -25,8 +25,8 @@ const codexAdapter = defineAgentClientAdapter({
     guidance: 'Use the host model picker for the complete model and reasoning-effort catalog.'
   },
   delegationEvidence: {
-    actualModel: 'unavailable',
-    actualReasoningEffort: 'unavailable'
+    actualModel: 'app-server',
+    actualReasoningEffort: 'app-server'
   },
   project: {
     ownedPathPrefixes: ['.codex/'],

package/lib/git/worktree-identity.ts

@@ -0,0 +1,86 @@
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+type GitWorktreeIdentity = Readonly<{
+  worktreeRoot: string;
+  commonDir: string;
+  branch: string;
+}>;
+
+function normalizeCanonicalPath(value: string, platform: NodeJS.Platform = process.platform): string {
+  return platform === 'win32'
+    ? path.win32.normalize(value).replaceAll('/', '\\').toLowerCase()
+    : path.posix.normalize(value);
+}
+
+function sameFilesystemEntry(left: string, right: string, platform: NodeJS.Platform = process.platform): boolean {
+  const leftReal = fs.realpathSync.native(left);
+  const rightReal = fs.realpathSync.native(right);
+  const leftStat = fs.statSync(leftReal, { bigint: true });
+  const rightStat = fs.statSync(rightReal, { bigint: true });
+  if (leftStat.ino !== 0n && rightStat.ino !== 0n) {
+    return leftStat.dev === rightStat.dev && leftStat.ino === rightStat.ino;
+  }
+  return normalizeCanonicalPath(leftReal, platform) === normalizeCanonicalPath(rightReal, platform);
+}
+
+function git(root: string, args: string[]): string {
+  return execFileSync('git', args, {
+    cwd: root,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe']
+  }).trim();
+}
+
+function resolveGitWorktreeIdentity(worktreeRoot: string): GitWorktreeIdentity {
+  try {
+    const canonical = fs.realpathSync.native(worktreeRoot);
+    const topLevel = fs.realpathSync.native(git(canonical, ['rev-parse', '--show-toplevel']));
+    if (!sameFilesystemEntry(canonical, topLevel)) {
+      throw new Error('worktree root is not the Git top-level directory');
+    }
+    const commonDir = fs.realpathSync.native(git(canonical, [
+      'rev-parse', '--path-format=absolute', '--git-common-dir'
+    ]));
+    const branch = git(canonical, ['symbolic-ref', '--short', 'HEAD']);
+    return { worktreeRoot: canonical, commonDir, branch };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`SANDBOX_CONTROL_WORKTREE_INVALID: ${message}`);
+  }
+}
+
+function assertGitWorktreeBinding(
+  stateRoot: string,
+  worktreeRoot: string,
+  expectedBranch: string
+): GitWorktreeIdentity {
+  const state = resolveGitWorktreeIdentity(stateRoot);
+  const worktree = resolveGitWorktreeIdentity(worktreeRoot);
+  if (!sameFilesystemEntry(state.commonDir, worktree.commonDir)) {
+    throw new Error('SANDBOX_CONTROL_WORKTREE_INVALID: state and worktree roots have different Git common directories');
+  }
+  if (worktree.branch !== expectedBranch) {
+    throw new Error(`SANDBOX_CONTROL_WORKTREE_INVALID: expected branch '${expectedBranch}', got '${worktree.branch}'`);
+  }
+  return worktree;
+}
+
+function assertGitRepositoryBinding(stateRoot: string, worktreeRoot: string): GitWorktreeIdentity {
+  const state = resolveGitWorktreeIdentity(stateRoot);
+  const worktree = resolveGitWorktreeIdentity(worktreeRoot);
+  if (!sameFilesystemEntry(state.commonDir, worktree.commonDir)) {
+    throw new Error('SANDBOX_CONTROL_WORKTREE_INVALID: state and worktree roots have different Git common directories');
+  }
+  return worktree;
+}
+
+export {
+  assertGitWorktreeBinding,
+  assertGitRepositoryBinding,
+  normalizeCanonicalPath,
+  resolveGitWorktreeIdentity,
+  sameFilesystemEntry
+};
+export type { GitWorktreeIdentity };