Skip to content

[codex] Guard dev session schemas against silent drift #431

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Cheggin merged 2 commits into from
May 13, 2026
Merged

[codex] Guard dev session schemas against silent drift #431

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
002e37c
Guard and copy dev session schemas per worktree
Cheggin May 13, 2026
d1266fd
Merge branch 'main' into codex/session-schema-identity-guard
Cheggin May 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .github/workflows/ci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,10 @@ jobs:
working-directory: app
run: yarn install --frozen-lockfile

- name: Check SessionDb schema manifest
working-directory: app
run: yarn db:schema:check

- name: Run vitest with coverage
working-directory: app
run: yarn test:coverage
Expand Down
33 changes: 33 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# Browser Use Desktop Agent Notes

## Local Dev Profiles

- The app's runtime database lives under Electron `userData`, not under the git
worktree. Do not assume the default profile when working across branches.
- Use `task worktree:profile:path` to get this branch's isolated profile path.
It resolves to `.task/user-data/<current-branch>` by default.
- Use `task worktree:up` to start the app against that isolated profile.
- Use `task worktree:profile:clean FORCE=1` to delete this branch's isolated
profile after quitting the app.
- Use `task db:worktree:copy FROM=default` to copy `sessions.db` from the
platform default profile into this branch profile. Pass `FROM=branch:<name>`
to copy from another branch profile, including branch names with `/`. Use an
absolute path, `./relative/path`, `~/path`, or `FROM=path:<path>` for explicit
filesystem paths. Pass `FORCE=1` if the target DB already exists.
- Use `task db:worktree:doctor` after copying or when local task runs fail. It
compares the target `sessions.db` schema version and schema ID against the
current checkout's `src/main/sessions/schema-manifest.json`.
- If the app was launched with `AGB_USER_DATA_DIR`, run `task agent:run` with
the same `AGB_USER_DATA_DIR`. The local task runner reads
`<userData>/local-task-server.json`; pointing the CLI at a different profile
will miss the running app even if `sessions.db` is valid.
- Quit the app before copying or cleaning profile files. SQLite WAL files and
Electron runtime files can be open while the app is running.

## Session Schema Changes

- `DB_SCHEMA_VERSION` gates migrations at runtime.
- `src/main/sessions/schema-manifest.json` tracks the expected fresh schema ID
for CI/main drift detection.
- Run `task db:schema:check` after touching `SessionDb` migrations.
- Run `task db:schema:update` only after an intentional schema change.
71 changes: 71 additions & 0 deletions Taskfile.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,65 @@ tasks:
cmds:
- npm run start:reset-sessions

worktree:profile:path:
desc: Print this branch's isolated local userData path
silent: true
cmds:
- |
NAME="{{default "" .NAME}}"
if [ -n "$NAME" ]; then
node app/scripts/dev-profile.mjs path --name "$NAME"
else
node app/scripts/dev-profile.mjs path
fi

worktree:up:
desc: Start the app using this branch's isolated local userData profile
cmds:
- |
NAME="{{default "" .NAME}}"
if [ -n "$NAME" ]; then
PROFILE="$(node app/scripts/dev-profile.mjs path --name "$NAME")"
else
PROFILE="$(node app/scripts/dev-profile.mjs path)"
fi
AGB_USER_DATA_DIR="$PROFILE" task up

worktree:profile:clean:
desc: Delete this branch's isolated local userData profile; requires FORCE=1
silent: true
cmds:
- |
TARGET="{{default "" .TARGET}}"
FORCE="{{default "" .FORCE}}"
ALLOW_RUNNING="{{default "" .ALLOW_RUNNING}}"
TARGET="$TARGET" FORCE="$FORCE" ALLOW_RUNNING="$ALLOW_RUNNING" node app/scripts/dev-profile.mjs clean

db:worktree:copy:
desc: Copy sessions.db from FROM profile into this branch profile, then check schema
silent: true
cmds:
- |
FROM="{{default "default" .FROM}}"
TO="{{default "" .TO}}"
FORCE="{{default "" .FORCE}}"
ALLOW_RUNNING="{{default "" .ALLOW_RUNNING}}"
DB_ONLY=1 FROM="$FROM" TO="$TO" FORCE="$FORCE" ALLOW_RUNNING="$ALLOW_RUNNING" node app/scripts/dev-profile.mjs copy

db:worktree:doctor:
desc: Diagnose this branch profile's sessions.db schema against the checkout
silent: true
cmds:
- |
TARGET="{{default "" .TARGET}}"
JSON="{{default "" .JSON}}"
ALLOW_RUNNING="{{default "" .ALLOW_RUNNING}}"
if [ "$JSON" = "1" ]; then
JSON=1 TARGET="$TARGET" ALLOW_RUNNING="$ALLOW_RUNNING" node app/scripts/dev-profile.mjs doctor
else
TARGET="$TARGET" ALLOW_RUNNING="$ALLOW_RUNNING" node app/scripts/dev-profile.mjs doctor
fi

windows:node:check:
desc: "Windows: verify local development is using Node 20.x or 22.x"
platforms: [windows]
Expand Down Expand Up @@ -369,6 +428,18 @@ tasks:
cmds:
- npm run typecheck

