forgeos 0.1.0-alpha.7 → 0.1.0-alpha.71

package/src/forge/agent-fabric/local-coding-worker.ts

@@ -0,0 +1,285 @@
+import { execFileSync } from "node:child_process";
+import { closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { sha256Digest } from "./canonical.ts";
+import { AgentFabricError } from "./errors.ts";
+import type { LocalCodingTaskProposal } from "./local-task-contract.ts";
+import type { Digest } from "./types.ts";
+import { localFabricPath } from "./local-paths.ts";
+
+function git(root: string, args: readonly string[], maxBuffer = 128 * 1024): string {
+  try {
+    return execFileSync("git", ["-c", "core.fsmonitor=false", ...args], {
+      cwd: root, encoding: "utf8", windowsHide: true,
+      timeout: 10_000, maxBuffer, stdio: ["ignore", "pipe", "ignore"],
+    });
+  } catch {
+    throw new AgentFabricError("AF_INVALID_STATE", `Git operation failed: ${args[0] ?? "unknown"}`);
+  }
+}
+
+/** Git checkout may invoke post-checkout and configured smudge/process filters. */
+function inertCheckoutOptions(repositoryRoot: string, configRoot = repositoryRoot): string[] {
+  const hooksDir = localFabricPath(repositoryRoot, "empty-hooks");
+  mkdirSync(hooksDir, { recursive: true, mode: 0o700 });
+  let names = "";
+  try {
+    names = execFileSync("git", ["config", "--name-only", "--get-regexp",
+      "^filter\\..*\\.(process|smudge|clean)$"], {
+      cwd: configRoot, encoding: "utf8", windowsHide: true,
+      timeout: 10_000, maxBuffer: 64 * 1024, stdio: ["ignore", "pipe", "ignore"],
+    });
+  } catch (error) {
+    if ((error as { status?: number }).status !== 1) {
+      throw new AgentFabricError("AF_INVALID_STATE", "Cannot inspect Git checkout filters");
+    }
+  }
+  const options = ["-c", `core.hooksPath=${hooksDir}`, "-c", "core.fsmonitor=false"];
+  for (const name of new Set(names.split(/\r?\n/u).filter(Boolean))) {
+    if (!/^filter\.[a-z0-9_.-]+\.(?:process|smudge|clean)$/iu.test(name)) {
+      throw new AgentFabricError("AF_INVALID_STATE", "Unsupported Git checkout filter setting");
+    }
+    options.push("-c", `${name}=`);
+  }
+  return options;
+}
+
+export function buildLocalCodingContext(repositoryRoot: string, task: Readonly<LocalCodingTaskProposal>): string {
+  const sources = task.sourcePaths.map((path) => ({
+    path,
+    content: git(repositoryRoot, ["show", `${task.baseCommit}:${path}`], task.limits.maximumContextBytes + 1),
+  }));
+  const content = JSON.stringify({ baseCommit: task.baseCommit, sources });
+  if (Buffer.byteLength(content, "utf8") > task.limits.maximumContextBytes) {
+    throw new AgentFabricError("AF_INVALID_STATE", "Pinned source context exceeds the approved byte limit");
+  }
+  return content;
+}
+
+/** Check the complete proposal before recording a successful result or a patch effect intent. */
+export function validateLocalCodingModelOutput(text: string, task: Readonly<LocalCodingTaskProposal>): readonly { path: string; content: string }[] {
+  if (Buffer.byteLength(text, "utf8") > task.limits.maximumPatchBytes) {
+    throw new AgentFabricError("AF_INVALID_STATE", "Model output exceeds the approved patch byte limit");
+  }
+  let parsed: unknown;
+  const fenced = /^```(?:json)?\r?\n([\s\S]*?)\r?\n```$/u.exec(text.trim());
+  try { parsed = JSON.parse(fenced ? fenced[1]! : text); } catch {
+    throw new AgentFabricError("AF_INVALID_STATE", "Model output is not strict JSON");
+  }
+  if (!parsed || typeof parsed !== "object") {
+    throw new AgentFabricError("AF_INVALID_STATE", "Model output is not a file proposal");
+  }
+  // Small local models sometimes emit the files array directly. Both forms
+  // undergo the same strict path, content, count, and size checks below.
+  const root = parsed as Record<string, unknown>;
+  const rootKeys = Object.keys(root).sort().join(",");
+  const fileMap = !Array.isArray(parsed) && rootKeys !== "files" &&
+    rootKeys !== "files,schemaVersion" && Object.keys(root).every((path) =>
+      task.writablePaths.includes(path) && typeof root[path] === "string");
+  const proposedFiles = Array.isArray(parsed) ? parsed : fileMap
+    ? Object.entries(root).map(([path, content]) => ({ path, content })) : root.files;
+  if ((!Array.isArray(parsed) && !fileMap &&
+      (rootKeys !== "files" &&
+       (rootKeys !== "files,schemaVersion" ||
+        (root.schemaVersion !== 1 && root.schemaVersion !== "1")))) ||
+      !Array.isArray(proposedFiles) || proposedFiles.length < 1 || proposedFiles.length > task.writablePaths.length) {
+    throw new AgentFabricError("AF_INVALID_STATE", "Model file proposal has unsupported structure");
+  }
+  const seen = new Set<string>();
+  return proposedFiles.map((item: unknown) => {
+    if (!item || typeof item !== "object" || Array.isArray(item)) {
+      throw new AgentFabricError("AF_INVALID_STATE", "Invalid model file proposal");
+    }
+    const file = item as Record<string, unknown>;
+    if (Object.keys(file).sort().join(",") !== "content,path" ||
+        typeof file.path !== "string" || !task.writablePaths.includes(file.path) ||
+        seen.has(file.path.toLowerCase()) || typeof file.content !== "string" ||
+        file.content.includes("\u0000")) {
+      throw new AgentFabricError("AF_INVALID_STATE", "Model proposed an unauthorized file or content");
+    }
+    seen.add(file.path.toLowerCase());
+    return { path: file.path, content: file.content };
+  });
+}
+
+function checkedTarget(worktreeRoot: string, path: string): string {
+  const target = resolve(worktreeRoot, path);
+  const prefix = `${worktreeRoot}${process.platform === "win32" ? "\\" : "/"}`;
+  if (!target.startsWith(prefix)) {
+    throw new AgentFabricError("AF_INVALID_STATE", "Model path escapes the isolated checkout");
+  }
+  let cursor = worktreeRoot;
+  for (const segment of path.split("/")) {
+    cursor = join(cursor, segment);
+    if (existsSync(cursor) && lstatSync(cursor).isSymbolicLink()) {
+      throw new AgentFabricError("AF_INVALID_STATE", "Model path traverses a symbolic link");
+    }
+  }
+  return target;
+}
+
+function syncParentDirectories(path: string, root: string): void {
+  // Directory fsync is supported on POSIX. Windows file flush persists the file
+  // itself; a missing directory entry after a crash remains a readback failure.
+  if (process.platform === "win32") return;
+  let directory = dirname(path);
+  while (directory.startsWith(`${root}/`) || directory === root) {
+    const fd = openSync(directory, "r");
+    try { fsyncSync(fd); } finally { closeSync(fd); }
+    if (directory === root) break;
+    directory = dirname(directory);
+  }
+}
+
+export interface LocalPatchEvidence {
+  worktreeRoot: string;
+  baseCommit: string;
+  changedPaths: readonly string[];
+  diffDigest: Digest;
+  diffBytes: number;
+  diffPath: string;
+  verification: "diff_check_passed" | "diff_check_failed";
+}
+
+/** Recheck the live checkout before showing or accepting its saved diff. */
+export function verifyLocalPatchEvidence(patch: LocalPatchEvidence): void {
+  const canonical = realpathSync(patch.worktreeRoot);
+  const checkoutRoot = realpathSync(git(canonical, ["rev-parse", "--show-toplevel"]).trim());
+  if (checkoutRoot !== canonical || git(canonical, ["rev-parse", "HEAD"]).trim() !== patch.baseCommit) {
+    throw new AgentFabricError("AF_CONFLICT", "Approved patch checkout moved from its recorded base");
+  }
+  if (git(canonical, ["diff", "--no-ext-diff", "--cached", "--binary"]).length > 0 ||
+      git(canonical, ["ls-files", "--others", "--exclude-standard"]).length > 0) {
+    throw new AgentFabricError("AF_CONFLICT", "Patch checkout has unrecorded files or staged changes");
+  }
+  const diff = git(canonical, ["diff", "--no-ext-diff", "--binary"], patch.diffBytes + 1);
+  if (sha256Digest(diff) !== patch.diffDigest ||
+      sha256Digest(readFileSync(patch.diffPath, "utf8")) !== patch.diffDigest) {
+    throw new AgentFabricError("AF_CONFLICT", "Live patch no longer matches its recorded diff");
+  }
+}
+
+/** Observe an interrupted materialization without creating a checkout or writing files. */
+export function readbackLocalCodingPatch(
+  repositoryRoot: string, taskId: string,
+  task: Readonly<LocalCodingTaskProposal>, modelText: string,
+): LocalPatchEvidence {
+  const files = validateLocalCodingModelOutput(modelText, task);
+  const worktreePath = localFabricPath(repositoryRoot, "worktrees", taskId.replace(/^task:/u, ""));
+  if (!existsSync(worktreePath)) throw new AgentFabricError("AF_CONFLICT", "Patch checkout was not materialized");
+  const worktreeRoot = realpathSync(worktreePath);
+  const normalized = (value: string) => process.platform === "win32" ? value.toLowerCase() : value;
+  if (normalized(realpathSync(git(worktreeRoot, ["rev-parse", "--show-toplevel"]).trim())) !== normalized(worktreeRoot) ||
+      git(worktreeRoot, ["rev-parse", "HEAD"]).trim() !== task.baseCommit) {
+    throw new AgentFabricError("AF_CONFLICT", "Patch checkout does not match its approved base");
+  }
+  for (const file of files) {
+    const target = checkedTarget(worktreeRoot, file.path);
+    if (!existsSync(target) || readFileSync(target, "utf8") !== file.content) {
+      throw new AgentFabricError("AF_CONFLICT", "Patch checkout differs from the committed model result");
+    }
+  }
+  if (git(worktreeRoot, ["diff", "--no-ext-diff", "--cached", "--binary"]).length > 0 ||
+      git(worktreeRoot, ["ls-files", "--others", "--exclude-standard"]).length > 0) {
+    throw new AgentFabricError("AF_CONFLICT", "Patch checkout has unrecorded files or staged changes");
+  }
+  const diff = git(worktreeRoot, ["diff", "--no-ext-diff", "--binary"], task.limits.maximumPatchBytes + 1);
+  const diffBytes = Buffer.byteLength(diff, "utf8");
+  if (diffBytes === 0 || diffBytes > task.limits.maximumPatchBytes) {
+    throw new AgentFabricError("AF_CONFLICT", "Patch readback is empty or exceeds the approved limit");
+  }
+  const changedPaths = git(worktreeRoot, ["diff", "--no-ext-diff", "--name-only"]).trim().split(/\r?\n/u).filter(Boolean);
+  if (changedPaths.length !== files.length ||
+      changedPaths.some((path) => !files.some((file) => file.path === path))) {
+    throw new AgentFabricError("AF_CONFLICT", "Patch readback changed an unauthorized path");
+  }
+  const diffPath = localFabricPath(repositoryRoot, "artifacts", `${taskId.replace(/^task:/u, "")}.diff`);
+  if (!existsSync(diffPath) || readFileSync(diffPath, "utf8") !== diff) {
+    throw new AgentFabricError("AF_CONFLICT", "Patch artifact is missing or differs from checkout");
+  }
+  let verification: LocalPatchEvidence["verification"] = "diff_check_passed";
+  try { git(worktreeRoot, ["diff", "--check"]); }
+  catch { verification = "diff_check_failed"; }
+  const patch: LocalPatchEvidence = { worktreeRoot, baseCommit: task.baseCommit,
+    changedPaths, diffDigest: sha256Digest(diff), diffBytes, diffPath, verification };
+  verifyLocalPatchEvidence(patch);
+  return patch;
+}
+
+/** Apply a model's file proposal only inside a fresh checkout of the pinned commit. */
+export function materializeLocalCodingPatch(
+  repositoryRoot: string,
+  taskId: string,
+  task: Readonly<LocalCodingTaskProposal>,
+  modelText: string,
+): LocalPatchEvidence {
+  const files = validateLocalCodingModelOutput(modelText, task);
+  const worktreeRoot = localFabricPath(repositoryRoot, "worktrees", taskId.replace(/^task:/u, ""));
+  const existing = existsSync(worktreeRoot);
+  if (!existing) {
+    mkdirSync(dirname(worktreeRoot), { recursive: true });
+    git(repositoryRoot, [...inertCheckoutOptions(repositoryRoot),
+      "worktree", "add", "--detach", "--no-checkout", "--", worktreeRoot, task.baseCommit]);
+    // Resolve includeIf and worktree-specific filter settings from the new
+    // worktree before any checkout reads untrusted repository content.
+    git(worktreeRoot, [...inertCheckoutOptions(repositoryRoot, worktreeRoot),
+      "reset", "--hard", task.baseCommit]);
+  }
+  const canonical = realpathSync(worktreeRoot);
+  const reportedRoot = realpathSync(git(canonical, ["rev-parse", "--show-toplevel"]).trim());
+  if ((process.platform === "win32" ? reportedRoot.toLowerCase() : reportedRoot) !==
+      (process.platform === "win32" ? canonical.toLowerCase() : canonical)) {
+    throw new AgentFabricError("AF_INVALID_STATE", "Isolated checkout root is not its own Git worktree");
+  }
+  if (git(canonical, ["rev-parse", "HEAD"]).trim() !== task.baseCommit) {
+    throw new AgentFabricError("AF_INVALID_STATE", "Isolated checkout is not at the approved base commit");
+  }
+  for (const file of files) {
+    const target = checkedTarget(canonical, file.path);
+    if (existing) {
+      if (!existsSync(target) || readFileSync(target, "utf8") !== file.content) {
+        throw new AgentFabricError("AF_CONFLICT", "Existing checkout differs from the recorded model result");
+      }
+    } else {
+      mkdirSync(dirname(target), { recursive: true });
+      writeFileSync(target, file.content, { flag: "w", flush: true });
+      syncParentDirectories(target, canonical);
+    }
+  }
+  git(canonical, [...inertCheckoutOptions(repositoryRoot, canonical),
+    "add", "-N", "--", ...files.map((file) => file.path)]);
+  const diff = git(canonical, ["diff", "--no-ext-diff", "--binary", "--", ...files.map((file) => file.path)],
+    task.limits.maximumPatchBytes + 1);
+  const diffBytes = Buffer.byteLength(diff, "utf8");
+  if (diffBytes === 0 || diffBytes > task.limits.maximumPatchBytes) {
+    throw new AgentFabricError("AF_INVALID_STATE", "Resulting diff is empty or exceeds the approved patch limit");
+  }
+  const changedPaths = git(canonical, ["diff", "--no-ext-diff", "--name-only", "--", ...files.map((file) => file.path)])
+    .trim().split(/\r?\n/u).filter(Boolean);
+  if (changedPaths.length === 0 || changedPaths.some((path) => !task.writablePaths.includes(path))) {
+    throw new AgentFabricError("AF_INVALID_STATE", "Resulting diff contains an unauthorized path");
+  }
+  const diffPath = localFabricPath(repositoryRoot, "artifacts", `${taskId.replace(/^task:/u, "")}.diff`);
+  mkdirSync(dirname(diffPath), { recursive: true });
+  if (existsSync(diffPath)) {
+    if (readFileSync(diffPath, "utf8") !== diff) {
+      throw new AgentFabricError("AF_CONFLICT", "Existing diff artifact differs from the model result");
+    }
+  } else {
+    writeFileSync(diffPath, diff, { flag: "wx", flush: true });
+    syncParentDirectories(diffPath, repositoryRoot);
+  }
+  if (sha256Digest(readFileSync(diffPath, "utf8")) !== sha256Digest(diff)) {
+    throw new AgentFabricError("AF_INVALID_STATE", "Diff artifact failed readback");
+  }
+  let verification: LocalPatchEvidence["verification"] = "diff_check_passed";
+  try {
+    git(canonical, ["diff", "--check", "--", ...files.map((file) => file.path)]);
+  } catch {
+    verification = "diff_check_failed";
+  }
+  const patch = { worktreeRoot: canonical, baseCommit: task.baseCommit, changedPaths,
+    diffDigest: sha256Digest(diff), diffBytes, diffPath, verification };
+  verifyLocalPatchEvidence(patch);
+  return patch;
+}

package/src/forge/agent-fabric/local-control-store.ts

@@ -0,0 +1,239 @@
+import type { DbAdapter } from "../runtime/db/adapter.ts";
+import { sha256Digest, stableStringify } from "./canonical.ts";
+import { AgentFabricError } from "./errors.ts";
+import { ForgeAgentConductor } from "./hardened-conductor.ts";
+import { MemoryControlJournal } from "./journal.ts";
+import { replayControlState } from "./hardened-reducer.ts";
+import { ResourceLedger } from "./resource-ledger.ts";
+import type {
+  Clock, ControlEventEnvelope, OwnerAuthorizationVerifier, ResourceDefinition,
+  UncommittedControlEvent,
+} from "./types.ts";
+
+const CREATE_EVENTS_TABLE = `
+  CREATE TABLE IF NOT EXISTS _forge_agent_fabric_control_events (
+    root_execution_id TEXT NOT NULL,
+    event_sequence INTEGER NOT NULL,
+    event_id TEXT NOT NULL,
+    idempotency_key TEXT,
+    envelope_json TEXT NOT NULL,
+    PRIMARY KEY (root_execution_id, event_sequence),
+    UNIQUE (root_execution_id, event_id),
+    UNIQUE (root_execution_id, idempotency_key)
+  )`;
+
+export interface LocalControlStoreOptions {
+  adapter: DbAdapter;
+  clock: Clock;
+  ownerAuthorizationVerifier: OwnerAuthorizationVerifier;
+  resourceDefinitions?: readonly ResourceDefinition[];
+}
+
+export interface LocalControlTransitionResult<T> {
+  result: T;
+  events: readonly ControlEventEnvelope[];
+}
+
+/**
+ * Single-process PGlite transaction boundary around the synchronous P0a Conductor.
+ * Only trusted server code may call transition; callbacks must have no external effects.
+ */
+export class LocalControlStore {
+  private tail: Promise<void> = Promise.resolve();
+  private readonly definitions: readonly ResourceDefinition[];
+  private schemaReady?: Promise<unknown>;
+  private closed = false;
+  private readonly externalRoots = new Set<string>();
+  private readonly externalRuns = new Set<Promise<unknown>>();
+
+  constructor(private readonly options: LocalControlStoreOptions) {
+    if (options.adapter.kind !== "pglite") {
+      throw new AgentFabricError("AF_INVALID_STATE", "Local control store requires the PGlite adapter");
+    }
+    this.definitions = structuredClone(options.resourceDefinitions ?? []);
+  }
+
+  private async serialized<T>(operation: () => Promise<T>): Promise<T> {
+    if (this.closed) throw new AgentFabricError("AF_INVALID_STATE", "Local control store is closed");
+    const predecessor = this.tail;
+    let release!: () => void;
+    this.tail = new Promise<void>((resolve) => { release = resolve; });
+    await predecessor;
+    try {
+      this.schemaReady ??= this.options.adapter.query(CREATE_EVENTS_TABLE);
+      await this.schemaReady;
+      return await operation();
+    } finally {
+      release();
+    }
+  }
+
+  private async load(rootExecutionId: string): Promise<ControlEventEnvelope[]> {
+    if (!rootExecutionId || rootExecutionId.length > 128) {
+      throw new AgentFabricError("AF_INVALID_STATE", "Invalid root execution identity");
+    }
+    const result = await this.options.adapter.query(
+      `SELECT event_sequence, envelope_json FROM _forge_agent_fabric_control_events
+       WHERE root_execution_id = $1 ORDER BY event_sequence`,
+      [rootExecutionId],
+    );
+    const events: ControlEventEnvelope[] = [];
+    for (const row of result.rows) {
+      if (typeof row.envelope_json !== "string") {
+        throw new AgentFabricError("AF_INVALID_EVENT", "Stored control envelope is missing");
+      }
+      let event: ControlEventEnvelope;
+      try {
+        event = JSON.parse(row.envelope_json) as ControlEventEnvelope;
+      } catch {
+        throw new AgentFabricError("AF_INVALID_EVENT", "Stored control envelope is not JSON");
+      }
+      if (!event || typeof event !== "object" ||
+          event.rootExecutionId !== rootExecutionId || event.sequence !== row.event_sequence) {
+        throw new AgentFabricError("AF_INVALID_EVENT", "Stored control envelope is outside its stream");
+      }
+      events.push(event);
+    }
+    replayControlState(events, {
+      ownerAuthorizationVerifier: this.options.ownerAuthorizationVerifier,
+      resourceDefinitions: this.definitions,
+    });
+    return events;
+  }
+
+  async readAll(rootExecutionId: string): Promise<readonly ControlEventEnvelope[]> {
+    return this.serialized(async () => structuredClone(await this.load(rootExecutionId)));
+  }
+
+  private hydrate(rootExecutionId: string, before: readonly ControlEventEnvelope[]): {
+    journal: MemoryControlJournal;
+    conductor: ForgeAgentConductor;
+  } {
+    const journal = new MemoryControlJournal();
+    for (const stored of before) {
+      const {
+        sequence: _sequence,
+        predecessorEventId: _predecessorEventId,
+        predecessorEventDigest: _predecessorEventDigest,
+        eventDigest: _eventDigest,
+        ...uncommitted
+      } = stored;
+      const restored = journal.append({
+        expectedSequence: journal.readAll().length,
+        event: uncommitted as UncommittedControlEvent,
+      });
+      if (stableStringify(restored) !== stableStringify(stored)) {
+        throw new AgentFabricError("AF_INVALID_EVENT", "Stored control event changed during hydration");
+      }
+    }
+    const ledger = this.definitions.length > 0
+      ? new ResourceLedger(this.definitions)
+      : undefined;
+    return {
+      journal,
+      conductor: new ForgeAgentConductor(
+        rootExecutionId, journal, this.options.clock, sha256Digest,
+        this.options.ownerAuthorizationVerifier, ledger,
+      ),
+    };
+  }
+
+  private async persist(rootExecutionId: string, beforeCount: number, additions: readonly ControlEventEnvelope[]): Promise<void> {
+    if (additions.length === 0) return;
+    const transaction = await this.options.adapter.begin();
+    try {
+      const cursor = await transaction.query(
+        `SELECT COALESCE(MAX(event_sequence), 0) AS current_sequence
+         FROM _forge_agent_fabric_control_events WHERE root_execution_id = $1`,
+        [rootExecutionId],
+      );
+      if (Number(cursor.rows[0]?.current_sequence) !== beforeCount) {
+        throw new AgentFabricError("AF_CONFLICT", "Local control journal compare-and-swap failed");
+      }
+      for (const event of additions) {
+        await transaction.query(
+          `INSERT INTO _forge_agent_fabric_control_events
+           (root_execution_id, event_sequence, event_id, idempotency_key, envelope_json)
+           VALUES ($1, $2, $3, $4, $5)`,
+          [rootExecutionId, event.sequence, event.eventId, event.idempotencyKey ?? null,
+            stableStringify(event)],
+        );
+      }
+      await transaction.commit();
+    } catch (error) {
+      await transaction.rollback().catch(() => undefined);
+      throw error;
+    }
+  }
+
+  async transition<T>(
+    rootExecutionId: string,
+    operation: (conductor: ForgeAgentConductor) => T,
+  ): Promise<LocalControlTransitionResult<T>> {
+    return this.serialized(async () => {
+      if (this.externalRoots.has(rootExecutionId)) {
+        throw new AgentFabricError("AF_CONFLICT", "External attempt is still in flight for this root");
+      }
+      const before = await this.load(rootExecutionId);
+      const { journal, conductor } = this.hydrate(rootExecutionId, before);
+      const result = operation(conductor);
+      if (result && typeof result === "object" && "then" in result) {
+        throw new AgentFabricError("AF_INVALID_STATE", "Control transitions must be synchronous");
+      }
+      const after = journal.readAll();
+      const additions = after.slice(before.length);
+      await this.persist(rootExecutionId, before.length, additions);
+      return { result, events: after };
+    });
+  }
+
+  /**
+   * Keep one external attempt per root while releasing the database writer
+   * lock for the model call. The permit is committed in a prior transition.
+   * A crash leaves it without an outcome, which recovery classifies as uncertain.
+   */
+  async runExternal<T>(
+    rootExecutionId: string,
+    operation: (conductor: ForgeAgentConductor) => Promise<T>,
+  ): Promise<LocalControlTransitionResult<T>> {
+    const prepared = await this.serialized(async () => {
+      if (this.externalRoots.has(rootExecutionId)) {
+        throw new AgentFabricError("AF_CONFLICT", "External attempt is already in flight for this root");
+      }
+      const before = await this.load(rootExecutionId);
+      const { journal, conductor } = this.hydrate(rootExecutionId, before);
+      this.externalRoots.add(rootExecutionId);
+      return { before, journal, conductor };
+    });
+    // No database transaction or writer lock remains open around the model call.
+    // A status read can therefore see only a committed journal prefix.
+    const execution = (async (): Promise<LocalControlTransitionResult<T>> => {
+      let result: T | undefined;
+      let failure: unknown;
+      try {
+        result = await operation(prepared.conductor);
+      } catch (error) {
+        failure = error;
+      }
+      const after = await this.serialized(async () => {
+        const events = prepared.journal.readAll();
+        await this.persist(rootExecutionId, prepared.before.length, events.slice(prepared.before.length));
+        return events;
+      });
+      if (failure !== undefined) throw failure;
+      return { result: result as T, events: after };
+    })();
+    this.externalRuns.add(execution);
+    try { return await execution; } finally {
+      this.externalRuns.delete(execution);
+      this.externalRoots.delete(rootExecutionId);
+    }
+  }
+
+  async close(): Promise<void> {
+    await Promise.allSettled([...this.externalRuns]);
+    this.closed = true;
+    await this.tail;
+    await this.options.adapter.close();
+  }
+}