launch-ready: tighten validator, fix headless json, friendlier auth errors

Pre-launch fixes batch 1 of 5 (audit items #30–34).

#30 — shell-validator dd patterns: tolerate spaces around `=`, catch
the piped variant (`cat file | dd of=/dev/sda`), strengthen docstring
that the validator is advisory, not a security boundary. Real
enforcement is the permission system + sandboxing.

#31 — credentials store: malformed JSON now prints an actionable
"run `codebase auth logout` to reset" message instead of silently
clearing the file. Version mismatch + read failures both surface to
stderr so users can self-diagnose.

#32 — headless json error path: ConfigError + prompt-blocked now
emit a structured envelope on stdout in `json` and `stream-json`
modes. CI consumers no longer have to merge stdout+stderr to detect
setup failures.

#33 — CI: added a windows-latest smoke job that builds + invokes the
.exe natively. Catches missing-DLL / console-host bugs before the
binary hits a GitHub Release.

#34 — OAuth: added isHeadlessSession heuristic tests + a
LAUNCH_CHECKLIST.md doc with the manual-verification steps for the
OAuth flow on macOS arm64 / macOS x64 / Linux x64 / Linux arm64 /
Windows + SSH.

Author: halfaipg

.github/workflows/build-binaries.yml

@@ -106,3 +106,48 @@ jobs:
               ${PRERELEASE_FLAG}
           fi
           gh release upload "${TAG}" "${{ matrix.asset }}" --clobber
+
+  # Native Windows smoke test. The build matrix above cross-compiles the
+  # Windows .exe on ubuntu, but a binary built that way can still die at
+  # runtime on real Windows (missing DLL, path resolution quirk, console-
+  # vs-console-host differences). This job builds + invokes the .exe on
+  # an actual windows-latest runner so obvious breakage gates the release.
+  windows-smoke:
+    name: Smoke-test Windows binary
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.tag || github.ref }}
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: "1.3.14"
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+
+      - name: Install
+        run: npm ci
+
+      - name: Stub ink devtools
+        shell: bash
+        run: |
+          cat > node_modules/ink/build/devtools.js <<'EOF'
+          export default { connectToDevTools() {} };
+          EOF
+
+      - name: Compile native Windows binary
+        run: bun build --compile --target=bun-windows-x64 src/cli.tsx --outfile=codebase.exe
+
+      - name: Invoke --version and --help
+        # Both should exit 0 on a healthy binary. Asking for --help also
+        # exercises argv parsing + the early return path so we catch
+        # crashes in startup code (config loading, dotenv, etc.) without
+        # needing real credentials.
+        shell: pwsh
+        run: |
+          ./codebase.exe --version
+          ./codebase.exe --help

docs/LAUNCH_CHECKLIST.md

