Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
105 KB
Raw Blame
/**
 * Shared-checkout-safe commit, push and pull for classic (unmanaged) brain
 * repos (#6530). Many writers (agents, crons, hooks, gbrain's own
 * write-through) commit to ONE checkout, so nothing here rebases, stashes or
 * resets the working tree:
 *
 *   1. two locks per checkout: the short commit lock (`git rev-parse --git-path
 *      brain-commit.lock`, the same flock a bash `flock -x` takes) for local
 *      index/HEAD changes only, and the publish lock (brain-publish.lock) for
 *      the network push; a publisher takes the commit lock only to advance, and
 *      an unattended publisher that finds the publish lock busy leaves a request
 *      the holder honors after it releases (so no commit is stranded);
 *   2. commits carry only the caller's paths (`commit --only -- <paths>`);
 *   3. a rejected push is integrated IN MEMORY (`merge-tree --write-tree`, or a
 *      3-way `read-tree` into a temporary index on git < 2.38) into a merge
 *      commit built with `commit-tree`; no working tree is touched;
 *   4. the shared checkout advances only by `merge --ff-only`, which refuses
 *      (and changes nothing) when HEAD moved or a file it must change is dirty.
 *
 * Managed canonical worktrees are refused: the persistence owner is their
 * only writer. The one exception is a keep-checkout publish (`keepCheckout`,
 * `--push-only --keep-checkout`): it pushes HEAD, merging a moved remote in
 * memory, but never moves the checkout and skips its pre-push hook, so `gbrain sources
 * refresh` stays the only importer of remote files into a managed worktree
 * (#7010; the owner's Git effects publish this way). CLI-only; never exposed
 * over MCP (it pushes with host credentials).
 */
