machine-bridge-mcp 2.0.0 → 3.0.0-beta.102

package/src/local/filesystem-identity.mjs

@@ -0,0 +1,54 @@
+// @ts-check
+
+/**
+ * Convert filesystem identity fields without allowing IEEE-754 rounding to make distinct
+ * platform identifiers compare equal. BigInt observations are preferred; injected Number
+ * observations remain supported only when exactly representable. When the platform
+ * exposes a change-time generation, retain it so immediate inode reuse cannot create an
+ * ABA-equivalent identity during destructive snapshot checks.
+ * @param {unknown} info
+ * @param {string} [label]
+ */
+export function filesystemIdentity(info, label = "filesystem entry") {
+  if (!info || typeof info !== "object") throw new Error(`${label} identity is unavailable`);
+  const record = /** @type {Record<string, unknown>} */ (info);
+  const generation = filesystemGeneration(record, label);
+  return Object.freeze({
+    dev: exactFilesystemInteger(record.dev, `${label} device`),
+    ino: exactFilesystemInteger(record.ino, `${label} inode`),
+    ...generation,
+  });
+}
+/** @param {{dev: bigint, ino: bigint, ctimeNs?: bigint, ctimeMs?: number} | null | undefined} left @param {{dev: bigint, ino: bigint, ctimeNs?: bigint, ctimeMs?: number} | null | undefined} right */
+export function sameFilesystemIdentity(left, right) {
+  if (!left || !right || left.dev !== right.dev || left.ino !== right.ino) return false;
+  if (left.ctimeNs !== undefined || right.ctimeNs !== undefined) return left.ctimeNs !== undefined && left.ctimeNs === right.ctimeNs;
+  if (left.ctimeMs !== undefined || right.ctimeMs !== undefined) return left.ctimeMs !== undefined && left.ctimeMs === right.ctimeMs;
+  return true;
+}
+/** @param {Record<string, unknown>} record @param {string} label */
+function filesystemGeneration(record, label) {
+  if (record.ctimeNs !== undefined) return { ctimeNs: exactFilesystemInteger(record.ctimeNs, `${label} change time`) };
+  if (record.ctimeMs !== undefined) return { ctimeMs: filesystemTimeMs(record.ctimeMs, `${label} change time`) };
+  return {};
+}
+
+/** @param {unknown} value @param {string} label */
+export function exactFilesystemInteger(value, label) {
+  if (typeof value === "bigint") {
+    if (value < 0n) throw new Error(`${label} is invalid`);
+    return value;
+  }
+  if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0) return BigInt(value);
+  throw new Error(`${label} cannot be represented losslessly`);
+}
+
+/** @param {unknown} value @param {string} label */
+export function filesystemTimeMs(value, label) {
+  if (typeof value === "bigint") {
+    if (value < 0n || value > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error(`${label} cannot be represented safely`);
+    return Number(value);
+  }
+  if (typeof value === "number" && Number.isFinite(value) && value >= 0) return value;
+  throw new Error(`${label} is invalid`);
+}

package/src/local/fixed-process-environment.mjs

@@ -0,0 +1,21 @@
+// @ts-check
+import { BridgeError } from "./errors.mjs";
+/** @type {Readonly<Record<string, string>>} */
+export const STRUCTURED_GIT_FIXED_ENVIRONMENT = Object.freeze({
+  GIT_OPTIONAL_LOCKS: "0", GIT_CONFIG_NOSYSTEM: "1", GIT_ATTR_NOSYSTEM: "1", GIT_NO_LAZY_FETCH: "1", GIT_TERMINAL_PROMPT: "0",
+});
+/** @param {unknown} value @returns {Readonly<Record<string, string>>} */
+export function validateFixedProcessEnvironment(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new BridgeError("invalid_request", "internal process environment must be an object");
+  }
+  /** @type {Record<string, string>} */
+  const normalized = Object.create(null);
+  for (const [key, raw] of Object.entries(value)) {
+    if (!Object.hasOwn(STRUCTURED_GIT_FIXED_ENVIRONMENT, key) || raw !== STRUCTURED_GIT_FIXED_ENVIRONMENT[key]) {
+      throw new BridgeError("invalid_request", "internal process environment override is not approved");
+    }
+    normalized[key] = raw;
+  }
+  return Object.freeze(normalized);
+}

package/src/local/full-access-test.mjs

