Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* `gbrain bootstrap repo` — private-repo creation with a hard privacy gate
* [G8, CX2-1, plan D6]. Library module: the CLI dispatcher wires it later.
*
* Invariants (G8):
* - A pre-existing `origin` is accepted in exactly two shapes, else refused
* (pointed at `attach`): (a) the receipt already recorded this exact
* `repo_url` (idempotent re-run -> disposition 'reused'); or (b) the origin
* is owned by the authed gh user with NO recorded `repo_url` AND is SAFE to
* adopt -> disposition 'adopted'. SAFE means EMPTY (`assertAdoptableOrigin`),
* or a non-empty remote that matches this workspace's `pending_repo_url`
* proof (our own interrupted push, resumable). A non-empty remote with no
* matching pending marker is refused (`ORIGIN_NOT_EMPTY`) — we never adopt a
* user's existing project from a git-ancestry guess. Org-owned origins
* (owner != login) are out of scope.
* - Repo-local git identity (from the authed gh user) is set in BOTH the
* create and adopt paths before any commit; `repo_url` is recorded only
* AFTER a successful push (a push failure must never look "done" to status).
* - Repo privacy is verified via the GitHub API; the answer
* must be the literal `true`. "Couldn't verify" (rate limit / 5xx) is a
* typed refuse-and-re-run, NEVER treated as private or public. The first
* push happens only AFTER the verify passes (create runs without --push).
* - Idempotent re-runs key off the REMOTE URL, not the name probe — a name
* probe can be fooled by an unrelated repo taking the slug. A receipt
* missing repo_url (crash window) adopts an origin only when the authed
* gh user owns it; undefined is never a wildcard.
*
* All gh/git interaction goes through an injectable `ExecRunner` so tests use
* a recording fake; the default spawns via Bun. Commands are argv arrays
* (never shell strings); git commands carry `-C <workspace>` and
* `gh repo create` uses `--source <workspace>` so the runner needs no cwd.
*/
import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
import { join, resolve } from 'node:path';
import { configDir } from '../config.ts';
import { invalidateBackupStatus } from '../backup/status-file.ts';
import { realpathOrResolve } from '../path-confine.ts';
import { defaultRunner, isProxyBlocked403, parseGithubOwnerRepo, type ExecRunner } from '../repo-visibility.ts';
import { detectExecutionEnvironment } from '../execution-env.ts';
import { scanAllowProblems, stagedScanPublishRefusal } from '../git/range-secret-scan.ts';
import type { OperationError } from '../ops/contract.ts';
import { loadWorkspaceAllowlist, scanFiles, SCAN_ALLOW_FILENAME, type SecretFinding } from '../secret-scan.ts';
import { SECRET_SCAN_REFUSAL_DOCS } from '../workspace-push.ts';
import { shellQuote } from '../mcp-registration.ts';
import { GITHUB_URL_PLACEHOLDER } from './assets.ts';
import {
guardReceiptOverwrite,
readManifest,
readReceipt,
writeReceipt,
type AgentManifest,
type InstallReceipt,
type ManifestState,
} from './format.ts';
import { BootstrapError } from './lock.ts';
import { recordCommitAsync, recordIntentAsync } from '../git/commit-ledger.ts';
// ---------------------------------------------------------------------------
// Exec seam (shared by uninstall.ts; the dispatcher passes the real runner)
// ---------------------------------------------------------------------------
// Canonical definitions moved to repo-visibility.ts (the visibility ladder
// needs the same seam and must stay a leaf module); re-exported here so every
// existing consumer (uninstall.ts, bootstrap.ts, tests) keeps its import path.
export { defaultRunner, type ExecResult, type ExecRunner } from '../repo-visibility.ts';
// ---------------------------------------------------------------------------
// Receipt extension: the created repo URL [CX2-12 idempotency key]
// ---------------------------------------------------------------------------
/** The receipt gains the created repo URL; format.ts consumers tolerate
* unknown fields, so this is a structural extension, not a format bump. */
export interface RepoReceipt extends InstallReceipt {
repo_url?: string;
/** Proof-of-intent written BEFORE the first push and cleared once `repo_url`
* is recorded. If a push lands but the run crashes before recording `repo_url`,
* a re-run sees a non-empty origin that matches `pending_repo_url` and knows
* the content is OURS (safe to resume) rather than a user's existing project
* (which would carry no pending marker). See createPrivateRepo Gate 4. */
pending_repo_url?: string;
}
// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------
/** The one copy of the cloud repo-adoption instruction (two error sites). */
export const CLOUD_ATTACH_FLOW_HINT =
'Create the private repo from a normal machine (or github.com), open a cloud session ON that repo, ' +
'then run `gbrain bootstrap attach`.';
/** GitHub repo-name slug: lowercase, alnum runs joined by '-'. */
export function slugifyRepoName(name: string): string {
const slug = name
.toLowerCase()
.replace(/[^a-z0-9]+/g, '-')
.replace(/^-+|-+$/g, '');
return slug || 'agent';
}
/** Parse owner/name out of an https or ssh GitHub remote URL. Thin adapter
* over the canonical repo-visibility parser (one grammar, three consumers). */
export function parseGithubRemote(url: string): { owner: string; name: string } | null {
const p = parseGithubOwnerRepo(url);
return p ? { owner: p.owner, name: p.repo } : null;
}
/** Re-exported for existing consumers; the single definition lives in
* assets.ts (shared with render.ts's DERIVED_DEFAULTS). */
export { GITHUB_URL_PLACEHOLDER };
function requireInitializedManifest(workspaceDir: string): { state: ManifestState; manifest: AgentManifest } {
const state = readManifest(workspaceDir);
switch (state.state) {
case 'initialized':
return { state, manifest: state.manifest };
case 'template':
throw new BootstrapError(
'TEMPLATE_UNINITIALIZED',
'this is an uninitialized template — run `gbrain bootstrap render` first',
);
case 'absent':
throw new BootstrapError(
'NOT_A_WORKSPACE',
`not an agent workspace (no agent.json in ${workspaceDir}) — run \`gbrain bootstrap render\` first`,
);
case 'invalid':
throw new BootstrapError('MANIFEST_INVALID', `agent.json is invalid: ${state.reason}`);
case 'newer_format':
throw new BootstrapError(
'NEWER_FORMAT',
`agent.json format_version ${state.manifest.format_version} is newer than this gbrain understands — upgrade gbrain first`,
);
}
}
function isRateLimitOr5xx(stderr: string): boolean {
return /HTTP 5\d\d|HTTP 429|rate limit/i.test(stderr);
}
/** `gh auth status`'s `--active` flag (added in cli/cli v2.57.0, 2024-09-11)
* scopes the check to only the active account instead of aggregating every
* registered account. On an older `gh`, passing an unrecognized flag makes
* the WHOLE command fail — so Gate 2 must detect support before using it. */
const GH_ACTIVE_FLAG_MIN_VERSION = [2, 57, 0] as const;
/** Parses the `X.Y.Z` out of `gh --version`'s first line (`gh version X.Y.Z (DATE)`).
* Returns null on any unrecognized format — callers treat that as "unknown,
* don't assume support". */
function parseGhVersion(versionOutput: string): readonly [number, number, number] | null {
const m = /\bgh version (\d+)\.(\d+)\.(\d+)/.exec(versionOutput);
if (!m) return null;
return [Number(m[1]), Number(m[2]), Number(m[3])];
}
function ghVersionAtLeast(v: readonly [number, number, number], min: readonly [number, number, number]): boolean {
for (let i = 0; i < 3; i++) {
if (v[i] !== min[i]) return v[i]! > min[i]!;
}
return true;
}
/** The authenticated gh login, or null when it cannot be read/parsed. */
async function fetchAuthedLogin(runner: ExecRunner): Promise<string | null> {
const res = await runner(['gh', 'api', 'user']);
if (res.code !== 0) return null;
try {
const parsed = JSON.parse(res.stdout) as { login?: unknown };
return typeof parsed.login === 'string' && parsed.login.length > 0 ? parsed.login : null;
} catch {
return null;
}
}
/** The authed gh user's login + id. Throws GH_AUTH (exit 2) on failure. */
async function resolveGhIdentity(runner: ExecRunner): Promise<{ login: string; userId: number | string }> {
const userRes = await runner(['gh', 'api', 'user']);
if (userRes.code !== 0) {
throw new BootstrapError(
'GH_AUTH',
`could not read the authenticated GitHub user (gh api user failed: ${userRes.stderr.trim() || `exit ${userRes.code}`}) — check \`gh auth status\``,
{ exitCode: 2 },
);
}
try {
const parsed = JSON.parse(userRes.stdout) as { login?: unknown; id?: unknown };
if (typeof parsed.login !== 'string' || parsed.login.length === 0) throw new Error('missing login');
const userId = typeof parsed.id === 'number' || typeof parsed.id === 'string' ? parsed.id : 0;
return { login: parsed.login, userId };
} catch (e) {
throw new BootstrapError('GH_AUTH', `unexpected \`gh api user\` output (${(e as Error).message})`, { exitCode: 2 });
}
}
/**
* Set the repo-local git author identity from the authed gh user (never touches
* global git config). Required before ANY commit — a freshly cloned repo on a
* machine with no global `user.name`/`user.email` would otherwise fail at commit.
* Runs in both the create AND adoption paths (the adoption path is why this is a
* shared helper — a clone-then-adopt on a fresh machine hit exactly this).
*/
async function setRepoLocalIdentity(
runner: ExecRunner,
workspaceDir: string,
ident: { login: string; userId: number | string },
): Promise<void> {
// Fail loudly if the config writes fail — otherwise a later commit falls back
// to (possibly absent) global identity and dies with a misleading error.
const nameRes = await runner(['git', '-C', workspaceDir, 'config', 'user.name', ident.login]);
const emailRes = await runner([
'git', '-C', workspaceDir, 'config', 'user.email',
`${ident.userId}+${ident.login}@users.noreply.github.com`,
]);
const failed = nameRes.code !== 0 ? nameRes : emailRes.code !== 0 ? emailRes : null;
if (failed) {
throw new BootstrapError(
'REPO_CREATE_FAILED',
`could not set the repo-local git identity (git config failed: ${failed.stderr.trim() || `exit ${failed.code}`}) — commits would fail; fix the git state and re-run \`gbrain bootstrap repo\``,
);
}
}
/**
* Guard for the create-repo-first / pre-record adoption path (an origin the human
* created, with no recorded `repo_url` yet). The origin must be EMPTY to adopt.
*
* Empty-only is deliberate. A non-empty remote cannot be proven to be OURS from
* git alone — "remote HEAD equals/precedes local HEAD" is ALSO true of a user's
* own existing project that `render` happened to run inside, so an ancestor/SHA
* heuristic would silently adopt (and later push identity/personal data into)
* that project. We refuse instead. The happy path stays empty because the
* no-daemon push is gated until the repo phase records `repo_url` (see
* `repoPhaseComplete` in hook.ts), so nothing lands on the remote before this
* runs. Genuinely-ours interrupted pushes are matched separately by
* `pending_repo_url` at the call site — this function is the fallback for
* everything else. Throws on refusal; never adopts on uncertainty.
*/
async function assertAdoptableOrigin(
runner: ExecRunner,
workspaceDir: string,
owner: string,
name: string,
): Promise<void> {
const ls = await runner(['git', '-C', workspaceDir, 'ls-remote', 'origin']);
if (ls.code !== 0) {
throw new BootstrapError(
'REMOTE_CHECK_FAILED',
`could not list ${owner}/${name} to confirm it is safe to adopt (git ls-remote failed: ${ls.stderr.trim() || `exit ${ls.code}`}) — nothing was pushed; re-run \`gbrain bootstrap repo\``,
{ details: { owner, name } },
);
}
// All refs (not just --heads): a repo with only tags is not "empty".
if (ls.stdout.trim().length === 0) return; // genuinely empty → safe to adopt
throw new BootstrapError(
'ORIGIN_NOT_EMPTY',
`${owner}/${name} already has content that bootstrap did not put there. ` +
'`gbrain bootstrap repo` adopts only an EMPTY repo you just created. ' +
'Create a new EMPTY private repo (no README/.gitignore/license) under your own account and point this workspace at it, ' +
'or run `gbrain bootstrap attach` if this is an existing agent workspace.',
{ details: { owner, name } },
);
}
/**
* Privacy verify [G8]: `gh api repos/{owner}/{name} --jq .private` must print
* the literal `true`. Any failure to VERIFY is VERIFY_UNAVAILABLE (refuse +
* re-run) — never interpreted as an answer. An affirmative non-`true` answer
* is the hard REPO_NOT_PRIVATE stop. Defense in depth: the repo owner must be
* the authenticated gh user — a private repo someone ELSE owns is still not
* ours to bless.
*/
async function verifyRepoPrivate(runner: ExecRunner, owner: string, name: string): Promise<void> {
const login = await fetchAuthedLogin(runner);
if (login === null) {
throw new BootstrapError(
'VERIFY_UNAVAILABLE',
`could not read the authenticated GitHub user to verify ownership of ${owner}/${name} — check \`gh auth status\` and re-run \`gbrain bootstrap repo\`.`,
{ details: { owner, name } },
);
}
if (login !== owner) {
throw new BootstrapError(
'ORIGIN_EXISTS',
`${owner}/${name} is owned by ${owner}, not the authenticated GitHub user (${login}) — ` +
'bootstrap only blesses repos it created under your own account. ' +
'If this is a clone of an existing agent workspace, run `gbrain bootstrap attach` instead.',
{ details: { owner, name, login } },
);
}
const res = await runner(['gh', 'api', `repos/${owner}/${name}`, '--jq', '.private']);
if (res.code !== 0) {
// Classify the failure so the operator gets the REAL fix: a sandbox
// egress proxy blocking REST for a repo not attached to the session is a
// different problem from a token/rate-limit failure [D14 messaging].
const proxyBlocked = isProxyBlocked403(res.stderr);
const reason = proxyBlocked
? "this sandbox's egress proxy blocks GitHub REST for repos not attached to the session"
: isRateLimitOr5xx(res.stderr)
? 'GitHub API rate limit / server error'
: `gh api failed: ${res.stderr.trim() || `exit ${res.code}`}`;
const nextStep = proxyBlocked ? CLOUD_ATTACH_FLOW_HINT : 'The repo may be fine — re-run `gbrain bootstrap repo` to verify.';
throw new BootstrapError(
'VERIFY_UNAVAILABLE',
`could not verify that ${owner}/${name} is private (${reason}). ` +
`${nextStep} Nothing is pushed to a repo whose privacy is unverified.`,
{ details: { owner, name, stderr: res.stderr } },
);
}
if (res.stdout.trim() !== 'true') {
throw new BootstrapError(
'REPO_NOT_PRIVATE',
`${owner}/${name} is NOT private (API said: ${res.stdout.trim() || 'empty'}). ` +
'Make it private in the GitHub settings (or delete it) before re-running `gbrain bootstrap repo`.',
{ details: { owner, name, answer: res.stdout.trim() } },
);
}
}
/** Replace the GITHUB.md placeholder line with the real URL (simple string
* replace; also fills a still-raw {{GITHUB_REPO_URL}} token defensively so a
* later verify token-sweep can't trip on it). */
function updateGithubMd(workspaceDir: string, url: string): void {
const path = join(workspaceDir, 'GITHUB.md');
if (!existsSync(path)) return;
const raw = readFileSync(path, 'utf8');
const next = raw.split(GITHUB_URL_PLACEHOLDER).join(url).split('{{GITHUB_REPO_URL}}').join(url);
if (next !== raw) writeFileSync(path, next, 'utf8');
}
/** Load-or-synthesize the machine-local receipt (minimal one when render's is
* missing — crash between render and receipt write), with the bootstrap/ subdir
* ensured and the overwrite guard run. Shared by the record helpers. */
function loadReceiptForWrite(gbrainHomeDir: string, workspaceDir: string, manifest: AgentManifest): RepoReceipt {
const existing = readReceipt(gbrainHomeDir) as RepoReceipt | null;
const receipt: RepoReceipt = existing ?? {
receipt_version: 1,
workspace_dir: realpathOrResolve(workspaceDir),
source_id: manifest.source_id,
agent_name: manifest.agent_name,
created_at: new Date().toISOString(),
created_by: manifest.created_by,
brain_created_by_bootstrap: false,
created_paths: [],
registrations: [],
};
// writeReceipt assumes the bootstrap/ subdir exists (render creates it);
// repo may run first after a crash, so create it defensively.
mkdirSync(join(gbrainHomeDir, 'bootstrap'), { recursive: true });
const guard = guardReceiptOverwrite(gbrainHomeDir); // throws on newer-format receipts
if (guard.brokenBackupPath) {
console.error(`WARNING: the install receipt was unreadable; backed it up to ${guard.brokenBackupPath} and wrote a fresh one.`);
}
return receipt;
}
/** Proof-of-intent: record `pending_repo_url` BEFORE the first push, so a
* post-push/pre-record crash is recognized as OURS on re-run (see Gate 4). */
function recordPendingRepo(gbrainHomeDir: string, workspaceDir: string, manifest: AgentManifest, url: string): void {
const receipt = loadReceiptForWrite(gbrainHomeDir, workspaceDir, manifest);
receipt.pending_repo_url = url;
writeReceipt(gbrainHomeDir, receipt);
}
/** Record the created/adopted repo URL AFTER a successful push, clearing the
* pending marker (the durable idempotency key). */
function recordRepoInReceipt(gbrainHomeDir: string, workspaceDir: string, manifest: AgentManifest, url: string): void {
const receipt = loadReceiptForWrite(gbrainHomeDir, workspaceDir, manifest);
receipt.repo_url = url;
delete receipt.pending_repo_url;
writeReceipt(gbrainHomeDir, receipt);
// Fix-path invalidation: the workspace just gained a verified remote — the
// backup-coverage cache must stop warning NOW, not at the next 30-day
// recompute (backup/status-file.ts). Best-effort by construction.
invalidateBackupStatus();
}
// ---------------------------------------------------------------------------
// First-push content + push-target binding [FIX3, FIX4]
// ---------------------------------------------------------------------------
/** Files git would include in a commit right now (staged + untracked, minus
* ignored), relative to the workspace — the input to the pre-commit scan.
* Fail-closed: a `git ls-files` failure is a hard refuse, NEVER a vacuous empty
* set (an empty set would let the secret scan pass without seeing anything). */
async function stagedAndUntrackedFiles(runner: ExecRunner, workspaceDir: string): Promise<string[]> {
const res = await runner([
'git', '-C', workspaceDir, 'ls-files', '--cached', '--others', '--exclude-standard', '-z',
]);
if (res.code !== 0) {
throw new BootstrapError(
'REPO_CREATE_FAILED',
`could not enumerate files for the pre-push secret scan (git ls-files failed: ${res.stderr.trim() || `exit ${res.code}`}) — nothing was committed or pushed; fix the git state and re-run \`gbrain bootstrap repo\``,
);
}
return res.stdout.split('\0').filter((s) => s.length > 0);
}
/** Tracked files in the current HEAD tree — the set that would be pushed when a
* clean commit already exists. Fail-closed like stagedAndUntrackedFiles. */
async function trackedFiles(runner: ExecRunner, workspaceDir: string): Promise<string[]> {
const res = await runner(['git', '-C', workspaceDir, 'ls-files', '-z']);
if (res.code !== 0) {
throw new BootstrapError(
'REPO_CREATE_FAILED',
`could not enumerate tracked files for the pre-push secret scan (git ls-files failed: ${res.stderr.trim() || `exit ${res.code}`}) — nothing was pushed; fix the git state and re-run \`gbrain bootstrap repo\``,
);
}
return res.stdout.split('\0').filter((s) => s.length > 0);
}
/** Secret scan the given workspace-relative files; throw on any finding. This
* is the SAME scanner bootstrap verify uses (src/core/secret-scan.ts) — the
* first push is NEVER made without it. */
function secretScanOrThrow(workspaceDir: string, relFiles: string[]): void {
const allowlist = loadWorkspaceAllowlist(workspaceDir);
const findings = scanFiles(relFiles.map((f) => join(workspaceDir, f)), {
allowlist,
workspaceRoot: workspaceDir,
});
if (findings.length > 0) {
const sample = findings.slice(0, 5).map((f) => {
const { since } = f as SecretFinding & { since?: string };
return `${f.file}:${f.line} [${f.pattern}${since ? ` since gbrain v${since.replace(/^v/, '')}` : ''}] ${f.fingerprint}`;
}).join('; ');
throw new BootstrapError(
'SECRET_SCAN_BLOCKED',
`secret scan found ${findings.length} finding(s) before the first push: ${sample}` +
`${findings.length > 5 ? '; …' : ''} — nothing was committed or pushed. ` +
'Remove a real credential first; allowlist only a reviewed false positive by appending its fingerprint to ' +
`${shellQuote(resolve(workspaceDir, SCAN_ALLOW_FILENAME))} (${SECRET_SCAN_REFUSAL_DOCS}), then re-run \`gbrain bootstrap repo\`.` +
scanAllowProblems(allowlist).map((p) => ` ${SCAN_ALLOW_FILENAME} line ${p.entry}: ${p.problem}.`).join(''),
{ details: { findings: findings.length } },
);
}
}
/**
* Guarantee at least one commit exists so the first push has content — the
* freshly-rendered workspace is uncommitted, so a bare `git push` would fail
* ("src refspec ... does not match") and (on retry) the adoption path would
* false-succeed against an empty remote. Stages everything, runs the secret
* scan (NEVER bypassed), commits. No-op when a commit already exists and the
* tree is clean.
*/
export async function ensureWorkspaceCommit(runner: ExecRunner, workspaceDir: string): Promise<void> {
const head = await runner(['git', '-C', workspaceDir, 'rev-parse', '--verify', 'HEAD']);
const hasCommit = head.code === 0;
const statusRes = await runner(['git', '-C', workspaceDir, 'status', '--porcelain']);
const dirty = statusRes.code === 0 && statusRes.stdout.trim().length > 0;
if (hasCommit && !dirty) {
// A clean commit already exists (e.g. a re-run, or an adopted repo whose
// tree was committed earlier). Do NOT return before scanning: the committed
// tree is exactly what a `git push` will publish, so secret-scan it too —
// the early return used to skip the scan entirely (a pre-existing commit
// could push secrets unscanned).
const tracked = await trackedFiles(runner, workspaceDir);
secretScanOrThrow(workspaceDir, tracked);
return; // there is already something to push
}
const add = await runner(['git', '-C', workspaceDir, 'add', '-A']);
if (add.code !== 0) {
throw new BootstrapError(
'REPO_CREATE_FAILED',
`git add failed before the first commit: ${add.stderr.trim() || `exit ${add.code}`}`,
);
}
// Secret scan the staged+untracked set — do NOT bypass it [G8/D6].
const files = await stagedAndUntrackedFiles(runner, workspaceDir);
secretScanOrThrow(workspaceDir, files);
const staged = await runner(['git', '-C', workspaceDir, 'diff', '--cached', '--name-only']);
const nothingStaged = staged.code === 0 && staged.stdout.trim().length === 0;
if (nothingStaged) {
if (hasCommit) return; // clean commit already exists; nothing new to add
throw new BootstrapError(
'REPO_CREATE_FAILED',
'the workspace has no files to commit — render identity files first (`gbrain bootstrap render`), then re-run `gbrain bootstrap repo`',
);
}
await recordIntentAsync(workspaceDir, { writer: 'bootstrap', head_before: hasCommit ? head.stdout.trim() || null : null, message: 'gbrain: bootstrap workspace' });
const commit = await runner(['git', '-C', workspaceDir, 'commit', '-m', 'gbrain: bootstrap workspace']);
if (commit.code !== 0 && !hasCommit) {
throw new BootstrapError(
'REPO_CREATE_FAILED',
`git commit failed before the first push: ${commit.stderr.trim() || `exit ${commit.code}`}`,
);
}
if (commit.code === 0) {
const sha = await runner(['git', '-C', workspaceDir, 'rev-parse', 'HEAD']);
if (sha.code === 0) await recordCommitAsync(workspaceDir, { sha: sha.stdout.trim(), writer: 'bootstrap' });
}
}
/** The current branch, defaulting to 'main' (a pre-first-commit HEAD reports
* 'HEAD' / errors). */
async function currentBranch(runner: ExecRunner, workspaceDir: string): Promise<string> {
const res = await runner(['git', '-C', workspaceDir, 'rev-parse', '--abbrev-ref', 'HEAD']);
const b = res.code === 0 ? res.stdout.trim() : '';
return b && b !== 'HEAD' ? b : 'main';
}
/**
* [FIX4/G8] Bind the just-verified privacy result to the ACTUAL push target.
* A concurrent `git remote set-url origin …` between verify and push could
* redirect content elsewhere; re-read origin and refuse unless it still parses
* to the owner/name we verified private. Checks BOTH the fetch URL and the push
* URL (`remote.origin.pushurl`) — `git push` uses the push URL when set, so a
* verified-private fetch URL paired with a foreign/public push URL would
* otherwise leak the workspace.
*/
async function assertOriginMatches(
runner: ExecRunner,
workspaceDir: string,
owner: string,
name: string,
): Promise<void> {
// Fetch URL: must resolve to the verified-private owner/name (the primary bind).
const fetchRes = await runner(['git', '-C', workspaceDir, 'remote', 'get-url', 'origin']);
const fetchUrl = fetchRes.code === 0 ? fetchRes.stdout.trim() : '';
const fetchParsed = fetchUrl ? parseGithubRemote(fetchUrl) : null;
if (!fetchParsed || fetchParsed.owner !== owner || fetchParsed.name !== name) {
throw new BootstrapError(
'ORIGIN_EXISTS',
`origin now resolves to ${fetchUrl || '(unset)'}, not the verified-private ${owner}/${name} — refusing to push. ` +
'The remote changed after the privacy verification; restore it (git remote set-url origin <the created repo>) ' +
'and re-run `gbrain bootstrap repo`.',
{ details: { which: 'fetch', expected: `${owner}/${name}`, actual: fetchUrl } },
);
}
// Push URL: `git push` uses `remote.origin.pushurl` when set, so a verified
// fetch URL + a foreign push URL would leak. Read the config key directly (no
// dash-flag): unset → exit != 0 → `git push` falls back to the fetch URL
// (already validated). Only a DISTINCT, configured push URL is a refusal.
const pushRes = await runner(['git', '-C', workspaceDir, 'config', 'remote.origin.pushurl']);
const pushUrl = pushRes.code === 0 ? pushRes.stdout.trim() : '';
if (pushUrl) {
const pushParsed = parseGithubRemote(pushUrl);
if (!pushParsed || pushParsed.owner !== owner || pushParsed.name !== name) {
throw new BootstrapError(
'ORIGIN_EXISTS',
`origin push URL resolves to ${pushUrl}, not the verified-private ${owner}/${name} — refusing to push. ` +
'A separate push URL (remote.origin.pushurl) points elsewhere; clear that config key ' +
'and re-run `gbrain bootstrap repo`.',
{ details: { which: 'push', expected: `${owner}/${name}`, actual: pushUrl } },
);
}
}
}
/**
* [FIX3] The adoption/idempotent path must not report reused-success against an
* empty remote (a prior run that created the repo + set origin but whose push
* failed). Lightweight `ls-remote` check: if the branch is already on the
* remote, the workspace is genuinely pushed; otherwise complete the push
* (scan-gated, bound to the verified origin [FIX4]).
*/
async function ensureRemoteHasWorkspace(
runner: ExecRunner,
workspaceDir: string,
owner: string,
name: string,
scan: HistoryScan,
): Promise<void> {
const branch = await currentBranch(runner, workspaceDir);
const ls = await runner(['git', '-C', workspaceDir, 'ls-remote', '--heads', 'origin', branch]);
const remoteHasBranch = ls.code === 0 && ls.stdout.trim().length > 0;
if (remoteHasBranch) return; // genuinely pushed — reused success is honest
await ensureWorkspaceCommit(runner, workspaceDir);
const pushBranch = await currentBranch(runner, workspaceDir);
await assertOriginMatches(runner, workspaceDir, owner, name);
await assertHistoryPublishable(runner, workspaceDir, pushBranch, scan);
const push = await runner(['git', '-C', workspaceDir, 'push', '-u', 'origin', pushBranch, '--no-follow-tags', '--recurse-submodules=no']);
if (push.code !== 0) {
throw new BootstrapError(
'REPO_CREATE_FAILED',
`completing the deferred first push to ${owner}/${name} failed: ${push.stderr.trim() || `exit ${push.code}`} — ` +
'the repo exists and is private; commit your work and re-run `gbrain bootstrap repo`',
{ details: { branch: pushBranch, stderr: push.stderr } },
);
}
}
// ---------------------------------------------------------------------------
// createPrivateRepo
// ---------------------------------------------------------------------------
export interface CreatePrivateRepoOptions {
runner?: ExecRunner;
/** The gbrain home holding the install receipt (default: configDir()). */
gbrainHomeDir?: string;
/** The refusal for publishing `target` and its whole history (default: the range secret scan; a seam for runner fakes). */
scanHistory?: HistoryScan;
/** The whole-history scan's time budget (`--scan-timeout`; default 300 s). */
scanTimeoutMs?: number;
}
type HistoryScan = (workspaceDir: string, target: string) => OperationError | null;
const scanWholeHistory = (timeoutMs?: number): HistoryScan => (workspaceDir, target) => stagedScanPublishRefusal(workspaceDir, '', target,
{ timeoutMs, progress: line => process.stderr.write(`[gbrain] ${line}\n`), retryArgv: ['gbrain', 'bootstrap', 'repo'] });
/**
* #8902: a first push publishes the branch's whole history, including commits a script made with plain `git commit`
* that the staged scan never saw, so the commit about to be pushed is scanned with all of its history; a finding or
* an unreadable history refuses (publish_secret_found / publish_scan_unreadable) and nothing leaves the machine.
*/
async function assertHistoryPublishable(runner: ExecRunner, workspaceDir: string, branch: string, scan: HistoryScan): Promise<void> {
const tip = async () => {
const ref = await runner(['git', '-C', workspaceDir, 'rev-parse', '--verify', `refs/heads/${branch}^{commit}`]);
if (ref.code !== 0) {
throw new BootstrapError('REPO_CREATE_FAILED', `could not read branch ${branch} before the first push: ${ref.stderr.trim() || `exit ${ref.code}`} — nothing was pushed`);
}
return ref.stdout.trim();
};
const scanned = await tip();
const refusal = scan(workspaceDir, scanned);
if (refusal) throw refusal;
if (await tip() !== scanned) {
throw new BootstrapError('REPO_CREATE_FAILED', `branch ${branch} moved while its history was scanned — nothing was pushed; re-run \`gbrain bootstrap repo\``);
}
}
export interface CreatePrivateRepoResult {
url: string;
name: string;
/**
* How the repo came to be:
* - `created` — bootstrap ran `gh repo create` this run (brand-new repo).
* - `adopted` — a pre-existing origin the human created (create-repo-first),
* or one bootstrap created but crashed before recording, was verified and
* pushed to for the first time this run.
* - `reused` — a repo a prior run already recorded (`repo_url` match); this
* run only re-verified privacy and completed any deferred push.
* A single enum instead of overlapping booleans so invalid combinations
* ('created'+'adopted') are unrepresentable.
*/
disposition: 'created' | 'adopted' | 'reused';
/** Back-compat: true whenever an existing origin was used (adopted OR reused)
* rather than freshly created. Derived from `disposition`. */
reused: boolean;
}
/**
* Create (or idempotently re-verify) the dedicated private GitHub repo for an
* initialized agent workspace. See module header for the G8 invariants.
*/
export async function createPrivateRepo(
workspaceDir: string,
opts: CreatePrivateRepoOptions = {},
): Promise<CreatePrivateRepoResult> {
const runner = opts.runner ?? defaultRunner;
const gbrainHomeDir = opts.gbrainHomeDir ?? configDir();
const scan = opts.scanHistory ?? scanWholeHistory(opts.scanTimeoutMs);
// Gate 1: gh on PATH. Exit-code-2 semantics — the human installs gh.
const ghVersion = await runner(['gh', '--version']);
if (ghVersion.code !== 0) {
throw new BootstrapError(
'GH_MISSING',
'`gh` (GitHub CLI) is not available on PATH — install it (https://cli.github.com), then re-run `gbrain bootstrap repo`',
{ exitCode: 2 },
);
}
// Gate 2: authenticated. Exit-code-2 — the human runs `gh auth login`.
// `--hostname github.com` scopes the check to the host this flow actually
// targets (every downstream call — parseGithubOwnerRepo, the repo-create
// URL fallback, etc. — is github.com-only), so an unrelated broken account
// on some other configured host (e.g. a GitHub Enterprise instance) can't
// false-block it either. `--active` (only when the installed `gh` supports
// it) further restricts that host's check to the active account. Bare
// `gh auth status` aggregates EVERY registered account on EVERY host and
// exits 1 if any one of them is invalid — even an unused, long-expired
// account — which false-blocks this gate while the active account (what
// `gh`/`git` actually use) is perfectly healthy.
const ghVersionTuple = parseGhVersion(ghVersion.stdout);
const ghSupportsActiveFlag = ghVersionTuple !== null && ghVersionAtLeast(ghVersionTuple, GH_ACTIVE_FLAG_MIN_VERSION);
const ghAuthArgv = ghSupportsActiveFlag
? ['gh', 'auth', 'status', '--active', '--hostname', 'github.com']
: ['gh', 'auth', 'status', '--hostname', 'github.com'];
const ghAuth = await runner(ghAuthArgv);
if (ghAuth.code !== 0) {
throw new BootstrapError(
'GH_AUTH',
'GitHub CLI is not authenticated — run `gh auth login`, then re-run `gbrain bootstrap repo`',
{ exitCode: 2, details: { stderr: ghAuth.stderr } },
);
}
// Gate 3: manifest must say initialized (render ran) [CX2-1].
const { manifest } = requireInitializedManifest(workspaceDir);
// Gate 4: pre-existing origin [G8]. Two origins are acceptable:
// (a) one a prior run recorded (receipt `repo_url` matches) — idempotent
// re-run, disposition 'reused';
// (b) an origin owned by the authed gh user with NO recorded `repo_url` —
// either the human created it (create-repo-first) or we created it but
// crashed before recording. Adopting it requires it be SAFE (empty, or
// already carrying our history — see assertAdoptableOrigin), disposition
// 'adopted'. Anything else is refused and pointed at attach.
const originRes = await runner(['git', '-C', workspaceDir, 'remote', 'get-url', 'origin']);
if (originRes.code === 0 && originRes.stdout.trim()) {
const originUrl = originRes.stdout.trim();
const receipt = readReceipt(gbrainHomeDir) as RepoReceipt | null;
const sameWorkspace =
receipt !== null && realpathOrResolve(receipt.workspace_dir) === realpathOrResolve(workspaceDir);
const viaUrlMatch = sameWorkspace && receipt.repo_url === originUrl;
// A receipt without a recorded repo_url (crash between create and record, OR
// a create-repo-first clone rendered in place) may adopt ONLY when the
// authenticated gh user owns the origin — undefined is never a wildcard,
// and org-owned repos (owner != login) are out of scope by design.
let viaOwnedUndefined = false;
if (!viaUrlMatch && sameWorkspace && receipt.repo_url === undefined) {
const parsedOrigin = parseGithubRemote(originUrl);
if (parsedOrigin) {
const login = await fetchAuthedLogin(runner);
viaOwnedUndefined = login !== null && login === parsedOrigin.owner;
}
}
if (!viaUrlMatch && !viaOwnedUndefined) {
throw new BootstrapError(
'ORIGIN_EXISTS',
`this workspace already has an \`origin\` remote (${originUrl}) that bootstrap can neither adopt nor claim. ` +
'`gbrain bootstrap repo` creates a dedicated private repo, OR adopts an EMPTY private repo you created under your own account. ' +
'If this is a clone of an existing agent workspace, run `gbrain bootstrap attach` instead.',
{ details: { origin: originUrl } },
);
}
const parsed = parseGithubRemote(originUrl);
if (!parsed) {
throw new BootstrapError(
'ORIGIN_EXISTS',
`the recorded bootstrap origin (${originUrl}) is not a GitHub remote — cannot verify privacy; fix the remote or remove it and re-run`,
{ details: { origin: originUrl } },
);
}
// Adopting a not-yet-recorded origin: it must be safe. Empty is always safe.
// A NON-empty origin is safe only when it carries OUR interrupted push —
// proven by `pending_repo_url` matching (a user's existing project has no
// such marker). Everything else is refused (turns the old silent no-op into
// a clear ORIGIN_NOT_EMPTY).
if (viaOwnedUndefined) {
const ours = sameWorkspace && receipt.pending_repo_url === originUrl;
if (!ours) await assertAdoptableOrigin(runner, workspaceDir, parsed.owner, parsed.name);
}
// PRIVACY VERIFY [G8] — hard gate before any push.
await verifyRepoPrivate(runner, parsed.owner, parsed.name);
// Repo-local git identity so the (possibly first-ever) commit on a fresh
// machine succeeds — this path used to skip it, breaking clone-then-adopt.
await setRepoLocalIdentity(runner, workspaceDir, await resolveGhIdentity(runner));
updateGithubMd(workspaceDir, originUrl);
// Proof-of-intent BEFORE the push so a post-push/pre-record crash is
// recognized as ours on re-run (see the `pending_repo_url` bypass above).
recordPendingRepo(gbrainHomeDir, workspaceDir, manifest, originUrl);
// [FIX3] Don't report success on an empty remote — a prior run may have set
// origin but failed to push. Verify the remote has our branch; complete the
// (scan-gated) push if it doesn't.
await ensureRemoteHasWorkspace(runner, workspaceDir, parsed.owner, parsed.name, scan);
// Record repo_url AFTER a successful push (clears pending): recording before
// push let a push failure look "done" to `bootstrap status` (repo_url
// present), so a re-run skipped the repo phase and never pushed the workspace.
recordRepoInReceipt(gbrainHomeDir, workspaceDir, manifest, originUrl);
return { url: originUrl, name: parsed.name, disposition: viaUrlMatch ? 'reused' : 'adopted', reused: true };
}
// Cloud-sandbox guard: `gh repo create` inside a proxied cloud session
// makes a repo the session is NOT attached to — REST verification 403s and
// the proxy denies every push to it, so creation there is a dead end by
// construction. Fail fast with the flow that works instead. (Adoption of an
// EXISTING attached origin above is untouched — that is the sanctioned path.)
if (detectExecutionEnvironment() === 'cloud-sandbox') {
throw new BootstrapError(
'CLOUD_SANDBOX_REPO',
'this is a cloud sandbox session — a repo created from inside it would not be attached to the ' +
"session's GitHub scope (verification and pushes are blocked by the proxy). " +
CLOUD_ATTACH_FLOW_HINT,
{ exitCode: 2 },
);
}
// Ensure a git repo exists (main branch on fresh init).
const gitDir = await runner(['git', '-C', workspaceDir, 'rev-parse', '--git-dir']);
if (gitDir.code !== 0) {
const init = await runner(['git', '-C', workspaceDir, 'init', '-b', 'main']);
if (init.code !== 0) {
throw new BootstrapError('REPO_CREATE_FAILED', `git init failed: ${init.stderr.trim() || `exit ${init.code}`}`);
}
}
// Repo-local identity from the authed gh user (never global git config).
const ident = await resolveGhIdentity(runner);
const login = ident.login;
await setRepoLocalIdentity(runner, workspaceDir, ident);
// Name: slug(agent_name)-workspace, probed for availability, suffix -2..-100.
// The probe is best-effort convenience; `gh repo create` remains the
// authority (a probe fooled by rate limiting surfaces as a loud create
// failure, never a silent wrong-repo adoption — idempotency keys off the
// remote URL, not this probe) [G8].
const base = `${slugifyRepoName(manifest.agent_name)}-workspace`;
let name: string | null = null;
for (let i = 1; i <= 100; i++) {
const candidate = i === 1 ? base : `${base}-${i}`;
const probe = await runner(['gh', 'repo', 'view', `${login}/${candidate}`]);
if (probe.code !== 0) {
name = candidate;
break;
}
}
if (name === null) {
throw new BootstrapError(
'REPO_CREATE_FAILED',
`could not find a free repo name after 100 candidates (base: ${base}) — delete stale ${base}-* repos or rename the agent`,
);
}
// Create: private, sourced from the workspace. Deliberately WITHOUT --push:
// nothing leaves this machine until the privacy bit is verified [G8].
const create = await runner(['gh', 'repo', 'create', name, '--private', '--source', workspaceDir]);
if (create.code !== 0) {
throw new BootstrapError(
'REPO_CREATE_FAILED',
`gh repo create failed: ${create.stderr.trim() || `exit ${create.code}`}`,
{ details: { name, stderr: create.stderr } },
);
}
// The remote URL is the durable identity (idempotency key). Prefer what git
// actually recorded; fall back to the constructed URL.
const postOrigin = await runner(['git', '-C', workspaceDir, 'remote', 'get-url', 'origin']);
const url = postOrigin.code === 0 && postOrigin.stdout.trim() ? postOrigin.stdout.trim() : `https://github.com/${login}/${name}`;
// PRIVACY VERIFY [G8] — the hard gate, BEFORE the first push. Must be the
// literal `true`; only then does any workspace content leave this machine.
await verifyRepoPrivate(runner, login, name);
// [FIX3] Ensure the first push has content: a freshly-rendered workspace is
// uncommitted, so stage + secret-scan + commit before pushing (create →
// verify → commit → push; the scan is never bypassed).
await ensureWorkspaceCommit(runner, workspaceDir);
// Proof-of-intent before the push: if we crash after pushing but before
// recording repo_url, a re-run recognizes the (now non-empty) repo as ours.
recordPendingRepo(gbrainHomeDir, workspaceDir, manifest, url);
const branch = await currentBranch(runner, workspaceDir);
// [FIX4] Bind the verified privacy result to the actual push target.
await assertOriginMatches(runner, workspaceDir, login, name);
await assertHistoryPublishable(runner, workspaceDir, branch, scan);
const push = await runner(['git', '-C', workspaceDir, 'push', '-u', 'origin', branch, '--no-follow-tags', '--recurse-submodules=no']);
if (push.code !== 0) {
throw new BootstrapError(
'REPO_CREATE_FAILED',
`git push to the verified-private repo failed: ${push.stderr.trim() || `exit ${push.code}`} — the repo exists and is private; commit your work and re-run \`gbrain bootstrap repo\``,
{ details: { name, branch, stderr: push.stderr } },
);
}
updateGithubMd(workspaceDir, url);
recordRepoInReceipt(gbrainHomeDir, workspaceDir, manifest, url);
return { url, name, disposition: 'created', reused: false };
}