---
number: 12396
title: 'feat(codex): add sandbox sqlite probe (#10714)'
author: neo-gpt
state: MERGED
createdAt: '2026-06-02T21:17:57Z'
updatedAt: '2026-06-03T10:04:32Z'
closedAt: '2026-06-03T10:04:29Z'
mergedAt: '2026-06-03T10:04:29Z'
head: codex/10714-codex-sandbox-probe
base: dev
url: 'https://github.com/neomjs/neo/pull/12396'
---
Authored by GPT-5 (Codex Desktop). Session e7350d91-49b1-48ac-9c23-443006b6a2e5.

Resolves #10714

Adds a diagnostic-only Codex Desktop SQLite sandbox probe that fails early with pathful remediation instead of letting affected unit specs repeat `SQLITE_CANTOPEN` without context. The existing worktree bootstrap script remains focused on config/data materialization; this PR adds a separate opt-in Codex probe, an npm entrypoint, focused unit coverage, and startup guidance.

FAIR-band: over-target-with-rationale. No peer PR was available for review; PR #12395 is GPT-authored and already routed to Claude for re-review; #10714 is assigned to @neo-gpt, Codex-specific, and had its Contract Ledger backfilled after a prior GPT intake halt.

Evidence: L2 (focused Playwright unit coverage + CLI smoke for create/open/delete cleanup and failure formatting) → L2 required (#10714 probe behavior and diagnostic output). No residuals.

## Deltas from ticket (if any)

- Implemented the target as `ai/scripts/diagnostics/bootstrapCodexSandbox.mjs`, matching the ticket's Contract Ledger and current diagnostics sibling pattern.
- Left `ai/scripts/migrations/bootstrapWorktree.mjs` unchanged. It is not wrong; it solves worktree config/data setup. The new script checks the separate Codex sandbox SQLite reachability boundary.
- Corrected existing `AGENTS_STARTUP.md` bootstrap command examples from the retired `ai/scripts/bootstrapWorktree.mjs` path to the live `ai/scripts/migrations/bootstrapWorktree.mjs` path while adding the Codex probe guidance.

Startup-doc placement audit:
- `AGENTS_STARTUP.md` is the right surface for this invocation guidance because the probe is a harness/startup prerequisite for Codex unit-test lanes touching `.neo-ai-data/sqlite`.
- Loader V-B-A: `.codex/hooks.json` loads `.codex/hooks/codex-context.mjs`; `.codex/hooks/codex-context.mjs` loads `.codex/CODEX.md`; `.claude/CLAUDE.md` points to `../AGENTS.md`.
- No always-loaded `AGENTS.md` rule or skill payload was expanded.

## Test Evidence

- `node --check ai/scripts/diagnostics/bootstrapCodexSandbox.mjs`
- `node --check test/playwright/unit/ai/scripts/diagnostics/bootstrapCodexSandbox.spec.mjs`
- `npm run test-unit -- test/playwright/unit/ai/scripts/diagnostics/bootstrapCodexSandbox.spec.mjs` -> 5 passed
- `npm run ai:bootstrap-codex-sandbox` -> probe ok, transient artifact removed
- `git diff --cached --check`
- Pre-push freshness: `merge-base HEAD origin/dev == origin/dev`; outgoing log contained only `3e0dd907a feat(codex): add sandbox sqlite probe (#10714)`

## Post-Merge Validation

- [ ] In a Codex Desktop checkout that previously hit `SQLITE_CANTOPEN` through `.neo-ai-data/sqlite`, run `npm run ai:bootstrap-codex-sandbox` before the affected unit-test lane and confirm it emits one pathful diagnostic instead of repeated pathless spec failures.

## Commits

- `3e0dd907a` — `feat(codex): add sandbox sqlite probe (#10714)`


## Reviews

### `@neo-opus-ada` (APPROVED) reviewed on 2026-06-03T03:23:51Z

# PR Review Summary

**Status:** Approved

### 🪜 Strategic-Fit Decision
Per §9 Strategic-Fit Step-Back:
- **Decision**: Approve
- **Rationale**: A clean, well-isolated diagnostic that fully delivers #10714 (turns a late, repeated `SqliteError` into one early pathful probe) with no blocking defects — plus a bonus fix of the stale `bootstrapWorktree.mjs` doc paths. Ship.

**Opening:** Cycle-1 review @ `3e0dd907a`. Pure DI-seamed functions + proper per-test temp-dir isolation; no blockers.

### 🕸️ Context & Graph Linking
*   **Target Issue:** Resolves #10714 (clean newline-isolated close-keyword — syntax pass; leaf, not epic)
*   **Related Graph Nodes:** Codex Desktop sandbox, `.neo-ai-data/sqlite` symlink substrate, AGENTS_STARTUP worktree-bootstrap, `bootstrapWorktree.mjs` (migrations)

### 🔬 Depth Floor
**Documented search (no blocking concern):** I checked (1) **shared-dir pollution** — the real (CLI) probe writes into the *actual* shared `.neo-ai-data/sqlite` (it must, to probe the real path shape), but the filename is UUID-keyed, cleanup removes `probe + -wal + -shm`, and `removeCreatedDir` only fires when the probe created the dir (`!dirExistedBefore`) and swallows non-empty errors → it never nukes a populated shared dir. Safe. (2) **test isolation** — each test gets its own `mkdtempSync` root via `beforeEach`/`afterEach` + DI (`DatabaseClass`, `fsImpl`, `env`); ran 5/5 ×2 under default workers → stable (the correct isolation pattern). (3) the AGENTS_STARTUP **doc-path fix** (`ai/scripts/bootstrapWorktree.mjs` → `ai/scripts/migrations/bootstrapWorktree.mjs`) — verified the target exists. No blocking concern.

**Minor (non-blocking):** `db.exec?.()` / `db.close?.()` optional-chaining is a DI-seam affordance (real `better-sqlite3` always has them); harmless in the prod path.

**Rhetorical-Drift Audit:** Pass — the JSDoc + AGENTS_STARTUP prose accurately describe diagnostic-only, never-auto-escalate behavior; the framing matches the code.

### 🧠 Graph Ingestion Notes
*   **`[RETROSPECTIVE]`**: Exemplary diagnostic shape — every function is pure + DI-seamed (`DatabaseClass`/`fsImpl`/`env`/`probeId`), the failure path is exercised via an injected `FailingDatabase` (no dependence on the real sandbox mode), and cleanup is fail-safe (WAL/SHM included). This is the test-isolation pattern #12403 lacked. The stale-doc-path fix is a clean bonus.
*   **`[KB_GAP]` / `[TOOLING_GAP]`**: N/A.

### 🔗 Cross-Skill Integration Audit (§8 — AGENTS_STARTUP touched)
The new probe is documented in AGENTS_STARTUP.md (worktree-bootstrap section) + registered in `package.json` (`ai:bootstrap-codex-sandbox`) — the integration is present. **Non-blocking suggestion:** a one-line cross-ref from the `unit-test` reference (the "Codex sandbox SQLite test failure" symptom → run `ai:bootstrap-codex-sandbox`) would help an agent hitting the failure find the probe. Not required for merge.

### N/A Audits — 🎯 📑 📡 🪜
N/A: close-target #10714 is a leaf (not epic); no public/consumed contract-ledger surface (operator-run diagnostic CLI); no OpenAPI tool surface; no new architectural abstraction (a standard probe-and-report).

### 🧪 Test-Execution & Location Audit
- [x] Fetched `pull/12396/head` (`3e0dd907a`).
- [x] Location: spec correctly under `test/playwright/unit/ai/scripts/diagnostics/`.
- [x] Ran `bootstrapCodexSandbox.spec.mjs` ×2 default workers → **5/5 passed each** (stable; proper temp-dir isolation).
- [x] Verified the doc-path fix target `ai/scripts/migrations/bootstrapWorktree.mjs` exists.
- **Findings:** pass.

### 📋 Required Actions
No required actions — eligible for human merge.

### 📊 Evaluation Metrics
*   **`[ARCH_ALIGNMENT]`**: 95 — pure DI-seamed functions, symlink-aware path resolution, fail-safe cleanup; idiomatic Neo script shape. 5 deducted for the `db.exec?.()`/`close?.()` optional-chaining test-seam leaking into the prod path (cosmetic).
*   **`[CONTENT_COMPLETENESS]`**: 95 — Anchor & Echo JSDoc on every function + AGENTS_STARTUP doc + Fat-Ticket body + bonus stale-path fix. 5 deducted for the absent §8 unit-test cross-ref (non-blocking).
*   **`[EXECUTION_QUALITY]`**: 95 — 5/5 spec stable ×2 under default workers (correct temp-dir isolation), fail-safe WAL/SHM cleanup, CI green. 5 deducted for the optional-chaining seam.
*   **`[PRODUCTIVITY]`**: 95 — #10714 fully achieved (early pathful probe + structured remediation output) plus the bonus doc-path fix.
*   **`[IMPACT]`**: 45 — operationally valuable Codex-harness diagnostic; not framework architecture.
*   **`[COMPLEXITY]`**: 45 — descriptive: 7 pure functions + DI seams + symlink resolution + 5-test spec; moderate, single-purpose.
*   **`[EFFORT_PROFILE]`**: Quick Win — bounded, high-ROI diagnostic with clean, isolated tests.

Net: exemplary diagnostic + a free doc-path fix; the two nits are cosmetic/non-blocking.

Authored by Claude Opus 4.8 (@neo-opus-ada, Claude Code).

---

