@link-assistant/hive-mind 2.13.4 → 2.14.0

package/src/formal-ai-sidecar.lib.mjs

@@ -43,18 +43,23 @@
 
 import { execFile } from 'node:child_process';
 import fs from 'node:fs';
-import path from 'node:path';
 import { promisify } from 'node:util';
 
 import { FORMAL_AI_MINIMUM_VERSION, isFormalAiVersionAtLeast } from './formal-ai-version.lib.mjs';
 import { ensureFormalAiSidecarImage, resolveFormalAiSidecarImage } from './formal-ai-image.lib.mjs';
 import { isFormalAiModel } from './formal-ai-model.lib.mjs';
 import { getModelFromArgs } from './model-args.lib.mjs';
-import { resolveBotStateDir } from './session-store.lib.mjs';
 import { withStateLock } from './state-lock.lib.mjs';
+import { attachDockerNetwork, DEFAULT_IMAGE_TIMEOUT_MS, dockerOk, dockerText, ensureDockerVolume, ensureInternalDockerNetwork, inspectDockerContainer, readDockerContainerAddress, readDockerImageDigest, readSidecarState, reconcileSidecarLeases, resolveSidecarStatePath, sleep, writeSidecarState } from './docker-sidecar.lib.mjs';
 
 const execFileAsync = promisify(execFile);
 
+// Re-exported because callers of this module have always imported them from
+// here; the implementations now live in the shared sidecar module.
+export { inspectDockerContainer, readDockerImageDigest };
+
+const LOG_PREFIX = 'formal-ai-sidecar';
+
 /** Container, network, volume and alias names. Stable so reconciliation works across restarts. */
 export const FORMAL_AI_SIDECAR_CONTAINER_NAME = 'hive-mind-formal-ai';
 export const FORMAL_AI_SIDECAR_NETWORK_NAME = 'hive-mind-formal-ai';
@@ -92,17 +97,13 @@ export const FORMAL_AI_SIDECAR_LABEL = 'com.link-assistant.hive-mind.formal-ai';
 
 const STATE_FILE_NAME = 'formal-ai-sidecar.json';
 const SIDECAR_LOCK_NAME = 'formal-ai-sidecar';
-const DEFAULT_DOCKER_TIMEOUT_MS = 120_000;
 // Pulling a sidecar image is the one Docker call that legitimately takes many
 // minutes, so it gets its own budget instead of the general command timeout.
-const DEFAULT_IMAGE_TIMEOUT_MS = 600_000;
 const DEFAULT_HEALTH_ATTEMPTS = 60;
 const DEFAULT_HEALTH_DELAY_MS = 1000;
 
 const EMPTY_STATE = Object.freeze({ version: 1, image: null, imageDigest: null, startedAt: null, leases: [], lastUpdate: null });
 
-const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
-
 /**
  * True when a task will be driven by Formal AI.
  *
@@ -149,27 +150,13 @@ export const isFormalAiSidecarEnabled = (env = process.env) => {
   return !['0', 'false', 'no', 'off'].includes(raw);
 };
 
-export const resolveFormalAiSidecarStatePath = (env = process.env) => path.join(resolveBotStateDir(env), STATE_FILE_NAME);
+export const resolveFormalAiSidecarStatePath = (env = process.env) => resolveSidecarStatePath(STATE_FILE_NAME, env);
 
 /** Read the durable sidecar record. A missing or corrupt file is an empty record, never a throw. */
-export const readFormalAiSidecarState = ({ env = process.env, fsImpl = fs } = {}) => {
-  try {
-    const parsed = JSON.parse(fsImpl.readFileSync(resolveFormalAiSidecarStatePath(env), 'utf8'));
-    return { ...EMPTY_STATE, ...parsed, leases: Array.isArray(parsed?.leases) ? parsed.leases : [] };
-  } catch {
-    return { ...EMPTY_STATE, leases: [] };
-  }
-};
+export const readFormalAiSidecarState = ({ env = process.env, fsImpl = fs } = {}) => readSidecarState({ fileName: STATE_FILE_NAME, emptyState: EMPTY_STATE, env, fsImpl });
 
 /** Persist the sidecar record atomically so a crash mid-write cannot corrupt it. */