db:schema:check:
desc: Verify the tracked SessionDb schema identity manifest
dir: "{{.APP_DIR}}"
cmds:
- npm run db:schema:check

db:schema:update:
desc: Regenerate the tracked SessionDb schema identity manifest
dir: "{{.APP_DIR}}"
cmds:
- npm run db:schema:update

logs:all:
desc: Tail all local app logs with colored human-readable formatting
silent: true
Expand Down
25 changes: 25 additions & 0 deletions app/docs/AGENT_LOCAL_RUNBOOK.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,11 @@ inspect task state, or debug app-spawned agent sessions.
## Local Commands

- Start the app from the repo root: `task up`
- Start against this branch's isolated profile: `task worktree:up`
- Print this branch's profile path: `task worktree:profile:path`
- Clean this branch's isolated profile: `task worktree:profile:clean FORCE=1`
- Copy `sessions.db` into this branch profile: `task db:worktree:copy FROM=default`
- Diagnose the copied DB schema: `task db:worktree:doctor`
- Start with a clean Vite cache: `task up:clean`
- Submit a task to a running app: `task agent:run PROMPT="open example.com and report the title" ENGINE=codex`
- Run checks: `task lint`, `task typecheck`, `cd app && npm run test`
Expand All @@ -21,6 +26,22 @@ AGB_USER_DATA_DIR="$(mktemp -d)" task up
`--user-data-dir=<path>` overrides `AGB_USER_DATA_DIR`. The app logs the
resolved user data path and CDP port in `main.startup`.

For branch/worktree-local development, prefer the repo-owned profile path:

```bash
task db:worktree:copy FROM=default
task worktree:up
AGB_USER_DATA_DIR="$(task worktree:profile:path)" task agent:run \
PROMPT="open example.com and report the title" ENGINE=codex
```

`task db:worktree:copy` copies only `sessions.db` plus WAL/SHM companions into
the current branch profile, then runs the schema doctor. Use `FROM=branch:<name>`
to copy from another branch profile, including branch names with `/`. Use an
absolute path, `./relative/path`, `~/path`, or `FROM=path:<path>` for explicit
filesystem paths. Quit the app before copying; pass `FORCE=1` only when
replacing an existing target DB is intentional.

## Runtime State

Default Electron `userData` locations:
Expand All @@ -33,6 +54,10 @@ Important files under `userData`:

- `sessions.db` - SQLite session store. Main tables are `sessions`,
`session_events`, and `session_attachments`.
- Session schema changes are guarded by `DB_SCHEMA_VERSION` plus
`src/main/sessions/schema-manifest.json`. Run `task db:schema:check` after
intentional session schema edits, and `task db:schema:update` when a migration
intentionally changes the fresh database schema.
- `sessions.db-wal` / `sessions.db-shm` - WAL files. Do not delete or edit
them while the app is running.
- `logs/` - JSONL logs. Core channels are `main.log`, `browser.log`,
Expand Down
3 changes: 3 additions & 0 deletions app/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,9 @@
"visual:qa": "npm run visual:capture && npm run visual:diff",
"qa:review": "open tests/visual/review.html",
"qa": "npm run lint && npm run typecheck && npm run test",
"db:schema:check": "ts-node --project tsconfig.json --compiler-options '{\"module\":\"CommonJS\"}' scripts/session-schema-manifest.ts --check && vitest run tests/unit/sessions/SessionDb.schemaIdentity.test.ts",
Copy link
Copy Markdown

@cubic-dev-ai cubic-dev-ai Bot May 13, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: The new db:schema:* scripts use single-quoted --compiler-options JSON, which is not cross-shell safe and can fail on Windows npm runs. Use escaped double quotes so ts-node receives valid JSON on all platforms.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At app/package.json, line 52:

<comment>The new `db:schema:*` scripts use single-quoted `--compiler-options` JSON, which is not cross-shell safe and can fail on Windows npm runs. Use escaped double quotes so ts-node receives valid JSON on all platforms.</comment>

<file context>
@@ -49,6 +49,8 @@
     "visual:qa": "npm run visual:capture && npm run visual:diff",
     "qa:review": "open tests/visual/review.html",
     "qa": "npm run lint && npm run typecheck && npm run test",
+    "db:schema:check": "ts-node --project tsconfig.json --compiler-options '{\"module\":\"CommonJS\"}' scripts/session-schema-manifest.ts --check && vitest run tests/unit/sessions/SessionDb.schemaIdentity.test.ts",
+    "db:schema:update": "ts-node --project tsconfig.json --compiler-options '{\"module\":\"CommonJS\"}' scripts/session-schema-manifest.ts --write",
     "start:reset-onboarding": "node scripts/reset-onboarding.mjs",
</file context>
Fix with Cubic

"db:schema:update": "ts-node --project tsconfig.json --compiler-options '{\"module\":\"CommonJS\"}' scripts/session-schema-manifest.ts --write",
"dev:profile": "node scripts/dev-profile.mjs",
"start:reset-onboarding": "node scripts/reset-onboarding.mjs",
"start:reset-sessions": "node scripts/reset-sessions.mjs",
"sync-domain-skills": "node scripts/sync-domain-skills.mjs",
Expand Down
Loading
Loading