openase AGENTS.md

Workspace Notes

Environment

• This workspace may not have go or gofmt on PATH. If Go validation is needed, first try the workspace-local toolchain under .tooling/go/bin/, for example PATH=$PWD/.tooling/go/bin:$PATH go test ./....
• If .tooling/go/bin is unavailable, a verified fallback toolchain is installed at $HOME/.local/go1.26.1/bin/go; prepend PATH=$HOME/.local/go1.26.1/bin:$PATH for builds, tests, and gofmt.
• The frontend toolchain may also require a newer Node than /usr/bin/node provides. If Svelte/Vite startup fails on node:util.styleText, use PATH=$HOME/.nvm/versions/node/v22.22.1/bin:$PATH for vitest, prettier, and other web/ checks.
• In embedded-postgres backed tests, creating ProjectRepo.labels or Agent.capabilities via direct Ent builders currently serializes TEXT[] as JSON-like literals and fails with pq: malformed array literal. Prefer API/service paths that already normalize array input, or avoid asserting on those fields in direct Ent setup until the repository-side array encoding is fixed.
• Fresh empty databases can currently race schema migration when openase all-in-one starts serve and orchestrate concurrently. For local validation against a brand-new DB, pre-run one migration pass first (for example by opening the DB once through internal/runtime/database.Open) before launching all-in-one.
• internal/webui/static/.keep must remain tracked on clean checkouts. CI jobs like make openapi-check compile internal/webui/ui.go without first building frontend assets, and deleting the placeholder causes go:embed all:static: no matching files found.
• Local redeploy cleanup must identify repo-local openase processes by resolved /proc/<pid>/exe, not only by argv. Older runs may survive as <repo-root>/bin/openase (deleted) and keep serving stale code on 127.0.0.1:19836 until explicitly killed.
• Tests that touch ~/.openase/... must isolate HOME per test run, preferably with t.TempDir() or a test-name-derived temp home. When parallel execution exposes cross-test contamination, fix the isolation boundary first instead of lowering concurrency to hide the problem.
• Ticket-runtime go test runs can inherit OPENASE_TICKET_ID and similar OpenASE env vars from the harness. Tests that assert missing ticket context should scrub inherited env vars explicitly instead of relying on the parent process env being empty.
• scripts/ci/backend_coverage.sh rewrites HOME to a temp directory before make check. In this workspace export OPENASE_PGTEST_SHARED_ROOT=$HOME/.cache/openase/pgtest so internal/testutil/pgtest reuses the extracted binaries instead of a cold temp-home cache that may miss the sibling postgres binary next to initdb.
• Backend CI runs on GitHub-hosted runners. Prefer OPENASE_GO_TEST_PROGRESS_MODE=json for backend CI jobs so go test emits continuous progress instead of relying on sparse wrapper heartbeats.
• web/playwright.config.ts currently hard-codes 127.0.0.1:4173 with reuseExistingServer: false. When concurrent workspaces already occupy that port, the local CI gate can fail even if the code is correct; in that case, keep the repo config unchanged and run the equivalent Playwright step with a temporary copied config on an alternate localhost port, then restore any generated internal/webui/static artifacts before committing.
• scripts/dev/test_ephemeral_chat_blackbox.py can fail against real local providers because rate limits or missing provider env vars surface before chat startup. For deterministic local validation in this workspace, prefer python3 scripts/dev/test_ephemeral_chat_blackbox.py --base-url http://127.0.0.1:19836 --provider-mode fake-codex --timeout-seconds 90.
• This workspace currently has no X11/Wayland display server and no xvfb-run helper installed. Electron GUI E2E should either run on a machine with a display (or an Xvfb-wrapped CI job) or skip explicitly when DISPLAY / WAYLAND_DISPLAY are absent.
• pnpm in this workspace can ignore install scripts by default. If Electron is installed but its binary payload is missing, run the bundled installer directly (for example node desktop/node_modules/electron/install.js) before attempting Playwright or packaging flows.
• Claude Code auth can be misleading in this environment: claude auth status may report loggedIn: true while real prompt execution still fails with 401 Invalid authentication credentials, and claude --debug-file ... -p ... shows OAuth refresh attempts returning 400 from https://platform.claude.com/v1/oauth/token. Current Claude builds also store OAuth metadata under ~/.claude/.credentials.json -> claudeAiOauth, with expiresAt as a millisecond Unix timestamp instead of the older top-level RFC3339 fields. Before treating Claude as ready here, verify with a real claude -p ... prompt, not status output alone.
• Additional Claude auth note: the current CLI also exposes CLAUDE_CODE_OAUTH_TOKEN, but exporting the stale claudeAiOauth.accessToken into that env var still fails real prompts with 401 Invalid authentication credentials, and the stored refreshToken fails with 401 Invalid bearer token. claude auth login and claude setup-token both fall back to interactive browser OAuth flows on this machine, so unattended runs still need an externally refreshed login or a valid ANTHROPIC_API_KEY.
• Further Claude auth note: this machine's saved Snap Firefox profile at ~/snap/firefox/common/.mozilla/firefox/6sfz7ccx.default/ does contain real claude.ai / claude.com / platform.claude.com cookies, but that still does not unlock unattended Claude Code auth. Raw HTTP reuse of those cookies against Claude OAuth can still hit Cloudflare 403 Just a moment..., and a real headless Firefox session with the saved cookies can get past Cloudflare but still lands on https://platform.claude.com/login?returnTo=%2F%3F with the normal Claude Platform sign-in page instead of an approval/code page. Treat that as more evidence that unattended runs here need a valid ANTHROPIC_API_KEY or a fresh human-completed platform login.
• Official Claude Code settings docs now also mention ANTHROPIC_AUTH_TOKEN, but on this machine injecting the stored claudeAiOauth.accessToken into ANTHROPIC_AUTH_TOKEN still fails real claude -p --bare ... prompts with 401 and message OAuth authentication is currently not supported. Injecting the stored refreshToken into ANTHROPIC_AUTH_TOKEN fails with 401 Invalid bearer token. So neither documented bearer-token path nor Claude's stored OAuth tokens provide an unattended escape hatch here.