Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* 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();
}
}