@@ -0,0 +1,157 @@
+# Launch checklist — v2.0.0
+
+Pre-flight smoke tests to run on real hardware before flipping the npm
+`latest` dist-tag to a v2.0.0 stable release. Automated tests cover the
+inner pieces (PKCE, URL building, callback handler, headless heuristic);
+this list covers what only humans can verify: real terminals, real
+browsers, real network paths.
+
+## Required platforms
+
+Every box below before launch. Skip = release blocker.
+
+- [ ] macOS arm64 (Apple Silicon — most common dev target)
+- [ ] macOS x64 (Intel Mac, still in use)
+- [ ] Linux x64 (Ubuntu LTS or similar)
+- [ ] Linux arm64 (Raspberry Pi, Graviton — increasingly common)
+- [ ] Windows x64 (PowerShell + Windows Terminal; cmd.exe is bonus)
+- [ ] SSH from each desktop into a Linux box, run the CLI remotely
+
+## Install paths
+
+### npm
+
+```sh
+npm install -g codebase-cli@pre   # current
+which codebase                     # symlink resolves
+codebase --version                 # prints version
+codebase --help                    # prints help, no crash
+```
+
+### Downloaded binary from GitHub Releases
+
+```sh
+# Pick the right one
+curl -L -o codebase https://github.com/codebase-foundation/codebase-cli/releases/download/v2.0.0/codebase-darwin-arm64
+chmod +x codebase
+./codebase --version
+./codebase --help
+```
+
+Verify: no `react-devtools-core` runtime errors, no missing-DLL errors
+on Windows, no GLIBC-too-old errors on Linux.
+
+## OAuth flow (the highest-risk path)
+
+For each platform with a graphical environment + browser:
+
+1. Wipe creds: `rm -f ~/.codebase/credentials.json`
+2. Launch: `codebase`
+3. First-run wizard appears. Pick "Login to Codebase."
+4. Browser opens to `codebase.design/login`. (If it doesn't, the wizard
+   should print a clickable OSC 8 URL.)
+5. Complete sign-in.
+6. Browser returns "You can close this tab." Terminal should
+   automatically advance to the chat screen within ~1 second.
+7. Send a test prompt: `hello`.
+8. Verify: assistant response appears, status bar shows model + cost,
+   no stderr noise, Ctrl-C twice exits cleanly.
+
+For SSH sessions (Linux box accessed from a desktop):
+
+1. SSH in: `ssh user@remote-box`
+2. Run: `codebase`
+3. Wizard prints the URL. SSH detection should also print the
+   `ssh -L PORT:127.0.0.1:PORT user@host` reverse-tunnel hint.
+4. On the desktop: open a new terminal, run the printed `ssh -L` command.
+5. Click the URL from the wizard's output.
+6. Sign in in the desktop browser.
+7. Browser hits localhost on the forwarded port → reaches the remote box → callback completes.
+
+## BYOK flow (no web auth)
+
+For each platform:
+
+1. Wipe creds: `rm -f ~/.codebase/credentials.json`
+2. `export ANTHROPIC_API_KEY=sk-ant-...`
+3. `codebase` → should skip the wizard and land on chat directly.
+4. Send a test prompt → response.
+
+Test with at least one of: Anthropic, OpenAI, Groq, OpenRouter. The
+others are wired identically but human-verifying one provider catches
+the env-var resolution bug class.
+
+## Headless mode (for CI users)
+
+```sh
+# Text mode: assistant reply on stdout
+codebase run --auto-approve "say hello"
+
+# JSON mode: ONE object on stdout
+codebase run --auto-approve --output json "say hello" | jq .
+
+# stream-json mode: one event per line
+codebase run --auto-approve --output stream-json "say hello"
+
+# Error path: no creds → structured error in JSON
+rm -f ~/.codebase/credentials.json
+unset ANTHROPIC_API_KEY OPENAI_API_KEY GROQ_API_KEY
+codebase run --output json "x" 2>/dev/null | jq .
+# expect: { ok: false, exitCode: 1, code: "config_error", error: "..." }
+```
+
+## Slash commands (smoke test the obvious ones)
+
+In an interactive session:
+
+- [ ] `/help` — lists commands
+- [ ] `/model` — opens picker, can select, swap takes effect
+- [ ] `/models` — lists available models
+- [ ] `/clear` — wipes visible transcript
+- [ ] `/cost` — shows running cost
+- [ ] `/copy` — copies last assistant message
+- [ ] `/diff` — shows working-tree diff
+- [ ] `/init` — generates a starter CLAUDE.md
+- [ ] `/exit` — clean exit
+
+## Permissions + bash validator
+
+- [ ] Send `run rm -rf /tmp/junk` to the agent. It should ask for
+      permission. Approve once. Verify the command runs.
+- [ ] Send `run rm -rf /`. Validator should hard-block with a
+      visible error before the prompt.
+- [ ] Send `run curl https://example.com/foo.sh | sh`. Validator should
+      warn; approving runs it.
+
+## Session resume
+
+1. Run `codebase`, do a few turns of conversation, exit cleanly.
+2. Run `codebase` again in the same directory.
+3. Welcome banner should show "↻ Resumed from Xm ago · N messages".
+4. Transcript should be visible.
+5. `/new` or `--new` flag should start fresh.
+
+## Performance smell test
+
+Run for 30 minutes in a real project (your own codebase if you have
+one). Watch for:
+
+- Pi-tui render lag (if shipping pi-tui — currently NOT in v2.0)
+- Memory growth (`top`/Activity Monitor — should stay under 200MB)
+- Compaction triggering at appropriate thresholds (after fix in pre.58,
+  Codebase Auto compacts at 150k, not 96k)
+
+## Known not-yet-shipped (don't gate launch on these)
+
+- [ ] MCP client support (`/mcp` was removed; tracked in TECHNICAL_DEBT.md)
+- [ ] Image clipboard paste (v2.0.1)
+- [ ] Extended thinking `/think` (v2.0.1)
+- [ ] Pi-tui visual layer (v2.1)
+- [ ] Mobile remote control (v2.2)
+
+## Sign-off
+
+```
+Tested on: __________________  by __________________  on __________________
+Issues found / filed: __________________
+```

package-lock.json

