Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* dx-explore — drive the REAL fresh-user experience under a PTY and record it.
*
* The e2e door tests (test/e2e/bootstrap-real-{claude,codex}.serial.test.ts)
* prove the install WORKS headlessly. This script captures what installing
* FEELS like: every picker, prompt, spinner, silence window, and line of copy
* a fresh user sees, as timestamped transcripts ready for a
* Don't-Make-Me-Think DX audit. It is a developer instrument, not a test —
* transcripts land in .context/dx-runs/ (gitignored) and nothing asserts.
*
* Scenarios (all hermetic — temp HOME/GBRAIN_HOME/CLAUDE_CONFIG_DIR/CODEX_HOME;
* the operator's real config is never WRITTEN. Two narrow reads exist for
* auth: codex-install copies ~/.codex/auth.json into the temp CODEX_HOME, and
* the claude seed records the API key's last 20 chars — both copies are
* scrubbed at cleanup even under --keep, so no credential material outlives
* the run):
*
* help First-touch comprehension surfaces: bare `gbrain`,
* `gbrain --help`, `gbrain init --help`, `gbrain bootstrap
* --help`, `gbrain bootstrap` bare. Cheap, no keys.
* init Interactive `gbrain init` (keyless) with a naive-user
* autopilot: wait for each screen to settle, snapshot it,
* press Enter (accept the default), repeat. What a user who
* "just hits Enter" experiences, with stall timing.
* claude-install REAL interactive `claude` in a fresh empty workspace,
* driven by the README paste block pointed at THIS repo's
* BOOTSTRAP_FOR_AGENTS.md, with a scripted persona appendix
* so the interview completes unattended. Pays real API cost;
* takes 10-25 min. Run in background and watch session/screen.txt.
* codex-install Same for REAL `codex` (interactive TUI).
* opencode-install Same for REAL `opencode` (bootstrap-supported; the keyless
* run rides the anonymous free tier and should COMPLETE).
* drive -- <cmd> Manual mode: spawn ANY command under the PTY and steer it
* across separate shell calls via a file control channel:
* watch: cat <dir>/session/screen.txt
* type: echo '{"line":"hello"}' >> <dir>/session/input.jsonl
* keys: echo '{"key":"Down"}' >> <dir>/session/input.jsonl
* note: echo '{"note":"picker confuses me"}' >> ...
* stop: echo '{"stop":true}' >> ...
* {"line": ...} sends text + Enter; {"send": ...} sends raw
* bytes (mind that zsh `echo` mangles \r — prefer "line").
* Launch as a background task; this is how an agent in
* Conductor explores a live TUI across tool calls.
*
* Usage:
* bun run scripts/dx-explore.ts help
* bun run scripts/dx-explore.ts init
* bun run scripts/dx-explore.ts claude-install
* bun run scripts/dx-explore.ts codex-install
* bun run scripts/dx-explore.ts opencode-install [--keyless]
* bun run scripts/dx-explore.ts drive [--no-hermetic-home] -- gbrain init
* Options: --dir <out> transcript dir (default .context/dx-runs/<scenario>-<ts>)
* --gbrain <bin> use an existing gbrain binary (default: compile+cache)
* --rebuild force recompile of the cached binary
* --keep keep hermetic temp homes for forensics
*
* Output bundle per scenario dir: meta.json, raw.txt, visible.txt,
* frames.jsonl, stalls.md, events.jsonl (inputs/notes timeline), steps.md
* (autopilot screen-by-screen), session/ (live: screen.txt, status.json).
*
* Progress prints to stderr; the transcript dir path is the only stdout line
* (pipe-friendly), matching the repo's progress discipline.
*/
import { spawnSync } from 'node:child_process';
import * as fs from 'node:fs';
import * as os from 'node:os';
import * as path from 'node:path';
import {
launchTty,
saveTranscript,
seedClaudeTuiConfig,
parseDriveCommand,
ptySupported,
redactSecrets,
stripAnsi,
MIN_REDACT_SECRET_LEN,
type TtySession,
} from '../test/helpers/tty-harness.ts';
const REPO_ROOT = path.resolve(import.meta.dir, '..');
/** Screen patterns that mean the paste-in install reached a passing verify —
* ONE list shared by the claude-install and codex-install scenarios so the
* two can't drift when the bootstrap's success copy changes. */
const VERIFY_SUCCESS_PATTERNS: Array<RegExp | string> = [
/bootstrap verify.*exit(?:ed|s)? 0/i,
/verify\b.*\b(passed|0\b)/i,
/All checks passed/i,
];
// Same synthetic persona the door tests use — the interview can complete
// unattended and nothing real about the operator ever enters a transcript.
const PERSONA = {
AGENT_NAME: 'Lighthouse',
PRINCIPAL_NAME: 'Pat Example',
AGENT_PURPOSE: 'Maintain the research corpus and draft the weekly memo without re-briefing.',
AGENT_TOP_JOBS: 'corpus upkeep; weekly memo; meeting prep',
PRINCIPAL_CONTEXT: 'Runs a small research group; builds internal tooling; values signal over noise.',
VOICE_REGISTER: 'Direct: three options, the second one wins.',
};
function log(msg: string): void {
process.stderr.write(`[dx-explore] ${msg}\n`);
}
function nowStamp(): string {
return new Date().toISOString().replace(/[:.]/g, '-').replace('T', '-').slice(0, 19);
}
// ── arg parsing ──────────────────────────────────────────────────────────────
interface CliArgs {
scenario: string;
dir?: string;
gbrainBin?: string;
rebuild: boolean;
keep: boolean;
/** Strip provider API keys from the child env — the TRUE keyless posture.
* Without this, a Conductor session's ANTHROPIC_API_KEY leaks into the
* hermetic run and the keyless first-touch path is never exercised. */
keyless: boolean;
hermeticHome: boolean;
driveArgv: string[];
}
/** Provider keys the hermetic base allows through; --keyless drops them.
* Also the redaction-map source: every non-empty value here is scrubbed
* from every written artifact. */
const PROVIDER_KEY_NAMES = [
'ANTHROPIC_API_KEY',
'ANTHROPIC_AUTH_TOKEN',
'OPENAI_API_KEY',
'XAI_API_KEY',
'GSTACK_ANTHROPIC_API_KEY',
'GSTACK_OPENAI_API_KEY',
];
function parseArgs(argv: string[]): CliArgs {
const out: CliArgs = {
scenario: '',
rebuild: false,
keep: false,
keyless: false,
hermeticHome: true,
driveArgv: [],
};
let i = 0;
const sep = argv.indexOf('--');
const own = sep >= 0 ? argv.slice(0, sep) : argv;
out.driveArgv = sep >= 0 ? argv.slice(sep + 1) : [];
while (i < own.length) {
const a = own[i]!;
if (a === '--dir') out.dir = own[++i];
else if (a === '--gbrain') out.gbrainBin = own[++i];
else if (a === '--rebuild') out.rebuild = true;
else if (a === '--keep') out.keep = true;
else if (a === '--keyless') out.keyless = true;
else if (a === '--no-hermetic-home') out.hermeticHome = false;
else if (!out.scenario && !a.startsWith('--')) out.scenario = a;
else {
log(`unknown argument: ${a}`);
process.exit(2);
}
i++;
}
return out;
}
// ── compiled gbrain binary (what a real user runs) ───────────────────────────
/** Compile (or reuse) a standalone gbrain binary. `bun run src/cli.ts` adds a
* multi-second transpile stall to EVERY invocation that a real install never
* has — a compiled binary keeps the timing honest. Cached under
* .context/dx-runs/bin/ keyed on nothing (use --rebuild after code changes). */
function ensureGbrainBinary(explicit: string | undefined, rebuild: boolean): string {
if (explicit) {
fs.accessSync(explicit, fs.constants.X_OK);
return path.resolve(explicit);
}
const binDir = path.join(REPO_ROOT, '.context', 'dx-runs', 'bin');
const binPath = path.join(binDir, 'gbrain');
if (!rebuild && fs.existsSync(binPath)) {
log(`reusing compiled gbrain at ${binPath} (--rebuild to refresh)`);
return binPath;
}
fs.mkdirSync(binDir, { recursive: true });
log('compiling gbrain (bun build --compile)…');
const res = spawnSync('bun', ['build', '--compile', '--no-compile-autoload-bunfig', '--outfile', binPath, 'src/cli.ts'], {
cwd: REPO_ROOT,
encoding: 'utf8',
timeout: 300_000,
maxBuffer: 64 * 1024 * 1024,
});
if (res.status !== 0 || !fs.existsSync(binPath)) {
throw new Error(`bun build --compile failed (exit ${res.status}):\n${(res.stderr ?? '').slice(-2000)}`);
}
log(`compiled ${binPath}`);
return binPath;
}
// ── scenario plumbing ────────────────────────────────────────────────────────
interface ScenarioCtx {
outDir: string;
gbrainBin: string;
keep: boolean;
/** temp dirs to remove on completion unless --keep */
cleanups: string[];
/** Files carrying credential material (copied auth.json, seeded key
* suffixes). ALWAYS deleted at cleanup — --keep keeps transcripts and
* hermetic dirs for forensics, never credentials. */
secretPaths: string[];
/** Secret VALUES (name → value) redacted from every written artifact —
* transcripts, the live screen mirror, events.jsonl. Structural, not
* checklist: writes go through redactSecrets at the write site. */
redact: Record<string, string>;
events: Array<{ tMs: number; kind: 'input' | 'note' | 'screen' | 'friction'; data: string }>;
t0: number;
}
/** Non-empty provider-key VALUES currently in the environment — the redaction
* map for every artifact write. */
function buildRedactMap(): Record<string, string> {
const out: Record<string, string> = {};
for (const name of PROVIDER_KEY_NAMES) {
const v = process.env[name];
if (v && v.trim().length >= MIN_REDACT_SECRET_LEN) out[name] = v;
}
return out;
}
function newCtx(args: CliArgs, needsGbrain: boolean): ScenarioCtx {
const outDir = path.resolve(
args.dir ?? path.join(REPO_ROOT, '.context', 'dx-runs', `${args.scenario}-${nowStamp()}`),
);
fs.mkdirSync(outDir, { recursive: true });
const ctx: ScenarioCtx = {
outDir,
gbrainBin: needsGbrain ? ensureGbrainBinary(args.gbrainBin, args.rebuild) : '',
keep: args.keep,
cleanups: [],
secretPaths: [],
redact: buildRedactMap(),
events: [],
t0: Date.now(),
};
installSignalScrub(ctx);
return ctx;
}
function tmp(ctx: ScenarioCtx, prefix: string): string {
const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
ctx.cleanups.push(dir);
return dir;
}
function event(ctx: ScenarioCtx, kind: 'input' | 'note' | 'screen' | 'friction', data: string): void {
ctx.events.push({ tMs: Date.now() - ctx.t0, kind, data });
}
/** Delete every credential copy. Idempotent; safe to call from a signal
* handler AND from finishCtx (a second call is a no-op). This is the
* "no credential outlives the run" guarantee — it must run even when a
* 10-25min install is Ctrl-C'd (finally does NOT run on SIGINT default). */
function scrubSecrets(ctx: ScenarioCtx): void {
for (const p of ctx.secretPaths) {
try {
fs.rmSync(p, { force: true });
} catch {
/* best-effort */
}
}
}
/** Wire SIGINT/SIGTERM so an interrupted run still scrubs credentials before
* the process dies. Registered once per scenario ctx. */
function installSignalScrub(ctx: ScenarioCtx): void {
const handler = (sig: NodeJS.Signals) => {
scrubSecrets(ctx);
process.stderr.write(`\n[dx-explore] ${sig}: scrubbed credential copies, exiting.\n`);
process.exit(130);
};
process.once('SIGINT', handler);
process.once('SIGTERM', handler);
}
function finishCtx(ctx: ScenarioCtx): void {
// Scrub credentials FIRST — before any other I/O that could throw (an
// events.jsonl write failure must not strand auth files).
scrubSecrets(ctx);
fs.writeFileSync(
path.join(ctx.outDir, 'events.jsonl'),
redactSecrets(
ctx.events.map((e) => JSON.stringify(e)).join('\n') + (ctx.events.length ? '\n' : ''),
ctx.redact,
),
);
if (ctx.keep && ctx.secretPaths.length > 0) {
log(`--keep: retained hermetic dirs, but scrubbed ${ctx.secretPaths.length} credential file(s)`);
}
if (!ctx.keep) {
for (const d of ctx.cleanups) {
try {
fs.rmSync(d, { recursive: true, force: true });
} catch {
/* best-effort */
}
}
} else {
fs.writeFileSync(
path.join(ctx.outDir, 'hermetic-dirs.json'),
JSON.stringify(ctx.cleanups, null, 2),
);
}
// The one stdout line: where the transcript landed.
console.log(ctx.outDir);
}
/** Live session mirror so a watcher (or a Conductor agent) can follow along:
* session/screen.txt (latest visible tail) + session/status.json. Each tick
* strips only a bounded RAW tail (a full-buffer stripAnsi every 500ms is
* quadratic on a 25-minute session) and redacts before writing — the mirror
* is a live artifact that outlives an interrupted run, so it must never
* carry a raw key even transiently. */
function mirrorSession(dir: string, session: TtySession, redact?: Record<string, string>): () => void {
const sessDir = path.join(dir, 'session');
fs.mkdirSync(sessDir, { recursive: true });
const timer = setInterval(() => {
try {
fs.writeFileSync(
path.join(sessDir, 'screen.txt'),
redactSecrets(stripAnsi(session.raw().slice(-131_072)).slice(-8000), redact),
);
fs.writeFileSync(
path.join(sessDir, 'status.json'),
JSON.stringify(
{
running: !session.exited(),
exitCode: session.exitCode(),
elapsedMs: Date.now() - session.startedAtMs,
frames: session.frames().length,
},
null,
2,
),
);
} catch {
/* best-effort */
}
}, 500);
return () => clearInterval(timer);
}
function saveSession(ctx: ScenarioCtx, name: string, session: TtySession, extraMeta: Record<string, unknown> = {}): void {
const dir = name ? path.join(ctx.outDir, name) : ctx.outDir;
saveTranscript(dir, {
frames: session.frames(),
raw: session.raw(),
redact: ctx.redact,
meta: {
scenario: name || path.basename(ctx.outDir),
argv: session.argv,
startedAtIso: new Date(session.startedAtMs).toISOString(),
exitCode: session.exitCode(),
durationMs: Date.now() - session.startedAtMs,
...extraMeta,
},
});
assertNoSecrets(dir, ctx.redact, ctx.t0);
}
/** Independent double-check of the structural redaction above: grep every
* written artifact for each raw secret value and HARD-FAIL on a hit (delete
* the leaking file, mark the run failed). A leak here means redactSecrets
* missed a rendering (e.g. ANSI-interleaved) — that is a bug to fix, never
* a warning to scroll past. */
function assertNoSecrets(dir: string, redact: Record<string, string>, sinceMs: number): void {
const values = Object.entries(redact).filter(([, v]) => v && v.length >= MIN_REDACT_SECRET_LEN);
if (values.length === 0) return;
const walk = (d: string): string[] =>
fs.readdirSync(d, { withFileTypes: true }).flatMap((e) => {
const p = path.join(d, e.name);
return e.isDirectory() ? walk(p) : e.isFile() ? [p] : [];
});
let leaked = false;
for (const file of walk(dir)) {
// NEVER touch files that predate this run: --dir can point anywhere
// (repo root, even $HOME) and deleting a pre-existing .env that happens
// to contain the key would be data loss, not leak containment.
try { if (fs.statSync(file).mtimeMs < sinceMs - 1000) continue; } catch { continue; }
let body: string;
try { body = fs.readFileSync(file, 'utf8'); } catch { continue; }
// Joined-data pass for frame records: a secret split across JSONL
// records never appears contiguously in the file body.
let joinedData = '';
if (file.endsWith('.jsonl')) {
for (const line of body.split('\n')) {
try { joinedData += String(JSON.parse(line)?.data ?? ''); } catch { /* not a data record */ }
}
}
for (const [name, value] of values) {
const hit =
body.includes(value) ||
stripAnsi(body).includes(value) || // ANSI-interleaved rendering
(joinedData !== '' && (joinedData.includes(value) || stripAnsi(joinedData).includes(value)));
if (hit) {
leaked = true;
fs.rmSync(file, { force: true });
log(`SECRET LEAK: ${file} contained ${name} despite structural redaction — file deleted; fix redactSecrets coverage before trusting transcripts`);
}
}
}
if (leaked) {
process.exitCode = 1;
}
}
// ── scenario: help ───────────────────────────────────────────────────────────
async function scenarioHelp(ctx: ScenarioCtx, args: CliArgs): Promise<void> {
const home = tmp(ctx, 'gb-dx-home-');
const ws = tmp(ctx, 'gb-dx-ws-');
const dropEnv = args.keyless ? PROVIDER_KEY_NAMES : undefined;
const surfaces: Array<{ name: string; argv: string[] }> = [
{ name: 'step-01-bare', argv: [ctx.gbrainBin] },
{ name: 'step-02-help', argv: [ctx.gbrainBin, '--help'] },
{ name: 'step-03-init-help', argv: [ctx.gbrainBin, 'init', '--help'] },
{ name: 'step-04-bootstrap-help', argv: [ctx.gbrainBin, 'bootstrap', '--help'] },
{ name: 'step-05-bootstrap-bare', argv: [ctx.gbrainBin, 'bootstrap'] },
{ name: 'step-06-status-fresh', argv: [ctx.gbrainBin, 'status'] },
];
for (const s of surfaces) {
log(`running ${s.name}: ${s.argv.join(' ')}`);
const session = launchTty(s.argv, {
cwd: ws,
env: { HOME: home, GBRAIN_HOME: home },
dropEnv,
timeoutMs: 120_000,
});
await session.waitForExit(110_000);
await session.close();
saveSession(ctx, s.name, session);
}
}
// ── scenario: init (naive-user autopilot) ────────────────────────────────────
async function scenarioInit(ctx: ScenarioCtx, args: CliArgs): Promise<void> {
const home = tmp(ctx, 'gb-dx-home-');
const ws = tmp(ctx, 'gb-dx-ws-');
log(
`interactive \`gbrain init\` (${args.keyless ? 'TRUE keyless — provider keys stripped' : 'ambient keys allowed'}), ` +
'naive-user autopilot: Enter accepts every default',
);
const session = launchTty([ctx.gbrainBin, 'init'], {
cwd: ws,
env: { HOME: home, GBRAIN_HOME: home },
dropEnv: args.keyless ? PROVIDER_KEY_NAMES : undefined,
timeoutMs: 600_000,
});
const stopMirror = mirrorSession(ctx.outDir, session, ctx.redact);
const steps: string[] = [];
let lastMarkPos = 0;
const MAX_STEPS = 15;
try {
for (let step = 1; step <= MAX_STEPS && !session.exited(); step++) {
const settled = await session.waitForQuiet({ quietMs: 2000, timeoutMs: 180_000 });
const shot = session.visibleSince(lastMarkPos);
lastMarkPos = session.mark();
const tSec = ((Date.now() - session.startedAtMs) / 1000).toFixed(1);
steps.push(
`## Step ${step} (t+${tSec}s${settled ? '' : ', NEVER SETTLED within 180s'})\n\n` +
'```\n' + shot.trim().slice(-3000) + '\n```\n',
);
event(ctx, 'screen', shot.slice(-2000));
if (session.exited()) break;
log(`step ${step}: screen settled at t+${tSec}s — pressing Enter (default)`);
event(ctx, 'input', 'Enter');
session.sendKey('Enter');
await Bun.sleep(300);
}
await session.waitForExit(60_000);
} finally {
stopMirror();
await session.close();
}
fs.writeFileSync(
path.join(ctx.outDir, 'steps.md'),
`# gbrain init — naive-user autopilot (Enter through every prompt)\n\n${steps.join('\n')}`,
);
saveSession(ctx, '', session, { autopilot: 'enter-through-defaults', keyless: args.keyless });
}
// ── scenarios: claude-install / codex-install ────────────────────────────────
/**
* Handle the harness's own first-run chrome dialogs (Claude Code: workspace
* trust, bypass-permissions warning) so an unattended run reaches the input
* prompt. Each handled dialog is recorded as a note — the dialogs ARE part of
* the real first-run friction, just not gbrain's copy. Returns once the
* screen has been quiet with no dialog visible, or at the deadline.
*/
async function settlePastBootDialogs(
ctx: ScenarioCtx,
session: TtySession,
opts: { deadlineMs?: number } = {},
): Promise<void> {
const deadline = Date.now() + (opts.deadlineMs ?? 90_000);
const handled = new Set<string>();
while (Date.now() < deadline) {
await session.waitForQuiet({ quietMs: 2000, timeoutMs: 30_000 });
if (session.exited()) return;
// Bounded strip: a repaint-heavy TUI (observed: grok's splash animation)
// grows the raw buffer by MBs — stripping the FULL buffer every
// iteration is the quadratic hot loop; strip a raw tail instead.
const tail = stripAnsi(session.raw().slice(-131_072)).slice(-2500);
if (!handled.has('trust') && /trust this ?folder/i.test(tail.replace(/\s+/g, ' '))) {
handled.add('trust');
event(ctx, 'note', 'boot dialog: workspace trust — accepted (option 1)');
session.send('1');
await Bun.sleep(300);
session.sendKey('Enter');
continue;
}
if (!handled.has('bypass') && /Bypass ?Permissions ?mode/i.test(tail.replace(/\s+/g, ''))) {
handled.add('bypass');
event(ctx, 'note', 'boot dialog: bypass-permissions warning — accepted (option 2)');
session.send('2');
await Bun.sleep(300);
session.sendKey('Enter');
continue;
}
// Codex directory-trust dialog: "Do you trust the contents of this
// directory? › 1. Yes, continue 2. No, quit".
if (!handled.has('codex-trust') && /trust ?the ?contents ?of ?this ?directory/i.test(tail.replace(/\s+/g, ''))) {
handled.add('codex-trust');
event(ctx, 'note', 'boot dialog: codex directory trust — accepted (option 1)');
session.send('1');
await Bun.sleep(300);
session.sendKey('Enter');
continue;
}
// Grok Build sign-in screen (observed keyless copy: "Not signed in").
// No unattended path exists past it — record the friction and stop
// settling; the caller's wall clock must not burn on a login dialog.
if (/not signed in/i.test(tail)) {
event(ctx, 'note', 'boot dialog: grok sign-in required — no unattended path; stopping settle');
return;
}
// Quiet with no KNOWN dialog: if the tail still LOOKS like a prompt
// (numbered options / y-n / picker glyph), note it — a silently
// mis-settled boot is otherwise invisible in the audit trail.
if (/(?:^|\n)\s*(?:\d+\.\s|[❯›]\s)|\((?:y\/n|Y\/n)\)/m.test(tail.slice(-400))) {
event(ctx, 'note', 'settle: quiet with an unmatched dialog-shaped tail — proceeding (note-only; check the transcript if the paste lands oddly)');
}
return; // quiet + no dialog = at the input prompt
}
}
/** Stage the compiled gbrain into a fresh bin dir (PATH-prepend target) so
* the agent's bare `gbrain` runs this checkout. */
function stageBinDir(ctx: ScenarioCtx): string {
const binDir = tmp(ctx, 'gb-dx-bin-');
fs.copyFileSync(ctx.gbrainBin, path.join(binDir, 'gbrain'));
fs.chmodSync(path.join(binDir, 'gbrain'), 0o755);
return binDir;
}
interface InstallSessionOpts {
argv: string[];
cwd: string;
env: Record<string, string | undefined>;
extraAllow?: string[];
dropEnv?: string[];
/** The pasted prompt. Per-agent: the bootstrap runbook block for
* claude/codex, a brain-only GROK.md-driven block for grok. */
prompt: string;
/** Success copy to race against (default: the bootstrap verify patterns).
* Brain-only scenarios pass their own — grok's is the doctor banner. */
successPatterns?: Array<RegExp | string>;
timeoutMs?: number;
meta: Record<string, unknown>;
}
/** The shared install-session tail the claude/codex/grok scenarios all run:
* launch → mirror → settle boot dialogs → paste the prompt → race
* verify-success copy vs exit → let trailing output land → save. Per-agent
* PREPARATION (TUI seeds, auth copies, git init) deliberately stays in each
* scenario — the loop is what was duplicated, the prep genuinely differs. */
async function runInstallSession(ctx: ScenarioCtx, opts: InstallSessionOpts): Promise<void> {
const timeoutMs = opts.timeoutMs ?? 1_800_000;
let earlyTerminal: string | undefined;
log(`watch live: cat ${path.join(ctx.outDir, 'session', 'screen.txt')}`);
const session = launchTty(opts.argv, {
cwd: opts.cwd,
env: opts.env,
extraAllow: opts.extraAllow,
dropEnv: opts.dropEnv,
timeoutMs,
});
const stopMirror = mirrorSession(ctx.outDir, session, ctx.redact);
try {
await settlePastBootDialogs(ctx, session);
// Sign-in wall / textless splash: no unattended path exists past either.
// Observed (grok v1.0.4 keyless): headless prints "Not signed in"; the
// TUI loops a full-screen glyph animation with NO textual prompt for 8+
// minutes. Try one Enter (the common skip-splash gesture), then if the
// screen still carries no meaningful text — or shows the sign-in copy —
// record the friction (that IS the keyless measurement) and end early
// instead of pasting into a wall for the full wall clock.
const tailText = () => stripAnsi(session.raw().slice(-131_072)).slice(-2500);
// Sign-in copy, both surfaces observed (GROK-CLI-PIN.md): headless prints
// "Not signed in"; the TUI settles (~6s, after an intro animation) onto
// "Approve in your browser to finish signing in" + a device code.
const signInWall = () =>
/not signed in|approve in your browser|finish signing in|sign in with/i.test(tailText());
// Word-like text only: splash/spinner screens render Braille-pattern
// glyphs (U+2800 range, observed) with scattered digits/SGR residue but
// ZERO 3+-letter runs, while any real prompt/sign-in screen carries
// words. Counting letter runs beats enumerating glyph exceptions.
const meaningfulLen = (s: string) => (s.match(/[A-Za-z]{3,}/g) ?? []).join('').length;
if (!session.exited() && (signInWall() || meaningfulLen(tailText()) < 40)) {
event(ctx, 'note', 'sign-in wall or textless splash — sending one Enter (skip-splash attempt)');
session.sendKey('Enter');
await Bun.sleep(3000);
if (!session.exited() && (signInWall() || meaningfulLen(tailText()) < 40)) {
event(ctx, 'note', 'sign-in wall / no textual prompt persists — ending session early (keyless friction recorded)');
earlyTerminal = 'sign-in-wall-or-splash';
return; // finally owns cleanup; save happens after it
}
}
event(ctx, 'input', 'paste install prompt');
// Scope the verify match to output AFTER the paste: the pasted prompt
// itself contains verify-adjacent copy, and matching the full buffer
// re-scans a growing transcript every poll.
const pasteMark = session.mark();
session.send(opts.prompt);
await Bun.sleep(1500);
session.sendKey('Enter');
const raceBudget = Math.max(timeoutMs - 300_000, Math.floor(timeoutMs * 0.8));
const done = await Promise.race([
session
.waitForAny(opts.successPatterns ?? VERIFY_SUCCESS_PATTERNS, { timeoutMs: raceBudget, since: pasteMark })
.then(() => 'verify-signal')
.catch(() => 'no-signal'),
session.waitForExit(raceBudget).then(() => 'exited'),
]);
event(ctx, 'note', `terminal condition: ${done}`);
await session.waitForQuiet({ quietMs: 5000, timeoutMs: 60_000 });
} finally {
stopMirror();
await session.close();
}
saveSession(ctx, '', session, earlyTerminal ? { ...opts.meta, terminal: earlyTerminal } : opts.meta);
}
/** The README paste block, pointed at THIS repo's runbook, plus a persona
* appendix so the interview completes unattended. The appendix is the ONLY
* deviation from the shipped block — flagged in meta so the audit discounts it. */
function installPrompt(): string {
const runbook = path.join(REPO_ROOT, 'BOOTSTRAP_FOR_AGENTS.md');
return (
`Read and follow every step of: ${runbook}\n` +
`Goal: set yourself up as my persistent personal agent in this folder, with gbrain ` +
`as your memory. Interview me before writing any identity file — never invent ` +
`answers. Ask before anything destructive. You are not done until ` +
`\`gbrain bootstrap verify\` exits 0.\n\n` +
`[Unattended-run appendix — I am stepping away; use these interview answers instead ` +
`of asking me, and do not wait for my input: ` +
`agent name: ${PERSONA.AGENT_NAME}; my name: ${PERSONA.PRINCIPAL_NAME}; ` +
`purpose: ${PERSONA.AGENT_PURPOSE}; top jobs: ${PERSONA.AGENT_TOP_JOBS}; ` +
`about me: ${PERSONA.PRINCIPAL_CONTEXT}; voice: ${PERSONA.VOICE_REGISTER}. ` +
`gbrain is already installed and on PATH. If a step needs GitHub auth or an API key ` +
`that is unavailable, take the documented keyless/local fallback and continue.]`
);
}
async function scenarioClaudeInstall(ctx: ScenarioCtx, args: CliArgs): Promise<void> {
const home = tmp(ctx, 'gb-dx-home-');
const cfg = tmp(ctx, 'gb-dx-ccfg-');
const gbHome = tmp(ctx, 'gb-dx-gbhome-');
const ws = tmp(ctx, 'gb-dx-ws-');
const binDir = stageBinDir(ctx);
seedClaudeTuiConfig(cfg, {
apiKey: process.env.ANTHROPIC_API_KEY ?? process.env.GSTACK_ANTHROPIC_API_KEY,
// realpath: macOS tmpdirs live under /var → /private/var; claude compares
// against the resolved path, so an unresolved seed misses.
trustedDirs: [ws, fs.realpathSync(ws)],
});
// The seed records the key's last 20 chars — credential-adjacent, so it is
// scrubbed at cleanup even with --keep.
ctx.secretPaths.push(path.join(cfg, '.claude.json'));
log('REAL interactive claude running the paste-in bootstrap (10-25 min, real API cost)');
await runInstallSession(ctx, {
// dangerously-skip-permissions (spelled dash-free here): v1 measures flow
// + copy + stalls without permission-dialog babysitting. Permission-prompt
// COUNT is a separate drive-mode pass (the dialogs are Claude Code's
// chrome, not gbrain copy).
argv: ['claude', '--dangerously-skip-permissions'],
cwd: ws,
env: {
HOME: home,
CLAUDE_CONFIG_DIR: cfg,
GBRAIN_HOME: gbHome,
PATH: `${binDir}:${process.env.PATH ?? ''}`,
},
dropEnv: args.keyless ? PROVIDER_KEY_NAMES : undefined,
prompt: installPrompt(),
meta: {
promptDeviation: 'unattended persona appendix + local runbook path + preinstalled binary',
runbook: 'BOOTSTRAP_FOR_AGENTS.md (local)',
},
});
}
async function scenarioCodexInstall(ctx: ScenarioCtx, args: CliArgs): Promise<void> {
const home = tmp(ctx, 'gb-dx-home-');
const gbHome = tmp(ctx, 'gb-dx-gbhome-');
const ws = tmp(ctx, 'gb-dx-ws-');
const binDir = stageBinDir(ctx);
// Hermetic ~/.codex with ONLY the operator's auth (same posture as the
// codex door test). codex refuses untrusted cwds — a git repo satisfies it.
const codexHome = path.join(home, '.codex');
fs.mkdirSync(codexHome, { recursive: true });
const realAuth = path.join(os.homedir(), '.codex', 'auth.json');
if (fs.existsSync(realAuth)) {
const authCopy = path.join(codexHome, 'auth.json');
fs.copyFileSync(realAuth, authCopy);
fs.chmodSync(authCopy, 0o600); // copyFileSync doesn't preserve source mode
ctx.secretPaths.push(authCopy); // scrubbed at cleanup, even with --keep
}
spawnSync('git', ['init', '-q', ws]);
spawnSync('git', ['-C', ws, 'config', 'user.email', '[email protected]']);
spawnSync('git', ['-C', ws, 'config', 'user.name', 'DX Explore']);
log('REAL interactive codex running the paste-in bootstrap (10-25 min, real API cost)');
await runInstallSession(ctx, {
argv: ['codex', '--sandbox', 'workspace-write', '--ask-for-approval', 'never'],
cwd: ws,
env: {
HOME: home,
CODEX_HOME: codexHome,
GBRAIN_HOME: gbHome,
PATH: `${binDir}:${process.env.PATH ?? ''}`,
},
extraAllow: ['OPENAI_API_KEY', 'CODEX_*'],
dropEnv: args.keyless ? PROVIDER_KEY_NAMES : undefined,
prompt: installPrompt(),
meta: {
promptDeviation: 'unattended persona appendix + local runbook path + preinstalled binary',
runbook: 'BOOTSTRAP_FOR_AGENTS.md (local)',
},
});
}
// ── scenario: codex-plugin-install ──────────────────────────────────────────
/** The PLUGIN lane's first-run journey: marketplace add + plugin add happen
* via the CLI up front (the two documented commands), then a REAL interactive
* codex session answers a brain question through the plugin-provided MCP
* server. Friction observed here is the plugin lane's actual first-run UX —
* distinct from codex-install, which observes the bootstrap paste-in lane. */
async function scenarioCodexPluginInstall(ctx: ScenarioCtx, args: CliArgs): Promise<void> {
const home = tmp(ctx, 'gb-dx-home-');
const gbHome = tmp(ctx, 'gb-dx-gbhome-');
const ws = tmp(ctx, 'gb-dx-ws-');
const binDir = stageBinDir(ctx);
// Hermetic ~/.codex with ONLY the operator's auth (codex-install posture).
const codexHome = path.join(home, '.codex');
fs.mkdirSync(codexHome, { recursive: true });
const realAuth = path.join(os.homedir(), '.codex', 'auth.json');
if (fs.existsSync(realAuth)) {
const authCopy = path.join(codexHome, 'auth.json');
fs.copyFileSync(realAuth, authCopy);
fs.chmodSync(authCopy, 0o600);
ctx.secretPaths.push(authCopy);
}
spawnSync('git', ['init', '-q', ws]);
spawnSync('git', ['-C', ws, 'config', 'user.email', '[email protected]']);
spawnSync('git', ['-C', ws, 'config', 'user.name', 'DX Explore']);
// Stage a CLEAN tree (tracked files only) as the local marketplace source.
const stage = tmp(ctx, 'gb-dx-plugin-stage-');
spawnSync('sh', ['-c', `git -C '${REPO_ROOT}' archive HEAD | tar -x -C '${stage}'`]);
// The two documented install commands, up front (CLI, not the PTY).
const pluginEnv = {
...process.env,
HOME: home,
CODEX_HOME: codexHome,
PATH: `${binDir}:${process.env.PATH ?? ''}`,
};
for (const argv of [
['codex', 'plugin', 'marketplace', 'add', stage],
['codex', 'plugin', 'add', 'gbrain@gbrain'],
]) {
const r = spawnSync(argv[0], argv.slice(1), { env: pluginEnv, encoding: 'utf8' });
event(ctx, r.status === 0 ? 'note' : 'friction', `${argv.join(' ')} → exit ${r.status}${r.status === 0 ? '' : `: ${(r.stderr ?? '').slice(0, 300)}`}`);
if (r.status !== 0) throw new Error(`plugin install step failed: ${argv.join(' ')}`);
}
// A brain the plugin serve can answer from (keyless PGLite + one fact).
const initR = spawnSync(ctx.gbrainBin, ['init', '--pglite', '--no-embedding', '--non-interactive'], {
env: { ...pluginEnv, GBRAIN_HOME: gbHome },
cwd: ws,
encoding: 'utf8',
});
if (initR.status !== 0) throw new Error(`gbrain init failed: ${(initR.stderr ?? '').slice(0, 300)}`);
const seedR = spawnSync(ctx.gbrainBin, ['call', 'remember', JSON.stringify({
content: 'The dx-explore plugin probe codeword is heliograph.',
provenance: 'dx-explore codex-plugin-install scenario',
})], { env: { ...pluginEnv, GBRAIN_HOME: gbHome }, cwd: ws, encoding: 'utf8' });
if (seedR.status !== 0) {
// Fail fast — proceeding would burn a paid, minutes-long interactive
// session that can only fail confusingly on the codeword probe.
throw new Error(`seed remember failed: ${(seedR.stderr ?? '').slice(0, 300)}`);
}
log('REAL interactive codex with the gbrain PLUGIN installed (minutes, real API cost)');
await runInstallSession(ctx, {
argv: ['codex', '--sandbox', 'workspace-write', '--ask-for-approval', 'never'],
cwd: ws,
env: {
HOME: home,
CODEX_HOME: codexHome,
GBRAIN_HOME: gbHome,
GBRAIN_BIN: path.join(binDir, 'gbrain'),
PATH: `${binDir}:${process.env.PATH ?? ''}`,
},
extraAllow: ['OPENAI_API_KEY', 'CODEX_*'],
dropEnv: args.keyless ? PROVIDER_KEY_NAMES : undefined,
prompt:
'The gbrain plugin is installed. Using ONLY the gbrain MCP tools (do not guess), ' +
'answer: what is the dx-explore plugin probe codeword? Then reply with one line: ' +
'the codeword and which tool you used.\n\n' +
'[Unattended-run appendix — I am stepping away; do not wait for my input. ' +
'If no gbrain MCP tool is available, note the exact error and stop.]',
meta: {
promptDeviation: 'plugin lane (marketplace add + plugin add pre-run); brain question via plugin MCP',
runbook: 'docs/mcp/CODEX.md (plugin install section)',
},
});
}
// ── scenario: grok-install ───────────────────────────────────────────────────
/** Brain-only success copy for the grok scenario: the doctor banner proves
* the registration handshook (observed, docs/mcp/GROK-CLI-PIN.md) — grok has
* NO bootstrap path, so the bootstrap verify patterns must not be its bar. */
const GROK_INSTALL_SUCCESS_PATTERNS: Array<RegExp | string> = [
/7 tools discovered/i,
/handshake OK/i,
];
/** GROK.md-driven brain-only prompt — deliberately NOT the bootstrap paste
* block: the docs classify grok as brain-only install (no `gbrain bootstrap`
* support), so the scenario must not test an unsupported flow. */
function grokInstallPrompt(): string {
const guide = path.join(REPO_ROOT, 'docs', 'mcp', 'GROK.md');
return (
`Read and follow: ${guide}\n` +
`Goal: wire the gbrain memory brain into you (Grok Build) over stdio MCP — ` +
`brain-only install, no bootstrap. Steps: ` +
`1) run \`gbrain init --pglite --no-embedding --non-interactive\`; ` +
`2) register gbrain exactly as the guide's Register section shows; ` +
`3) verify with \`grok mcp doctor gbrain\` — you are not done until it reports ` +
`the tools-discovered check passing; ` +
`4) one recall round-trip: use the gbrain remember tool to store ` +
`"${PERSONA.AGENT_NAME} prefers ${PERSONA.VOICE_REGISTER}" and then recall it.\n\n` +
`[Unattended-run appendix — I am stepping away; do not wait for my input. ` +
`gbrain is already installed and on PATH. If a step needs auth that is ` +
`unavailable, note the exact error and stop.]`
);
}
async function scenarioGrokInstall(ctx: ScenarioCtx, args: CliArgs): Promise<void> {
const home = tmp(ctx, 'gb-dx-home-');
const gbHome = tmp(ctx, 'gb-dx-gbhome-');
const ws = tmp(ctx, 'gb-dx-ws-');
const binDir = stageBinDir(ctx);
// Hermetic ~/.grok seeded with the auto-update kill-switch (config-only
// mechanism, default ON — observed v1.0.4). Auth travels via XAI_API_KEY
// env only; grok MAY persist derived credentials after an authed session,
// so the known candidate is pre-registered for the scrub (rm of a file
// that never appears is a no-op).
const grokHome = path.join(home, '.grok');
fs.mkdirSync(grokHome, { recursive: true });
// Verbatim kill-switch homes (update together): seedGrokConfig in
// test/helpers/agent-harness.ts and the grok-door auth-preflight printf
// in .github/workflows/heavy-tests.yml.
fs.writeFileSync(path.join(grokHome, 'config.toml'), '[cli]\nauto_update = false\n');
ctx.secretPaths.push(path.join(grokHome, 'mcp_credentials.json'));
log('REAL interactive grok running the GROK.md brain-only install (real API cost when authed)');
log('keyless runs stop at the observed sign-in screen — that friction IS the measurement');
await runInstallSession(ctx, {
argv: ['grok'],
cwd: ws,
env: {
HOME: home,
GROK_HOME: grokHome,
GBRAIN_HOME: gbHome,
PATH: `${binDir}:${process.env.PATH ?? ''}`,
// Never let a keyless first-run bounce the OPERATOR's browser for
// sign-in; the settle loop stops at the observed "Not signed in" copy.
BROWSER: '/usr/bin/false',
},
extraAllow: ['XAI_API_KEY'],
// --keyless drops provider keys AFTER extraAllow re-admission — a keyless
// grok-install must measure the sign-in wall, not silently run authed.
dropEnv: args.keyless ? PROVIDER_KEY_NAMES : undefined,
prompt: grokInstallPrompt(),
successPatterns: GROK_INSTALL_SUCCESS_PATTERNS,
meta: {
promptDeviation: 'unattended appendix + local GROK.md path + preinstalled binary',
runbook: 'docs/mcp/GROK.md (local, brain-only — grok has no bootstrap path)',
},
});
}
// ── scenario: opencode-install ───────────────────────────────────────────────
async function scenarioOpencodeInstall(ctx: ScenarioCtx, args: CliArgs): Promise<void> {
const home = tmp(ctx, 'gb-dx-home-');
const gbHome = tmp(ctx, 'gb-dx-gbhome-');
const ws = tmp(ctx, 'gb-dx-ws-');
const binDir = stageBinDir(ctx);
// Hermetic HOME + BOTH XDG dirs (config/auth/data all move — observed
// v1.18.18, OPENCODE-CLI-PIN.md §Path seams), seeded with the config half
// of the double autoupdate kill; the env half rides the session env below.
const xdgConfig = path.join(home, '.config');
const ocCfgDir = path.join(xdgConfig, 'opencode');
fs.mkdirSync(ocCfgDir, { recursive: true });
fs.writeFileSync(
path.join(ocCfgDir, 'opencode.json'),
JSON.stringify({ $schema: 'https://opencode.ai/config.json', autoupdate: false }, null, 2) + '\n',
);
// Auth travels env-only for the anthropic leg; a login flow would persist
// auth.json — pre-register the known candidate for the scrub (rm of a file
// that never appears is a no-op).
ctx.secretPaths.push(path.join(home, '.local', 'share', 'opencode', 'auth.json'));
spawnSync('git', ['init', '-q', ws]);
spawnSync('git', ['-C', ws, 'config', 'user.email', '[email protected]']);
spawnSync('git', ['-C', ws, 'config', 'user.name', 'DX Explore']);
log('REAL interactive opencode running the paste-in bootstrap (opencode is a bootstrap-supported harness)');
log('keyless runs ride the anonymous free tier (observed) — the flow should COMPLETE keyless; a sign-in wall here is itself a pin-refresh signal');
await runInstallSession(ctx, {
argv: ['opencode'],
cwd: ws,
env: {
HOME: home,
XDG_CONFIG_HOME: xdgConfig,
XDG_DATA_HOME: path.join(home, '.local', 'share'),
OPENCODE_DISABLE_AUTOUPDATE: '1',
GBRAIN_HOME: gbHome,
PATH: `${binDir}:${process.env.PATH ?? ''}`,
// Never let a first-run bounce the OPERATOR's browser for sign-in.
BROWSER: '/usr/bin/false',
},
extraAllow: ['ANTHROPIC_API_KEY'],
// --keyless drops provider keys AFTER extraAllow re-admission — on
// opencode that measures the FREE-TIER path, not a wall (observed).
dropEnv: args.keyless ? PROVIDER_KEY_NAMES : undefined,
prompt: installPrompt(),
meta: {
promptDeviation: 'unattended persona appendix + local runbook path + preinstalled binary',
runbook: 'BOOTSTRAP_FOR_AGENTS.md (local — opencode is bootstrap-supported)',
},
});
}
// ── scenario: drive (manual control channel) ─────────────────────────────────
async function scenarioDrive(ctx: ScenarioCtx, args: CliArgs): Promise<void> {
if (args.driveArgv.length === 0) {
log('drive mode needs a command: dx-explore.ts drive -- gbrain init');
process.exit(2);
}
// `gbrain` as argv[0] resolves to the compiled binary.
const argv = [...args.driveArgv];
if (argv[0] === 'gbrain') argv[0] = ctx.gbrainBin;
const sessDir = path.join(ctx.outDir, 'session');
fs.mkdirSync(sessDir, { recursive: true });
const inputPath = path.join(sessDir, 'input.jsonl');
fs.writeFileSync(inputPath, '');
const env: Record<string, string | undefined> = {};
if (args.hermeticHome) {
const home = tmp(ctx, 'gb-dx-home-');
env.HOME = home;
env.GBRAIN_HOME = home;
}
log(`driving: ${argv.join(' ')}`);
log(`watch: cat ${path.join(sessDir, 'screen.txt')}`);
log(`input: echo '{"line":"some text"}' >> ${inputPath} (sends text + Enter)`);
log(` echo '{"key":"Down"}' >> ${inputPath}`);
log(`stop: echo '{"stop":true}' >> ${inputPath}`);
const session = launchTty(argv, {
cwd: process.cwd(),
env,
timeoutMs: 3_600_000,
});
const stopMirror = mirrorSession(ctx.outDir, session, ctx.redact);
let offset = 0;
let stopping = false;
try {
while (!session.exited() && !stopping) {
await Bun.sleep(200);
let content = '';
try {
content = fs.readFileSync(inputPath, 'utf8');
} catch {
continue;
}
if (content.length <= offset) continue;
const fresh = content.slice(offset);
offset = content.length;
for (const line of fresh.split('\n')) {
if (!line.trim()) continue;
const cmd = parseDriveCommand(line);
if (!cmd) {
log(`skipping malformed drive command: ${line.slice(0, 120)}`);
continue;
}
if (cmd.kind === 'send') {
event(ctx, 'input', cmd.data);
session.send(cmd.data);
} else if (cmd.kind === 'key') {
event(ctx, 'input', `<${cmd.key}>`);
session.sendKey(cmd.key);
} else if (cmd.kind === 'note') {
event(ctx, 'note', cmd.text);
} else if (cmd.kind === 'stop') {
stopping = true;
break;
}
}
}
} finally {
stopMirror();
await session.close();
}
saveSession(ctx, '', session, { mode: 'drive', command: argv.join(' ') });
}
// ── main ─────────────────────────────────────────────────────────────────────
const SCENARIOS: Record<string, { needsGbrain: boolean; run: (ctx: ScenarioCtx, args: CliArgs) => Promise<void> }> = {
help: { needsGbrain: true, run: scenarioHelp },
init: { needsGbrain: true, run: scenarioInit },
'claude-install': { needsGbrain: true, run: scenarioClaudeInstall },
'codex-install': { needsGbrain: true, run: scenarioCodexInstall },
'codex-plugin-install': { needsGbrain: true, run: scenarioCodexPluginInstall },
'grok-install': { needsGbrain: true, run: scenarioGrokInstall },
'opencode-install': { needsGbrain: true, run: scenarioOpencodeInstall },
drive: { needsGbrain: true, run: scenarioDrive },
};
async function main(): Promise<void> {
if (!ptySupported()) {
log('this Bun lacks PTY (terminal:) support — upgrade Bun (engines.bun in package.json) before running dx scenarios');
process.exit(2);
}
const args = parseArgs(process.argv.slice(2));
const scenario = SCENARIOS[args.scenario];
if (!scenario) {
log(`usage: bun run scripts/dx-explore.ts <${Object.keys(SCENARIOS).join('|')}> [options] [-- cmd...]`);
process.exit(2);
}
const ctx = newCtx(args, scenario.needsGbrain);
log(`transcripts → ${ctx.outDir}`);
try {
await scenario.run(ctx, args);
} finally {
finishCtx(ctx);
}
}
await main();