@@ -4,17 +4,15 @@ import { join, resolve } from "node:path";
 import process from "node:process";
 import { createMonotonicDeadline } from "./monotonic-deadline.mjs";
 import { LocalRuntime } from "./runtime.mjs";
+import { isTerminalManagedJobStatus } from "./managed-job-terminal.mjs";
 import { generateSshKeyPair } from "./ssh-key.mjs";
 import { runExecutable } from "./shell.mjs";
 import { allToolNames, assertCanonicalFullPolicy, policyProfile } from "./tools.mjs";
+const FULL_ACCESS_RESOURCE_WAIT_MS = 10_000;
+const FULL_ACCESS_JOB_WAIT_MS = 5 * 60_000;
+const FULL_ACCESS_JOB_CLEANUP_WAIT_MS = 30_000;
 
-const TERMINAL_JOB_STATES = new Set([
-  "succeeded", "failed", "cancelled", "runner_failed", "runner_launch_failed",
-  "recovery_failed", "recovery_exhausted", "succeeded_cleanup_failed",
-  "failed_cleanup_failed", "cancelled_cleanup_failed",
-]);
-
-export async function runFullAccessTest({ workspace, policy = policyProfile("full", "explicit") } = {}) {
+export async function runFullAccessTest({ workspace, policy = policyProfile("full", "explicit"), resourceCoordinatorOptions = null } = {}) {
   const canonicalPolicy = assertCanonicalFullPolicy(policy);
   const root = await mkdtemp(join(tmpdir(), "machine-mcp-full-test-"));
   const jobRoot = join(root, "jobs");
@@ -28,6 +26,8 @@ export async function runFullAccessTest({ workspace, policy = policyProfile("ful
   const previousSentinel = process.env[sentinelKey];
   process.env[sentinelKey] = "visible";
   let runtime;
+  let unsettledJobId = "";
+  let removeRoot = true;
 
   try {
     runtime = new LocalRuntime({
@@ -37,6 +37,9 @@ export async function runFullAccessTest({ workspace, policy = policyProfile("ful
       resources: {},
       logger: silentLogger(),
       recoverJobs: false,
+      resourceCoordinatorRoot: join(root, "resource-coordinator"),
+      resourceCoordinatorOptions,
+      processResourceWaitMs: FULL_ACCESS_RESOURCE_WAIT_MS,
     });
 
     const toolNames = runtime.tools();
@@ -68,7 +71,7 @@ export async function runFullAccessTest({ workspace, policy = policyProfile("ful
     checks.push(check("full-parent-environment", inherited.code === 0 && inherited.stdout === "visible"));
 
     const shellCommand = process.platform === "win32" ? "[Console]::Out.Write('full-shell')" : "printf full-shell";
-    const shell = await runtime.execCommand(shellCommand, 10);
+    const shell = await runtime.execCommand({ command: shellCommand, timeout_seconds: 10 });
     checks.push(check("shell-execution", shell.code === 0 && shell.stdout.trim() === "full-shell"));
 
     const key = await generateSshKeyPair({
@@ -141,7 +144,9 @@ export async function runFullAccessTest({ workspace, policy = policyProfile("ful
       steps: [{ argv: [process.execPath, "{{temp:main.js}}", mainMarker], timeout_seconds: 10 }],
       finally_steps: [{ argv: [process.execPath, "-e", "require('node:fs').writeFileSync(process.argv[1],'cleanup')", cleanupMarker], timeout_seconds: 10 }],
     });
-    const job = await waitForJob(runtime.managedJobManager, accepted.job_id, 15_000);
+    unsettledJobId = accepted.job_id;
+    const job = await waitForJob(runtime.managedJobManager, accepted.job_id, FULL_ACCESS_JOB_WAIT_MS);
+    unsettledJobId = "";
     checks.push(check("detached-managed-job", job.status === "succeeded"
       && await fileEquals(mainMarker, "main")
       && await fileEquals(cleanupMarker, "cleanup"), {
@@ -171,21 +176,34 @@ export async function runFullAccessTest({ workspace, policy = policyProfile("ful
       },
     };
   } finally {
-    runtime?.stop();
+    if (runtime && unsettledJobId) {
+      try {
+        const status = runtime.managedJobManager.read({ job_id: unsettledJobId });
+        if (!isTerminalManagedJobStatus(status.status)) {
+          runtime.managedJobManager.cancel({ job_id: unsettledJobId });
+          await waitForJob(runtime.managedJobManager, unsettledJobId, FULL_ACCESS_JOB_CLEANUP_WAIT_MS);
+        }
+      } catch {
+        removeRoot = false;
+      }
+    }
+    await runtime?.stop();
     if (previousSentinel === undefined) delete process.env[sentinelKey];
     else process.env[sentinelKey] = previousSentinel;
-    await rm(root, { recursive: true, force: true });
+    if (removeRoot) await rm(root, { recursive: true, force: true });
   }
 }
 
 async function waitForJob(manager, jobId, timeoutMs) {
   const deadline = createMonotonicDeadline(timeoutMs);
+  let lastStatus = "unknown";
   while (!deadline.expired()) {
     const value = manager.read({ job_id: jobId });
-    if (TERMINAL_JOB_STATES.has(value.status)) return value;
+    lastStatus = String(value.status || "unknown");
+    if (isTerminalManagedJobStatus(value.status)) return value;
     await new Promise((resolvePromise) => { setTimeout(resolvePromise, 50); });
   }
-  throw new Error("full access managed-job test timed out");
+  throw new Error(`full access managed-job test timed out while status=${lastStatus}`);
 }
 
 async function equivalentPath(left, right) {

package/src/local/git-commit.mjs

@@ -0,0 +1,69 @@
+import { BridgeError } from "./errors.mjs";
+import { assertStructuredGitCommitStateClear } from "./git-operation-state.mjs";
+
+const GIT_HASH = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+
+export async function createStructuredGitCommit({ git, message, disabledHooksPath, runInternalProcess, gitExecutable, context = {}, environment = {} }) {
+  const base = [
+    "--no-pager",
+    `--git-dir=${git.gitDir}`,
+    `--work-tree=${git.root}`,
+    "-c", "core.fsmonitor=false",
+    "-c", "color.ui=false",
+    "-c", `core.hooksPath=${disabledHooksPath}`,
+    "-c", "commit.gpgSign=false",
+  ];
+  const run = (args, stdin = null) => runInternalProcess(
+    gitExecutable(), [...base, ...args], 60_000, true, 64 * 1024, context, git.root, stdin, environment,
+  );
+
+  await assertStructuredGitCommitStateClear(git.gitDir);
+  const treeResult = await run(["write-tree"]);
+  const tree = requireHash(treeResult, "Git staged index could not be written");
+
+  const headResult = await run(["rev-parse", "--verify", "HEAD^{commit}"]);
+  let oldHead = "";
+  if (headResult.code === 0) oldHead = requireHash(headResult, "Git HEAD is invalid");
+
+  const symbolic = await run(["symbolic-ref", "-q", "HEAD"]);
+  if (symbolic.code !== 0 && symbolic.code !== 1) throw commitFailure("Git HEAD could not be resolved", symbolic.code);
+  const symbolicRef = symbolic.code === 0 ? String(symbolic.stdout || "").trim() : "";
+  if (symbolicRef) {
+    const refValidation = await run(["check-ref-format", symbolicRef]);
+    if (refValidation.code !== 0) throw commitFailure("Git HEAD reference is invalid", refValidation.code);
+  }
+  if (!oldHead && !symbolicRef) throw commitFailure("Git repository has no commit parent or branch reference", headResult.code);
+
+  if (oldHead) {
+    const headTreeResult = await run(["rev-parse", "--verify", "HEAD^{tree}"]);
+    const headTree = requireHash(headTreeResult, "Git HEAD tree is invalid");
+    if (headTree === tree) throw commitFailure("Git staged index has no changes to commit", 1, "git_commit_empty");
+  }
+
+  const commitArgs = ["commit-tree", tree];
+  if (oldHead) commitArgs.push("-p", oldHead);
+  commitArgs.push("-F", "-");
+  const commitResult = await run(commitArgs, message);
+  const commit = requireHash(commitResult, "Git commit object could not be created");
+
+  const targetRef = symbolicRef || "HEAD";
+  const expected = oldHead || "0".repeat(tree.length);
+  const updateResult = await run(["update-ref", "-m", "machine-bridge-mcp structured commit", targetRef, commit, expected]);
+  if (updateResult.code !== 0) {
+    throw commitFailure("Git history changed concurrently or the reference update failed", updateResult.code, "git_commit_conflict");
+  }
+  return Object.freeze({ committed: true });
+}
+
+function requireHash(result, message) {
+  if (result.code !== 0) throw commitFailure(message, result.code);
+  const value = String(result.stdout || "").trim();
+  if (!GIT_HASH.test(value)) throw commitFailure(message, result.code);
+  return value;
+}
+
+function commitFailure(message, code, reason = "git_commit_failed") {
+  return new BridgeError("execution_failed", message, {
+    details: { reason, code: Number.isInteger(code) ? code : 1 },
+  });
+}

package/src/local/git-config-safety.mjs

@@ -0,0 +1,55 @@
+import { join } from "node:path";
+import { BridgeError } from "./errors.mjs";
+import { pathEntryIfExists } from "./path-inspection.mjs";
+
+const MAX_GIT_CONFIG_BYTES = 256 * 1024;
+
+export async function assertStructuredGitConfigSafe({
+  git,
+  inspectWorkingTree = false,
+  resolveExistingPath,
+  runInternalProcess,
+  gitExecutable,
+  context = {},
+  environment = {},
+}) {
+  const files = new Set([join(git.commonDir, "config"), join(git.gitDir, "config.worktree")]);
+  for (const file of files) {
+    const entry = await pathEntryIfExists(file);
+    if (!entry) continue;
+    if (entry.isSymbolicLink() || !entry.isFile() || Number(entry.nlink) !== 1 || Number(entry.size) > MAX_GIT_CONFIG_BYTES) {
+      throw unsafeConfigError();
+    }
+    const canonical = await resolveExistingPath(file, context);
+    const result = await runInternalProcess(
+      gitExecutable(),
+      ["--no-pager", "config", "--file", canonical, "--no-includes", "--null", "--name-only", "--list"],
+      10_000,
+      true,
+      MAX_GIT_CONFIG_BYTES,
+      context,
+      git.root,
+      null,
+      environment,
+    );
+    if (result.code !== 0) throw unsafeConfigError();
+    const keys = String(result.stdout || "").split("\0").map((value) => value.trim().toLowerCase()).filter(Boolean);
+    if (keys.some((key) => key.startsWith("include.") || key.startsWith("includeif.") || key === "core.attributesfile" || key === "diff.orderfile"
+      || key === "extensions.partialclone" || /^remote\..+\.(?:promisor|partialclonefilter)$/.test(key))) {
+      throw unsafeConfigError();
+    }
+    if (inspectWorkingTree && keys.some((key) => key === "core.excludesfile" || executableFilterKey(key))) {
+      throw unsafeConfigError();
+    }
+  }
+}
+
+function executableFilterKey(key) {
+  return /^filter\..+\.(?:clean|smudge|process)$/.test(key);
+}
+
+function unsafeConfigError() {
+  return new BridgeError("authorization_denied", "repository Git configuration is incompatible with the structured Git safety boundary", {
+    details: { reason: "unsafe_repository_git_config" },
+  });
+}

package/src/local/git-log-parser.mjs

@@ -0,0 +1,41 @@
+// @ts-check
+
+import { BridgeError } from "./errors.mjs";
+
+const FULL_HASH = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+const SHORT_HASH = /^[0-9a-f]{4,64}$/;
+
+/** @param {unknown} stdout @param {boolean} [includeAuthorEmail] */
+export function parseStructuredGitLog(stdout, includeAuthorEmail = false) {
+  /** @type {Array<{hash: string, short: string, authored_at: string, author_name: string, subject: string, author_email?: string}>} */
+  const commits = [];
+  const records = String(stdout || "").split("\x1e");
+  for (let raw of records) {
+    if (!raw) continue;
+    if (raw === "\n" || raw === "\r\n") continue;
+    if (raw.startsWith("\r\n")) raw = raw.slice(2);
+    else if (raw.startsWith("\n")) raw = raw.slice(1);
+    if (!raw) continue;
+    const fields = raw.split("\x1f");
+    if (fields.length !== 6) throw parseError();
+    const [hash, short, authored_at, author_name, author_email, subject] = fields;
+    if (!FULL_HASH.test(hash) || !SHORT_HASH.test(short) || !validIsoDate(authored_at)) throw parseError();
+    /** @type {{hash: string, short: string, authored_at: string, author_name: string, subject: string, author_email?: string}} */
+    const commit = { hash, short, authored_at, author_name, subject };
+    if (includeAuthorEmail) commit.author_email = author_email;
+    commits.push(commit);
+  }
+  return commits;
+}
+
+/** @param {string} value */
+function validIsoDate(value) {
+  return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:[+-]\d{2}:\d{2}|Z)$/.test(value)
+    && Number.isFinite(Date.parse(value));
+}
+
+function parseError() {
+  return new BridgeError("execution_failed", "Git log output failed structured framing validation", {
+    details: { reason: "git_log_parse_failed" },
+  });
+}

package/src/local/git-metadata-boundary.mjs

@@ -0,0 +1,77 @@
+import { stat } from "node:fs/promises";
+import { isAbsolute, join, resolve } from "node:path";
+import { BridgeError } from "./errors.mjs";
+import { pathEntryIfExists } from "./path-inspection.mjs";
+import { readBoundedRegularFileSync } from "./secure-file.mjs";
+
+const MAX_ALTERNATES_BYTES = 64 * 1024;
+const MAX_ALTERNATE_STORES = 64;
+
+export async function resolveGitMetadataBoundary({ gitDir, commonDir, resolveExistingPath, context = {} }) {
+  const objectDir = await requireDirectory(join(commonDir, "objects"), resolveExistingPath, context, "Git object directory");
+  const alternateObjectDirs = await resolveAlternateObjectStores(objectDir, resolveExistingPath, context);
+  const metadataPaths = [];
+  for (const candidate of [
+    join(gitDir, "HEAD"),
+    join(gitDir, "index"),
+    join(gitDir, "refs"),
+    join(gitDir, "logs"),
+    join(gitDir, "reftable"),
+    join(commonDir, "packed-refs"),
+    join(commonDir, "shallow"),
+    join(commonDir, "refs"),
+    join(commonDir, "logs"),
+    join(commonDir, "reftable"),
+    join(commonDir, "info"),
+    join(objectDir, "pack"),
+    join(objectDir, "info"),
+  ]) {
+    const entry = await pathEntryIfExists(candidate);
+    if (!entry) continue;
+    if (entry.isSymbolicLink()) throw boundaryError("Git metadata path must not be a symbolic link");
+    metadataPaths.push(await resolveExistingPath(candidate, context));
+  }
+  return Object.freeze({ objectDir, alternateObjectDirs: Object.freeze(alternateObjectDirs), metadataPaths: Object.freeze(metadataPaths) });
+}
+
+async function resolveAlternateObjectStores(primaryObjectDir, resolveExistingPath, context) {
+  const queue = [primaryObjectDir];
+  const seen = new Set([primaryObjectDir]);
+  const alternates = [];
+  while (queue.length) {
+    const objectDir = queue.shift();
+    const marker = join(objectDir, "info", "alternates");
+    const entry = await pathEntryIfExists(marker);
+    if (!entry) continue;
+    if (entry.isSymbolicLink() || !entry.isFile() || Number(entry.nlink) !== 1) throw boundaryError("Git alternates metadata must be a single-link regular file");
+    const bytes = readBoundedRegularFileSync(marker, MAX_ALTERNATES_BYTES, "Git alternates metadata", {
+      verifyPathIdentity: true,
+      rejectMultipleLinks: true,
+    });
+    const text = bytes.toString("utf8");
+    if (text.includes("\0") || text.includes("\r")) throw boundaryError("Git alternates metadata is invalid");
+    for (const raw of text.split("\n")) {
+      if (!raw) continue;
+      if (raw.length > 4096 || /[\u0000-\u001f\u007f]/.test(raw)) throw boundaryError("Git alternate object path is invalid");
+      const candidate = isAbsolute(raw) ? raw : resolve(objectDir, raw);
+      const canonical = await requireDirectory(candidate, resolveExistingPath, context, "Git alternate object directory");
+      if (seen.has(canonical)) continue;
+      if (seen.size >= MAX_ALTERNATE_STORES) throw new BridgeError("limit_exceeded", `Git alternate object store count exceeds ${MAX_ALTERNATE_STORES}`);
+      seen.add(canonical);
+      alternates.push(canonical);
+      queue.push(canonical);
+    }
+  }
+  return alternates;
+}
+
+async function requireDirectory(path, resolveExistingPath, context, label) {
+  const canonical = await resolveExistingPath(path, context);
+  const info = await stat(canonical);
+  if (!info.isDirectory()) throw boundaryError(`${label} is unavailable`);
+  return canonical;
+}
+
+function boundaryError(message) {
+  return new BridgeError("path_boundary", message, { details: { reason: "git_metadata_boundary" } });
+}

package/src/local/git-metadata-tree-safety.mjs

@@ -0,0 +1,59 @@
+// @ts-check
+import { lstat, opendir } from "node:fs/promises";
+import { join } from "node:path";
+import { BridgeError } from "./errors.mjs";
+export const MAX_GIT_METADATA_ENTRIES = 1_000_000;
+export const MAX_GIT_METADATA_DEPTH = 64;
+
+/**
+ * @param {string[]} roots
+ * @param {{opendir?: typeof opendir, lstat?: typeof lstat, maximumEntries?: number, signal?: AbortSignal}} [options]
+ */
+export async function assertGitMetadataTreesSafe(roots, options = {}) {
+  const openDirectory = options.opendir || opendir;
+  const inspect = options.lstat || lstat;
+  const maximumEntries = Number(options.maximumEntries ?? MAX_GIT_METADATA_ENTRIES);
+  if (!Number.isSafeInteger(maximumEntries) || maximumEntries < 1) throw new TypeError("Git metadata entry limit must be a positive safe integer");
+  /** @type {Array<{path: string, depth: number}>} */
+  const queue = [];
+  for (const path of new Set(roots.map(String))) {
+    abortIfNeeded(options.signal);
+    const info = await inspect(path);
+    if (info.isSymbolicLink()) throw boundaryError();
+    if (info.isFile()) continue;
+    if (!info.isDirectory()) throw boundaryError();
+    queue.push({ path, depth: 0 });
+  }
+  let visited = 0;
+  for (let index = 0; index < queue.length; index += 1) {
+    abortIfNeeded(options.signal);
+    const current = queue[index];
+    const directory = await openDirectory(current.path);
+    try {
+      for await (const entry of directory) {
+        abortIfNeeded(options.signal);
+        visited += 1;
+        if (visited > maximumEntries) throw new BridgeError("limit_exceeded", `Git metadata entry count exceeds ${maximumEntries}`);
+        const target = join(current.path, entry.name);
+        if (entry.isSymbolicLink()) throw boundaryError();
+        if (entry.isDirectory()) {
+          if (current.depth >= MAX_GIT_METADATA_DEPTH) throw new BridgeError("limit_exceeded", `Git metadata depth exceeds ${MAX_GIT_METADATA_DEPTH}`);
+          queue.push({ path: target, depth: current.depth + 1 });
+          continue;
+        }
+        if (entry.isFile()) continue;
+        const info = await inspect(target);
+        if (info.isSymbolicLink() || !info.isFile()) throw boundaryError();
+      }
+    } finally { await directory.close().catch(() => { /* Directory-handle close is best-effort after bounded traversal ends. */ }); }
+  }
+  return visited;
+}
+
+/** @param {AbortSignal | undefined} signal */
+function abortIfNeeded(signal) { if (signal?.aborted) throw signal.reason instanceof Error ? signal.reason : new BridgeError("cancelled", "Git metadata inspection cancelled"); }
+function boundaryError() {
+  return new BridgeError("path_boundary", "Git metadata tree contains a symbolic link or special file", {
+    details: { reason: "git_metadata_boundary" },
+  });
+}

package/src/local/git-operation-state.mjs

@@ -0,0 +1,19 @@
+// @ts-check
+
+import { join } from "node:path";
+import { BridgeError } from "./errors.mjs";
+import { pathEntryIfExists } from "./path-inspection.mjs";
+
+const IN_PROGRESS_HISTORY_MARKERS = Object.freeze([
+  "MERGE_HEAD", "CHERRY_PICK_HEAD", "REVERT_HEAD", "REBASE_HEAD", "BISECT_START", "rebase-apply", "rebase-merge", "sequencer",
+]);
+
+/** @param {string} gitDir */
+export async function assertStructuredGitCommitStateClear(gitDir) {
+  for (const marker of IN_PROGRESS_HISTORY_MARKERS) {
+    if (!await pathEntryIfExists(join(gitDir, marker))) continue;
+    throw new BridgeError("execution_failed", "Git commit is unavailable while a merge, rebase, cherry-pick, revert, or bisect operation is in progress", {
+      details: { reason: "git_commit_repository_state", code: 1 },
+    });
+  }
+}