import { appendFileSync, copyFileSync, existsSync, mkdtempSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { rangeSecretRefusal, scanRange } from './range-secret-scan.ts';
import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
import { literalPathspecs } from '../git-env.ts';
import { git, gitOk, type GitRun } from './git-run.ts';
export type { SkippedPath } from './skipped-paths.ts';
import { assertNoUnmergedPaths, withoutUnmergedPaths, checkoutBehindStrayGitfile, directoryStatus, worktreeOfGitdir, flaggedChanges, stagedRemovals, STAGED_FOR_REMOVAL_WHY, unindexedFiles, unstagedPaths, type SkippedPath } from './skipped-paths.ts';
import { GIT_SSRF_SUBCOMMAND_FLAGS, ownRemoteTransportFlags as transportFlags } from '../git-transport.ts';
import { canonicalFilesystemPath } from '../persistence/root-registry.ts';
import { assertManagedFilesystemWrite, hasFilesystemPublication, managedFilesystemRootFor, type ManagedFilesystemRoot } from '../persistence/filesystem-guard.ts';
import { acquireNativeLock, acquireNativeLockSync, type NativeLockSyncHandle } from '../persistence/native-lock.ts';
import { recordCommit, recordIntent } from './commit-ledger.ts';
import { CREDENTIAL_STATE_NAME, credentialRefusal, pushCredentialRefusedError, readCredentialRefusalFile, recordCredentialRefusalFile, type CredentialRefusalState } from './push-credential.ts';
import { OperationError, opError } from '../ops/contract.ts';
import { shellQuote, type Action } from '../agent-output.ts';
import { isSyncable } from '../sync.ts';
import { untrackAdmitted, untrackTargets, type UntrackPageVerdict } from './untrack-admission.ts';
export { untrackAdmitted, untrackPageCandidates } from './untrack-admission.ts';
import { relativeEscapesRoot } from '../path-confine.ts';

export const COMMIT_LOCK_NAME = 'brain-commit.lock';
/** Taken by pre-#6530 helpers and hooks; held too so they still exclude us during the mixed-version window. */
export const LEGACY_PUSH_LOCK_NAME = 'gbrain-push.lock';
export const COMMIT_LOCK_ENV = 'BRAIN_COMMIT_LOCK_HELD';
export const PUBLISH_LOCK_NAME = 'brain-publish.lock';
const PUBLISH_REQUEST_NAME = 'brain-publish.requested';
const CONFLICT_STATE_NAME = 'brain-integrate-conflict.json';
/** Write-through files gbrain wrote but could not commit (lock busy past the short budget, or a refused commit): one `<iso>\t<json path>` line each. */
const PENDING_NAME = 'brain-writethrough-pending.log';
/** Toplevel-relative source root(s) of this checkout, one value each (`gbrain sources harden` writes them); unset means the whole checkout. */
export const SOURCE_ROOT_CONFIG = 'gbrain.sourceRoot';
/** Set to the commit lock path on every commit gbrain makes under that lock; the opt-in commit guard admits only these. */
export const COMMIT_VIA_ENV = 'GBRAIN_COMMIT_VIA';
const MAX_PUSH_ATTEMPTS = 8;
const sleeper = new Int32Array(new SharedArrayBuffer(4));
const INDEX_LOCK_RETRIES = 5;

export type CheckoutState = 'advanced' | 'unchanged' | 'lagging';

export interface CommitPushResult {
  /**
   * `push_deferred`: an unattended publish found another publish running and left it a request to publish HEAD too.
   * `committed_local`: a managed canonical worktree, or a checkout with no Git remote (`no_remote`), where commit-push only commits the named paths and never pushes.
   */
  outcome: 'pushed' | 'nothing_to_commit' | 'pushed_checkout_lagging' | 'push_deferred' | 'committed_local';
  /** The commit now on the remote branch (the caller's commit or the merge built over it). */
  sha: string | null;
  committed: string | null;
  branch: string;
  remote: string;
  paths: string[];
  /** Remote commits merged in to publish. */
  integrated: number;
  /** `remote`: a push reported failure but every push destination already holds the commit (a lost acknowledgement or a concurrent pusher). */
  confirmed?: 'push' | 'remote';
  checkout: CheckoutState;
  lagging_reason?: string;
  /** Opt-in quarantine (git config gbrain.quarantine): the local versions of conflicting files, parked under a ref; the remote's version was published. */
  quarantined?: QuarantineEntry;
  /** The checkout has no Git remote: the paths were committed locally (or were already committed) and nothing was pushed. */
  no_remote?: true;
  /** Conflicted files where the remote held a version this checkout had already replaced: this checkout's version was published. */
  superseded_remote_paths?: string[];
  /** A managed canonical worktree: the named paths were committed (or had no change) and nothing was pushed. */
  managed?: true;
  /** Managed only: commits on the branch its upstream lacks as last fetched; null when no fetched upstream can be read. */
  unpublished?: number | null;
  /** Managed only: the branch's configured upstream (`origin/main`); null when it names none. */
  upstream?: string | null;
}

export interface PullResult {
  status: 'up_to_date' | 'advanced' | 'ahead' | 'skipped_dirty' | 'lagging';
  from?: string;
  to?: string;
  merged?: boolean;
  /** Why the checkout could not advance (dirty must-change file, HEAD moved). */
  reason?: string;
}

export interface CommitPushOptions {
  repo: string;
  /** Paths to commit, absolute or relative to `cwd`. Ignored with pushOnly. */
  paths?: string[];
  message?: string;
  pushOnly?: boolean;
  cwd?: string;
  lockWaitMs?: number;
  /** `--resolve`: blob choice per conflicted path for the in-memory merge. */
  resolutions?: Map<string, Resolution>;
  /**
   * `--expect-remote`: the remote commit the resolutions were chosen against (required with resolutions). Without
   * resolutions it binds the publish (#7686): HEAD is merged with that commit, pushed with a lease on it, and a remote that
   * moved anywhere else refuses, so a rewrite made after the caller checked the remote is never merged back.
   */
  expectRemote?: string;
  /** How long a foreground publish waits for another publish to finish. */
  publishWaitMs?: number;
  /** Unattended callers (the post-commit hook): publish, but advance the checkout only when it has no local edit. */
  advanceOnlyWhenClean?: boolean;
  /** Push-only: publish HEAD to this remote branch instead of the checked-out branch's upstream (the helper's `--push-only <branch>`). */
  branch?: string;
  /** Push-only: never advance the checkout and skip its pre-push hook (a managed canonical worktree; see the header). */
  keepCheckout?: boolean;
  /** The secret scan's time budget (`--scan-timeout`; default 300 s) and where its progress lines go. */
  scanTimeoutMs?: number;
  scanProgress?: (line: string) => void;
  /** Commit the pending write-through files (`--pending`) instead of named paths. */
  pending?: boolean;
  /** `--untrack` (#7753): remove the named paths from Git and the index, keeping the files on disk. */
  untrack?: boolean;
  /** GST-2964: what the brain says about the code-extension files an untrack in a managed canonical worktree names (read by src/commands/git.ts); absent, they refuse. */
  untrackPages?: UntrackPageVerdict;
  /** Commit and publish files outside the configured source root(s): the user's explicit choice, or gbrain's own scaffolding at the checkout root. */
  allowOutsideSourceRoot?: boolean;
  /** `--base <path>=<blob>`: the blob (or `absent`) each named path had at HEAD when the writer read it; a moved one refuses `commit_base_moved`. */
  bases?: Map<string, string>;
}

export type Resolution = { kind: 'ours' } | { kind: 'theirs' } | { kind: 'file'; path: string };

interface Ctx {
  root: string;
  branch: string;
  remote: string;
  mergeRef: string;
  trackingRef: string;
  keepCheckout?: boolean;
  scanTimeoutMs?: number;
  scanProgress?: (line: string) => void;
}

/** Remote operations: transport hardening on every call, credentials allowed, no prompt. */
function remoteGit(root: string, sub: 'fetch' | 'push', args: string[], timeoutMs = 120_000): GitRun {
  return git(root, [...transportFlags(), sub, ...GIT_SSRF_SUBCOMMAND_FLAGS, ...args], { auth: true, timeoutMs, returnStopped: true });
}

export function gitVersion(root: string): [number, number] {
  const m = /git version (\d+)\.(\d+)/.exec(gitOk(root, ['version'], 'version'));
  return m ? [Number(m[1]), Number(m[2])] : [0, 0];
}

function absGitPath(root: string, rel: string): string {
  const p = gitOk(root, ['rev-parse', '--git-path', rel], 'rev-parse --git-path');
  if (!p) throw opError('git_unavailable', `git rev-parse --git-path ${rel} printed nothing in ${root}.`, 'Check that git works in this checkout (git status).');
  return isAbsolute(p) ? p : resolve(root, p);
}

/** The checkout's toplevel; throws `commit_paths_invalid` outside a work tree. */
/** The operator step that commits and pushes only `paths` (relative to `root`) with one -m per message paragraph: the fix text doctor and repair print instead of a bare git add/commit. */
export function commitPushCommand(root: string, paths: readonly string[], messages: readonly string[]): string {
  return shellQuote(['gbrain', 'git', 'commit-push', '--path', root, ...messages.flatMap(m => ['-m', m]), '--', ...paths]);
}

export function checkoutRoot(dir: string): string {
  const r = git(dir, ['rev-parse', '--show-toplevel']);
  const top = (r.code === 0 && r.stdout.trim()) || checkoutBehindStrayGitfile(dir);
  if (!top) {
    throw opError('commit_paths_invalid', `${dir} is not inside a git checkout.`,
      'Run the command inside the brain checkout or pass --path <checkout>.');
  }
  return worktreeOfGitdir(top);
}

function resolveCtx(root: string): Ctx {
  const sym = git(root, ['symbolic-ref', '--quiet', '--short', 'HEAD']);
  if (sym.code !== 0) {
    throw opError('git_detached_head', `${root} is on a detached HEAD, so there is no branch to publish.`,
      'Check out the branch the remote tracks (git switch <branch>), then rerun.');
  }
  const branch = sym.stdout.trim();
  if (git(root, ['rev-parse', '--verify', '--quiet', 'HEAD']).code !== 0) {
    throw opError('git_detached_head', `Branch ${branch} in ${root} has no commit yet.`,
      'Make the first commit on this branch with git, then rerun.', { reason: 'unborn' });
  }
  const remote = git(root, ['config', '--get', `branch.${branch}.remote`]).stdout.trim() || 'origin';
  const mergeRef = git(root, ['config', '--get', `branch.${branch}.merge`]).stdout.trim() || `refs/heads/${branch}`;
  if (remote === '.' || git(root, ['remote', 'get-url', '--', remote]).code !== 0) {
    throw opError('git_unavailable', `Branch ${branch} in ${root} has no usable remote (${remote}); nothing was committed.`,
      `Add the remote (git remote add ${remote} <url>) or set the branch upstream, then rerun.`);
  }
  const short = mergeRef.replace(/^refs\/heads\//, '');
  return { root, branch, remote, mergeRef, trackingRef: `refs/remotes/${remote}/${short}` };
}

/** `--push-only <branch>`: publish to an explicit remote branch (validated as one exact ref, never a pattern). */
function withBranch(ctx: Ctx, branch: string | undefined): Ctx {
  if (!branch) return ctx;
  const short = branch.replace(/^refs\/heads\//, '');
  if (!short || git(ctx.root, ['check-ref-format', `refs/heads/${short}`]).code !== 0) {
    throw opError('commit_paths_invalid', `${branch} is not a valid branch name.`, 'Pass one exact branch name, e.g. --branch main.', { detail: branch });
  }
  return { ...ctx, mergeRef: `refs/heads/${short}`, trackingRef: `refs/remotes/${ctx.remote}/${short}` };
}

/** The git-dir entries a rebase, merge, cherry-pick or revert leaves while it is in progress. */
export const GIT_OPERATION_MARKERS = ['rebase-merge', 'rebase-apply', 'MERGE_HEAD', 'CHERRY_PICK_HEAD', 'REVERT_HEAD', 'sequencer'] as const;

/** Refuse while another git operation is mid-flight; never abort it for the user. */
export function assertNoOperationInProgress(root: string): void {
  for (const marker of GIT_OPERATION_MARKERS) {
    if (existsSync(absGitPath(root, marker))) {
      throw opError('git_operation_in_progress', `A git ${marker.startsWith('rebase') ? 'rebase' : marker.toLowerCase().replace(/_head$/, '')} is in progress in ${root}.`,
        `Finish or abort it first. A stuck rebase may hold another writer's autostash: save it with git stash store <sha from .git/${marker}/autostash> before deleting anything. See docs/guides/shared-checkout-git.md#stuck-rebase.`,
        { detail: marker });
    }
  }
}

// ── Lock ────────────────────────────────────────────────────────────────────

export interface CommitLock { release(): void; lockPath: string; reentrant: boolean }

/**
 * Take this checkout's commit lock (and the legacy push lock). Re-entrant only
 * when BRAIN_COMMIT_LOCK_HELD names this exact lock AND the lock is really
 * held: a stale, spoofed or generic (`1`) marker cannot bypass a lock.
 */
export function acquireCommitLock(root: string, waitMs = defaultLockWaitMs()): CommitLock {
  const lockPath = absGitPath(root, COMMIT_LOCK_NAME);
  const legacyPath = absGitPath(root, LEGACY_PUSH_LOCK_NAME);
  const marker = process.env[COMMIT_LOCK_ENV];
  if (marker && marker !== '1' && resolve(marker) === lockPath) {
    const probe = acquireNativeLockSync(lockPath, { timeoutMs: 0 });
    if (!probe) return { release() {}, lockPath, reentrant: true };
    return withLegacy(root, probe, lockPath, legacyPath, waitMs);
  }
  const handle = acquireNativeLockSync(lockPath, { timeoutMs: waitMs });
  if (!handle) throw lockBusy(lockPath, waitMs);
  return withLegacy(root, handle, lockPath, legacyPath, waitMs);
}

function withLegacy(root: string, handle: NativeLockSyncHandle, lockPath: string, legacyPath: string, waitMs: number): CommitLock {
  let legacy: NativeLockSyncHandle | null;
  try { legacy = acquireNativeLockSync(legacyPath, { timeoutMs: waitMs }); }
  catch (e) { handle.release(); throw e; }
  if (!legacy) { handle.release(); throw lockBusy(legacyPath, waitMs, root); }
  return { lockPath, reentrant: false, release() { legacy!.release(); handle.release(); } };
}

/** The same locks for async callers (`gbrain sync`'s pull), without blocking the event loop while waiting. */
export async function acquireCommitLockAsync(root: string, waitMs = defaultLockWaitMs(), signal?: AbortSignal): Promise<{ release(): Promise<void> }> {
  const lockPath = absGitPath(root, COMMIT_LOCK_NAME);
  const legacyPath = absGitPath(root, LEGACY_PUSH_LOCK_NAME);
  const handle = await acquireNativeLock(lockPath, { timeoutMs: waitMs, signal });
  if (!handle) throw lockBusy(lockPath, waitMs, root);
  let legacy;
  try { legacy = await acquireNativeLock(legacyPath, { timeoutMs: waitMs, signal }); }
  catch (e) { await handle.release(); throw e; }
  if (!legacy) { await handle.release(); throw lockBusy(legacyPath, waitMs, root); }
  return { async release() { await legacy.release(); await handle.release(); } };
}

function defaultLockWaitMs(): number {
  const raw = process.env.GBRAIN_COMMIT_LOCK_WAIT_SECONDS ?? process.env.GBRAIN_PUSH_LOCK_WAIT_SECONDS;
  const secs = raw === undefined ? 60 : Number(raw);
  return Number.isFinite(secs) && secs >= 0 ? secs * 1000 : 60_000;
}

function lockBusy(lockPath: string, waitMs: number, root?: string): OperationError {
  return opError('commit_lock_busy', `Another writer held this checkout's commit lock for ${Math.round(waitMs / 1000)}s.`,
    `Another commit or push is running in ${root ?? 'this checkout'} (lock ${lockPath}). Retry once it finishes; nothing was committed.`,
    { detail: lockPath, retryable: true });
}

// ── Paths ───────────────────────────────────────────────────────────────────

/** Repo-relative paths; refuses the root itself, `.git` and anything outside the checkout. */
export function scopePaths(root: string, paths: string[], cwd: string): string[] {
  if (paths.length === 0) {
    throw opError('commit_paths_invalid', 'No paths to commit.',
      'Pass the explicit file(s) you wrote; a repo-wide commit would sweep up other writers\' files.');
  }
  const out: string[] = [];
  for (const p of paths) {
    // GST-2767: a path reached through a symlinked directory (a source path linked to a subdirectory of the checkout) names
    // the file at its real location; only the parent is resolved, so a named symlink file stays itself.
    const named = resolve(cwd, p);
    const abs = join(canonicalFilesystemPath(dirname(named)), basename(named));
    const rel = relative(root, abs);
    if (rel === '' || rel === '.' || relativeEscapesRoot(rel)) {
      throw opError('commit_paths_invalid', `Path ${p} is ${rel === '' || rel === '.' ? 'the whole checkout' : 'outside the checkout'}.`,
        'Pass the explicit file(s) you wrote inside the checkout; a repo-wide commit would sweep up other writers\' files.', { detail: p });
    }
    if (rel.split(/[\\/]/)[0] === '.git') {
      throw opError('commit_paths_invalid', `Path ${p} is inside .git.`, 'Pass files in the working tree.', { detail: p });
    }
    out.push(rel.split('\\').join('/'));
  }
  return [...new Set(out)];
}

/** The checkout's configured source roots (`gbrain.sourceRoot`, toplevel-relative); [''] (the whole checkout) when none is set. */
export function configuredSourceRoots(root: string): string[] {
  const roots: string[] = [];
  for (const raw of git(root, ['config', '--get-all', SOURCE_ROOT_CONFIG]).stdout.split('\n').map(v => v.trim()).filter(Boolean)) {
    const rel = (isAbsolute(raw) ? relative(root, raw) : raw).split('\\').join('/').replace(/^(\.\/)+/, '').replace(/\/+$/, '');
    if (rel === '' || rel === '.') return [''];
    if (!relativeEscapesRoot(rel)) roots.push(rel);
  }
  return roots.length ? [...new Set(roots)] : [''];
}

const covers = (spec: string, path: string) => spec === '' || path === spec || path.startsWith(`${spec}/`);
export const insideSourceRoots = (path: string, roots: string[]) => roots.some(r => covers(r, path));

function outsideRootError(root: string, roots: string[], paths: string[], what: string): OperationError {
  return opError('commit_outside_source_root', `${what} ${paths.slice(0, 10).join(', ')}${paths.length > 10 ? ', ...' : ''}, outside this brain's source root (${roots.join(', ')}).`,
    `Commit only files under the source root. Files elsewhere in ${root} belong to other projects or writers; commit those with their own tools. Nothing was staged or committed.`,
    { detail: JSON.stringify({ roots, paths }) });
}

// ── Commit ──────────────────────────────────────────────────────────────────

function indexLocked(r: GitRun): boolean {
  return /index\.lock': File exists|Unable to create '.*index\.lock'/.test(r.stderr);
}

/** Run an index-writing git command; a lockless git holding index.lock gets a bounded, jittered retry. */
function withIndexRetry(root: string, args: string[], what: string, env?: NodeJS.ProcessEnv, input?: string): GitRun {
  for (let attempt = 0; ; attempt++) {
    const r = git(root, args, { env, timeoutMs: 120_000, input });
    if (r.code === 0 || !indexLocked(r)) return r;
    if (attempt >= INDEX_LOCK_RETRIES) {
      const lock = absGitPath(root, 'index.lock');
      let ageMs = 0;
      try { ageMs = Date.now() - statSync(lock).mtimeMs; } catch { /* gone */ }
      if (ageMs > 10 * 60_000) {
        throw opError('git_index_stale', `A Git index lock older than 10 minutes blocks ${root}: ${lock}.`,
          `If no git command is running in that checkout, remove ${lock}, then rerun. Nothing was committed.`, { detail: lock });
      }
      throw opError('git_index_locked', `Another git process kept ${root}'s index locked during ${what}.`,
        'A git command that does not take the commit lock is running in this checkout. Retry shortly; nothing was committed.', { detail: lock, retryable: true });
    }
    Atomics.wait(sleeper, 0, 0, 100 * 2 ** attempt + Math.floor(Math.random() * 100));
  }
}

/** A staged rename (`git mv`) commits both sides: committing only the new name would publish a duplicate and leave the deletion staged for another writer's commit. */
function withRenamePartners(root: string, rel: string[], env?: NodeJS.ProcessEnv): string[] {
  const fields = git(root, ['diff', '--cached', '-M', '--name-status', '-z'], { env }).stdout.split('\0');
  const out = new Set(rel);
  for (let i = 0; i < fields.length;) {
    const status = fields[i];
    if (!status) break;
    if (/^[RC]/.test(status)) {
      const [from, to] = [fields[i + 1], fields[i + 2]];
      if (status.startsWith('R') && (out.has(from) || out.has(to))) { out.add(from); out.add(to); }
      i += 3;
    } else i += 2;
  }
  return [...out];
}

/** Index entries under `rel` that differ from HEAD, whoever staged them, with rename detection off so both sides of a rename are listed. */
function stagedPaths(root: string, rel: string[]): string[] {
  return git(root, ['diff', '--cached', '--no-renames', '--name-only', '-z', '--', ...literalPathspecs(rel)]).stdout.split('\0').filter(Boolean);
}

/** The index entries under `rel` as `ls-files -s` records, so a failed commit can put them back exactly. */
function indexEntries(root: string, rel: string[]): string[] {
  return git(root, ['ls-files', '-s', '-z', '--', ...literalPathspecs(rel)]).stdout.split('\0').filter(Boolean);
}

/**
 * Put the index under `rel` back to `before` after a commit that did not land:
 * `git add` already staged the paths, and an entry left staged in the shared
 * index is what the next writer's commit without paths sweeps up. `--index-info`
 * writes fresh entries, so the skip-worktree and assume-unchanged flags in
 * `flagged` (`ls-files -v` records) are set again: a dropped flag lets the
 * next commit publish the edit it hid.
 */
function restoreIndex(root: string, rel: string[], before: string[], flagged: string[]): void {
  const pathOf = (line: string) => line.slice(line.indexOf('\t') + 1);
  const kept = new Set(before.map(pathOf));
  const zero = '0'.repeat(git(root, ['rev-parse', 'HEAD']).stdout.trim().length || 40);
  const records = [...indexEntries(root, rel).map(pathOf).filter(p => !kept.has(p)).map(p => `0 ${zero}\t${p}`), ...before];
  if (records.length) withIndexRetry(root, ['update-index', '-z', '--index-info'], 'index restore', undefined, records.map(l => `${l}\0`).join(''));
  for (const [option, pattern] of [['--skip-worktree', /^[sS] /], ['--assume-unchanged', /^[a-z] /]] as const) {
    const paths = flagged.filter(entry => pattern.test(entry)).map(entry => `${entry.slice(2)}\0`);
    if (paths.length) withIndexRetry(root, ['update-index', option, '-z', '--stdin'], 'index restore', undefined, paths.join(''));
  }
}

/**
 * `untrack`: commit the removal of the named paths instead (#7753); `db_only` (GST-2519, a managed canonical worktree)
 * admits only files under a storage.db_only dir HEAD's gbrain.yml declares (untrackAdmitted).
 */
interface CommitScope { roots: string[]; lockPath: string; markHeld: boolean; bases?: ReadonlyMap<string, string>; untrack?: 'any' | { dbOnly: ManagedFilesystemRoot; pages?: UntrackPageVerdict } }

/** A named path `git add -A` left out of the index while still exiting 0 (GST-2116). */

/**
 * GST-2116: a run that left a named path uncommitted fails, after committing (and, on a classic checkout, pushing) the
 * rest, so a write is never reported as saved when it is not. In a managed canonical worktree a skipped page is the
 * owner's to save (`writer_coordinator_required`); anything else is `commit_paths_skipped`.
 */
function skippedPathsError(root: string, skipped: SkippedPath[], result: CommitPushResult, managed?: ManagedFilesystemRoot, publish?: unknown, dryRun = false): OperationError {
  const list = `${skipped.slice(0, 20).map(s => `${s.path} (${s.reason}: ${s.why})`).join(', ')}${skipped.length > 20 ? ', ...' : ''}`;
  const pushed = !!result.committed && (result.outcome === 'pushed' || result.outcome === 'pushed_checkout_lagging');
  const done = result.committed
    ? `The other named paths were committed as ${result.committed.slice(0, 7)}${pushed ? ` and pushed to ${result.remote}/${result.branch}` : ', not pushed'}.`
    : 'Nothing was committed.';
  const failed = publish as { code?: string; message?: string; detail?: string } | undefined;
  const rest = `${done}${failed ? ` The push failed too (${failed.code ?? 'error'}): ${failed.message ?? String(publish)}` : ''}`;
  const detail = JSON.stringify({ ...(dryRun ? { dry_run: true } : {}), skipped, committed: result.committed, ...(pushed ? { pushed: result.sha } : {}), branch: result.branch,
    ...(failed ? { publish: { code: failed.code ?? null, detail: failed.detail ?? null } } : {}) });
  const docs = 'docs/guides/shared-checkout-git.md#outcomes';
  const flagged = skipped.filter(s => s.reason !== 'not_staged');
  // One update-index call per flag: given both, git clears only the first.
  const clears = (['assume_unchanged', 'skip_worktree'] as const)
    .map(reason => ({ flag: reason === 'skip_worktree' ? '--no-skip-worktree' : '--no-assume-unchanged', paths: flagged.filter(s => s.reason === reason).map(s => s.path) }))
    .filter(c => c.paths.length)
    .map(c => ['git', '-C', root, 'update-index', c.flag, '--', ...c.paths]);
  const clearCommand = clears.map(argv => shellQuote(argv)).join(' && ');
  const flagNote = 'an assume-unchanged or skip-worktree flag; an editor, an indexer or a sparse checkout can leave one, and people also set skip-worktree on purpose to keep local edits out of commits, so clearing it commits those edits';
  const chain = (steps: string[][], last?: Action): Action | undefined => steps.reduceRight<Action | undefined>((then, argv) =>
    ({ argv, consent: [], actor: 'agent', requires_exclusive: false, why: 'Clears the flag so git sees the edit on disk; the file keeps its bytes.', ...(then ? { then } : {}) }), last);
  const removals = skipped.filter(s => s.reason === 'staged_for_removal').map(s => s.path);
  if (removals.length && removals.length === skipped.length) {
    const quoted = removals.map(p => shellQuote([p])).join(' ');
    return opError('commit_paths_skipped', 'git did not commit ' + skipped.length + ' named path(s) in ' + root + ': ' + list + '. They are staged for removal from Git (git rm --cached) while the files stay on disk, and commit-push does not commit that removal. ' + rest,
      'To stop tracking them and keep the files, run gbrain git commit-push --untrack -m <msg> -- ' + quoted + '; to keep them tracked, git -C ' + shellQuote([root]) + ' restore --staged -- ' + quoted + '.',
      { docs: 'docs/guides/shared-checkout-git.md#untrack', detail,
        why: 'Something took these files out of the index while leaving them on disk; committing would either publish that removal or quietly add back what someone removed, and only the user knows which was meant.',
        fix: { ask_user: true, consent: [], actor: 'user', requires_exclusive: false,
          argv: ['git', '-C', root, 'restore', '--staged', '--', ...literalPathspecs(removals)],
          why: 'Puts the files back in the index as HEAD has them, so the next commit-push commits their edits; the bytes on disk are untouched.',
          user_message: 'Git has ' + removals.slice(0, 10).join(', ') + ' staged for removal while the files are still on disk, so they were not committed. Keep them in Git (git restore --staged), or stop tracking them and keep the files (gbrain git commit-push --untrack)?',
          verify: { argv: ['git', '-C', root, 'status', '--porcelain', '--', ...literalPathspecs(removals)] } } });
  }
  const pages = managed ? skipped.filter(s => isSyncable(s.path)) : [];
  if (managed && pages.length) {
    const source = managed.sourceId ? { argv: ['--source-id', managed.sourceId], mcp: { source_id: managed.sourceId } } : { argv: [], mcp: {} };
    const put: Action = { argv: ['gbrain', 'put', ...source.argv, '<slug>'],
      mcp: { tool: 'put_page', arguments: { slug: '<slug>', ...source.mcp, content: '<the page file>' } },
      inputs: [{ name: 'slug', how: `Each listed page path without its .md extension; pass the file's content on stdin: ${pages.slice(0, 5).map(s => s.path).join(', ')}` }],
      consent: [], actor: 'agent', requires_exclusive: false,
      why: 'put_page saves the page through the owner, which writes the file, commits only that path and pushes it.',
      verify: { argv: ['gbrain', 'sources', 'writer', 'status', managed.sourceId ?? '<source>', '--json'] } };
    return opError('writer_coordinator_required',
      `${root} is the managed canonical worktree${managed.sourceId ? ` of source ${managed.sourceId}` : ''}, and git did not commit ${skipped.length} named path(s): ${list}. ${rest}`,
      `${clears.length ? `First, with the user's agreement, clear the flags (${clearCommand}), since the owner's own Git step cannot see a flagged edit either. ` : ''}Then save those pages through gbrain (put_page, edit_page or capture; on the CLI, gbrain put${managed.sourceId ? ` --source-id ${managed.sourceId}` : ''} with the page slug and the page on stdin): the persistence owner commits and pushes them. Never commit page files around it.`,
      { docs, detail,
        why: 'The persistence owner is the only Git writer of pages in a managed worktree; a page file written there directly and left uncommitted is neither in Git nor in the database, so reporting success would lose the write silently.',
        fix: { ...(chain(clears, put) ?? put), ask_user: true,
          user_message: `These page files were written straight into the managed checkout and git did not commit them: ${pages.slice(0, 10).map(s => s.path).join(', ')}.${clears.length ? ` Git hides their edits (${flagNote}); clear the flags first.` : ''} Save each one through gbrain (put_page), which replaces the stored page with the file's content?` } });
  }
  return opError('commit_paths_skipped', `git did not commit ${skipped.length} named path(s) in ${root}: ${list}. ${rest}`,
    flagged.length
      ? `Git hides edits to the assume_unchanged and skip_worktree paths from commits. With the user's agreement clear the flags (${clearCommand}), then rerun the same commit-push.`
      : 'Git did not stage the not_staged paths (a file inside a nested Git repository is the usual cause). Move them into the brain checkout proper, or commit them in their own repository, then rerun.',
    { docs, detail,
      why: 'git add stages nothing and still exits 0 for a modified file flagged assume-unchanged or skip-worktree, or a file inside a nested repository; reporting success would leave the write uncommitted with nothing in any log.',
      fix: flagged.length
        ? { ...chain(clears)!, ask_user: true,
          user_message: `Git is set to ignore edits to ${flagged.slice(0, 10).map(s => s.path).join(', ')} (${flagNote}), so they were not committed. Clear those flags and commit the edits?`,
          verify: { argv: ['git', '-C', root, 'ls-files', '-v', '--', ...flagged.map(s => s.path)] } }
        : { consent: [], actor: 'user', requires_exclusive: false,
          why: 'Git cannot commit a file that belongs to another repository, so only moving it or committing it there settles it.',
          user_message: `Git did not commit ${skipped.slice(0, 10).map(s => s.path).join(', ')} in ${root} (a file inside a nested Git repository is the usual cause). Where should they be committed?` } });
}

/** `--base` keyed by the repository-relative path it names; each must also be a committed path. */
function scopeBases(root: string, opts: CommitPushOptions, rel: string[]): Map<string, string> | undefined {
  if (!opts.bases?.size) return undefined;
  const scoped = new Map<string, string>();
  for (const [path, blob] of opts.bases) {
    const [key] = scopePaths(root, [path], opts.cwd ?? process.cwd());
    if (!key || !rel.includes(key)) throw opError('commit_paths_invalid', `--base names ${path}, which is not one of the paths to commit.`, 'Name every --base path after -- as well.');
    scoped.set(key, blob);
  }
  return scoped;
}

/**
 * What commitPaths refuses before anything is staged (and the dry run with it): a path outside the source root(s), a
 * `--base` blob HEAD no longer holds, and a file another writer already staged under a named directory (name it to claim it).
 */
function admitPaths(root: string, rel: string[], roots: string[], bases?: ReadonlyMap<string, string>, dryRun = false): void {
  const outside = rel.filter(p => !insideSourceRoots(p, roots));
  if (outside.length) throw outsideRootError(root, roots, outside, 'Refusing to commit');
  assertNoUnmergedPaths(root, rel);
  for (const [path, base] of bases ?? []) {
    const head = git(root, ['rev-parse', '--verify', '-q', `HEAD:${path}`]).stdout.trim() || 'absent';
    if (head !== base) throw opError('commit_base_moved', `${path} changed at HEAD since the writer read it (base ${base}, HEAD ${head}).`,
      `Nothing was staged or committed. Read ${path} at HEAD again (git -C ${root} show HEAD:${path}), redo the change on it, and rerun with --base ${path}=${head}.`,
      { detail: JSON.stringify({ path, base, head }), docs: 'docs/guides/shared-checkout-git.md#base-check' });
  }
  const swept = stagedPaths(root, rel).filter(p => !rel.includes(p) && rel.some(spec => covers(spec, p)));
  const removed = new Set(stagedRemovals(root, swept));
  if (swept.length && swept.every(p => removed.has(p))) {
    const branch = git(root, ['symbolic-ref', '--quiet', '--short', 'HEAD']).stdout.trim();
    throw skippedPathsError(root, swept.map(path => ({ path, reason: 'staged_for_removal' as const, why: STAGED_FOR_REMOVAL_WHY })),
      { outcome: 'nothing_to_commit', sha: null, committed: null, branch, remote: '', paths: rel, integrated: 0, checkout: 'unchanged' }, undefined, undefined, dryRun);
  }
  if (swept.length) {
    const list = `${swept.slice(0, 10).join(', ')}${swept.length > 10 ? ', ...' : ''}`;
    throw opError('commit_prestaged_paths', `${swept.length} file(s) under the named path(s) were already staged by another writer: ${list}.`,
      'Nothing was staged or committed. If they are yours, name each file explicitly; otherwise leave them to the writer that staged them, or unstage them with the user\'s agreement (git restore --staged -- <file>; the working tree keeps its bytes). Files a parked gbrain Git effect left staged are gbrain\'s own: gbrain sources writer status lists the parked effects with their source and request id, and gbrain sources writer retry-effects with that source and --request-id commits them.',
      { detail: JSON.stringify({ paths: swept }), fix: { ask_user: true, consent: [], actor: 'user', requires_exclusive: false,
        argv: ['git', '-C', root, 'restore', '--staged', '--', ...literalPathspecs(swept)],
        why: 'Another writer staged these files; committing them would publish whatever that writer had in progress, and unstaging them drops its staging.',
        user_message: `Files already staged by another writer sit under the path you asked to commit (${list}). Commit only the files you name, or unstage those (their bytes stay on disk)?`,
        docs: 'docs/guides/shared-checkout-git.md#outcomes' } });
  }
}

/** The named paths' `ls-files -v` records that carry the assume-unchanged or skip-worktree flag. */
function flaggedEntries(root: string, rel: string[]): string[] {
  return gitOk(root, ['ls-files', '-v', '-z', '--', ...literalPathspecs(rel)], 'ls-files -v').split('\0').filter(entry => /^[a-zS] /.test(entry));
}

/**
 * Stage `rel` for a commit; returns the named skip-worktree files on disk it left out. GST-2118: git add refuses a named
 * skip-worktree file that is on disk; it is left to the skipped-path check, so the other paths still commit. #7984: a
 * tracked path stages with `add -u`, because `add -A` refuses a deletion whose only match left is an ignored path;
 * visible untracked files stage with `add -A`; a path already staged as deleted is staged. Any other path keeps git's own
 * refusal (missing, or only an ignored untracked file). `indexCopy` (#7752) stages into the index copy `env` names, with
 * no index-lock retry, so a dry run sees the rename pairs the real staging makes.
 */
function stagePaths(root: string, rel: string[], before: string[], flagged: string[], env?: NodeJS.ProcessEnv, indexCopy = false): Set<string> {
  const skipWorktree = new Set(flagged.filter(entry => /^[sS] /.test(entry)).map(entry => entry.slice(2)));
  const sparse = new Set([...skipWorktree].filter(p => rel.includes(p) && existsSync(join(root, p))));
  const live = rel.filter(p => !sparse.has(p));
  const listed = (args: string[]) => live.length ? git(root, [...args, '-z', '--', ...literalPathspecs(live)], { env }).stdout.split('\0').filter(Boolean) : [];
  const tracked = before.map(line => line.slice(line.indexOf('\t') + 1)).filter(p => !skipWorktree.has(p));
  const untracked = listed(['ls-files', '--others', '--exclude-standard']);
  const deleted = listed(['diff', '--cached', '--no-renames', '--name-only', '--diff-filter=D']);
  const matching = (paths: string[]) => live.filter(spec => paths.some(p => covers(spec, p)));
  const matched = new Set(matching([...tracked, ...untracked, ...deleted]));
  const unmatched = live.filter(spec => !matched.has(spec));
  for (const [mode, specs] of [['-u', matching(tracked)], ['-A', matching(untracked)], ['-A', unmatched]] as const) {
    if (!specs.length) continue;
    const args = ['add', mode, '--', ...literalPathspecs(specs)];
    const add = indexCopy ? git(root, args, { env }) : withIndexRetry(root, args, 'git add', env);
    if (add.code !== 0) throw opError('commit_paths_invalid', 'git add refused the given paths.', add.stderr.trim().slice(0, 300) || 'Check the paths exist or are tracked.');
  }
  return sparse;
}

/**
 * Stage and commit exactly `rel` (the caller holds the commit lock), after admitPaths. A commit git refuses leaves the
 * index as it found it. `skipped` lists the named paths git left out (GST-2116); the rest are still committed.
 */
function commitPaths(root: string, rel: string[], message: string, scope: CommitScope): { sha: string | null; skipped: SkippedPath[] } {
  admitPaths(root, rel, scope.roots, scope.bases);
  const dirtyBefore = directoryStatus(root, rel);
  const before = indexEntries(root, rel);
  const flagged = flaggedEntries(root, rel);
  if (scope.untrack) return { sha: untrackPaths(root, rel, message, scope, before, flagged), skipped: [] };
  let landed: { committed: boolean; paths: string[]; listed: string[] };
  try {
    const sparse = stagePaths(root, rel, before, flagged);
    const paths = withRenamePartners(root, rel);
    const partners = paths.filter(p => !insideSourceRoots(p, scope.roots));
    if (partners.length) throw outsideRootError(root, scope.roots, partners, 'A staged rename would commit');
    // A file git did not index would fail `commit --only` for every path; it is left out here and reported as skipped.
    const listed = gitOk(root, ['ls-files', '-v', '-z', '--', ...literalPathspecs(paths)], 'ls-files -v').split('\0').filter(Boolean);
    const unindexed = new Set(unindexedFiles(root, paths, listed));
    const staged = paths.filter(p => !unindexed.has(p) && !sparse.has(p));
    if (!staged.length || git(root, ['diff', '--cached', '--quiet', '--', ...literalPathspecs(staged)]).code === 0) {
      landed = { committed: false, paths, listed };
    } else {
      const env = { [COMMIT_VIA_ENV]: scope.lockPath, ...(scope.markHeld ? { [COMMIT_LOCK_ENV]: scope.lockPath } : {}) };
      // #7759: literal per path, never git's global --literal-pathspecs: Git exports that to the commit's hooks, where a
      // guard's glob pathspec ('*.json') then matches nothing and lets the commit through.
      recordIntent(root, { writer: 'commit_push', head_before: git(root, ['rev-parse', '--verify', '--quiet', 'HEAD']).stdout.trim() || null, message });
      const commit = withIndexRetry(root, ['commit', '--only', '-m', message, '--', ...literalPathspecs(staged)], 'git commit', env);
      if (commit.code !== 0) {
        throw opError('git_unavailable', `git commit failed in ${root}; the paths were unstaged again and keep their bytes.`,
          `${commit.stderr.trim().slice(0, 300)} A missing git identity (user.name, user.email) or a refusing pre-commit hook are common causes.`);
      }
      landed = { committed: true, paths, listed };
    }
  } catch (e) {
    try { restoreIndex(root, rel, before, flagged); } catch { /* the index lock outlasted the retries; the error below still stands */ }
    throw e;
  }
  // GST-2116: after the try, so a failure from here on never restores the index under a commit that landed.
  const sha = landed.committed ? gitOk(root, ['rev-parse', 'HEAD'], 'rev-parse HEAD') : null;
  if (sha) recordCommit(root, { sha, writer: 'commit_push' });
  return { sha, skipped: unstagedPaths(root, landed.paths, landed.listed, dirtyBefore, sha) };
}

/** The source roots a dry run checks paths against; a managed canonical worktree refuses --allow-outside-source-root as its real run does. */
function previewRoots(root: string, allowOutsideSourceRoot?: boolean): { managed: ManagedFilesystemRoot | null; roots: string[] } {
  const managed = managedFilesystemRootFor(root);
  if (managed && allowOutsideSourceRoot) {
    throw opError('commit_paths_invalid', `${root} is the managed canonical worktree${managed.sourceId ? ` of source ${managed.sourceId}` : ''}: commit-push there only commits the paths you name.`,
      `Run gbrain git commit-push with only -m and the page paths after --; gbrain sources refresh${managed.sourceId ? ` ${managed.sourceId}` : ''} brings remote commits in.`);
  }
  return { managed, roots: allowOutsideSourceRoot ? [''] : configuredSourceRoots(root) };
}

/**
 * #7752: `--dry-run` of a commit runs the real run's path checks in its order: the source roots, `--base` and files
 * another writer staged (admitPaths), the real run's staging (stagePaths) and the source roots of a staged rename's other
 * side. Staging goes into a temporary copy of the index, so the preview takes no lock and leaves the real index and the
 * worktree as they were (git may add loose objects for the staged files); each refusal carries the real run's code and text.
 */
export function previewPaths(root: string, rel: string[], opts: { allowOutsideSourceRoot?: boolean; bases?: Map<string, string>; cwd?: string } = {}): void {
  const { managed, roots } = previewRoots(root, opts.allowOutsideSourceRoot);
  admitPaths(root, rel, roots, scopeBases(root, { repo: root, bases: opts.bases, cwd: opts.cwd }, rel), true);
  const dir = mkdtempSync(join(tmpdir(), 'gbrain-preview-'));
  try {
    const index = join(dir, 'index');
    const live = absGitPath(root, 'index');
    if (existsSync(live)) copyFileSync(live, index);
    const env = { GIT_INDEX_FILE: index };
    stagePaths(root, rel, indexEntries(root, rel), flaggedEntries(root, rel), env, true);
    const partners = withRenamePartners(root, rel, env).filter(p => !insideSourceRoots(p, roots));
    if (partners.length) throw outsideRootError(root, roots, partners, 'A staged rename would commit');
    const listed = gitOk(root, ['ls-files', '-v', '-z', '--', ...literalPathspecs(rel)], 'ls-files -v', { env }).split('\0').filter(Boolean);
    const skipped = unstagedPaths(root, rel, listed, new Map(), null);
    const branch = git(root, ['symbolic-ref', '--quiet', '--short', 'HEAD']).stdout.trim();
    if (skipped.length) throw skippedPathsError(root, skipped, { outcome: 'nothing_to_commit', sha: null, committed: null, branch, remote: '', paths: rel, integrated: 0, checkout: 'unchanged' }, managed ?? undefined, undefined, true);
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
}

/**
 * `--dry-run --untrack`: the real run's path checks (source roots, the files HEAD holds, and in a managed canonical
 * worktree the storage.db_only admission) with no lock taken and nothing written; each refusal is the real run's.
 */
export function previewUntrack(root: string, rel: string[], opts: { allowOutsideSourceRoot?: boolean; untrackPages?: UntrackPageVerdict } = {}): string[] {
  const { managed, roots } = previewRoots(root, opts.allowOutsideSourceRoot);
  const outside = rel.filter(p => !insideSourceRoots(p, roots));
  if (outside.length) throw outsideRootError(root, roots, outside, 'Refusing to commit');
  return managed ? untrackAdmitted(root, rel, managed, opts.untrackPages) : untrackTargets(root, rel);
}

/**
 * #7753: commit the removal of `rel` from Git, keeping the files on disk, under the caller's commit lock. The index
 * loses the entries (`git rm --cached`), and the commit is built from HEAD in a temporary index (`commit --only` would
 * stage the files again), so nothing else staged rides along. It must change exactly the files HEAD held under `rel`,
 * each deleted: a commit carrying anything else (a pre-commit hook staging a sibling) is taken back before anything is
 * published, and the index is restored.
 */
function untrackPaths(root: string, rel: string[], message: string, scope: CommitScope, before: string[], flagged: string[]): string {
  const removed = scope.untrack === 'any' || !scope.untrack ? untrackTargets(root, rel) : untrackAdmitted(root, rel, scope.untrack.dbOnly, scope.untrack.pages);
  const parent = gitOk(root, ['rev-parse', 'HEAD'], 'rev-parse HEAD');
  const rm = withIndexRetry(root, ['rm', '--cached', '-r', '-q', '--ignore-unmatch', '--', ...literalPathspecs(rel)], 'git rm --cached');
  if (rm.code !== 0) {
    try { restoreIndex(root, rel, before, flagged); } catch { /* the refusal below still stands */ }
    throw opError('commit_paths_invalid', 'git rm --cached refused the given paths.', rm.stderr.trim().slice(0, 300) || 'Check the paths exist or are tracked.');
  }
  const dir = mkdtempSync(join(tmpdir(), 'gbrain-untrack-'));
  try {
    const env = { GIT_INDEX_FILE: join(dir, 'index') };
    gitOk(root, ['read-tree', parent], 'read-tree', { env });
    gitOk(root, ['update-index', '-z', '--force-remove', '--stdin'], 'update-index', { env, input: removed.map(p => `${p}\0`).join('') });
    recordIntent(root, { writer: 'commit_push', head_before: parent, message });
    const commit = git(root, ['commit', '-q', '-m', message], { timeoutMs: 120_000,
      env: { ...env, [COMMIT_VIA_ENV]: scope.lockPath, ...(scope.markHeld ? { [COMMIT_LOCK_ENV]: scope.lockPath } : {}) } });
    if (commit.code !== 0) {
      throw opError('git_unavailable', `git commit failed in ${root}; the paths are tracked again and keep their bytes.`,
        `${commit.stderr.trim().slice(0, 300)} A missing git identity (user.name, user.email) or a refusing pre-commit hook are common causes.`);
    }
    const head = gitOk(root, ['rev-parse', 'HEAD'], 'rev-parse HEAD');
    recordCommit(root, { sha: head, writer: 'commit_push' });
    const fields = git(root, ['diff-tree', '-r', '--no-renames', '--name-status', '-z', parent, head]).stdout.split('\0').filter(Boolean);
    const landed = new Set(fields.flatMap((status, i) => (i % 2 ? [] : [`${status}\t${fields[i + 1]}`])));
    const wanted = new Set(removed.map(p => `D\t${p}`));
    const extra = [...landed].filter(e => !wanted.has(e)).map(e => e.slice(e.indexOf('\t') + 1));
    const missing = removed.filter(p => !landed.has(`D\t${p}`));
    const first = git(root, ['rev-parse', '--verify', '--quiet', `${head}^1`]).stdout.trim();
    if (first === parent && !extra.length && !missing.length) return head;
    const undo = git(root, ['update-ref', '-m', 'gbrain: take back an untrack commit that changed other paths', 'HEAD', first, head]);
    throw opError('git_unavailable', `The untrack commit ${first !== parent ? 'was built on a HEAD that moved' : `changed ${[...extra, ...missing].slice(0, 10).join(', ')} beyond deleting the named paths`}, so ${undo.code === 0 ? 'it was taken back and nothing is committed' : `commit ${head.slice(0, 12)} is left unpublished`}.`,
      'A pre-commit hook or another process changed the commit. Rerun the same gbrain git commit-push --untrack command once it is done.');
  } catch (e) {
    try { restoreIndex(root, rel, before, flagged); } catch { /* the index lock outlasted the retries; the error below still stands */ }
    throw e;
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
}

// ── Pending write-through ───────────────────────────────────────────────────

export interface PendingWriteThrough { path: string; since: string }

const PENDING_NOTED = new Set(['commit_lock_busy', 'git_index_locked', 'git_index_stale', 'git_unavailable', 'git_command_stopped', 'git_operation_in_progress', 'commit_paths_unmerged']);

function readPendingFile(file: string, into: Map<string, string>): void {
  let text: string;
  try { text = readFileSync(file, 'utf8'); } catch { return; }
  for (const line of text.split('\n')) {
    const tab = line.indexOf('\t');
    if (tab === -1) continue;
    let path: unknown;
    try { path = JSON.parse(line.slice(tab + 1)); } catch { continue; }
    const since = line.slice(0, tab);
    if (typeof path === 'string' && path && (!into.has(path) || since < into.get(path)!)) into.set(path, since);
  }
}

/** Write-through files gbrain wrote in this checkout but could not commit, oldest first. A path committed since stays listed until the next locked commit settles the ledger. */
export function readPendingWriteThrough(repo: string): PendingWriteThrough[] {
  try {
    const file = absGitPath(checkoutRoot(repo), PENDING_NAME);
    const entries = new Map<string, string>();
    readPendingFile(file, entries);
    readPendingFile(`${file}.settle`, entries);
    return [...entries].map(([path, since]) => ({ path, since })).sort((a, b) => a.since.localeCompare(b.since));
  } catch {
    return [];
  }
}

/** The pending ledger's files that still differ from HEAD (doctor's `dirty_age`); the others were committed since. */
export function pendingWriteThroughStillDirty(repo: string): PendingWriteThrough[] {
  const pending = readPendingWriteThrough(repo);
  if (!pending.length) return [];
  const dirty = dirtyPaths(checkoutRoot(repo), pending.map(e => e.path));
  return pending.filter(e => dirty.has(e.path));
}

/**
 * Appends without the lock (O_APPEND), so a writer that could not get it still records its file. `root` is the checkout
 * root and `paths` are relative to it (`scopePaths`). The derived write-through also records each file right after writing
 * it (#8073), so a crash before its commit leaves the file for the next locked commit to sweep.
 */
export function notePending(root: string, paths: string[]): void {
  try { appendFileSync(absGitPath(root, PENDING_NAME), paths.map(p => `${new Date().toISOString()}\t${JSON.stringify(p)}\n`).join('')); } catch { /* best-effort */ }
}

/** Which of `paths` differ from HEAD in the index or the working tree. */
function dirtyPaths(root: string, paths: string[]): Set<string> {
  const out = new Set<string>();
  for (let i = 0; i < paths.length; i += 500) {
    const specs = literalPathspecs(paths.slice(i, i + 500));
    // GST-2118: status is blind to an assume-unchanged or skip-worktree entry, so a flagged edit is read from HEAD.
    for (const { path } of flaggedChanges(root, git(root, ['ls-files', '-v', '-z', '--', ...specs]).stdout.split('\0').filter(Boolean))) out.add(path);
    const entries = git(root, ['status', '--porcelain', '-z', '--untracked-files=all', '--', ...specs]).stdout.split('\0');
    for (let j = 0; j < entries.length; j++) {
      if (entries[j].length < 4) continue;
      out.add(entries[j].slice(3));
      if (/^[RC]/.test(entries[j])) j++;
    }
  }
  return out;
}

/** Drop ledger entries whose file no longer differs from HEAD (the caller holds the commit lock). New lines appended meanwhile go to a fresh ledger file. */
export function settlePending(root: string): void {
  try {
    const file = absGitPath(root, PENDING_NAME);
    const settle = `${file}.settle`;
    const moved = `${file}.${process.pid}.tmp`;
    if (existsSync(file)) renameSync(file, moved);
    const entries = new Map<string, string>();
    readPendingFile(settle, entries);
    readPendingFile(moved, entries);
    const dirty = (() => { try { return dirtyPaths(root, [...entries.keys()]); } catch { return null; } })();
    const keep = [...entries].filter(([path]) => !dirty || dirty.has(path)).map(([path, since]) => `${since}\t${JSON.stringify(path)}\n`);
    if (keep.length) { writeFileSync(`${settle}.tmp`, keep.join('')); renameSync(`${settle}.tmp`, settle); }
    else rmSync(settle, { force: true });
    rmSync(moved, { force: true });
  } catch { /* best-effort: the ledger only feeds retries and doctor */ }
}

/**
 * Commit-only entry for gbrain's own write paths (write-through pages, facts
 * fences, takes, timeline, lint fixes), always under the commit lock. A writer
 * holding the lock past `lockWaitMs` makes this fail `commit_lock_busy` (the
 * file write itself stands) and the file goes into the pending ledger, which
 * the next locked write-through or `gbrain git commit-push --pending` commits and
 * doctor's `dirty_age` reports. It never commits without the lock: that races
 * other writers on the shared index. Paths must sit under `repo` (the source
 * root). No marker is set, so the post-commit hook publishes. Returns the new
 * commit, or null when the paths had no change. A named path git left out fails
 * `commit_paths_skipped` after the rest is committed (GST-2116).
 */
export function commitPathsLocked(repo: string, rel: string[], message: string, opts: { lockWaitMs: number }): string | null {
  const root = checkoutRoot(repo);
  assertManagedFilesystemWrite(root);
  assertNoOperationInProgress(root);
  const paths = scopePaths(root, rel, root);
  const own = relative(realpathSync(root), realpathSync(repo)).split('\\').join('/');
  const roots = [relativeEscapesRoot(own) ? '' : own];
  let lock: CommitLock;
  try { lock = acquireCommitLock(root, opts.lockWaitMs); } catch (e) {
    if (PENDING_NOTED.has((e as { code?: string }).code ?? '')) notePending(root, paths);
    throw e;
  }
  try {
    const pending = withoutUnmergedPaths(root, [...dirtyPaths(root, readPendingWriteThrough(root).map(e => e.path).filter(p => !paths.includes(p) && insideSourceRoots(p, roots)))]);
    const scope = { roots, lockPath: lock.lockPath, markHeld: false };
    let commit: ReturnType<typeof commitPaths>;
    try {
      commit = commitPaths(root, [...paths, ...pending], pending.length ? `${message} (+${pending.length} pending write-through file(s))` : message, scope);
    } catch (e) {
      if (!pending.length) throw e;
      commit = commitPaths(root, paths, message, scope);
    }
    // GST-2118: a file git left out stays in the ledger, so doctor dirty_age reports it and --pending retries it loudly.
    const ownSkipped = commit.skipped.filter(s => paths.includes(s.path));
    if (ownSkipped.length) notePending(root, ownSkipped.map(s => s.path));
    settlePending(root);
    if (ownSkipped.length) {
      const branch = git(root, ['symbolic-ref', '--quiet', '--short', 'HEAD']).stdout.trim();
      throw skippedPathsError(root, ownSkipped, { outcome: commit.sha ? 'committed_local' : 'nothing_to_commit', sha: commit.sha, committed: commit.sha, branch, remote: '', paths, integrated: 0, checkout: 'unchanged' });
    }
    return commit.sha;
  } catch (e) {
    if (PENDING_NOTED.has((e as { code?: string }).code ?? '')) notePending(root, paths);
    throw e;
  } finally {
    lock.release();
  }
}

// ── In-memory integrate ─────────────────────────────────────────────────────

interface MergeTree {
  /** The merged tree; with conflicts, a placeholder every conflicted path must be resolved over. */
  tree: string | null;
  /** Raw repo-relative paths (NUL-delimited from git, never C-quoted). */
  conflicts: string[];
  /** Conflicts that are not one path's content (file/directory, renames): never resolvable by a blob choice. */
  structural: string[];
}

/** merge-tree conflict types a per-path blob choice fully resolves; anything else is structural. */
const RESOLVABLE_CONFLICTS = new Set(['CONFLICT (contents)', 'CONFLICT (add/add)', 'CONFLICT (modify/delete)', 'CONFLICT (binary)']);

const versions = new Map<string, [number, number]>();
function cachedGitVersion(root: string): [number, number] {
  let v = versions.get(root);
  if (!v) { v = gitVersion(root); versions.set(root, v); }
  return v;
}

/** `--no-write-fetch-head` exists from git 2.29; older git just writes FETCH_HEAD. */
function fetchFlags(root: string): string[] {
  const [maj, min] = cachedGitVersion(root);
  return ['--no-tags', ...(maj > 2 || (maj === 2 && min >= 29) ? ['--no-write-fetch-head'] : [])];
}

/**
 * merge-tree --write-tree on git >= 2.38; else (or with the GBRAIN_GIT_NO_MERGE_TREE=1 test seam) a 3-way read-tree
 * that treats any same-path change on both sides as a conflict. `base` replaces the merge base (a replayed commit's
 * parent); merge-tree takes it from git 2.40.
 */
function mergeTrees(root: string, ours: string, theirs: string, base?: string): MergeTree {
  const [maj, min] = cachedGitVersion(root);
  if ((maj > 2 || (maj === 2 && min >= (base ? 40 : 38))) && process.env.GBRAIN_GIT_NO_MERGE_TREE !== '1') {
    const r = git(root, ['merge-tree', '--write-tree', '--name-only', '-z', ...(base ? [`--merge-base=${base}`] : []), ours, theirs]);
    if (r.code !== 0 && r.code !== 1) throw opError('git_unavailable', 'git merge-tree failed.', r.stderr.trim().slice(0, 300));
    const f = r.stdout.split('\0');
    const tree = f[0] || null;
    if (r.code === 0) return { tree, conflicts: [], structural: [] };
    let i = 1;
    const conflicts = new Set<string>();
    while (i < f.length && f[i] !== '') conflicts.add(f[i++]);
    i++;
    const structural = new Set<string>();
    while (i < f.length && f[i] !== '') {
      const n = Number(f[i++]);
      if (!Number.isInteger(n) || n < 1) break;
      const paths = f.slice(i, i + n);
      const type = f[i + n] ?? '';
      i += n + 2;
      if (type.startsWith('CONFLICT') && !RESOLVABLE_CONFLICTS.has(type)) for (const p of paths) structural.add(p);
    }
    return { tree, conflicts: [...conflicts], structural: [...conflicts].filter(p => structural.has(p)) };
  }
  const mergeBase = base ?? git(root, ['merge-base', ours, theirs]).stdout.trim();
  if (!mergeBase) throw opError('integrate_conflict', 'The local and remote branches share no history.', 'Reconcile the branches by hand.');
  const dir = mkdtempSync(join(tmpdir(), 'gbrain-integrate-'));
  try {
    const env = { GIT_INDEX_FILE: join(dir, 'index') };
    const read = git(root, ['read-tree', '-m', '-i', '--aggressive', mergeBase, ours, theirs], { env });
    if (read.code !== 0) throw opError('git_unavailable', 'git read-tree failed.', read.stderr.trim().slice(0, 300));
    const unmerged = git(root, ['ls-files', '-u', '-z'], { env }).stdout.split('\0').filter(Boolean);
    if (!unmerged.length) return { tree: gitOk(root, ['write-tree'], 'write-tree', { env }), conflicts: [], structural: [] };
    const conflicts = [...new Set(unmerged.map(l => l.slice(l.indexOf('\t') + 1)))];
    const structural: string[] = [];
    for (const path of conflicts) {
      gitOk(root, ['update-index', '--force-remove', '--', path], 'update-index', { env });
      const mine = unmerged.find(l => l.slice(l.indexOf('\t') + 1) === path && l.split('\t')[0].split(' ')[2] === '2');
      if (!mine) continue;
      const [mode, sha] = mine.split('\t')[0].split(' ');
      if (git(root, ['update-index', '--add', '--cacheinfo', `${mode},${sha},${path}`], { env }).code !== 0) structural.push(path);
    }
    return { tree: gitOk(root, ['write-tree'], 'write-tree', { env }), conflicts, structural };
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
}

const treeOf = (root: string, commit: string) => gitOk(root, ['rev-parse', `${commit}^{tree}`], 'rev-parse tree');

interface Integration extends MergeTree {
  /** Local commits left out because an upstream commit already carries the same patch (`git patch-id`). */
  skipped: string[];
}

const MAX_REPLAY = 500;

/**
 * The tree a publish of `local` over `remote` should carry. A 3-way merge of the two tips
 * counts a local commit whose patch already reached the remote (cherry-picked or rebased there) as a new
 * change again: a remote that edited those lines since conflicts forever, and a remote that reverted it gets
 * the change back silently. So when any local commit is patch-equivalent to an upstream one, the local
 * commits are replayed in memory onto the remote tip instead, oldest first, leaving out the equivalent ones
 * and the clean merges (their content is their parents'). A merge that carries its own resolution, a root
 * commit, or more than MAX_REPLAY commits fall back to the tip merge.
 */
function integrate(root: string, local: string, remote: string): Integration {
  const commits = git(root, ['rev-list', '--reverse', '--topo-order', '--cherry-mark', '--right-only', '--parents', `${remote}...${local}`])
    .stdout.split('\n').filter(Boolean).map(line => {
      const [head, ...parents] = line.split(' ');
      return { sha: head.slice(1), equivalent: head.startsWith('='), parents };
    });
  const tipMerge = (): Integration => ({ ...mergeTrees(root, local, remote), skipped: [] });
  if (!commits.some(c => c.equivalent) || commits.length > MAX_REPLAY) return tipMerge();
  let acc = remote;
  const conflicts = new Set<string>();
  const structural = new Set<string>();
  const skipped: string[] = [];
  for (const c of commits) {
    if (c.equivalent) { skipped.push(c.sha); continue; }
    if (c.parents.length !== 1) {
      if (c.parents.length !== 2) return tipMerge();
      const own = mergeTrees(root, c.parents[0], c.parents[1]);
      if (own.conflicts.length || own.tree !== treeOf(root, c.sha)) return tipMerge();
      continue;
    }
    const step = mergeTrees(root, acc, c.sha, c.parents[0]);
    for (const p of step.conflicts) conflicts.add(p);
    for (const p of step.structural) structural.add(p);
    acc = gitOk(root, ['commit-tree', '--no-gpg-sign', step.tree!, '-p', acc, '-m', 'gbrain: replay'], 'commit-tree');
    recordCommit(root, { sha: acc, writer: 'replay', ref: null });
  }
  return { tree: treeOf(root, acc), conflicts: [...conflicts], structural: [...structural], skipped };
}

interface TreeEntry { mode: string; type: string; sha: string }

function treeEntry(root: string, commit: string, path: string): TreeEntry | null {
  for (const line of git(root, ['ls-tree', '-z', commit, '--', ...literalPathspecs([path])]).stdout.split('\0')) {
    const tab = line.indexOf('\t');
    if (tab === -1 || line.slice(tab + 1) !== path) continue;
    const [mode, type, sha] = line.slice(0, tab).split(' ');
    return { mode, type, sha };
  }
  return null;
}

/** One path's content conflict: a blob (or absent) on every side, no side has it as a directory or under a file. */
function blobConflict(root: string, base: string, ours: string, theirs: string, path: string): boolean {
  const sides = [base, ours, theirs].map(c => (c ? treeEntry(root, c, path) : null));
  if (sides.every(e => !e) || sides.some(e => e && e.type !== 'blob')) return false;
  const parts = path.split('/');
  for (let k = 1; k < parts.length; k++) {
    const prefix = parts.slice(0, k).join('/');
    if ([ours, theirs].some(c => treeEntry(root, c, prefix)?.type === 'blob')) return false;
  }
  return true;
}

const MAX_SUPERSEDED_HISTORY = 200;

/**
 * Content conflicts where the remote's blob is one this checkout held at the same path and then replaced with
 * another blob (a stale clone or writer brought an old copy back): the remote's version is history this side
 * already moved past, so these resolve to ours. Reads the last MAX_SUPERSEDED_HISTORY commits of `ours` that touch
 * the path. A blob ours never held there, a remote deletion, a structural conflict and a path the caller resolves
 * explicitly stay conflicts.
 */
function supersededPaths(root: string, ours: string, theirs: string, merged: MergeTree, explicit?: Map<string, Resolution>): string[] {
  const base = git(root, ['merge-base', ours, theirs]).stdout.trim();
  return merged.conflicts.filter(path => {
    if (explicit?.has(path) || merged.structural.includes(path) || path.includes('\n') || !blobConflict(root, base, ours, theirs, path)) return false;
    const remote = treeEntry(root, theirs, path);
    if (!remote) return false;
    const commits = git(root, ['log', '--format=%H', '-n', String(MAX_SUPERSEDED_HISTORY), ours, '--', ...literalPathspecs([path])]).stdout.split('\n').filter(Boolean);
    const blobs = git(root, ['cat-file', '--batch-check=%(objectname) %(objecttype)'], { input: commits.map(c => `${c}:${path}\n`).join('') })
      .stdout.split('\n').slice(0, commits.length).map(line => (line.endsWith(' blob') ? line.split(' ')[0] : null));
    const held = [treeEntry(root, ours, path)?.sha ?? null, ...blobs];
    const at = held.indexOf(remote.sha);
    return at > 0 && held.slice(0, at).some(sha => sha && sha !== remote.sha);
  });
}

/** Apply `--resolve` choices on top of the merge's placeholder tree; structural conflicts are refused. */
function resolvedTree(ctx: Ctx, ours: string, theirs: string, merged: MergeTree, resolutions: Map<string, Resolution>, cwd: string): string {
  if (merged.conflicts.some(p => !resolutions.has(p))) throw conflictError(ctx, ours, theirs, merged);
  const base = git(ctx.root, ['merge-base', ours, theirs]).stdout.trim();
  const structural = merged.conflicts.filter(p => merged.structural.includes(p) || !blobConflict(ctx.root, base, ours, theirs, p));
  if (structural.length) throw conflictError(ctx, ours, theirs, { ...merged, structural });
  const dir = mkdtempSync(join(tmpdir(), 'gbrain-resolve-'));
  try {
    const env = { GIT_INDEX_FILE: join(dir, 'index') };
    gitOk(ctx.root, ['read-tree', merged.tree!], 'read-tree', { env });
    for (const path of merged.conflicts) {
      const choice = resolutions.get(path)!;
      if (choice.kind === 'file') {
        const blob = gitOk(ctx.root, ['hash-object', '-w', '--', resolve(cwd, choice.path)], 'hash-object');
        gitOk(ctx.root, ['update-index', '--add', '--cacheinfo', `${treeEntry(ctx.root, ours, path)?.mode ?? '100644'},${blob},${path}`], 'update-index', { env });
        continue;
      }
      const entry = treeEntry(ctx.root, choice.kind === 'ours' ? ours : theirs, path);
      if (entry) gitOk(ctx.root, ['update-index', '--add', '--cacheinfo', `${entry.mode},${entry.sha},${path}`], 'update-index', { env });
      else gitOk(ctx.root, ['update-index', '--force-remove', '--', path], 'update-index', { env });
    }
    return gitOk(ctx.root, ['write-tree'], 'write-tree', { env });
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
}

function shellWord(v: string): string {
  return /^[A-Za-z0-9._\/@%+:-]+$/.test(v) ? v : `'${v.replace(/'/g, `'\\''`)}'`;
}

function conflictError(ctx: Ctx, ours: string, theirs: string, merged: MergeTree & { superseded?: string[] }, preface = ''): OperationError {
  const paths = merged.conflicts;
  const local = ours.slice(0, 12);
  const remote = theirs.slice(0, 12);
  const compare = `Compare the two versions (this machine's: git show ${local}:<path>; the remote's: git show ${remote}:<path>)`;
  const fix = merged.structural.length
    ? `${preface}The local commit ${local} stays local and the checkout is unchanged. ${merged.structural.map(shellWord).join(', ')} ${merged.structural.length === 1 ? 'is' : 'are'} a file/directory or rename conflict that a per-file choice cannot resolve. ${compare}, then move or remove the local path in a new commit (gbrain git commit-push -m "<msg>" -- <paths>) and rerun gbrain git commit-push --push-only. See docs/guides/shared-checkout-git.md#conflicts.`
    : `${preface}The local commit ${local} stays local and the checkout is unchanged. ${compare}, then run gbrain git commit-push --push-only${ctx.keepCheckout ? ' --keep-checkout' : ''} --scan-secrets --expect-remote ${remote} ${paths.map(p => `--resolve ${shellWord(p)}=ours|theirs`).join(' ')} (ours = this machine's version, theirs = the remote's, or =file:<path> with a merged copy). Until then every push from this checkout reports this conflict. See docs/guides/shared-checkout-git.md#conflicts.`;
  return opError('integrate_conflict', `Local and remote commits both changed ${paths.length} file(s) on ${ctx.branch}; nothing was merged.`, fix,
    { detail: JSON.stringify({ local: ours, remote: theirs, paths, structural: merged.structural, ...(merged.superseded?.length ? { superseded: merged.superseded } : {}) }),
      fix: { ask_user: true, consent: [], actor: 'user', requires_exclusive: false,
        why: 'Choosing which version of a file wins discards the other side; ask the user before resolving.',
        user_message: `Both this machine and the remote changed ${paths.join(', ')}. Which version should win, or should they be merged by hand?`,
        ...(merged.structural.length ? {} : { argv: ['gbrain', 'git', 'commit-push', '--push-only', ...(ctx.keepCheckout ? ['--keep-checkout'] : []), '--scan-secrets', '--path', ctx.root, '--expect-remote', theirs, ...paths.flatMap(p => ['--resolve', `${p}=<ours|theirs>`])] }),
        docs: 'docs/guides/shared-checkout-git.md#conflicts' } });
}

/** Honors the user's commit signing config, like the `git pull` it replaces. */
function buildMerge(ctx: Ctx, ours: string, theirs: string, tree: string, skipped: string[] = [], extra: string[] = []): string {
  const remote = `${ctx.remote}/${ctx.mergeRef.replace(/^refs\/heads\//, '')}`;
  const note = skipped.length
    ? ['-m', `Left out ${skipped.length} local commit(s) whose patch ${remote} already has: ${skipped.slice(0, 20).map(s => s.slice(0, 12)).join(' ')}${skipped.length > 20 ? ' ...' : ''}`] : [];
  const sha = gitOk(ctx.root, ['commit-tree', tree, '-p', ours, '-p', theirs, '-m', `gbrain: merge ${remote} into ${ctx.branch}`, ...note, ...extra.flatMap(m => ['-m', m])], 'commit-tree');
  recordCommit(ctx.root, { sha, writer: 'merge', ref: null });
  return sha;
}

function fetchTracking(ctx: Ctx): string | null {
  const r = remoteGit(ctx.root, 'fetch', [...fetchFlags(ctx.root), '--', ctx.remote, `+${ctx.mergeRef}:${ctx.trackingRef}`]);
  if (r.code !== 0) return null;
  return git(ctx.root, ['rev-parse', '--verify', '--quiet', ctx.trackingRef]).stdout.trim() || null;
}

function isAncestor(root: string, a: string, b: string): boolean {
  return git(root, ['merge-base', '--is-ancestor', a, b]).code === 0;
}

/**
 * #5138: true only when EVERY effective push destination (pushurl and
 * pushInsteadOf expanded) has `sha` on the exact target branch. A URL that git
 * would resolve as another remote alias fails closed, and remote evidence is
 * read live (ls-remote), never from a stale tracking ref or the fetch repo.
 */
function remoteContains(ctx: Ctx, sha: string): boolean {
  const branchRef = ctx.mergeRef;
  if (git(ctx.root, ['check-ref-format', branchRef]).code !== 0) return false;
  const urls = git(ctx.root, ['remote', 'get-url', '--push', '--all', '--', ctx.remote]).stdout.split('\n').map(u => u.trim()).filter(Boolean);
  if (urls.length === 0) return false;
  for (const url of urls) {
    if (git(ctx.root, ['ls-remote', '--get-url', '--', url]).stdout.trim() !== url) return false;
    const listed = git(ctx.root, [...transportFlags(), 'ls-remote', '--exit-code', '--', url, branchRef], { auth: true, timeoutMs: 60_000, returnStopped: true });
    if (listed.code !== 0) return false;
    const tip = listed.stdout.split(/\s/)[0];
    if (!/^[0-9a-f]{40,64}$/.test(tip)) return false;
    if (git(ctx.root, ['cat-file', '-e', `${tip}^{commit}`]).code !== 0) {
      const got = git(ctx.root, [...transportFlags(), 'fetch', '--quiet', ...fetchFlags(ctx.root), ...GIT_SSRF_SUBCOMMAND_FLAGS, '--', url, tip], { auth: true, timeoutMs: 120_000, returnStopped: true });
      if (got.code !== 0) return false;
    }
    if (!isAncestor(ctx.root, sha, tip)) return false;
  }
  return true;
}

/** GST-2456: the base a scanned push is scanned from and leased on: the fetched tip, or with pushurls (#5138) the one commit every push URL holds live (or none has the branch); else push_unconfirmed. */
function pushBase(ctx: Ctx, fetched: string, candidate: string): string {
  const urls = git(ctx.root, ['remote', 'get-url', '--push', '--all', '--', ctx.remote]).stdout.split('\n').map(u => u.trim()).filter(Boolean);
  if (urls.length === 1 && urls[0] === git(ctx.root, ['remote', 'get-url', '--', ctx.remote]).stdout.trim()) return fetched;
  const refuse = (why: string) => opError('push_unconfirmed', `Nothing was pushed: ${why}, so no one scanned range covers what this push would publish to every push URL of ${ctx.remote}.`,
    `Bring every push URL of ${ctx.remote} to the same commit of ${ctx.mergeRef.replace(/^refs\/heads\//, '')} (git remote get-url --push --all ${ctx.remote} lists them), then rerun gbrain git commit-push --push-only.`,
    { detail: candidate, retryable: true });
  const tips = new Set<string>();
  for (const url of urls) {
    if (git(ctx.root, ['ls-remote', '--get-url', '--', url]).stdout.trim() !== url) throw refuse(`push URL ${url} names another remote`);
    const listed = git(ctx.root, [...transportFlags(), 'ls-remote', '--exit-code', '--', url, ctx.mergeRef], { auth: true, timeoutMs: 60_000, returnStopped: true });
    if (listed.code === 2) { tips.add(''); continue; }
    const tip = listed.code === 0 ? listed.stdout.split(/\s/)[0] ?? '' : '';
    if (!/^[0-9a-f]{40,64}$/.test(tip)) throw refuse(`push URL ${url} could not be read`);
    if (git(ctx.root, ['cat-file', '-e', `${tip}^{commit}`]).code !== 0
      && git(ctx.root, [...transportFlags(), 'fetch', '--quiet', ...fetchFlags(ctx.root), ...GIT_SSRF_SUBCOMMAND_FLAGS, '--', url, tip], { auth: true, timeoutMs: 120_000, returnStopped: true }).code !== 0) {
      throw refuse(`the commit push URL ${url} holds could not be fetched`);
    }
    tips.add(tip);
  }
  if (tips.size !== 1) throw refuse(`the push URLs hold different commits of ${ctx.mergeRef.replace(/^refs\/heads\//, '')}`);
  return [...tips][0]!;
}

interface Published { sha: string; integrated: number; confirmed: 'push' | 'remote'; quarantined?: QuarantineEntry; superseded?: string[] }

// ── Quarantine (opt-in) ─────────────────────────────────────────────────────

const QUARANTINE_LEDGER_NAME = 'brain-quarantine.log';
export const QUARANTINE_REF_PREFIX = 'refs/gbrain/quarantine/';

export interface QuarantineEntry { ref: string; local: string; remote: string; paths: string[]; at: string }

const quarantineEnabled = (root: string) => git(root, ['config', '--type=bool', '--get', 'gbrain.quarantine']).stdout.trim() === 'true';

/** Name the local commit under refs/gbrain/quarantine/ and note which files it parks; the ref keeps it even if history is later rewritten. */
function parkLocalVersion(root: string, local: string, remote: string, paths: string[]): QuarantineEntry {
  const at = new Date().toISOString();
  const ref = `${QUARANTINE_REF_PREFIX}${at.replace(/[-:]/g, '').replace(/\.\d+Z$/, 'Z')}-${local.slice(0, 12)}`;
  gitOk(root, ['update-ref', ref, local], 'update-ref quarantine');
  const entry = { ref, local, remote, paths, at };
  appendFileSync(absGitPath(root, QUARANTINE_LEDGER_NAME), `${JSON.stringify(entry)}\n`);
  return entry;
}

/** Parked local versions whose ref still exists (deleting the ref is how the user says they are done with it). */
export function readQuarantine(repo: string): QuarantineEntry[] {
  try {
    const root = checkoutRoot(repo);
    const p = absGitPath(root, QUARANTINE_LEDGER_NAME);
    if (!existsSync(p)) return [];
    const live = new Set(git(root, ['for-each-ref', '--format=%(refname)', QUARANTINE_REF_PREFIX]).stdout.split('\n').filter(Boolean));
    return readFileSync(p, 'utf8').split('\n').flatMap(line => {
      try { const e = JSON.parse(line) as QuarantineEntry; return live.has(e.ref) ? [e] : []; } catch { return []; }
    });
  } catch {
    return [];
  }
}

/**
 * Push `start` (an immutable sha), merging remote commits in memory as needed.
 * When the remote already holds the candidate, the published tip (which may be
 * a merge built over it earlier) is returned so a lagging checkout catches up.
 */
function publish(ctx: Ctx, start: string, resolutions: Map<string, Resolution> | undefined, expectRemote: string | undefined, cwd: string): Published {
  const bound = expectRemote && !resolutions?.size ? gitOk(ctx.root, ['rev-parse', '--verify', `${expectRemote}^{commit}`], 'rev-parse --expect-remote') : undefined;
  // #8896: every publish (GST-2650: the derived write-through and a handed-off request too) scans <base>..<candidate> before
  // every push and leases the push on that base, so a remote that moved or was rewound since the tracking ref was fetched (a
  // stale ref hides commits from the scan) is fetched and scanned again; a missing tracking ref is fetched first, so the scan
  // covers what the remote lacks, never its whole history.
  let scannedBase = pushBase(ctx, git(ctx.root, ['rev-parse', '--verify', '--quiet', ctx.trackingRef]).stdout.trim() || (fetchTracking(ctx) ?? ''), start);
  let candidate = start;
  let integrated = 0;
  let lastError = '';
  let stalled = 0;
  let quarantined: QuarantineEntry | undefined;
  const superseded = new Set<string>();
  const notes = () => ({ ...(quarantined ? { quarantined } : {}), ...(superseded.size ? { superseded: [...superseded] } : {}) });
  const onRemote = (): Published => {
    const tip = fetchTracking(ctx);
    return { sha: tip && isAncestor(ctx.root, candidate, tip) ? tip : candidate, integrated, confirmed: 'remote', ...notes() };
  };
  for (let attempt = 0; attempt < MAX_PUSH_ATTEMPTS; attempt++) {
    if (attempt) Atomics.wait(sleeper, 0, 0, Math.min(2000, 50 * 2 ** attempt) + Math.floor(Math.random() * 100));
    let remoteTip = bound && !isAncestor(ctx.root, bound, candidate) ? bound : null;
    if (!remoteTip) {
      const lease = bound ?? scannedBase;
      assertNoSecretsInRange({ ...ctx, trackingRef: lease }, candidate);
      const push = lease && !isAncestor(ctx.root, lease, candidate) ? null
        : remoteGit(ctx.root, 'push', ['--no-follow-tags', '--recurse-submodules=no', ...(ctx.keepCheckout ? ['--no-verify'] : []), `--force-with-lease=${ctx.mergeRef}:${lease}`, '--', ctx.remote, `${candidate}:${ctx.mergeRef}`]);
      if (push?.code === 0) return { sha: candidate, integrated, confirmed: 'push', ...notes() };
      if (push) lastError = push.stderr.trim();
      if (remoteContains(ctx, candidate)) return onRemote();
      const refused = push ? credentialRefusal(push.stderr) : null;
      if (refused) throw pushCredentialRefusedError(ctx.root, ctx.remote, ctx.mergeRef.replace(/^refs\/heads\//, ''), refused, candidate);
      remoteTip = fetchTracking(ctx);
      if (!remoteTip) break;
      scannedBase = pushBase(ctx, remoteTip, candidate);
      if (bound && remoteTip !== bound) {
        throw opError('push_unconfirmed', `The remote moved to ${remoteTip.slice(0, 12)} after --expect-remote ${bound.slice(0, 12)} was checked, so nothing was pushed: publishing now could merge back commits a rewrite removed.`,
          'Check the remote history first (gbrain sources refresh checks it for a force-push), then rerun.', { detail: candidate, retryable: true });
      }
      if (isAncestor(ctx.root, remoteTip, candidate)) {
        if (++stalled > 1) break;
        continue;
      }
    }
    assertNoSecretsInRange({ ...ctx, trackingRef: remoteTip }, candidate);
    const raw = integrate(ctx.root, candidate, remoteTip);
    const kept = supersededPaths(ctx.root, candidate, remoteTip, raw, resolutions);
    const merged = kept.length
      ? { ...raw, superseded: kept, conflicts: raw.conflicts.filter(p => !kept.includes(p)),
        tree: resolvedTree(ctx, candidate, remoteTip, { ...raw, conflicts: kept }, new Map(kept.map(p => [p, { kind: 'ours' } as Resolution])), cwd) }
      : raw;
    let tree = merged.tree!;
    let mergeNotes: string[] = kept.length
      ? [`Kept this machine's version of ${kept.length} file(s) where the remote held a version this checkout had already replaced: ${kept.slice(0, 20).join(', ')}${kept.length > 20 ? ', ...' : ''}`] : [];
    if (merged.conflicts.length && !resolutions?.size && !merged.structural.length && quarantineEnabled(ctx.root)) {
      tree = resolvedTree(ctx, candidate, remoteTip, merged, new Map(merged.conflicts.map(p => [p, { kind: 'theirs' } as Resolution])), cwd);
      quarantined = parkLocalVersion(ctx.root, candidate, remoteTip, merged.conflicts);
      mergeNotes = [...mergeNotes, `Quarantined this machine's version of ${merged.conflicts.length} conflicting file(s) under ${quarantined.ref}: ${merged.conflicts.slice(0, 20).join(', ')}`];
    } else if (merged.conflicts.length) {
      if (!resolutions?.size) throw conflictError(ctx, candidate, remoteTip, merged);
      if (!expectRemote || !remoteTip.startsWith(expectRemote.toLowerCase())) {
        throw conflictError(ctx, candidate, remoteTip, merged,
          `The remote moved to ${remoteTip.slice(0, 12)}${expectRemote ? ` after the choice was made against ${expectRemote.slice(0, 12)}` : ''}; review the remote's current version before choosing. `);
      }
      tree = resolvedTree(ctx, candidate, remoteTip, merged, resolutions, cwd);
    }
    integrated += Number(git(ctx.root, ['rev-list', '--count', `${candidate}..${remoteTip}`]).stdout.trim() || 0);
    candidate = buildMerge(ctx, candidate, remoteTip, tree, merged.skipped, mergeNotes);
    for (const p of kept) superseded.add(p);
  }
  if (remoteContains(ctx, candidate)) return onRemote();
  throw opError('push_unconfirmed', `The commit is durable locally but no push to ${ctx.remote}/${ctx.mergeRef.replace(/^refs\/heads\//, '')} was confirmed.`,
    `git push failed (network, credentials, branch protection, or a remote that kept moving): ${lastError.slice(0, 500) || 'no detail'}. Rerun gbrain git commit-push --push-only${ctx.keepCheckout ? ' --keep-checkout' : ''} --scan-secrets once the remote is reachable; never git pull --rebase in this checkout.`,
    { detail: candidate, retryable: true });
}

/** Non-merge commits in `target` but not in `upstream` (at most 200) that change files outside `roots`; null when git cannot list them. */
export function localCommitsOutsideRoots(root: string, target: string, upstream: string, roots: string[]): Array<{ sha: string; paths: string[] }> | null {
  if (roots.includes('')) return [];
  const local = git(root, ['rev-list', '--no-merges', '--max-count=200', target, '--not', upstream]);
  if (local.code !== 0) return null;
  const offending: Array<{ sha: string; paths: string[] }> = [];
  for (const sha of local.stdout.split('\n').filter(Boolean)) {
    const paths = git(root, ['diff-tree', '--no-commit-id', '--name-only', '--no-renames', '-r', '-z', '--root', sha]).stdout.split('\0').filter(p => p && !insideSourceRoots(p, roots));
    if (paths.length) offending.push({ sha, paths });
  }
  return offending;
}

/**
 * Refuse to publish a local commit that changes files outside the configured source root(s). In a shared
 * checkout a commit made without paths (a cron's `git add <dir>; git commit`) carries whatever any writer
 * had staged; the source-root config is how a brain inside a larger repository says which files are its own.
 * Merge commits are not judged (gbrain's in-memory merges bring remote files in). With no root configured
 * the whole checkout is the root and nothing is refused.
 */
function assertLocalCommitsInsideRoots(ctx: Ctx, target: string, roots: string[]): void {
  const offending = localCommitsOutsideRoots(ctx.root, target, ctx.trackingRef, roots) ?? [];
  if (!offending.length) return;
  const files = [...new Set(offending.flatMap(o => o.paths))];
  const shas = offending.map(o => o.sha.slice(0, 12)).join(', ');
  throw opError('commit_outside_source_root', `${offending.length} local commit(s) (${shas}) change ${files.length} file(s) outside this brain's source root (${roots.join(', ')}): ${files.slice(0, 10).join(', ')}${files.length > 10 ? ', ...' : ''}. Nothing was pushed.`,
    `A commit made without gbrain git commit-push (for example a cron's git add plus git commit) can carry files other writers had staged. Show the user git show --stat ${offending[0].sha.slice(0, 12)}; if they want it published as is, rerun with --allow-outside-source-root. See docs/guides/shared-checkout-git.md#source-roots.`,
    { detail: JSON.stringify({ roots, commits: offending }),
      fix: { ask_user: true, consent: [], actor: 'user', requires_exclusive: false,
        argv: ['gbrain', 'git', 'commit-push', '--push-only', ...(ctx.keepCheckout ? ['--keep-checkout'] : []), '--scan-secrets', '--allow-outside-source-root', '--path', ctx.root],
        why: 'These commits change files that are not the brain\'s; publishing them can overwrite other projects\' or writers\' work on the remote.',
        user_message: `Local commit(s) ${shas} change files outside the brain's folder (${files.slice(0, 5).join(', ')}${files.length > 5 ? ', ...' : ''}). Publish them anyway?`,
        docs: 'docs/guides/shared-checkout-git.md#source-roots' } });
}

/** The automatic-publish secret gate: scan what the commits in trackingRef..target add (publish passes the base it leases its push on, under its lock). */
function assertNoSecretsInRange(ctx: Ctx, target: string): void {
  const refusal = rangeSecretRefusal(ctx.root, ctx.trackingRef, target, scanRange(ctx.root, ctx.trackingRef, target, ctx.scanTimeoutMs, ctx.scanProgress), {
    timeoutMs: ctx.scanTimeoutMs, retryArgv: ['gbrain', 'git', 'commit-push', '--push-only', ...(ctx.keepCheckout ? ['--keep-checkout'] : []), '--branch', ctx.mergeRef.replace(/^refs\/heads\//, ''), '--path', ctx.root] });
  if (refusal) throw refusal;
}

/** Advance the shared checkout (caller holds the commit lock) with a real compare-and-swap: fast-forward only, hooks off, never autostash. */
function advanceLocked(root: string, target: string, expectedHead: string): { checkout: CheckoutState; reason?: string } {
  const head = git(root, ['rev-parse', 'HEAD']).stdout.trim();
  if (head === target || isAncestor(root, target, head)) return { checkout: 'unchanged' };
  if (head !== expectedHead) {
    return { checkout: 'lagging', reason: isAncestor(root, expectedHead, head)
      ? `a newer local commit (${head.slice(0, 12)}) landed during the push; publishing it advances the checkout`
      : `HEAD moved to ${head.slice(0, 12)} during the push (a writer that did not take the commit lock)` };
  }
  if (!isAncestor(root, head, target)) return { checkout: 'lagging', reason: `HEAD ${head.slice(0, 12)} is not part of the published history (it was rewritten locally)` };
  const r = withIndexRetry(root, ['-c', 'core.hooksPath=/dev/null', '-c', 'merge.autoStash=false', 'merge', '--ff-only', '--quiet', target], 'checkout advance');
  if (r.code === 0) return { checkout: 'advanced' };
  const dirty = [...r.stderr.matchAll(/^\t(.+)$/gm)].map(m => m[1]);
  if (dirty.length) return { checkout: 'lagging', reason: `local edits in ${dirty.join(', ')} block the fast-forward` };
  throw opError('git_unavailable', `git could not fast-forward ${root} to ${target.slice(0, 12)}.`,
    `${r.stderr.trim().slice(0, 300) || `exit ${r.code}`}. Nothing in the working tree changed; run gbrain git commit-push --pull once git works in this checkout.`, { detail: target });
}

function advanceWithLock(root: string, target: string, expectedHead: string, onlyWhenClean: boolean, lockWaitMs?: number): { checkout: CheckoutState; reason?: string } {
  let lock: CommitLock;
  try { lock = acquireCommitLock(root, lockWaitMs); } catch (e) {
    if ((e as { code?: string }).code !== 'commit_lock_busy') throw e;
    return { checkout: 'lagging', reason: 'another writer held the commit lock; the next publish or --pull advances the checkout' };
  }
  try {
    if (onlyWhenClean && git(root, ['status', '--porcelain']).stdout.trim()) {
      return { checkout: 'lagging', reason: 'the checkout has local edits and this unattended run never moves files under them' };
    }
    return advanceLocked(root, target, expectedHead);
  } finally {
    lock.release();
  }
}

// ── Conflict state (doctor / put_page read it) ──────────────────────────────

export interface IntegrateConflictState { branch: string; at: string; local: string; remote: string; paths: string[] }

/** The unresolved integrate_conflict recorded for this checkout, if any. */
export function readIntegrateConflict(repo: string): IntegrateConflictState | null {
  try {
    const root = checkoutRoot(repo);
    const p = absGitPath(root, CONFLICT_STATE_NAME);
    return existsSync(p) ? JSON.parse(readFileSync(p, 'utf8')) as IntegrateConflictState : null;
  } catch {
    return null;
  }
}

/** GST-2961: the push refusal for the credential git used, recorded for this checkout until a push lands (by any route: when the remote pushes to the one URL it fetches from, a refused commit already on the remote-tracking ref is past), if any. */
export function readCredentialRefusal(repo: string): CredentialRefusalState | null {
  try {
    const root = checkoutRoot(repo);
    const state = readCredentialRefusalFile(absGitPath(root, CREDENTIAL_STATE_NAME));
    const pushesWhereItFetches = () => {
      const push = git(root, ['remote', 'get-url', '--push', '--all', '--', state!.remote]);
      const fetch = git(root, ['remote', 'get-url', '--', state!.remote]);
      const urls = push.stdout.trim().split('\n');
      return push.code === 0 && fetch.code === 0 && urls.length === 1 && urls[0] === fetch.stdout.trim();
    };
    if (state?.commit && state.remote && state.branch && pushesWhereItFetches() && isAncestor(root, state.commit, `refs/remotes/${state.remote}/${state.branch}`)) return null;
    return state;
  } catch {
    return null;
  }
}

function recordConflict(root: string, branch: string, e: unknown): void {
  try {
    const d = JSON.parse(String((e as { detail?: string }).detail ?? '{}'));
    writeFileSync(absGitPath(root, CONFLICT_STATE_NAME), JSON.stringify({ branch, at: new Date().toISOString(), local: d.local, remote: d.remote, paths: d.paths ?? [] }));
  } catch { /* best-effort */ }
}

// ── Public entry points ─────────────────────────────────────────────────────

function defaultPublishWaitMs(): number {
  const raw = process.env.GBRAIN_PUBLISH_LOCK_WAIT_SECONDS ?? process.env.GBRAIN_PUSH_LOCK_WAIT_SECONDS;
  const secs = raw === undefined ? 300 : Number(raw);
  return Number.isFinite(secs) && secs >= 0 ? secs * 1000 : 300_000;
}

/**
 * Q1: on a managed canonical worktree commit-push commits only the paths the caller names (pages written outside gbrain,
 * which would otherwise land as bare commits), under the commit lock, and nothing more: no fetch, merge, push or checkout
 * move, so the owner stays the only publisher. The commit reaches the remote on the owner's next Git publish, or with
 * `gbrain git commit-push --push-only --keep-checkout`.
 */
function commitManagedPaths(root: string, opts: CommitPushOptions, managed: ManagedFilesystemRoot): CommitPushResult {
  const where = `${root} is the managed canonical worktree${managed.sourceId ? ` of source ${managed.sourceId}` : ''}`;
  if (opts.pending || opts.branch || opts.resolutions || opts.expectRemote || opts.allowOutsideSourceRoot || opts.advanceOnlyWhenClean) {
    throw opError('commit_paths_invalid', `${where}: commit-push there only commits the paths you name.`,
      `Run gbrain git commit-push with only -m and the page paths after --; gbrain sources refresh${managed.sourceId ? ` ${managed.sourceId}` : ''} brings remote commits in.`);
  }
  const { result: committed, skipped } = commitPathsOnly(root, opts, where, configuredSourceRoots(root), 'Leave the checkout to its owner; gbrain sources writer status names its state.', managed);
  const counted = git(root, ['rev-list', '--count', '@{upstream}..HEAD']);
  const upstream = git(root, ['for-each-ref', '--format=%(upstream:short)', `refs/heads/${committed.branch}`]).stdout.trim();
  const result: CommitPushResult = { ...committed, managed: true, unpublished: counted.code === 0 ? Number(counted.stdout.trim()) : null, upstream: upstream || null };
  if (skipped.length) throw skippedPathsError(root, skipped, result, managed);
  return result;
}

/** A checkout with no Git remote at all: no remote is configured and the branch names none (a named but missing remote is refused by resolveCtx). A git command that fails is not proof of "no remote". */
function hasNoRemote(root: string): boolean {
  const branch = git(root, ['symbolic-ref', '--quiet', '--short', 'HEAD']);
  if (branch.code !== 0 || git(root, ['rev-parse', '--verify', '--quiet', 'HEAD']).code !== 0) return false;
  const remotes = git(root, ['remote']);
  if (remotes.code !== 0 || remotes.stdout.trim()) return false;
  return git(root, ['config', '--get', `branch.${branch.stdout.trim()}.remote`]).code === 1;
}

/** GBRA-133: with no remote there is nothing to publish to, so commit-push only commits the named paths, like a managed worktree. */
function commitRemotelessPaths(root: string, opts: CommitPushOptions): CommitPushResult {
  const where = `${root} has no Git remote, so there is nothing to publish to`;
  if (opts.pushOnly || opts.pending || opts.branch || opts.resolutions || opts.expectRemote || opts.advanceOnlyWhenClean) {
    throw opError('commit_paths_invalid', `${where}; commit-push there only commits the paths you name.`,
      'Run gbrain git commit-push -m <msg> -- <paths> to commit them locally, or add a remote (git remote add origin <url>) and set the branch upstream to publish.');
  }
  const { result: committed, skipped } = commitPathsOnly(root, opts, where, opts.allowOutsideSourceRoot ? [''] : configuredSourceRoots(root), 'Check out a branch (git switch <branch>), then rerun.');
  const result: CommitPushResult = { ...committed, no_remote: true };
  if (skipped.length) throw skippedPathsError(root, skipped, result);
  return result;
}

/** Commit only the named paths under the commit lock and nothing more: no fetch, merge, push or checkout move. */
function commitPathsOnly(root: string, opts: CommitPushOptions, where: string, roots: string[], detachedFix: string, managed?: ManagedFilesystemRoot): { result: CommitPushResult; skipped: SkippedPath[] } {
  if (!opts.message?.trim()) throw opError('commit_paths_invalid', 'A commit message is required.', 'Pass the commit message with -m.');
  const rel = scopePaths(root, opts.paths ?? [], opts.cwd ?? process.cwd());
  if (!rel.length) throw opError('commit_paths_invalid', `${where}: name the paths to commit.`, 'Pass -- <paths> after the message.');
  const branch = git(root, ['symbolic-ref', '--quiet', '--short', 'HEAD']).stdout.trim();
  if (!branch) throw opError('git_detached_head', `${root} is on a detached HEAD, so there is no branch to commit to.`, detachedFix);
  assertNoOperationInProgress(root);
  const lock = acquireCommitLock(root, opts.lockWaitMs);
  let commit: ReturnType<typeof commitPaths>;
  try {
    assertNoOperationInProgress(root);
    commit = commitPaths(root, rel, opts.message.trim(), { roots, lockPath: lock.lockPath, markHeld: true, bases: scopeBases(root, opts, rel),
      ...(opts.untrack ? { untrack: managed ? { dbOnly: managed, pages: opts.untrackPages } : 'any' as const } : {}) });
  } finally {
    lock.release();
  }
  const committed = commit.sha;
  const remote = git(root, ['config', '--get', `branch.${branch}.remote`]).stdout.trim();
  return { result: { outcome: committed ? 'committed_local' : 'nothing_to_commit', sha: committed, committed, branch, remote, paths: rel, integrated: 0, checkout: 'unchanged' }, skipped: commit.skipped };
}

export function commitAndPush(opts: CommitPushOptions): CommitPushResult {
  const root = checkoutRoot(opts.repo);
  if (opts.keepCheckout && !opts.pushOnly) throw opError('commit_paths_invalid', 'keepCheckout publishes commits already on the branch; it commits nothing.', 'Use --push-only --keep-checkout.');
  if (opts.untrack && (opts.pushOnly || opts.pending)) throw opError('commit_paths_invalid', 'untrack removes the paths you name; it does not combine with push-only or pending.', 'Use --untrack -m <msg> -- <paths>.');
  const managed = opts.keepCheckout || opts.pushOnly ? null : managedFilesystemRootFor(root);
  if (managed && !hasFilesystemPublication(root)) return commitManagedPaths(root, opts, managed);
  if (!opts.keepCheckout) assertManagedFilesystemWrite(root);
  if (hasNoRemote(root)) return commitRemotelessPaths(root, opts);
  const cwd = opts.cwd ?? process.cwd();
  const roots = configuredSourceRoots(root);
  const rel = opts.pushOnly ? [] : opts.pending
    ? [...dirtyPaths(root, readPendingWriteThrough(root).map(e => e.path).filter(p => insideSourceRoots(p, roots)))]
    : scopePaths(root, opts.paths ?? [], cwd);
  if (!opts.pushOnly && !opts.message?.trim()) {
    throw opError('commit_paths_invalid', 'A commit message is required.', 'Pass -m "<message>".');
  }
  const upstream = resolveCtx(root);
  const ctx = { ...withBranch(upstream, opts.branch), ...(opts.keepCheckout ? { keepCheckout: true } : {}),
    ...(opts.scanTimeoutMs ? { scanTimeoutMs: opts.scanTimeoutMs } : {}), ...(opts.scanProgress ? { scanProgress: opts.scanProgress } : {}) };
  const elsewhere = ctx.mergeRef !== upstream.mergeRef;
  assertNoOperationInProgress(root);

  let committed: string | null = null;
  let skipped: SkippedPath[] = [];
  if (!opts.pushOnly) {
    const lock = acquireCommitLock(root, opts.lockWaitMs);
    try {
      assertNoOperationInProgress(root);
      if (rel.length) ({ sha: committed, skipped } = commitPaths(root, rel, opts.message!.trim(), { roots: opts.allowOutsideSourceRoot ? [''] : roots, lockPath: lock.lockPath, markHeld: true, bases: scopeBases(root, opts, rel),
        ...(opts.untrack ? { untrack: managed ? { dbOnly: managed, pages: opts.untrackPages } : 'any' as const } : {}) }));
      settlePending(root);
    } finally {
      lock.release();
    }
  }

  const unattended = !!opts.advanceOnlyWhenClean;
  const publishLockPath = absGitPath(root, PUBLISH_LOCK_NAME);
  const requestPath = absGitPath(root, PUBLISH_REQUEST_NAME);
  const waitMs = unattended ? 0 : opts.publishWaitMs ?? defaultPublishWaitMs();
  let pub = acquireNativeLockSync(publishLockPath, { timeoutMs: waitMs });
  if (!pub) {
    writeFileSync(requestPath, `${process.pid}\n`);
    pub = acquireNativeLockSync(publishLockPath, { timeoutMs: 0 });
  }
  const unpublished: CommitPushResult = { outcome: 'committed_local', sha: null, committed, branch: ctx.branch, remote: ctx.remote, paths: rel, integrated: 0, checkout: 'unchanged' };
  if (!pub) {
    if (unattended) {
      const deferred: CommitPushResult = { ...unpublished, outcome: 'push_deferred' };
      if (skipped.length) throw skippedPathsError(root, skipped, deferred);
      return deferred;
    }
    const busy = opError('push_unconfirmed', `${committed ? 'The commit is durable locally, but another' : 'Another'} publish held this checkout's push lock for ${Math.round(waitMs / 1000)}s.`,
      `The running publish was asked to push HEAD too once it finishes. Rerun gbrain git commit-push --push-only${ctx.keepCheckout ? ' --keep-checkout' : ''} --scan-secrets to confirm; never git pull --rebase in this checkout.`,
      { detail: committed ?? '', retryable: true });
    if (skipped.length) throw skippedPathsError(root, skipped, unpublished, undefined, busy);
    throw busy;
  }

  const cycle = (onlyWhenClean: boolean, start: string | null, resolutions?: Map<string, Resolution>, expectRemote?: string) => {
    const requested = existsSync(requestPath);
    rmSync(requestPath, { force: true });
    try {
      const head = gitOk(root, ['rev-parse', 'HEAD'], 'rev-parse HEAD');
      const target = start && !isAncestor(root, start, head) ? start : head;
      if (!opts.allowOutsideSourceRoot) assertLocalCommitsInsideRoots(ctx, target, roots);
      const published = publish(ctx, target, resolutions, expectRemote, cwd);
      if (!elsewhere) rmSync(absGitPath(root, CONFLICT_STATE_NAME), { force: true });
      rmSync(absGitPath(root, CREDENTIAL_STATE_NAME), { force: true });
      const moved = published.sha === head || elsewhere || opts.keepCheckout ? { checkout: 'unchanged' as const } : advanceWithLock(root, published.sha, head, onlyWhenClean, opts.lockWaitMs);
      return { published, moved };
    } catch (e) {
      if ((e as { code?: string }).code === 'integrate_conflict' && !elsewhere) recordConflict(root, ctx.branch, e);
      if ((e as { code?: string }).code === 'push_credential_refused') recordCredentialRefusalFile(absGitPath(root, CREDENTIAL_STATE_NAME), e);
      if (requested) writeFileSync(requestPath, `${process.pid}\n`);
      throw e;
    }
  };

  let first: ReturnType<typeof cycle>;
  try {
    first = cycle(unattended, committed, opts.resolutions, opts.expectRemote);
  } catch (e) {
    if (skipped.length) throw skippedPathsError(root, skipped, unpublished, undefined, e);
    throw e;
  } finally {
    pub.release();
  }
  // Publishers that found the push lock busy left a request; honor it after releasing (no commit is stranded).
  for (let i = 0; i < 16 && existsSync(requestPath); i++) {
    const again = acquireNativeLockSync(publishLockPath, { timeoutMs: 0 });
    if (!again) break;
    try { cycle(true, null); } catch { break; } finally { again.release(); }
  }

  const { published, moved } = first;
  const result: CommitPushResult = {
    outcome: moved.checkout === 'lagging' ? 'pushed_checkout_lagging' : committed || opts.pushOnly ? 'pushed' : 'nothing_to_commit',
    sha: published.sha, committed, branch: ctx.branch, remote: ctx.remote, paths: rel,
    integrated: published.integrated, confirmed: published.confirmed, checkout: moved.checkout, ...(moved.reason ? { lagging_reason: moved.reason } : {}),
    ...(published.quarantined ? { quarantined: published.quarantined } : {}),
    ...(published.superseded ? { superseded_remote_paths: published.superseded } : {}),
  };
  if (skipped.length) throw skippedPathsError(root, skipped, result);
  return result;
}

/**
 * Bring remote commits into the shared checkout without rebasing it: fetch
 * outside the lock, then (under the commit lock) fast-forward, or merge
 * diverged history in memory and fast-forward to the merge. Never pushes.
 * `requireClean` keeps the unattended cron's conservative "any local edit →
 * skip" rule.
 */
export function pullShared(repo: string, opts: { requireClean?: boolean; lockWaitMs?: number; fetchTimeoutMs?: number; remoteBranch?: string } = {}): PullResult {
  const root = checkoutRoot(repo);
  assertManagedFilesystemWrite(root);
  const ctx = withBranch(resolveCtx(root), opts.remoteBranch);
  if (opts.requireClean && git(root, ['status', '--porcelain']).stdout.trim()) return { status: 'skipped_dirty' };
  assertNoOperationInProgress(root);
  const fetched = remoteGit(root, 'fetch', [...fetchFlags(root), '--', ctx.remote, `+${ctx.mergeRef}:${ctx.trackingRef}`], opts.fetchTimeoutMs ?? 300_000);
  if (fetched.code !== 0) {
    throw opError('git_unavailable', `git fetch from ${ctx.remote} failed in ${root}.`, fetched.stderr.trim().slice(0, 300) || 'Check the remote and its credentials.');
  }
  const remoteTip = gitOk(root, ['rev-parse', ctx.trackingRef], 'rev-parse tracking ref');
  const lock = acquireCommitLock(root, opts.lockWaitMs);
  try {
    assertNoOperationInProgress(root);
    if (opts.requireClean && git(root, ['status', '--porcelain']).stdout.trim()) return { status: 'skipped_dirty' };
    const head = gitOk(root, ['rev-parse', 'HEAD'], 'rev-parse HEAD');
    if (head === remoteTip || isAncestor(root, remoteTip, head)) return { status: head === remoteTip ? 'up_to_date' : 'ahead' };
    let target = remoteTip;
    let merged = false;
    if (!isAncestor(root, head, remoteTip)) {
      const tree = integrate(root, head, remoteTip);
      if (tree.conflicts.length) throw conflictError(ctx, head, remoteTip, tree);
      target = buildMerge(ctx, head, remoteTip, tree.tree!, tree.skipped);
      merged = true;
    }
    const moved = advanceLocked(root, target, head);
    if (moved.checkout === 'lagging') return { status: 'lagging', from: head, reason: moved.reason };
    return { status: 'advanced', from: head, to: target, merged };
  } finally {
    lock.release();
  }
}