-export const writeFormalAiSidecarState = (state, { env = process.env, fsImpl = fs } = {}) => {
-  const target = resolveFormalAiSidecarStatePath(env);
-  fsImpl.mkdirSync(path.dirname(target), { recursive: true });
-  const temporary = `${target}.tmp`;
-  fsImpl.writeFileSync(temporary, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
-  fsImpl.renameSync(temporary, target);
-  return state;
-};
+export const writeFormalAiSidecarState = (state, { env = process.env, fsImpl = fs } = {}) => writeSidecarState(state, { fileName: STATE_FILE_NAME, env, fsImpl });
 
 /**
  * Serialize every sidecar mutation — task launches, task releases and image
@@ -180,35 +167,6 @@ export const writeFormalAiSidecarState = (state, { env = process.env, fsImpl = f
  */
 export const withFormalAiSidecarLock = (fn, options = {}) => withStateLock(SIDECAR_LOCK_NAME, fn, options);
 
-const dockerText = async (run, args, { timeoutMs = DEFAULT_DOCKER_TIMEOUT_MS } = {}) => {
-  const result = await run('docker', args, { encoding: 'utf8', timeout: timeoutMs });
-  return String(result?.stdout ?? '').trim();
-};
-
-const dockerOk = async (run, args, options) => {
-  try {
-    await dockerText(run, args, options);
-    return true;
-  } catch {
-    return false;
-  }
-};
-
-/**
- * Inspect a container without treating "absent" as an error.
- *
- * @returns {Promise<{exists: boolean, running: boolean, image: string|null, imageDigest: string|null}>}
- */
-export const inspectDockerContainer = async (name, { run = execFileAsync, timeoutMs } = {}) => {
-  try {
-    const raw = await dockerText(run, ['inspect', name, '--format', '{{.State.Running}}|{{.Config.Image}}|{{.Image}}'], { timeoutMs });
-    const [running, image, imageDigest] = raw.split('|');
-    return { exists: true, running: running === 'true', image: image || null, imageDigest: imageDigest || null };
-  } catch {
-    return { exists: false, running: false, image: null, imageDigest: null };
-  }
-};
-
 /**
  * The sidecar's IPv4 address on the internal network.
  *
@@ -218,22 +176,7 @@ export const inspectDockerContainer = async (name, { run = execFileAsync, timeou
  * post-attachment would be a needless gamble; the address cannot change during
  * a lease, because an image replacement requires zero leases.
  */
-export const readFormalAiSidecarAddress = async ({ containerName = FORMAL_AI_SIDECAR_CONTAINER_NAME, network = FORMAL_AI_SIDECAR_NETWORK_NAME, run = execFileAsync, timeoutMs } = {}) => {
-  try {
-    return (await dockerText(run, ['inspect', containerName, '--format', `{{with index .NetworkSettings.Networks "${network}"}}{{.IPAddress}}{{end}}`], { timeoutMs })) || null;
-  } catch {
-    return null;
-  }
-};
-
-/** Resolve the local content digest of an image reference, or null when it is absent. */
-export const readDockerImageDigest = async (image, { run = execFileAsync, timeoutMs } = {}) => {
-  try {
-    return (await dockerText(run, ['image', 'inspect', image, '--format', '{{.Id}}'], { timeoutMs })) || null;
-  } catch {
-    return null;
-  }
-};
+export const readFormalAiSidecarAddress = async ({ containerName = FORMAL_AI_SIDECAR_CONTAINER_NAME, network = FORMAL_AI_SIDECAR_NETWORK_NAME, run = execFileAsync, timeoutMs } = {}) => readDockerContainerAddress(containerName, network, { run, timeoutMs });
 
 /**
  * Create the private network the sidecar and its tasks share.
@@ -244,34 +187,7 @@ export const readDockerImageDigest = async (image, { run = execFileAsync, timeou
  * artifact from the Compose deployment and is replaced when nothing is
  * attached to it.
  */
-export const ensureFormalAiNetwork = async ({ run = execFileAsync, timeoutMs, log = null, verbose = false } = {}) => {
-  // `null` means "absent", which is different from "present but not internal".
-  let internal = null;
-  let containers = 0;
-  try {
-    const raw = await dockerText(run, ['network', 'inspect', FORMAL_AI_SIDECAR_NETWORK_NAME, '--format', '{{.Internal}}|{{len .Containers}}'], { timeoutMs });
-    const [internalFlag, containerCount] = raw.split('|');
-    internal = internalFlag === 'true';
-    containers = Number(containerCount) || 0;
-  } catch {
-    // Absent; fall through to creation.
-  }
-
-  if (internal === true) return { created: false, internal: true };
-
-  if (internal === false) {
-    if (containers > 0) {
-      if (log) await log(`⚠️ Formal AI network '${FORMAL_AI_SIDECAR_NETWORK_NAME}' is not internal but still has ${containers} attached container(s); leaving it in place`);
-      return { created: false, internal: false };
-    }
-    if (verbose && log) await log(`[VERBOSE] formal-ai-sidecar: replacing non-internal network '${FORMAL_AI_SIDECAR_NETWORK_NAME}'`);
-    await dockerOk(run, ['network', 'rm', FORMAL_AI_SIDECAR_NETWORK_NAME], { timeoutMs });
-  }
-
-  await dockerText(run, ['network', 'create', '--internal', '--label', `${FORMAL_AI_SIDECAR_LABEL}=network`, FORMAL_AI_SIDECAR_NETWORK_NAME], { timeoutMs });
-  if (verbose && log) await log(`[VERBOSE] formal-ai-sidecar: created internal network '${FORMAL_AI_SIDECAR_NETWORK_NAME}'`);
-  return { created: true, internal: true };
-};
+export const ensureFormalAiNetwork = async ({ run = execFileAsync, timeoutMs, log = null, verbose = false } = {}) => ensureInternalDockerNetwork({ name: FORMAL_AI_SIDECAR_NETWORK_NAME, label: FORMAL_AI_SIDECAR_LABEL, run, timeoutMs, log, verbose, logPrefix: LOG_PREFIX });
 
 /**
  * Create the persisted-memory volume if it is missing and hand it to the
@@ -281,16 +197,12 @@ export const ensureFormalAiNetwork = async ({ run = execFileAsync, timeoutMs, lo
  * task boundaries, sidecar stops, image replacement and rollback.
  */
 export const ensureFormalAiMemoryVolume = async ({ image, run = execFileAsync, timeoutMs, log = null, verbose = false } = {}) => {
-  if (await dockerOk(run, ['volume', 'inspect', FORMAL_AI_MEMORY_VOLUME_NAME], { timeoutMs })) {
-    return { created: false };
-  }
-
-  await dockerText(run, ['volume', 'create', '--label', `${FORMAL_AI_SIDECAR_LABEL}=memory`, FORMAL_AI_MEMORY_VOLUME_NAME], { timeoutMs });
+  const result = await ensureDockerVolume({ name: FORMAL_AI_MEMORY_VOLUME_NAME, label: FORMAL_AI_SIDECAR_LABEL, role: 'memory', run, timeoutMs, log, verbose, logPrefix: LOG_PREFIX });
+  if (!result.created) return result;
   // A fresh named volume is root-owned; the image runs application commands as
   // `box`, so seed the ownership exactly as upstream's own upgrade fixture does.
   await dockerOk(run, ['run', '--rm', '--volume', `${FORMAL_AI_MEMORY_VOLUME_NAME}:${FORMAL_AI_MEMORY_MOUNT}`, '--entrypoint', 'chown', image, '-R', 'box:box', FORMAL_AI_MEMORY_MOUNT], { timeoutMs });
-  if (verbose && log) await log(`[VERBOSE] formal-ai-sidecar: created memory volume '${FORMAL_AI_MEMORY_VOLUME_NAME}'`);
-  return { created: true };
+  return result;
 };
 
 /** Build the `docker run` argv for the sidecar. Exported so tests can assert the contract. */
@@ -369,29 +281,7 @@ export const waitForFormalAiSidecarHealth = async ({ containerName = FORMAL_AI_S
  * `LEASE_START_GRACE_MS` elapses; afterwards, and always once the container has
  * been observed, liveness is Docker's answer alone.
  */
-const LEASE_START_GRACE_MS = 60 * 60 * 1000;
-
-const reconcileLeases = async (leases, { run, timeoutMs, log, verbose, now = () => Date.now() }) => {
-  const live = [];
-  for (const lease of leases) {
-    if (!lease?.sessionId) continue;
-    const container = await inspectDockerContainer(lease.sessionId, { run, timeoutMs });
-    if (container.exists && container.running) {
-      live.push(lease.containerSeen ? lease : { ...lease, containerSeen: true });
-      continue;
-    }
-    if (!lease.containerSeen) {
-      const age = now() - (Date.parse(lease.acquiredAt ?? '') || 0);
-      if (age < LEASE_START_GRACE_MS) {
-        if (verbose && log) await log(`[VERBOSE] formal-ai-sidecar: keeping lease '${lease.sessionId}' whose container has not appeared yet (${Math.round(age / 1000)}s into the ${Math.round(LEASE_START_GRACE_MS / 1000)}s launch grace)`);
-        live.push(lease);
-        continue;
-      }
-    }
-    if (verbose && log) await log(`[VERBOSE] formal-ai-sidecar: dropping stale lease '${lease.sessionId}' (container exists=${container.exists} running=${container.running})`);
-  }
-  return live;
-};
+const reconcileLeases = async (leases, options) => reconcileSidecarLeases(leases, { ...options, logPrefix: LOG_PREFIX });
 
 /**
  * Re-derive the sidecar record from Docker.
@@ -522,17 +412,7 @@ export const acquireFormalAiSidecar = async ({ sessionId, tool = null, model = n
  */
 export const attachTaskToFormalAiNetwork = async ({ sessionId, run = execFileAsync, timeoutMs, log = null, verbose = false } = {}) => {
   if (!sessionId) return { attached: false, error: 'no sessionId' };
-  try {
-    await dockerText(run, ['network', 'connect', FORMAL_AI_SIDECAR_NETWORK_NAME, sessionId], { timeoutMs });
-    if (verbose && log) await log(`[VERBOSE] formal-ai-sidecar: attached task container '${sessionId}' to '${FORMAL_AI_SIDECAR_NETWORK_NAME}'`);
-    return { attached: true, error: null };
-  } catch (error) {
-    const message = error?.stderr?.toString?.().trim() || error?.message || String(error);
-    // Docker reports an already-attached container as an error; that is success.
-    if (/already exists in network/i.test(message)) return { attached: true, error: null };
-    if (log) await log(`⚠️ Could not attach task container '${sessionId}' to the Formal AI network: ${message}`);
-    return { attached: false, error: message };
-  }
+  return attachDockerNetwork({ network: FORMAL_AI_SIDECAR_NETWORK_NAME, container: sessionId, run, timeoutMs, log, verbose, logPrefix: LOG_PREFIX });
 };
 
 /**

package/src/gemini.lib.mjs

@@ -8,7 +8,11 @@ if (typeof globalThis.use === 'undefined') {
   await ensureUseM();
 }
 
-const { $ } = await use('command-stream');
+const { $: __rawDollar$ } = await use('command-stream');
+// Issue #2168: retry transient git network failures (push/fetch/pull) the same
+// way `gh` calls are retried, for every command run through this module's `$`.
+const { wrapDollarWithGitRetry } = await import('./git-retry.lib.mjs');
+const $ = wrapDollarWithGitRetry(__rawDollar$);
 
 import { log, buildToolErrorMessage } from './lib.mjs';
 import { reportError } from './sentry.lib.mjs';

package/src/git-push-guard.lib.mjs

@@ -0,0 +1,230 @@
+/**
+ * Blocking destructive git pushes from inside a routed task (issue #2164, R13).
+ *
+ * The issue asks that agents lose the *physical ability* to destroy data:
+ * "immediately apply block of all delete operations or history changes like git
+ * reset and so on detected up on git push". A `git reset` is harmless on its
+ * own — nothing is lost until the rewritten history reaches the remote — so the
+ * point where the damage becomes real, and therefore the point worth guarding,
+ * is the push.
+ *
+ * Three layers were planned for R13. This module is layer 2:
+ *
+ *   1. Branch protection on the remote (`src/protect-branch.mjs`) — server-side
+ *      and unbypassable, but only covers branches somebody protected.
+ *   2. This `pre-push` hook — covers every branch and every remote in the task
+ *      container, costs nothing, and is defeated by `git push --no-verify`.
+ *   3. The router's git transport (`/git/…`), which routed tasks now push
+ *      through. It is unbypassable for the same reason the model traffic is —
+ *      the task holds no other credential — and it refuses branch deletions
+ *      outright (measured: `git push origin :refs/heads/x` → HTTP 403).
+ *
+ * Layer 3 originally covered deletions but not force pushes: the router decided
+ * by looking for a `force-ref-updates` capability that git never sends, so a
+ * non-fast-forward push was relayed unchanged (measured in
+ * `experiments/issue-2164/probe-git-transport.sh`, reported upstream as
+ * link-assistant/router#272). That was fixed in link-assistant/router#273 and
+ * ships from 0.110.0, which is at or below the pin — the router now asks
+ * GitHub's compare API whether the proposed tip is ahead of the current one and
+ * fails closed when it cannot tell.
+ *
+ * So this hook is no longer the only thing standing between an agent and a
+ * rewritten branch. It is still worth keeping: it is the layer that applies to
+ * every remote rather than only the routed one, it costs nothing, and it stops
+ * the push locally instead of after a round trip. It remains defeated by
+ * `--no-verify`, so it is a speed bump and the docs say so.
+ *
+ * The hook is delivered by mounting a host directory read-only into the task
+ * container and pointing git at it with `GIT_CONFIG_COUNT`/`GIT_CONFIG_KEY_0`
+ * (git >= 2.31). Env vars rather than `git config --global` because the task's
+ * `~/.gitconfig` is bind-mounted from the *host*: writing to it would reconfigure
+ * the operator's own machine.
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/2164
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/** Only `pre-push` is provided; git silently skips hook names that do not exist. */
+export const GIT_PUSH_GUARD_HOOK_NAME = 'pre-push';
+
+/** Operator escape hatch, propagated from an explicit `solve` opt-in (see `hasForcePushOptIn`). */
+export const GIT_PUSH_GUARD_ESCAPE_ENV = 'HIVE_MIND_ALLOW_DESTRUCTIVE_PUSH';
+
+/** Where the hook directory is mounted inside a Docker-isolated task. */
+export const GIT_PUSH_GUARD_CONTAINER_DIR = '/home/box/.hive-mind/git-hooks';
+
+/**
+ * The hook itself.
+ *
+ * git feeds `<local ref> <local sha> <remote ref> <remote sha>` on stdin, one
+ * line per ref being updated, and a non-zero exit aborts the whole push. Two
+ * things are refused:
+ *
+ *   - an all-zero *local* sha, which is how `git push --delete`, `git push
+ *     :branch` and `--mirror`/`--prune` deletions present themselves;
+ *   - an update where the remote's current commit is not an ancestor of what we
+ *     are about to send, i.e. a force push discarding commits that exist only on
+ *     the remote — the shape a `git reset --hard` + `push --force` takes.
+ *
+ * A remote sha we do not have locally is refused too: it cannot be proven to be
+ * an ancestor, and the honest answer to "would this destroy something?" is
+ * "unknown". Everything else — ordinary fast-forward pushes, new branches, new
+ * tags — passes untouched.
+ *
+ * POSIX sh, no bashisms: the isolation image's /bin/sh is dash.
+ */
+export const PRE_PUSH_GUARD_SCRIPT = `#!/bin/sh
+# Hive Mind push guard (issue #2164). Refuses branch/tag deletions and
+# history-rewriting (non-fast-forward) pushes from inside an isolated task.
+# Generated file - edit src/git-push-guard.lib.mjs instead.
+set -u
+
+remote_name="\${1:-}"
+remote_url="\${2:-}"
+allow="\${${GIT_PUSH_GUARD_ESCAPE_ENV}:-}"
+status=0
+
+is_zero_sha() {
+  [ -n "$1" ] || return 0
+  case "$1" in
+    *[!0]*) return 1 ;;
+    *) return 0 ;;
+  esac
+}
+
+refuse() {
+  status=1
+  echo "🛑 Hive Mind push guard: refused to $1" >&2
+  echo "   remote: \${remote_name} \${remote_url}" >&2
+  echo "   ref:    $2" >&2
+}
+
+while read -r local_ref local_sha remote_ref remote_sha; do
+  [ -n "\${remote_ref:-}" ] || continue
+  if is_zero_sha "\${local_sha:-}"; then
+    refuse "delete a remote ref" "\${remote_ref}"
+    continue
+  fi
+  is_zero_sha "\${remote_sha:-}" && continue
+  if ! git cat-file -e "\${remote_sha}^{commit}" 2>/dev/null; then
+    refuse "overwrite a remote commit this clone does not have (\${remote_sha})" "\${remote_ref}"
+    continue
+  fi
+  if ! git merge-base --is-ancestor "\${remote_sha}" "\${local_sha}" 2>/dev/null; then
+    refuse "rewrite history (the remote's \${remote_sha} is not an ancestor of \${local_sha})" "\${remote_ref}"
+  fi
+done
+
+if [ "\${status}" -ne 0 ]; then
+  case "\${allow}" in
+    1 | true | TRUE | yes | YES)
+      echo "⚠️  ${GIT_PUSH_GUARD_ESCAPE_ENV} is set, so the push is allowed anyway." >&2
+      exit 0
+      ;;
+  esac
+  echo "" >&2
+  echo "Destructive pushes are blocked for routed tasks (--use-router, issue #2164)." >&2
+  echo "Nothing was sent. Push a new commit instead, or ask a human operator to run it." >&2
+fi
+
+exit "\${status}"
+`;
+
+/**
+ * Host directory holding the generated hook.
+ *
+ * Deliberately NOT the bot state directory: that holds the router's signing
+ * secret, and this directory is mounted into every routed task.
+ */
+export function resolveGitPushGuardHostDir({ env = process.env, homeDir = os.homedir() } = {}) {
+  const explicit = String(env.HIVE_MIND_GIT_HOOKS_DIR || '').trim();
+  return explicit || path.join(homeDir, '.hive-mind', 'git-hooks');
+}
+
+/**
+ * Write the hook to the host, ready to be mounted.
+ *
+ * Rewritten on every launch so an upgrade cannot leave a stale hook behind.
+ * Never throws: a task that cannot get its guard is still a task worth running
+ * (the caller warns), because the remaining layers — branch protection — are
+ * the ones that were never bypassable anyway.
+ *
+ * @returns {{installed: boolean, dir: string, hookPath: string, error: string|null}}
+ */
+export function installGitPushGuard({ env = process.env, homeDir = os.homedir(), fsImpl = fs } = {}) {
+  const dir = resolveGitPushGuardHostDir({ env, homeDir });
+  const hookPath = path.join(dir, GIT_PUSH_GUARD_HOOK_NAME);
+  try {
+    fsImpl.mkdirSync(dir, { recursive: true });
+    fsImpl.writeFileSync(hookPath, PRE_PUSH_GUARD_SCRIPT, { mode: 0o755 });
+    // writeFileSync only applies `mode` when it creates the file, so an existing
+    // hook keeps whatever permissions it had — including non-executable ones,
+    // which git ignores silently.
+    fsImpl.chmodSync(hookPath, 0o755);
+    return { installed: true, dir, hookPath, error: null };
+  } catch (error) {
+    return { installed: false, dir, hookPath, error: error?.message || String(error) };
+  }
+}
+
+/**
+ * Turn `[key, value]` pairs into git's `GIT_CONFIG_COUNT`/`GIT_CONFIG_KEY_n`
+ * environment form (git >= 2.31).
+ *
+ * A routed task needs several such settings — the hook path here, plus the URL
+ * rewrite and CA that send git through the router (issue #2164) — and they share
+ * one counter, so building them separately would have each overwrite the other.
+ * The order is preserved because git applies these last-to-win, which is what
+ * lets `credential.helper=` clear an inherited helper list.
+ *
+ * @param {Array<[string, string]>} entries
+ * @returns {Record<string,string>}
+ */
+export function buildGitConfigEnv(entries = []) {
+  const usable = entries.filter(entry => Array.isArray(entry) && entry[0]);
+  if (usable.length === 0) return {};
+  const taskEnv = { GIT_CONFIG_COUNT: String(usable.length) };
+  usable.forEach(([key, value], index) => {
+    taskEnv[`GIT_CONFIG_KEY_${index}`] = key;
+    taskEnv[`GIT_CONFIG_VALUE_${index}`] = value ?? '';
+  });
+  return taskEnv;
+}
+
+/**
+ * Environment that points git at the mounted hook for every repository in the
+ * container, without writing to the bind-mounted `~/.gitconfig`.
+ *
+ * `extraConfig` carries any other settings the same task needs, so all of them
+ * end up under one `GIT_CONFIG_COUNT`.
+ */
+export function buildGitPushGuardEnv({ hooksPath = GIT_PUSH_GUARD_CONTAINER_DIR, allowDestructive = false, extraConfig = [] } = {}) {
+  const entries = [...(hooksPath ? [['core.hooksPath', hooksPath]] : []), ...extraConfig];
+  const taskEnv = buildGitConfigEnv(entries);
+  if (Object.keys(taskEnv).length === 0) return {};
+  if (allowDestructive) taskEnv[GIT_PUSH_GUARD_ESCAPE_ENV] = '1';
+  return taskEnv;
+}
+
+/**
+ * Read the existing fork-divergence opt-in out of a raw argument vector.
+ *
+ * `--allow-fork-divergence-resolution-using-force-push-with-lease` already means
+ * "this operator accepts a force push", and Hive Mind performs one itself in
+ * `solve.fork-sync.lib.mjs`. Blocking that would break a documented workflow, so
+ * the opt-in is propagated into the container rather than overridden.
+ *
+ * @param {string[]} args
+ */
+export function hasForcePushOptIn(args) {
+  const list = Array.isArray(args) ? args : [];
+  return list.some(arg => {
+    const value = String(arg ?? '');
+    return value === '--allow-fork-divergence-resolution-using-force-push-with-lease' || value === '--allow-fork-divergence-resolution-using-force-push-with-lease=true';
+  });
+}
+
+export default { buildGitConfigEnv, buildGitPushGuardEnv, hasForcePushOptIn, installGitPushGuard, resolveGitPushGuardHostDir, GIT_PUSH_GUARD_CONTAINER_DIR, PRE_PUSH_GUARD_SCRIPT };

package/src/git-retry.lib.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+
+/**
+ * Retry wrapper for network-facing *git* commands.
+ *
+ * Issue #2168 asked for retry on "any git/github operation". The `gh` half was
+ * already covered by src/github-rate-limit.lib.mjs (`wrapDollarWithGhRetry`),
+ * but the ~36 `git push` / `git fetch` / `git pull` call sites scattered across
+ * src/*.mjs had no retry at all: a single `fatal: unable to access ...` or
+ * `RPC failed; curl 56 ... connection reset` aborted the whole session.
+ *
+ * Wrapping every call site by hand would have to be repeated for every new call
+ * site, so the retry is installed on command-stream's `$` tag instead - exactly
+ * the shape already used for `gh`. Anything that runs through a wrapped `$`
+ * gets the retry for free, and the existing ESLint rules that push code towards
+ * the wrapped `$` keep new call sites covered.
+ *
+ * Only *network* subcommands are retried. Local plumbing (`git commit`,
+ * `git checkout`, ...) is deterministic: re-running it cannot turn a failure
+ * into a success, and a blind second attempt could mask the real error.
+ *
+ * `git clone` is intentionally NOT in the list: a partially-written destination
+ * directory makes the second attempt fail with "already exists and is not an
+ * empty directory", which would replace the real (transient) diagnosis with a
+ * confusing one. Repository cloning in this codebase goes through
+ * `gh repo clone`, which is already covered by the gh retry wrapper.
+ */
+
+// Subcommands that talk to the remote and are safe to re-run verbatim.
+const GIT_NETWORK_SUBCOMMANDS = Object.freeze(['push', 'fetch', 'pull', 'ls-remote']);
+
+/**
+ * Decide whether `command` is a git command that reaches the network.
+ *
+ * Handles the `git -C <dir> push ...` and `git --no-pager fetch ...` forms by
+ * skipping leading option tokens (and their argument, for the options that take
+ * one) before looking at the subcommand.
+ *
+ * @param {string} command - the reconstructed shell command line.
+ * @returns {string|null} the matched subcommand, or null when not a git network command.
+ */
+export const matchGitNetworkCommand = command => {
+  const text = String(command ?? '').trim();
+  if (!/^git(?:\s|$)/.test(text)) return null;
+  const tokens = text.split(/\s+/).slice(1);
+  const optionsWithValue = new Set(['-C', '-c', '--git-dir', '--work-tree', '--namespace', '--exec-path']);
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (!token.startsWith('-')) {
+      // `git clone` is excluded on purpose - see the module header.
+      return GIT_NETWORK_SUBCOMMANDS.includes(token) ? token : null;
+    }
+    if (optionsWithValue.has(token)) i++;
+  }
+  return null;
+};
+
+/**
+ * Wrap command-stream's `$` so that git network commands are retried on
+ * transient failures. Non-git commands (and local git plumbing) are passed
+ * straight through, so the wrapper is safe to install globally.
+ *
+ * @template T
+ * @param {(strings: TemplateStringsArray, ...values: unknown[]) => Promise<T>} dollar
+ * @param {object} [options] - forwarded to gitCmdRetry per call.
+ * @returns {(strings: TemplateStringsArray, ...values: unknown[]) => Promise<T>}
+ */
+export const wrapDollarWithGitRetry = (dollar, options = {}) => {
+  if (typeof dollar !== 'function') {
+    throw new TypeError(`Expected command-stream's $ export to be a function, received ${typeof dollar}.`);
+  }
+  const wrapped = (strings, ...values) => {
+    // Options-call form: `$({ cwd })` returns a new tag bound to those options.
+    if (strings && !Array.isArray(strings) && typeof strings === 'object') {
+      return wrapDollarWithGitRetry(dollar(strings), options);
+    }
+    let preview = '';
+    for (let i = 0; i < strings.length; i++) {
+      preview += strings[i];
+      if (i < values.length) preview += String(values[i] ?? '');
+    }
+    const subcommand = matchGitNetworkCommand(preview);
+    if (!subcommand) return dollar(strings, ...values);
+    // Lazy import keeps this module free of a static cycle with lib.mjs.
+    return (async () => {
+      const { gitCmdRetry } = await import('./lib.mjs');
+      return gitCmdRetry(() => dollar(strings, ...values), {
+        label: `git ${subcommand}`,
+        ...options,
+      });
+    })();
+  };
+  wrapped.raw = typeof dollar.raw === 'function' ? dollar.raw : dollar;
+  return wrapped;
+};
+
+export default { matchGitNetworkCommand, wrapDollarWithGitRetry };

package/src/github-pr-idempotency.lib.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+
+/**
+ * Make `gh pr create` safe to retry.
+ *
+ * Issue #2168: `gh pr create` aborted a solve run on GitHub's transient
+ * GraphQL internal error. The fix is to retry — but a mutation that failed
+ * *after* GitHub committed it (a 5xx on the response path, not the request
+ * path) would make the retry fail again with
+ *
+ *   GraphQL: A pull request already exists for konard:issue-4804-203a323f30b1.
+ *
+ * which is not transient and would abort the run just the same, only one step
+ * later. Retrying a write is only correct when the write is idempotent, so
+ * this module turns "already exists" into "here is the pull request you were
+ * trying to create".
+ */
+
+/**
+ * Combined text of an error-ish value, mirroring the collector used by the
+ * transient classifier.
+ */
+const errorText = error => {
+  if (!error) return '';
+  if (typeof error === 'string') return error;
+  const parts = [];
+  if (typeof error.message === 'string') parts.push(error.message);
+  if (error.stderr) parts.push(error.stderr.toString());
+  if (error.stdout) parts.push(error.stdout.toString());
+  if (error.cause) parts.push(errorText(error.cause));
+  return parts.join('\n');
+};
+
+/**
+ * Detect `gh pr create`'s "a pull request already exists" rejection.
+ *
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+export const isPullRequestAlreadyExistsError = error => {
+  const text = errorText(error).toLowerCase();
+  if (!text) return false;
+  return text.includes('a pull request already exists') || (text.includes('pull request') && text.includes('already exists'));
+};
+
+/**
+ * Look up the pull request that already exists for `headRef`.
+ *
+ * `gh pr list --head` matches on the branch name; for a fork the head is
+ * `owner:branch`, and GitHub still indexes it under the bare branch name, so
+ * the bare name is what we query with.
+ *
+ * @param {object} params
+ * @param {string} params.owner
+ * @param {string} params.repo
+ * @param {string} params.headRef - branch name, with or without an `owner:` prefix.
+ * @param {(command: string, options?: object) => Promise<{stdout: string}>} params.execGh - retry-wrapped exec (e.g. `execGhWithRetry`).
+ * @param {(msg: string, options?: object) => Promise<void>|void} [params.log]
+ * @returns {Promise<string|null>} PR URL, or null when none could be resolved.
+ */
+export const findExistingPullRequestUrl = async ({ owner, repo, headRef, execGh, log = null }) => {
+  const branch = String(headRef || '').includes(':') ? String(headRef).split(':').pop() : String(headRef || '');
+  if (!branch) return null;
+  try {
+    const { stdout } = await execGh(`gh pr list --repo ${owner}/${repo} --head ${branch} --state all --limit 1 --json url,number,state`, {
+      label: 'gh pr list (existing PR lookup)',
+    });
+    const parsed = JSON.parse((stdout || '[]').toString().trim() || '[]');
+    const first = Array.isArray(parsed) ? parsed[0] : null;
+    if (first?.url) {
+      if (log) await Promise.resolve(log(`   Recovered existing PR #${first.number} (${first.state}) for head ${branch}: ${first.url}`));
+      return first.url;
+    }
+  } catch (lookupError) {
+    if (log) await Promise.resolve(log(`   Could not look up the existing PR for head ${branch}: ${lookupError.message}`, { level: 'warn' }));
+  }
+  return null;
+};
+
+export default {
+  isPullRequestAlreadyExistsError,
+  findExistingPullRequestUrl,
+};