Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
import { assertManagedFilesystemWrite, isManagedFilesystemPath, managedFilesystemRootFor } from './persistence/filesystem-guard.ts';
import { OWNERSHIP_MARKER_GLOBS } from './persistence/root-metadata.ts';
import { OperationError } from './ops/contract.ts';
/**
* workspace-push.ts — the `gbrain sources push` core: scan-gated
* add → commit → pull → push for an agent-workspace repo
* (agent-bootstrap plan: D6, G6, G8, G14/A5, B4, CX2-3, CX2-6, CX2-7, S3#2).
*
* The WHOLE sequence runs under ONE cross-platform lock [G14/A5, CX2-6]:
* an atomic-mkdir lock dir at `<gbrainHome>/locks/push-<hash>.lock` with an
* owner file ({pid, acquired_at, token}). flock(1) is NOT a dependency
* (absent on macOS, the v1 target). Steal policy applies the pid-reuse
* learning (pglite-lock #2058/#2348): a holder is stolen ONLY when its pid
* is affirmatively dead AND the lock is older than the stale window — BOTH
* conditions. A second concurrent caller gets a clean `skipped_in_flight`
* (exit 0 at the CLI), never an error.
*
* Sequence (each step gates the next):
* 1. resolve the repo ROOT via `git rev-parse --show-toplevel` [CX2-3] —
* a workspace layout registers `repo/brain` as the source dir while the
* enclosing repo owns `.git`; push always operates on the root.
* 2. deny-glob backstop [G6]: a TRACKED file matching the deny list
* (`*.pglite`, `.env*`, `*.pem`, `*.key`, `.gbrain/**`) HARD-FAILS the
* push regardless of .gitignore state (a truncated .gitignore can't
* leak). Untracked deny matches — INCLUDING gitignored ones — are
* excluded from staging, loudly.
* 3. `git add -A` FIRST, then un-stage any staged deny match. Repo-local
* git identity (`gbrain-bootstrap` / `bootstrap@localhost`) is set ONLY
* when none exists, so a commit can never fail on a fresh machine.
* 4. secret scan (src/core/secret-scan.ts) over the STAGED blobs
* (`git cat-file -p :<path>`, size-capped, binary-skipped) so scanned
* bytes == committed bytes — no scan→stage TOCTOU window. Findings
* block the commit (index restored to HEAD, disk untouched) and name
* file+pattern; per-finding override via `<ws>/.gbrain-scan-allow`.
* 5. commit (skipped when clean).
* 6. COMMIT FIRST, then `divergenceSafePull` [CX2-7] — pulling before
* committing returns `skipped_dirty` and strands local work.
* 7. push — even on a clean tree: a prior failed run may have left local
* ahead of origin.
* 8. write `<gbrainHome>/bootstrap/push-status.json` {ts, ok, reason?,
* ahead?} on success AND failure [B4] (doctor + SessionStart digest
* read it).
*
* Remote-privacy gate [G8]: refuses a remote that is not VERIFIABLY private.
* Verification routes through the repo-visibility LADDER (repo-visibility.ts):
* REST first (`gh api repos/...` — never GraphQL, which cloud proxies pin),
* then pure git protocol (authed ls-remote + attributed anonymous probe), so
* the gate keeps working where gh is broken/blocked. Unverifiable visibility
* is a refusal with the per-rung reason, never fail-open. Escape hatches for
* self-hosted git you trust, loudly logged, most-portable last: CLI
* `allowUnverifiedRemote` > env GBRAIN_ALLOW_UNVERIFIED_REMOTE=1 > file-plane
* config `push.allow_unverified_remote` (readable by detached hook children
* that can never see a shell export or the DB plane).
*/
import {
existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync,
} from 'fs';
import { dirname, isAbsolute, join, resolve } from 'path';
import { createHash, randomBytes } from 'crypto';
import { execFileSync, spawn } from './spawn.ts';
import { GIT_ENV, GIT_ENV_AUTH, GIT_SSRF_SUBCOMMAND_FLAGS, detectDefaultBranch, divergenceSafePull, type PullStrategy } from './git-remote.ts';
import { loadConfigFileOnly } from './config.ts';
import { ensureGbrainHome } from './gbrain-home.ts';
import { invalidateBackupStatus, loadBackupStatus } from './backup/status-file.ts';
import {
githubOwnerRepoString,
readCachedPrivateVerdict,
verifyRepoVisibility,
writeVisibilityCache,
} from './repo-visibility.ts';
import { isProcessAlive } from './pglite-lock.ts';
import {
ALLOWLIST_FINGERPRINT_MIN_HEX, loadWorkspaceAllowlist, matchesGlob, pathAllowlisted, scanText,
SCAN_ALLOW_FILENAME, SCAN_MAX_FILE_BYTES,
type SecretFinding,
} from './secret-scan.ts';
import { scanTextStream } from './secret-scan-stream.ts';
import { withoutRuleAllowed, type AllowlistProblem } from './secret-scan-allowlist.ts';
import { shellQuote } from './mcp-registration.ts';
import { gitChildEnv } from './git-env.ts';
import { recordCommit, recordIntent } from './git/commit-ledger.ts';
import { scanAllowProblems, stagedScanPublishRefusal } from './git/range-secret-scan.ts';
// ── Types ───────────────────────────────────────────────────────────────────
export type WorkspacePushStatus =
| 'pushed' // local HEAD reached origin (with or without a new commit)
| 'skipped_in_flight' // another push holds the lock — clean skip [G14/A5]
| 'blocked_tracked_deny' // a TRACKED file matches the deny globs [G6]
| 'blocked_secrets' // unallowlisted secret-scan findings [D6]
| 'blocked_unscannable' // a staged blob could not be scanned — fail CLOSED
| 'blocked_history' // the range scan of the commits it would push refused (publish_secret_found / publish_scan_unreadable)
| 'refused_visibility' // remote not verifiably private [G8]
| 'pull_conflict' // divergenceSafePull aborted a conflicted rebase
| 'push_failed' // push rejected / origin unreachable
| 'error'; // not a git repo / no origin / unexpected failure
export interface WorkspacePushResult {
ok: boolean;
status: WorkspacePushStatus;
reason?: string;
repoRoot?: string;
branch?: string;
/** True when this run created a new commit. */
committed?: boolean;
/** Commits local is ahead of origin/<branch> after the run (0 on success). */
ahead?: number;
lockHolderPid?: number | null;
/** Tracked paths that hard-failed the deny-glob backstop. */
denyMatches?: string[];
/** Untracked deny-glob matches excluded from staging (kept on disk). */
excludedUntracked?: string[];
findings?: PushSecretFinding[];
/** Staged paths the secret scan could not read (fail-closed block reason). */
unscannable?: string[];
/** blocked_secrets: `.gbrain-scan-allow` lines that allow nothing (a malformed rule entry, an unknown rule name). */
allowlistProblems?: AllowlistProblem[];
/** blocked_history: the refusal's code, what to do (a longer `--scan-timeout` after a timeout) and its findings JSON (never a value). */
code?: string;
suggestion?: string;
detail?: string;
}
/** Troubleshooting section for push refusals (DX-8 in docs/guides/write-refusals.md). */
export const SECRET_SCAN_REFUSAL_DOCS =
'https://github.com/garrytan/gbrain/blob/master/docs/guides/write-refusals.md#secret-scan-refusals-and-redaction';
/**
* An allowlist line that suppressed a private key's header-only value before
* the scanner claimed the key body too. The line no longer matches; the
* finding's current fingerprint is the reviewed replacement.
*/
export interface StaleAllowlistEntry {
entry: string;
replacement: string;
}
/**
* A blocking finding plus everything needed to act on it from any working
* directory (DX-3/ENG-11). The guidance rides here, not in `reason`, because
* `reason` is clipped to 140 chars by `sanitizePushReason` on every status
* surface.
*/
export interface PushSecretFinding extends SecretFinding {
file: string;
/** The gbrain version that added or changed the rule, when the scanner reports one. */
since?: string;
/** Absolute path of the `.gbrain-scan-allow` file the gate reads. */
allowlistPath: string;
/** Shell command appending this finding's fingerprint to the allowlist. */
allowCommand: string;
/** Shell command re-running this push, runnable from any directory. */
retryCommand: string;
docs: string;
staleAllowlistEntry?: StaleAllowlistEntry;
}
export interface WorkspacePushOpts {
/** Any directory inside the repo; the root is resolved via rev-parse [CX2-3]. */
dir: string;
/** Branch to pull/push; default `detectDefaultBranch(root)`. */
branch?: string;
/** How the pre-push pull reconciles divergence (`sources.config.pull_strategy`, #5429); default rebase. */
pullStrategy?: PullStrategy;
/** Escape hatch for self-hosted git: skip the gh privacy verification [G8]. Logged. */
allowUnverifiedRemote?: boolean;
commitMessage?: string;
logger?: (line: string) => void;
/** The range secret scan's time budget (`--scan-timeout`; default 300 s). */
scanTimeoutMs?: number;
/**
* TEST SEAM: hold the lock for N ms after acquisition, before any git work.
* Lets a concurrency test make "N callers, 1 winner" deterministic.
*/
holdLockMs?: number;
}
/**
* Deny-glob backstop list [G6]. Matched with secret-scan's glob dialect.
* #5186: ownership markers (`OWNERSHIP_MARKER_GLOBS`) and the bootstrap lock
* are denied like credentials; the ownership token never reaches a remote.
*/
export const PUSH_DENY_GLOBS: readonly string[] = [
'*.pglite', '.env*', '*.pem', '*.key', '.gbrain/**', ...OWNERSHIP_MARKER_GLOBS, '.gbrain-bootstrap.lock/**',
];
/**
* Staged blobs up to this size are read whole and scanned in memory; larger
* ones are streamed through the windowed scan (secret-scan-stream.ts) up to
* PUSH_STREAM_SCAN_MAX_BYTES.
*/
export const PUSH_MAX_SCAN_BYTES = SCAN_MAX_FILE_BYTES;
/**
* Hard ceiling of the streamed pre-push scan: a staged blob over it blocks the
* push as unscannable. Above the largest canonical file (a 256 MiB page plus
* its frontmatter).
*/
export const PUSH_STREAM_SCAN_MAX_BYTES = 512 * 1024 ** 2;
// ── Cross-platform push lock [CX2-6, G14/A5] ────────────────────────────────
/** A holder is stolen only when pid is DEAD **and** the lock is older than this. */
export const PUSH_LOCK_STALE_MS = 120_000;
interface LockOwner {
pid: number;
acquired_at: string; // ISO
token: string;
}
export interface PushLockHandle {
dir: string;
token: string;
release(): void;
}
export type PushLockResult =
| { acquired: true; handle: PushLockHandle }
| { acquired: false; holderPid: number | null };
export function pushLockDir(repoRoot: string): string {
let canonical = repoRoot;
try { canonical = realpathSync(repoRoot); } catch { /* absent or unresolvable: hash the raw path */ }
const hash = createHash('sha256').update(canonical).digest('hex').slice(0, 16);
return join(ensureGbrainHome(), 'locks', `push-${hash}.lock`);
}
function readLockOwner(lockDir: string): LockOwner | null {
try {
const raw = JSON.parse(readFileSync(join(lockDir, 'owner.json'), 'utf-8'));
if (typeof raw?.pid === 'number' && typeof raw?.acquired_at === 'string' && typeof raw?.token === 'string') {
return raw as LockOwner;
}
return null;
} catch {
return null;
}
}
function lockAgeMs(lockDir: string, owner: LockOwner | null): number {
if (owner) {
const t = Date.parse(owner.acquired_at);
if (Number.isFinite(t)) return Date.now() - t;
}
try {
return Date.now() - statSync(lockDir).mtimeMs;
} catch {
return 0; // can't tell → treat as fresh (never steal on uncertainty)
}
}
function tryMkdirLock(lockDir: string): boolean {
try {
mkdirSync(lockDir); // atomic on POSIX — the lock primitive [CX2-6]
return true;
} catch {
return false;
}
}
/**
* Acquire the per-repo push lock. Never blocks: returns `{acquired: false}`
* with the live holder's pid when contended. Steals ONLY dead-pid AND
* stale-age holders (both — the pid-reuse learning); a live pid is never
* stolen regardless of age, and a young lock is never stolen regardless of
* pid state (a concurrent acquirer may not have written owner.json yet).
*/
export function acquirePushLock(repoRoot: string): PushLockResult {
const lockDir = pushLockDir(repoRoot);
mkdirSync(dirname(lockDir), { recursive: true, mode: 0o700 });
const writeOwnerAndHandle = (): PushLockResult => {
const owner: LockOwner = {
pid: process.pid,
acquired_at: new Date().toISOString(),
token: randomBytes(16).toString('hex'),
};
writeFileSync(join(lockDir, 'owner.json'), JSON.stringify(owner), { mode: 0o600 });
return {
acquired: true,
handle: {
dir: lockDir,
token: owner.token,
release: () => releasePushLock(lockDir, owner.token),
},
};
};
if (tryMkdirLock(lockDir)) return writeOwnerAndHandle();
const owner = readLockOwner(lockDir);
const alive = owner ? isProcessAlive(owner.pid) : false; // no owner file → can't prove alive
const age = lockAgeMs(lockDir, owner);
if (!alive && age > PUSH_LOCK_STALE_MS) {
// Dead AND stale → steal: remove, then re-race the mkdir exactly once.
try {
rmSync(lockDir, { recursive: true, force: true });
} catch { /* raced with another stealer */ }
if (tryMkdirLock(lockDir)) return writeOwnerAndHandle();
return { acquired: false, holderPid: readLockOwner(lockDir)?.pid ?? null };
}
return { acquired: false, holderPid: owner?.pid ?? null };
}
/** Ownership-checked release: only removes the lock if OUR token still owns it. */
function releasePushLock(lockDir: string, token: string): void {
try {
const owner = readLockOwner(lockDir);
if (owner && owner.token !== token) return; // stolen + re-acquired — not ours
rmSync(lockDir, { recursive: true, force: true });
} catch { /* best-effort */ }
}
// ── git helpers ─────────────────────────────────────────────────────────────
function git(
root: string,
args: string[],
opts: { timeoutMs?: number; auth?: boolean } = {},
): string {
return execFileSync('git', ['-C', root, ...args], {
stdio: ['ignore', 'pipe', 'pipe'],
timeout: opts.timeoutMs ?? 60_000,
maxBuffer: 64 * 1024 * 1024,
env: gitChildEnv({ ...(opts.auth ? GIT_ENV_AUTH : GIT_ENV) }),
}).toString();
}
/** PR B: the workspace push commit, with its commit-ledger intent and commit lines (src/core/git/commit-ledger.ts). */
function commitRecorded(root: string, message: string): void {
recordIntent(root, { writer: 'workspace_push', head_before: tryGit(root, ['rev-parse', '--verify', '--quiet', 'HEAD']), message });
git(root, ['commit', '-m', message], { timeoutMs: 60_000 });
recordCommit(root, { sha: tryGit(root, ['rev-parse', 'HEAD']) ?? '', writer: 'workspace_push' });
}
function tryGit(root: string, args: string[], opts: { timeoutMs?: number; auth?: boolean } = {}): string | null {
try {
return git(root, args, opts).trim();
} catch {
return null;
}
}
/** Raw-bytes git output (no encoding) — for reading staged blobs verbatim. */
function gitBuffer(root: string, args: string[], timeoutMs = 60_000): Buffer {
return execFileSync('git', ['-C', root, ...args], {
stdio: ['ignore', 'pipe', 'pipe'],
timeout: timeoutMs,
maxBuffer: 64 * 1024 * 1024,
env: gitChildEnv({ ...GIT_ENV }),
});
}
/**
* Mirror of git-remote.ts's private `durableSsrfFlags()`: push acts on an
* ALREADY-configured origin; the file transport honors the same env escape
* hatch (`GBRAIN_GIT_ALLOW_FILE_TRANSPORT=1`) the durability paths and the
* test suite use. Default stays `never`.
*/
function pushSsrfFlags(): string[] {
const fileAllow = process.env.GBRAIN_GIT_ALLOW_FILE_TRANSPORT === '1' ? 'always' : 'never';
return [
'-c', 'http.followRedirects=false',
'-c', `protocol.file.allow=${fileAllow}`,
'-c', 'protocol.ext.allow=never',
];
}
/** Resolve the repo ROOT for any dir inside it [CX2-3]; null when not a repo. */
export function resolveWorkspaceRoot(dir: string): string | null {
return tryGit(dir, ['rev-parse', '--show-toplevel'], { timeoutMs: 10_000 });
}
function listZ(root: string, args: string[]): string[] {
const out = git(root, [...args, '-z']);
return out.split('\0').filter((s) => s.length > 0);
}
/**
* Index blob id and size of each of `paths` (stage 0 entries only), from one
* `ls-files -s` and one `cat-file --batch-check`. Empty on any git error: a
* path missing here takes the whole-blob read, which fails closed.
*/
function stagedBlobSizes(root: string, paths: readonly string[]): Map<string, { oid: string; size: number }> {
const out = new Map<string, { oid: string; size: number }>();
try {
const wanted = new Set(paths);
const entries = listZ(root, ['ls-files', '-s']).flatMap((rec) => {
const m = /^(\d{6}) ([0-9a-f]+) 0\t(.*)$/s.exec(rec);
return m && m[1] !== '160000' && wanted.has(m[3]!) ? [{ oid: m[2]!, path: m[3]! }] : [];
});
if (entries.length === 0) return out;
const batch = execFileSync('git', ['-C', root, 'cat-file', '--batch-check=%(objectname) %(objecttype) %(objectsize)'], {
input: entries.map((e) => e.oid).join('\n') + '\n',
stdio: ['pipe', 'pipe', 'pipe'],
timeout: 60_000,
maxBuffer: 64 * 1024 * 1024,
env: gitChildEnv({ ...GIT_ENV }),
}).toString();
const sizes = new Map<string, number>();
for (const line of batch.split('\n')) {
const [oid, type, size] = line.split(' ');
if (type === 'blob') sizes.set(oid!, Number(size));
}
for (const e of entries) {
const size = sizes.get(e.oid);
if (size !== undefined) out.set(e.path, { oid: e.oid, size });
}
} catch {
out.clear();
}
return out;
}
/**
* Stream one staged blob (`git cat-file blob <oid>`) through the windowed
* scan, never holding it whole. Throws when git fails, exceeds 10 minutes, or
* delivers a byte count other than the index recorded.
*/
async function scanStagedBlobStreamed(root: string, blob: { oid: string; size: number }, allowlist: string[]): Promise<SecretFinding[]> {
const child = spawn('git', ['-C', root, 'cat-file', 'blob', blob.oid], {
stdio: ['ignore', 'pipe', 'pipe'],
env: gitChildEnv({ ...GIT_ENV }),
});
const exited = new Promise<number | null>((resolve, reject) => {
child.once('error', reject);
child.once('close', resolve);
});
exited.catch(() => {});
let stderr = '';
child.stderr.on('data', (d: Buffer) => { stderr = (stderr + d.toString()).slice(0, 200); });
let bytes = 0;
async function* counted(): AsyncGenerator<Uint8Array> {
for await (const chunk of child.stdout) {
bytes += (chunk as Buffer).length;
yield chunk as Buffer;
}
}
const timer = setTimeout(() => child.kill('SIGKILL'), 600_000);
try {
const findings = await scanTextStream(counted(), { allowlist });
const code = await exited;
if (code !== 0) throw new Error(`git cat-file exited ${code}: ${stderr.trim()}`);
if (bytes !== blob.size) throw new Error(`read ${bytes} of ${blob.size} bytes`);
return findings;
} finally {
clearTimeout(timer);
if (child.exitCode === null && child.signalCode === null) child.kill('SIGKILL');
}
}
/**
* Read and scan one staged, non-deleted blob: its findings, or the
* `unscannable` entry naming why it cannot be proven clean (fail closed).
* Up to PUSH_MAX_SCAN_BYTES (or when its size is unknown) the blob is read
* whole; above it, streamed by oid up to PUSH_STREAM_SCAN_MAX_BYTES.
*/
async function scanStagedBlob(
root: string, rel: string, staged: { oid: string; size: number } | undefined, allowlist: string[],
): Promise<SecretFinding[] | string> {
if (staged && staged.size > PUSH_MAX_SCAN_BYTES) {
if (staged.size > PUSH_STREAM_SCAN_MAX_BYTES) return `${rel} (${staged.size}B exceeds the ${PUSH_STREAM_SCAN_MAX_BYTES}B scan ceiling)`;
try {
return await scanStagedBlobStreamed(root, staged, allowlist);
} catch (e) {
return `${rel} (unreadable: ${(e as Error).message.slice(0, 80)})`;
}
}
let blob: Buffer;
try {
blob = gitBuffer(root, ['cat-file', '-p', `:${rel}`]);
} catch (e) {
// NOT a deletion (the caller checked) — we cannot prove this file is clean.
// A blob we can't read (missing index entry, over maxBuffer, git error)
// must never sail through the only pre-push secret gate.
return `${rel} (unreadable: ${(e as Error).message.slice(0, 80)})`;
}
if (blob.length > PUSH_MAX_SCAN_BYTES) {
// Its size was not looked up, and it is too big to scan in-memory → block rather than exempt.
return `${rel} (${blob.length}B exceeds the ${PUSH_MAX_SCAN_BYTES}B scan cap)`;
}
// Binary (NUL-sniffed) files are scanned ANYWAY — a NUL byte doesn't mean
// the blob is secret-free (an ASCII key can sit inside a "binary" file).
// Buffer.toString('utf-8') keeps ASCII runs intact so the named patterns
// still fire; invalid byte sequences become U+FFFD and simply don't match.
const text = blob.toString('utf-8');
return scanText(text, { allowlist });
}
/**
* Ensure SOME git identity exists so the commit can't fail on a fresh
* machine. Never overrides an existing name/email (any config scope).
*/
function ensureLocalIdentity(root: string): void {
if (tryGit(root, ['config', '--get', 'user.email']) === null) {
git(root, ['config', 'user.email', 'bootstrap@localhost']);
}
if (tryGit(root, ['config', '--get', 'user.name']) === null) {
git(root, ['config', 'user.name', 'gbrain-bootstrap']);
}
}
// ── Remote-privacy verification [G8] ────────────────────────────────────────
export type RemotePrivacyVerdict =
| { verdict: 'private' }
| { verdict: 'not_private'; detail: string }
| { verdict: 'unverifiable'; detail: string };
/** Parse `owner/repo` out of a github.com remote URL (https, scp-like, or
* ssh://). Back-compat adapter over the canonical repo-visibility parser. */
export function parseGithubOwnerRepo(url: string): string | null {
return githubOwnerRepoString(url);
}
/**
* Verify the origin remote is a PRIVATE repo via the repo-visibility ladder
* (REST first, git-protocol fallback — see repo-visibility.ts for the full
* verdict matrix). Anything short of a proven `private` is either
* `not_private` (proven public) or `unverifiable` — the caller refuses both
* unless an escape hatch is set [G8: never fail-open]. Fresh `private`
* verdicts are cached (1h TTL, private-only) so the per-turn push cadence
* doesn't re-pay the network probes every turn [D11].
*/
export async function verifyRemotePrivacy(root: string): Promise<RemotePrivacyVerdict> {
const url = tryGit(root, ['remote', 'get-url', 'origin'], { timeoutMs: 10_000 });
if (!url) return { verdict: 'unverifiable', detail: 'no origin remote configured' };
if (readCachedPrivateVerdict(url) !== null) return { verdict: 'private' };
const v = await verifyRepoVisibility({ originUrl: url, repoDir: root });
writeVisibilityCache(url, v);
if (v.verdict === 'private') return { verdict: 'private' };
if (v.verdict === 'public') return { verdict: 'not_private', detail: v.detail };
return { verdict: 'unverifiable', detail: v.detail };
}
/** File-plane escape hatch [D18]: `gbrain config set push.allow_unverified_remote true`.
* Read tolerantly from ~/.gbrain/config.json — detached hook children never see
* a shell export, and the DB plane is unreadable while a serve holds the
* single-writer lock, so the file plane is the only channel that always works. */
export function configAllowsUnverifiedRemote(): boolean {
try {
const cfg = loadConfigFileOnly();
const v = cfg?.push?.allow_unverified_remote as unknown;
return v === true || v === 'true' || v === '1';
} catch {
return false;
}
}
// ── push-status.json [B4] ───────────────────────────────────────────────────
/** Legacy single-file location (pre-per-root). Read-only compatibility: the
* reader consults it only when NO per-root files exist yet (fresh upgrade). */
export function pushStatusPath(): string {
return join(ensureGbrainHome(), 'bootstrap', 'push-status.json');
}
/** Stable short key for per-root state files [D3/D13]: one gbrain home serves
* many bootstrap workspaces, so every push/debounce/announce state file is
* keyed by workspace root — a single shared file is last-writer-wins, which
* either masks one workspace's failure or defeats another's debounce. */
export function workspaceRootHash(root: string): string {
return createHash('sha256').update(root).digest('hex').slice(0, 12);
}
export function pushStatusPathForRoot(root: string): string {
return join(ensureGbrainHome(), 'bootstrap', `push-status-${workspaceRootHash(root)}.json`);
}
/** One parsed push-status record [D8: one reader, three formatters]. */
export interface PushStatusEntry {
ts?: string;
ok?: boolean;
reason?: string;
ahead?: number;
repoRoot?: string;
/** #6083: machine code of a refusal (`writer_coordinator_required` on a managed worktree). */
code?: string;
/** Absolute path of the status file (per-root announce-state keying). */
file: string;
}
const PUSH_STATUS_FILE_RE = /^push-status-[0-9a-f]{12}\.json$/;
/** One push-status file as a record, or null when it is missing, torn or not
* a JSON object (#7377: a whole-file primitive, array or null is unreadable,
* never an empty record that reads as a success). Never throws. */
function parsePushStatusFile(file: string): PushStatusEntry | null {
try {
const s: unknown = JSON.parse(readFileSync(file, 'utf8'));
return s !== null && typeof s === 'object' && !Array.isArray(s) ? { ...(s as Omit<PushStatusEntry, 'file'>), file } : null;
} catch {
return null;
}
}
/** #7377: a recorded repoRoot is gone only when stat answers ENOENT or
* ENOTDIR. A denied traversal (EACCES, EPERM), an I/O error or a value that
* is not an absolute path is unreadable, never proof the workspace is gone. */
function pushStatusRootState(root: unknown): 'present' | 'gone' | 'unreadable' {
if (root === undefined) return 'present';
if (typeof root !== 'string' || !isAbsolute(root)) return 'unreadable';
try {
statSync(root);
return 'present';
} catch (err) {
const code = (err as NodeJS.ErrnoException).code;
return code === 'ENOENT' || code === 'ENOTDIR' ? 'gone' : 'unreadable';
}
}
/** Every authoritative push-status file, classified: a live record, the
* record of a workspace that no longer exists, or unreadable. Per-root files
* win; the legacy global file is consulted only when none exist. */
function classifyPushStatusFiles(): Array<PushStatusEntry | 'gone' | 'unreadable'> {
const dir = join(ensureGbrainHome(), 'bootstrap');
let names: string[] = [];
try {
names = readdirSync(dir).filter((n) => PUSH_STATUS_FILE_RE.test(n));
} catch {
return [];
}
// The legacy file is consulted only when NO per-root FILES exist on disk —
// a stale pre-upgrade record must never shadow live-but-unreadable state.
if (names.length === 0) {
const legacy = parsePushStatusFile(pushStatusPath());
return legacy ? [legacy] : existsSync(pushStatusPath()) ? ['unreadable'] : [];
}
return names.map((n) => {
// nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- n is a readdirSync(dir) entry that matched PUSH_STATUS_FILE_RE
const entry = parsePushStatusFile(join(dir, n));
if (!entry) return 'unreadable';
// A record whose workspace no longer exists is a ghost: it can never be
// cleared by a re-push (the root is gone), so it must not feed the
// failure banner / staleness note forever (deleted Conductor workspaces
// are routine). Entries without repoRoot (legacy shape in a per-root
// file) are kept — absence of evidence is not a ghost.
const state = pushStatusRootState(entry.repoRoot);
return state === 'present' ? entry : state;
});
}
/** Tolerant reader over every push-status file (banner, SessionStart note,
* and doctor all consume THIS — one parse, one schema owner). Per-root files
* win; the legacy global file is consulted only when none exist, so a stale
* pre-upgrade record can't shadow live per-root state. Unreadable files and
* records of gone workspaces are skipped; doctor tells them apart with
* pushStatusRecordCounts. */
export function readPushStatuses(): PushStatusEntry[] {
return classifyPushStatusFiles().filter((e): e is PushStatusEntry => typeof e !== 'string');
}
/** #7377: how many authoritative push-status files hold the record of a
* workspace that no longer exists, and how many hold nothing readable. Doctor
* reads an empty readPushStatuses() through this, so retained history of
* deleted workspaces is not reported as an unreadable status. */
export function pushStatusRecordCounts(): { gone: number; unreadable: number } {
const states = classifyPushStatusFiles();
return { gone: states.filter((s) => s === 'gone').length, unreadable: states.filter((s) => s === 'unreadable').length };
}
/** True when any push-status file exists on disk (parseable or not). The
* reader skips corrupt files silently; doctor pairs this with an empty read
* to say "status present but unreadable" instead of saying nothing. */
export function pushStatusFilesExist(): boolean {
const dir = join(ensureGbrainHome(), 'bootstrap');
try {
if (readdirSync(dir).some((n) => PUSH_STATUS_FILE_RE.test(n))) return true;
} catch {
/* fall through */
}
return existsSync(pushStatusPath());
}
/** The per-root status for one workspace, or null. Direct keyed read first —
* the scan is only a fallback for legacy records carrying a repoRoot field. */
export function readPushStatusForRoot(root: string): PushStatusEntry | null {
return parsePushStatusFile(pushStatusPathForRoot(root)) ?? readPushStatuses().find((e) => e.repoRoot === root) ?? null;
}
/**
* #5432: the push-status record that belongs to workspace `ws`, or null. A
* record matches by its repoRoot (symlinks resolved on both sides); a single
* legacy record with no repoRoot is attributed to `ws`. Another root's record
* is never reported as this workspace's push state.
*/
export function pushStatusForWorkspace(entries: readonly PushStatusEntry[], ws: string): PushStatusEntry | null {
// nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- comparison only: normalizes the operator's own push-status repoRoot and workspace path to compare them; nothing is read or written at the resolved path
const real = (p: string) => { try { return realpathSync(p); } catch { return resolve(p); } };
const target = real(ws);
const own = entries.find((e) => e.repoRoot !== undefined && real(e.repoRoot) === target);
if (own) return own;
return entries.length === 1 && entries[0]!.repoRoot === undefined ? entries[0]! : null;
}
/** One aggregation for every status surface (SessionStart note, doctor,
* banner counting): the failing entries and the stalest success timestamp. */
/** Failure reasons carry remote-influenced text (git stderr → rung log →
* push-status.reason). Clamp to a safe printable charset + length before ANY
* model- or human-visible surface embeds it (banner, doctor, status blob) so
* it can't become an injection or formatting vector — the free-form
* counterpart to hook.ts's reasonCode() for typed codes. */
export function sanitizePushReason(reason: string | undefined): string {
if (!reason) return 'unknown reason';
return reason.replace(/[^\x20-\x7E]/g, ' ').replace(/[`$\\]/g, "'").slice(0, 140);
}
const PUSH_REASON_MAX_CHARS = 140;
/**
* The `blocked_secrets` reason: a summary that `sanitizePushReason` passes
* through unclipped, so hook and doctor surfaces show the count, the first
* location and where the fix steps are. The location keeps its tail (file
* name and line) when the budget is short.
*/
export function blockedSecretsReason(findings: readonly PushSecretFinding[]): string {
const first = findings[0]!;
const head = `${findings.length} secret finding(s), first `;
const tail = ` [${first.pattern}]; nothing committed. Run gbrain sources push for fix steps`;
const budget = PUSH_REASON_MAX_CHARS - head.length - tail.length;
const loc = `${first.file}:${first.line}`;
const shown = loc.length <= budget ? loc : `...${loc.slice(-Math.max(1, budget - 3))}`;
return `${head}${shown}${tail}`.slice(0, PUSH_REASON_MAX_CHARS);
}
/**
* DX-4: before the scanner learned truncated key bodies, a private key with
* no END fence in view was claimed header-only, so an allowlist line could
* hold the fingerprint of the bare BEGIN header. The scanner reports that
* pre-wave fingerprint as `legacyFingerprint`; return the allowlist entry it
* matches, if any.
*/
function staleHeaderOnlyEntry(legacyFingerprint: string | undefined, allowlist: readonly string[]): string | undefined {
if (!legacyFingerprint) return undefined;
const legacyHex = legacyFingerprint.slice('sha256:'.length);
return allowlist.find((entry) => {
if (!entry.startsWith('sha256:')) return false;
const prefix = entry.slice('sha256:'.length).toLowerCase();
return prefix.length >= ALLOWLIST_FINGERPRINT_MIN_HEX && prefix.startsWith(legacyHex);
});
}
/** The exact `gbrain sources push` invocation that re-runs this push from any directory. */
function pushRetryCommand(opts: WorkspacePushOpts): string {
return [
// nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- display only: the printed retry command names the caller's own workspace dir; nothing is read or written here.
'gbrain sources push --path', shellQuote(resolve(opts.dir)),
...(opts.branch ? ['--branch', shellQuote(opts.branch)] : []),
...(opts.allowUnverifiedRemote ? ['--allow-unverified-remote'] : []),
].join(' ');
}
/** Attach the DX-3 refusal guidance to one file's findings; no value ever reaches the output. */
export function buildPushFindings(input: {
file: string;
findings: readonly SecretFinding[];
allowlist: readonly string[];
allowlistPath: string;
retryCommand: string;
}): PushSecretFinding[] {
return input.findings.map(({ legacyFingerprint, ...f }) => {
const out: PushSecretFinding = {
...f,
file: input.file,
allowlistPath: input.allowlistPath,
allowCommand: `printf '\\n%s\\n' ${f.fingerprint} >> ${shellQuote(input.allowlistPath)}`,
retryCommand: input.retryCommand,
docs: SECRET_SCAN_REFUSAL_DOCS,
};
const entry = staleHeaderOnlyEntry(legacyFingerprint, input.allowlist);
if (entry) out.staleAllowlistEntry = { entry, replacement: f.fingerprint };
return out;
});
}
/**
* Human rendering of a `blocked_secrets` result for `gbrain sources push`.
* Every line comes from the structured findings, so the CLI text and the
* `--json` output carry the same commands.
*/
export function formatBlockedSecrets(findings: readonly PushSecretFinding[]): string[] {
const version = (since: string) => `gbrain v${since.replace(/^v/, '')}`;
const lines = ['PUSH BLOCKED — secret scan findings (nothing committed):'];
for (const f of findings) {
lines.push(` ${f.file}:${f.line} [${f.pattern}] ${f.redactedPreview}`);
lines.push(` fingerprint: ${f.fingerprint}`);
if (f.since) lines.push(` rule [${f.pattern}] blocks pushes since ${version(f.since)}`);
if (f.staleAllowlistEntry) {
const { entry, replacement } = f.staleAllowlistEntry;
lines.push(
` stale allowlist entry: ${entry} matched only this key's BEGIN header ` +
`${f.since ? `before ${version(f.since)}` : 'before this version'}; the fingerprint now covers the key body.`,
);
lines.push(` if the key is a reviewed false positive, replace that line in ${shellQuote(f.allowlistPath)} with: ${replacement}`);
}
lines.push(` allow this finding: ${f.allowCommand}`);
}
const first = findings[0];
if (!first) return lines;
lines.push(
'Remove a real credential from the file (and rotate it) first. Allowlist only a reviewed false positive',
`with the "allow this finding" command above (it appends to ${shellQuote(first.allowlistPath)}), then retry:`,
` ${first.retryCommand}`,
`Docs: ${first.docs}`,
);
return lines;
}
/**
* #5799: a recorded push status that no longer describes a live legacy push.
* On a managed canonical worktree the legacy push is fenced
* (`writer_coordinator_required`) and the coordinator's git effect publishes
* page writes without ever writing push-status, so the refusal record (or a
* success from before the worktree was claimed) would feed the FAILING
* banner and the staleness note forever. True for a refusal record (its
* `code`, or the `reason` prefix an older record carries) and for any record
* whose root is a managed worktree now. A root whose marker cannot be read
* is not assumed managed.
*/
export function isSupersededPushStatus(entry: Pick<PushStatusEntry, 'code' | 'reason' | 'repoRoot'>): boolean {
if (entry.code === 'writer_coordinator_required' || entry.reason?.startsWith('writer_coordinator_required:')) return true;
if (entry.repoRoot === undefined) return false;
try {
return isManagedFilesystemPath(entry.repoRoot);
} catch {
return false;
}
}
/** The recorded statuses that still describe a live legacy push (#5799); the status surfaces read these. */
export function livePushStatuses(entries: readonly PushStatusEntry[]): PushStatusEntry[] {
return entries.filter((e) => !isSupersededPushStatus(e));
}
export function summarizePushStatuses(entries: PushStatusEntry[]): {
failing: PushStatusEntry[];
stalestTs: number | null;
} {
const failing = entries.filter((e) => e.ok === false);
const stamps = entries.map((e) => Date.parse(e.ts ?? '')).filter((t) => Number.isFinite(t));
return { failing, stalestTs: stamps.length > 0 ? Math.min(...stamps) : null };
}
function writePushStatus(
status: { ts: string; ok: boolean; reason?: string; ahead?: number; repoRoot: string; code?: string },
): void {
try {
const p = pushStatusPathForRoot(status.repoRoot);
mkdirSync(dirname(p), { recursive: true, mode: 0o700 });
// tmp+rename (the writeReceipt pattern): a concurrent reader never sees a
// torn half-written status file.
const tmp = `${p}.tmp-${process.pid}`;
writeFileSync(tmp, JSON.stringify(status, null, 2) + '\n', { mode: 0o600 });
renameSync(tmp, p);
} catch { /* best-effort — status telemetry never fails a push */ }
}
// ── The push sequence ───────────────────────────────────────────────────────
function sleep(ms: number): Promise<void> {
return new Promise((r) => setTimeout(r, ms));
}
/** Commits ahead of origin/<branch> (undefined when git can't answer).
* Exported for the backup-coverage probe (src/core/backup/coverage.ts). */
export function aheadCount(root: string, branch: string): number | undefined {
const out = tryGit(root, ['rev-list', '--count', `origin/${branch}..HEAD`], { timeoutMs: 15_000 });
if (out === null) return undefined;
const n = parseInt(out, 10);
return Number.isFinite(n) ? n : undefined;
}
/**
* #5606: `sources push` on a managed canonical worktree is refused with the
* managed equivalent named, not a bare "submit through the coordinator": the
* persistence owner's Git effect is the writer for page files, the writer
* verbs check and enable it, and files that are not pages are the operator's
* to push with plain git. Same code, so every surface that keys on it still does.
*/
export function managedPushRefusal(dir: string, root: string | null | undefined, cause: OperationError): OperationError {
const managed = managedFilesystemRootFor(root ?? dir) ?? managedFilesystemRootFor(dir);
const source = managed?.sourceId;
const name = source ?? '<source>';
const error = new OperationError('writer_coordinator_required',
`${managed?.root ?? root ?? dir} is the managed canonical worktree${source ? ` of source ${source}` : ''}; gbrain sources push is not its Git writer.`,
`Page writes there are committed and pushed by the persistence owner's Git effect, not by sources push. Check it with gbrain sources writer status${source ? ` ${source}` : ''} --json `
+ `(git_durability, parked effects). If git_durability is off or unknown, enable it with gbrain sources writer git-durability ${name} --enable --dry-run, then the apply command it prints; `
+ `after a push credential change, gbrain sources writer git-durability ${name} --pat-file <path> re-wires it and retries the parked pushes. `
+ 'Files that are not gbrain pages (MEMORY.md, daily notes) are not published by the owner: review the diff and push them with plain git; the sources push secret scan does not run then.');
error.detail = cause.detail;
return error;
}
type PushFailure = Pick<WorkspacePushResult, 'reason' | 'code' | 'suggestion' | 'detail'> & { status: 'error' | 'push_failed' | 'blocked_history' };
/**
* Step 7 of {@link workspacePush}: the push carries every local commit origin lacks, including ones a script made with
* plain `git commit` that the staged scan never saw, so the exact commit pushed is range-scanned against origin's tip,
* read from origin itself (the pull may have fetched another upstream remote) and leased on (#8902). Tags never ride
* along. Returns the failure (blocked_history for a scan refusal), or null when pushed.
*/
function pushScannedHead(root: string, branch: string, log: (line: string) => void, scanTimeoutMs?: number): PushFailure | null {
const target = tryGit(root, ['rev-parse', '--verify', 'HEAD^{commit}']);
if (!target) return { status: 'error', reason: 'HEAD names no commit; nothing to push' };
const heads = tryGit(root, [...pushSsrfFlags(), 'ls-remote', '--heads', 'origin', `refs/heads/${branch}`], { timeoutMs: 120_000, auth: true });
if (heads === null) return { status: 'push_failed', reason: `could not read origin's ${branch}; nothing pushed` };
const fetched = !heads || tryGit(root, [...pushSsrfFlags(), 'fetch', ...GIT_SSRF_SUBCOMMAND_FLAGS, '--no-tags', 'origin',
`+refs/heads/${branch}:refs/remotes/origin/${branch}`], { timeoutMs: 120_000, auth: true }) !== null;
if (!fetched) return { status: 'push_failed', reason: `could not fetch origin's ${branch}; nothing pushed` };
const base = heads ? tryGit(root, ['rev-parse', '--verify', '--quiet', `refs/remotes/origin/${branch}^{commit}`]) ?? '' : '';
if (heads && !base) return { status: 'push_failed', reason: `could not read origin's ${branch} after fetching it; nothing pushed` };
if (base && tryGit(root, ['merge-base', '--is-ancestor', base, target]) === null) {
return { status: 'push_failed', reason: `local ${branch} does not contain origin/${branch}; nothing pushed (rerun to pull first)` };
}
const refusal = stagedScanPublishRefusal(root, base, target, { timeoutMs: scanTimeoutMs, progress: log, retryArgv: ['gbrain', 'sources', 'push', '--path', root] });
if (refusal) {
log(`PUSH BLOCKED: ${refusal.code}: ${refusal.message}`);
return { status: 'blocked_history', code: refusal.code, reason: `${refusal.code}: ${refusal.message}`, suggestion: refusal.suggestion,
...(refusal.detail !== undefined ? { detail: String(refusal.detail) } : {}) };
}
try {
git(root, [...pushSsrfFlags(), 'push', ...GIT_SSRF_SUBCOMMAND_FLAGS, '--no-follow-tags', '--recurse-submodules=no', `--force-with-lease=refs/heads/${branch}:${base}`, 'origin', `${target}:refs/heads/${branch}`], {
timeoutMs: 120_000, auth: true,
});
return null;
} catch (e) {
return { status: 'push_failed', reason: `git push failed: ${(e as Error).message.slice(0, 200)}` };
}
}
export async function workspacePush(opts: WorkspacePushOpts): Promise<WorkspacePushResult> {
const log = (line: string) => opts.logger?.(line);
const root = resolveWorkspaceRoot(opts.dir);
try {
assertManagedFilesystemWrite(opts.dir);
if (root) assertManagedFilesystemWrite(root);
} catch (e) {
// #5198: the managed-worktree guard refuses before the lock and before
// finish(), so without this the previous success stays on record and every
// status surface calls a push that can never run "stale" instead of failing.
// No lock winner can be in flight here: the same guard refuses every legacy
// push of this root.
const refusal = e instanceof OperationError && e.code === 'writer_coordinator_required' ? managedPushRefusal(opts.dir, root, e) : e;
if (root && refusal instanceof OperationError) {
writePushStatus({ ts: new Date().toISOString(), ok: false, code: refusal.code, reason: `${refusal.code}: ${refusal.message}`, repoRoot: root });
}
throw refusal;
}
if (!root) {
return { ok: false, status: 'error', reason: `not a git repository: ${opts.dir}` };
}
const branch = opts.branch || detectDefaultBranch(root);
// ONE lock spans scan → stage → commit → pull → push [G14/A5, CX2-6].
const lock = acquirePushLock(root);
if (!lock.acquired) {
return {
ok: true,
status: 'skipped_in_flight',
repoRoot: root,
branch,
lockHolderPid: lock.holderPid,
reason: `push in flight (pid ${lock.holderPid ?? 'unknown'})`,
};
}
const finish = (r: WorkspacePushResult): WorkspacePushResult => {
// B4: written on success AND failure — only by the lock WINNER (a skip
// must not clobber the in-flight run's eventual status). Keyed per root
// [D13] so one workspace's success can never mask another's failure.
writePushStatus({
ts: new Date().toISOString(),
ok: r.ok,
...(r.code !== undefined ? { code: r.code } : {}),
...(r.reason !== undefined ? { reason: r.reason } : {}),
...(r.ahead !== undefined ? { ahead: r.ahead } : {}),
repoRoot: root,
});
// Fix-path invalidation: a successful push changes the backup-coverage
// answer (workspace failing→ok, unpushed→pushed) — but ONLY when the
// cached verdict carried something a push can fix. The routine healthy
// stop-push must not delete an ok cache every session (that would defeat
// the monthly compute throttle for the healthiest cohort).
if (r.ok) {
try {
const s = loadBackupStatus();
if (s && (s.overall === 'warn' || s.totals.failing > 0 || s.totals.unpushed > 0)) {
invalidateBackupStatus();
}
} catch {
/* best-effort */
}
}
return r;
};
try {
if (opts.holdLockMs && opts.holdLockMs > 0) await sleep(opts.holdLockMs);
// 2. deny-glob inputs: tracked + untracked listings. `--others` deliberately WITHOUT
// --exclude-standard: a gitignored deny match (brain.pglite behind a
// `*.pglite` ignore line) is still reported loudly in excludedUntracked.
let tracked: string[];
let untracked: string[];
try {
tracked = listZ(root, ['ls-files', '--cached']);
untracked = listZ(root, ['ls-files', '--others']);
} catch (e) {
return finish({
ok: false, status: 'error', repoRoot: root, branch,
reason: `git ls-files failed: ${(e as Error).message.slice(0, 140)}`,
});
}
// Deny-glob backstop [G6]: TRACKED match = hard fail, .gitignore state
// irrelevant (that's the point — a truncated .gitignore can't leak).
const denyMatch = (p: string) => PUSH_DENY_GLOBS.some((g) => matchesGlob(g, p));
const trackedDeny = tracked.filter(denyMatch);
if (trackedDeny.length > 0) {
const reason =
`tracked file(s) match the deny list (${trackedDeny.slice(0, 10).join(', ')}` +
`${trackedDeny.length > 10 ? ', …' : ''}) — remove from the index ` +
`(git rm --cached <path>) before pushing`;
log(`PUSH BLOCKED: ${reason}`);
return finish({
ok: false, status: 'blocked_tracked_deny', repoRoot: root, branch,
denyMatches: trackedDeny, reason,
});
}
// `--others` excludes index entries, so every listing IS untracked.
const untrackedDeny = untracked.filter(denyMatch);
// 3. stage FIRST — the scan below reads the STAGED blobs, so scanned
// bytes == committed bytes (scanning disk before `add -A` left a TOCTOU
// window where a file mutated after the snapshot was committed unscanned).
const excludedUntracked: string[] = [];
let stagedForScan: string[];
try {
ensureLocalIdentity(root);
git(root, ['add', '-A'], { timeoutMs: 120_000 });
// Un-stage any newly-added deny match (tracked ones already hard-failed
// above, so anything staged AND deny-matched got here via add -A —
// untrackedDeny names the expected set; the staged list is the source
// of truth). `git rm --cached` un-adds without touching the disk file.
const staged = listZ(root, ['diff', '--cached', '--name-only']);
for (const p of staged.filter(denyMatch)) {
git(root, ['rm', '--cached', '-q', '--', p]);
excludedUntracked.push(p);
log(`excluded from commit (deny list): ${p}`);
}
for (const p of untrackedDeny) {
if (!excludedUntracked.includes(p)) {
excludedUntracked.push(p); // ignored-but-deny-matched: never staged, still reported
}
}
stagedForScan = staged.filter((p) => !denyMatch(p));
} catch (e) {
return finish({
ok: false, status: 'error', repoRoot: root, branch,
reason: `stage/commit failed: ${(e as Error).message.slice(0, 200)}`,
});
}
// 4. secret scan over the STAGED content. This is the SOLE
// block-secrets-before-they-leave control, so it FAILS CLOSED: the only
// benign "no blob" case is a staged DELETION (removes content — nothing to
// leak); every OTHER unscannable case (cat-file error, a blob over
// PUSH_STREAM_SCAN_MAX_BYTES) BLOCKS the push naming the path, rather than
// silently exempting it. `git cat-file -p :<path>` reads the index blob
// verbatim (no filters) — exactly what a commit would record; a blob over
// PUSH_MAX_SCAN_BYTES is streamed by its index oid and scanned in windows.
let stagedDeletions: Set<string>;
try {
stagedDeletions = new Set(listZ(root, ['diff', '--cached', '--name-only', '--diff-filter=D']));
} catch {
// Can't enumerate deletions → treat nothing as a deletion (fail closed:
// a real deletion then reports unscannable, which is safe — it blocks,
// never leaks).
stagedDeletions = new Set();
}
const allowlist = loadWorkspaceAllowlist(root);
// nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- fixed filename under the resolved workspace root (same path loadWorkspaceAllowlist reads); used only in printed guidance.
const allowlistPath = join(root, SCAN_ALLOW_FILENAME);
const allowlistProblems = scanAllowProblems(allowlist);
for (const p of allowlistProblems) log(`${SCAN_ALLOW_FILENAME} line ${p.entry}: ${p.problem}`);
const retryCommand = pushRetryCommand(opts);
const findings: PushSecretFinding[] = [];
const unscannable: string[] = [];
const stagedBlobs = stagedBlobSizes(root, stagedForScan);
for (const rel of stagedForScan) {
if (pathAllowlisted(rel, allowlist)) continue; // user-declared safe path
if (stagedDeletions.has(rel)) continue; // deletion — no content to scan
const fileFindings = await scanStagedBlob(root, rel, stagedBlobs.get(rel), allowlist);
if (typeof fileFindings === 'string') {
unscannable.push(fileFindings);
continue;
}
const blocking = withoutRuleAllowed(fileFindings, rel, allowlist, hit => log(`${rel}:${hit.line} ${hit.pattern} allowed by ${SCAN_ALLOW_FILENAME} line: ${hit.entry}`));
if (blocking.length === 0) continue;
for (const f of buildPushFindings({ file: rel, findings: blocking, allowlist, allowlistPath, retryCommand })) {
findings.push(f);
}
}
if (findings.length > 0) {
// Restore the index to HEAD (disk files untouched) — a blocked push
// leaves nothing staged and nothing committed, same as before.
tryGit(root, ['reset', '-q']);
const reason = blockedSecretsReason(findings);
log(`PUSH BLOCKED: ${reason}`);
return finish({
ok: false, status: 'blocked_secrets', repoRoot: root, branch, findings, reason,
...(allowlistProblems.length ? { allowlistProblems } : {}),
});
}
if (unscannable.length > 0) {
// Fail CLOSED: an unscannable staged file could hide a secret. Restore
// the index to HEAD (nothing staged, nothing committed) and block.
tryGit(root, ['reset', '-q']);
const summary = unscannable.slice(0, 10).join(', ') + (unscannable.length > 10 ? ', …' : '');
const reason =
`secret scan could not read ${unscannable.length} staged file(s): ${summary} — nothing committed. ` +
`The pre-push secret gate fails closed: remove the file from the index (git rm --cached <path>), ` +
`keep it under the scan ceiling (${PUSH_STREAM_SCAN_MAX_BYTES}B), or allowlist it in ${SCAN_ALLOW_FILENAME}.`;
log(`PUSH BLOCKED: ${reason}`);
return finish({
ok: false, status: 'blocked_unscannable', repoRoot: root, branch, unscannable, reason,
});
}
// 5. commit (COMMIT FIRST, then pull — see step 6) [CX2-7].
let committed = false;
try {
const clean = tryGit(root, ['diff', '--cached', '--quiet']) !== null;
if (!clean) {
commitRecorded(root, opts.commitMessage ?? 'gbrain: workspace push');
committed = true;
}
} catch (e) {
return finish({
ok: false, status: 'error', repoRoot: root, branch,
reason: `stage/commit failed: ${(e as Error).message.slice(0, 200)}`,
});
}
// Remote-privacy gate [G8] — after the local commit (committing is safe
// and preserves the work either way), before anything touches the remote.
if (tryGit(root, ['remote', 'get-url', 'origin'], { timeoutMs: 10_000 }) === null) {
return finish({
ok: false, status: 'error', repoRoot: root, branch, committed,
reason: 'no origin remote configured — nothing to push to',
});
}
// Escape-hatch resolution [D18], most explicit first: CLI flag > env var >
// file-plane config. Every path warns loudly. The hatches downgrade ONLY
// the `unverifiable` verdict — the ladder still runs and an affirmatively
// PUBLIC origin refuses regardless, matching every piece of user-facing
// copy ("for self-hosted git you trust", never "push to public repos").
const unverifiedVia = opts.allowUnverifiedRemote
? 'the allow-unverified-remote flag'
: process.env.GBRAIN_ALLOW_UNVERIFIED_REMOTE === '1'
? 'GBRAIN_ALLOW_UNVERIFIED_REMOTE=1'
: configAllowsUnverifiedRemote()
? 'config push.allow_unverified_remote (sticky — unset it once verification works)'
: null;
{
const privacy = await verifyRemotePrivacy(root);
if (privacy.verdict === 'not_private') {
const reason = `origin is not private: ${privacy.detail} — refusing to push workspace contents` +
(unverifiedVia !== null ? ` (the unverified-remote override via ${unverifiedVia} does NOT cover proven-public origins)` : '');
log(`PUSH REFUSED: ${reason}`);
return finish({
ok: false, status: 'refused_visibility', repoRoot: root, branch, committed, reason,
});
}
if (privacy.verdict === 'unverifiable') {
if (unverifiedVia !== null) {
log(`WARN: origin visibility unverifiable — pushing anyway via ${unverifiedVia}; you are trusting this remote`);
} else {
const reason =
`cannot verify origin visibility (${privacy.detail}) — refusing to push. ` +
`Pass --allow-unverified-remote (or set GBRAIN_ALLOW_UNVERIFIED_REMOTE=1, or ` +
'`gbrain config set push.allow_unverified_remote true`) for self-hosted git you trust.';
log(`PUSH REFUSED: ${reason}`);
return finish({
ok: false, status: 'refused_visibility', repoRoot: root, branch, committed, reason,
});
}
}
}
// 6. pull AFTER commit [CX2-7] — a dirty tree is impossible here short of
// a mid-run writer, and divergenceSafePull handles that as skipped_dirty.
try {
const pull = divergenceSafePull(root, branch, { strategy: opts.pullStrategy });
if (pull.status === 'conflict_aborted') {
return finish({
ok: false, status: 'pull_conflict', repoRoot: root, branch, committed,
ahead: aheadCount(root, branch),
reason: pull.detail,
});
}
if (pull.status === 'skipped_dirty') {
log('WARN: tree re-dirtied mid-run — pull skipped; pushing the committed HEAD anyway');
}
} catch (e) {
// fetch failure etc. — still attempt the push; it will name the problem.
log(`WARN: pull failed (${(e as Error).message.slice(0, 120)}); attempting push`);
}
// 7. push — even with no new commit (a prior failure may have left local ahead).
const failed = pushScannedHead(root, branch, log, opts.scanTimeoutMs);
if (failed) return finish({ ok: false, ...failed, repoRoot: root, branch, committed, ahead: aheadCount(root, branch) });
const ahead = aheadCount(root, branch) ?? 0;
log(`pushed ${root} → origin/${branch}${committed ? ' (new commit)' : ''}`);
return finish({
ok: true, status: 'pushed', repoRoot: root, branch, committed, ahead,
...(excludedUntracked.length > 0 ? { excludedUntracked } : {}),
});
} finally {
lock.handle.release();
}
}