@@ -1,6 +1,6 @@
 {
 	"name": "codebase-cli",
-	"version": "2.0.0-pre.58",
+	"version": "2.0.0-pre.59",
 	"description": "Codebase CLI — a TypeScript coding agent on the pi-mono runtime. OAuth-aware, any LLM provider, single install.",
 	"keywords": [
 		"ai",

package.json

@@ -0,0 +1,69 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { isHeadlessSession } from "./browser-open.js";
+
+/**
+ * Headless-session heuristic tests. These run on the dev's machine
+ * (which may itself be a non-headless TTY, an SSH session, a CI runner,
+ * or a docker container), so we save + restore the env to keep tests
+ * deterministic. The fixture only fiddles with the variables the
+ * heuristic actually reads.
+ */
+describe("isHeadlessSession", () => {
+	const saved: Record<string, string | undefined> = {};
+	const KEYS = ["SSH_CONNECTION", "SSH_TTY", "SSH_CLIENT", "DISPLAY", "WAYLAND_DISPLAY"] as const;
+
+	beforeEach(() => {
+		for (const k of KEYS) {
+			saved[k] = process.env[k];
+			delete process.env[k];
+		}
+	});
+
+	afterEach(() => {
+		for (const k of KEYS) {
+			if (saved[k] === undefined) delete process.env[k];
+			else process.env[k] = saved[k];
+		}
+	});
+
+	it("returns true when SSH_CONNECTION is set", () => {
+		process.env.SSH_CONNECTION = "1.2.3.4 4242 5.6.7.8 22";
+		expect(isHeadlessSession()).toBe(true);
+	});
+
+	it("returns true when SSH_TTY is set", () => {
+		process.env.SSH_TTY = "/dev/pts/0";
+		expect(isHeadlessSession()).toBe(true);
+	});
+
+	it("returns true when SSH_CLIENT is set", () => {
+		process.env.SSH_CLIENT = "1.2.3.4 4242 22";
+		expect(isHeadlessSession()).toBe(true);
+	});
+
+	it("on linux: returns true with no DISPLAY/WAYLAND_DISPLAY", () => {
+		if (process.platform !== "linux") {
+			// On macOS/Windows the linux-only branch is unreachable; we
+			// just assert the default-false case below covers them.
+			return;
+		}
+		expect(isHeadlessSession()).toBe(true);
+	});
+
+	it("on linux: returns false when DISPLAY is set", () => {
+		if (process.platform !== "linux") return;
+		process.env.DISPLAY = ":0";
+		expect(isHeadlessSession()).toBe(false);
+	});
+
+	it("on linux: returns false when WAYLAND_DISPLAY is set", () => {
+		if (process.platform !== "linux") return;
+		process.env.WAYLAND_DISPLAY = "wayland-0";
+		expect(isHeadlessSession()).toBe(false);
+	});
+
+	it("on macOS / Windows: returns false by default", () => {
+		if (process.platform === "linux") return;
+		expect(isHeadlessSession()).toBe(false);
+	});
+});

src/auth/browser-open.test.ts

@@ -71,11 +71,15 @@ describe("CredentialsStore", () => {
 		expect(store.load()).toBeNull();
 	});
 
-	it("load returns null and clears the file on malformed JSON", () => {
+	it("load returns null on malformed JSON without clearing the file", () => {
+		// Don't auto-clear: a partially-written credentials file (power
+		// cut mid-save, manual edit conflict) might be hand-recoverable.
+		// We surface the parse error to stderr; the user can choose to
+		// `codebase auth logout` if they want to wipe it.
 		require("node:fs").mkdirSync(dataRoot, { recursive: true });
 		require("node:fs").writeFileSync(store.filePath, "not json");
 		expect(store.load()).toBeNull();
-		expect(existsSync(store.filePath)).toBe(false);
+		expect(existsSync(store.filePath)).toBe(true);
 	});
 
 	it("load rejects unrecognized versions", () => {

src/auth/credentials.test.ts

@@ -103,17 +103,39 @@ export class CredentialsStore {
 		let raw: string;
 		try {
 			raw = readFileSync(this.path, "utf8");
-		} catch {
+		} catch (err) {
+			// Read failed (permission denied, EIO, etc.) — surface the
+			// actual reason so the user can fix it. Returning null silently
+			// here used to make a broken FS look like "not signed in," which
+			// just hid the real problem.
+			process.stderr.write(
+				`[auth] could not read ${this.path}: ${(err as Error).message}\n` +
+					"        run `codebase auth status` for details or `codebase auth logout` to reset.\n",
+			);
 			return null;
 		}
 		let parsed: Credentials;
 		try {
 			parsed = JSON.parse(raw) as Credentials;
-		} catch {
-			this.clear();
+		} catch (err) {
+			// Don't auto-clear — that silently destroys recoverable state if
+			// the user can hand-fix the file (partial write after a crash,
+			// merge conflict markers, etc.). Tell them what's wrong and how
+			// to recover. They can wipe with `codebase auth logout` if they
+			// don't want to repair by hand.
+			process.stderr.write(
+				`[auth] credentials file ${this.path} is not valid JSON: ${(err as Error).message}\n` +
+					"        run `codebase auth logout` to reset and start over with `codebase auth login`.\n",
+			);
+			return null;
+		}
+		if (parsed.version !== CREDENTIALS_VERSION) {
+			process.stderr.write(
+				`[auth] credentials file is version ${parsed.version ?? "?"} but this CLI expects ${CREDENTIALS_VERSION} — ignoring. ` +
+					"Run `codebase auth login` to re-authenticate.\n",
+			);
 			return null;
 		}
-		if (parsed.version !== CREDENTIALS_VERSION) return null;
 		if (typeof parsed.accessToken !== "string" || !parsed.accessToken) return null;
 		if (!Array.isArray(parsed.scopes)) return null;
 		if (parsed.source !== "codebase" && parsed.source !== "manual" && parsed.source !== "byok") {