Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
57.2 KB
Raw Blame
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();
  }
}