Release 0.3.0

[Wirasm]

Release 0.3.0

Env-leak gate hardening, SSE reliability fixes, isolation cleanup smarter merge detection, build/version improvements, and deploy hardening.

Added

• Env-leak gate (target repo .env keys): scan auto-loaded .env files for sensitive keys and refuse to register or spawn into a codebase whose .env would silently re-inject keys into Claude/Codex subprocesses. Fail-closed by default (bug: concurrent-run guard has TOCTOU race with pre-created pending rows #1036).
• CLI --allow-env-keys, global allow_target_repo_keys config, PATCH /api/codebases/:id, Settings → Projects per-row toggle, and startup env-leak scan for granting/revoking consent without delete-and-re-add (polish(env-leak-gate): CLI escape hatch, retroactive consent, context-aware errors, docs #973, feat(env-leak-gate): polish sweep — CLI flag, config bypass, retroactive consent (#973) #983).
• Squash-merge / PR-merge detection in isolation cleanup --merged via git cherry and gh PR state, plus --include-closed flag (bug(claude-client): hasExplicitTokens uses ?? instead of ||, causing auth fallback to miss CLAUDE_API_KEY when CLAUDE_CODE_OAUTH_TOKEN is set to empty string #1027).
• Git commit hash in archon version output (archon setup --spawn fails on Windows when repo path contains spaces #1035).

Changed

• Env-leak gate error messages are context-aware (Web add / CLI / pre-spawn) (polish(env-leak-gate): CLI escape hatch, retroactive consent, context-aware errors, docs #973, feat(env-leak-gate): polish sweep — CLI flag, config bypass, retroactive consent (#973) #983).
• SSE event buffer TTL raised 3s → 60s and capacity 50 → 500 to fix dropped tool_result events during reconnect grace; cleanup timer resets per event (fix(setup): quote repo path in --spawn terminal commands (fixes #1035) #1037).
• Binary build detection moved to a build-time BUNDLED_IS_BINARY constant; logger uses pino-pretty as a destination stream on the main thread, fixing $bunfs crash in compiled binaries (fix(build): use build-time constants for binary detection and pretty stream logger #982).
• Cloud-init deploy hardened: dedicated archon user, 2GB swapfile, 443/udp for HTTP/3, fail-fast on network errors (deploy: harden cloud-init with archon user, swap, and fixes #981).

Fixed

• Env-leak worktree path lookup falls back to findCodebaseByPathPrefix so consent is inherited (bug: concurrent-run guard has TOCTOU race with pre-created pending rows #1036).
• EnvLeakError FATAL classification checks error.name instead of message text (bug: concurrent-run guard has TOCTOU race with pre-created pending rows #1036).
• Scanner distinguishes ENOENT from EACCES so unreadable .env files surface as findings (bug: concurrent-run guard has TOCTOU race with pre-created pending rows #1036).

Security

• Default allow_env_keys is false (fail-closed). Five remediation paths documented in docs/reference/security.md (bug: concurrent-run guard has TOCTOU race with pre-created pending rows #1036, polish(env-leak-gate): CLI escape hatch, retroactive consent, context-aware errors, docs #973, feat(env-leak-gate): polish sweep — CLI flag, config bypass, retroactive consent (#973) #983).

---

Merging this PR releases 0.3.0 to main. Tagging v0.3.0 after merge triggers binary builds (5 platforms) and Homebrew formula update via .github/workflows/release.yml.

Summary by CodeRabbit

• New Features

  • Environment-leak gate: prevents sensitive environment keys from auto-loading into AI subprocesses with per-codebase consent toggles in the Web UI and --allow-env-keys CLI flag.
  • Added PATCH /api/codebases/:id endpoint to manage environment-key consent on existing codebases.
  • Isolation cleanup now supports --include-closed to remove environments associated with closed/abandoned PRs.
  • Version command displays git commit hash.

• Improvements

  • Enhanced SSE reliability with larger event buffers and extended retention windows.
  • Improved merge detection with squash-merge and GitHub PR state awareness.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

Introduces environment-leak gate hardening across the system, scanning .env files for sensitive keys during repository registration and pre-spawn, with fail-closed defaults, consent toggles (UI/CLI/config), and audit logging. Also adds multi-signal merge detection (git ancestry, patch equivalence, PR state), improves SSE reliability, updates build metadata to include git commit hash, and hardens cloud deployment infrastructure.

Changes

Cohort / File(s)	Summary
Release & Version Metadata CHANGELOG.md, package.json, packages/paths/src/bundled-build.ts, packages/paths/src/bundled-build.test.ts, scripts/build-binaries.sh	Version bumped to 0.3.0; build constants (BUNDLED_IS_BINARY, BUNDLED_VERSION, BUNDLED_GIT_COMMIT) moved from bundled-version.ts to bundled-build.ts with git commit hash now embedded and recovered at runtime.
Env-Leak Scanner Utility packages/core/src/utils/env-leak-scanner.ts, packages/core/src/utils/env-leak-scanner.test.ts	New utility module defining sensitive env keys, auto-loaded dotenv filenames, EnvLeakError class, scanPathForSensitiveKeys() for detecting leaks in .env files, and formatLeakError() with context-aware remediation text.
CLI Integration packages/cli/src/cli.ts, packages/cli/src/commands/workflow.ts, packages/cli/src/commands/isolation.ts, packages/cli/src/commands/isolation.test.ts, packages/cli/src/commands/version.ts, packages/cli/src/commands/version.test.ts, packages/cli/src/commands/bundled-version.ts	Added --allow-env-keys flag for consent during auto-registration; added --include-closed for cleanup of abandoned PRs; version command now reports git commit via getDevGitCommit(); removed bundled-version.ts.
Database Schema & Codebase Operations migrations/000_combined.sql, migrations/021_add_allow_env_keys_to_codebases.sql, packages/core/src/db/codebases.ts, packages/core/src/db/codebases.test.ts, packages/core/src/types/index.ts	Added allow_env_keys BOOLEAN NOT NULL DEFAULT FALSE column; added findCodebaseByPathPrefix() for worktree lookup fallback; added updateCodebaseAllowEnvKeys() for consent updates; extended Codebase interface.
Config Management packages/core/src/config/config-types.ts, packages/core/src/config/config-loader.ts	Extended GlobalConfig and RepoConfig with optional allow_target_repo_keys bypass; added MergedConfig.allowTargetRepoKeys; added warn-once mechanism for gate bypass logging.
Client Pre-Spawn Gates packages/core/src/clients/claude.ts, packages/core/src/clients/claude.test.ts, packages/core/src/clients/codex.ts, packages/core/src/clients/codex.test.ts	Both clients now perform pre-spawn env-leak gate: resolve codebase, check allow_env_keys, load config with fail-closed semantics, scan path for leaks, throw EnvLeakError if findings exist.
Repository Registration & Clone packages/core/src/handlers/clone.ts, packages/core/src/handlers/clone.test.ts	Extended registration to accept allowEnvKeys and context; scan before DB write with audit logging on consent grant; block registration on findings unless bypass enabled.
Merge Detection & Cleanup packages/core/src/services/cleanup-service.ts, packages/core/src/services/cleanup-service.test.ts, packages/git/src/branch.ts, packages/git/src/git.test.ts, packages/isolation/src/pr-state.ts, packages/isolation/src/pr-state.test.ts	New multi-signal safe-to-remove check: isBranchMerged + isPatchEquivalent (squash-merge) + getPrState (GitHub PR state via gh CLI); added --include-closed option; graceful degradation when gh unavailable.
Isolation Operations packages/core/src/operations/isolation-operations.ts, packages/core/src/operations/isolation-operations.test.ts	Extended cleanupMergedEnvironments() to accept options: { includeClosed?: boolean } and forward to cleanup logic.
API Routes & Validation packages/server/src/routes/api.ts, packages/server/src/routes/api.codebases.test.ts, packages/server/src/routes/schemas/codebase.schemas.ts	Added PATCH /api/codebases/{id} endpoint for consent updates with audit logging; extended POST /api/codebases to accept allowEnvKeys; added env-leak error handling (422 responses); added validation schema for update payload.
Server Startup & SSE Reliability packages/server/src/index.ts, packages/server/src/adapters/web/transport.ts, packages/server/src/adapters/web/transport.test.ts	Early config load + startup env-leak scanning with warnings; increased buffer TTL (3s → 60s) and capacity (50 → 500 events); added throttled eviction warnings; improved buffer lifecycle management and expired-event accounting.
Web UI Consent Flow packages/web/src/lib/api.ts, packages/web/src/routes/SettingsPage.tsx	Extended CodebaseResponse with allow_env_keys field; added updateCodebase() API call; added consent toggle UI (grant/revoke with confirmation); conditional checkbox for env-leak errors during add flow.
Logger & Build Constants packages/paths/src/logger.ts, packages/paths/src/index.ts, packages/paths/package.json	Switched from Pino transport/worker to pino-pretty stream destination with graceful fallback; moved pino from optional to required dependencies; re-exported build constants.
Version & Build Detection packages/workflows/src/defaults/bundled-defaults.ts, packages/workflows/src/defaults/bundled-defaults.test.ts	Changed isBinaryBuild() from checking virtual FS path prefixes to returning BUNDLED_IS_BINARY constant; removed isBunVirtualFs() helper.
Error Classification packages/workflows/src/executor-shared.ts, packages/core/src/index.ts	Added named-error check for EnvLeakError in error classifier; re-exported leak scanning utilities from core index.
Test Fixtures & Mocks packages/core/src/handlers/command-handler.test.ts, packages/core/src/orchestrator/*test.ts, packages/core/package.json, packages/isolation/package.json	Updated codebase fixtures to include allow_env_keys: false; added test for env-leak-scanner.test.ts in test scripts.
Cloud Deployment Hardening deploy/cloud-init.yml	Added dedicated archon user with docker group membership; created 2GB swapfile; copied SSH authorized keys; changed ownership to archon; updated firewall to explicitly allow 443/tcp and 443/udp; refactored ownership & execution context for Docker operations.
Documentation & CLI Reference CLAUDE.md, packages/docs-web/src/content/docs/**/*.md	Added --allow-env-keys flag documentation; documented --include-closed cleanup option; added PATCH /api/codebases/:id endpoint docs; added comprehensive env-leak gate security documentation; expanded CLI and API reference sections.

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant CLI
    participant Server
    participant CodebaseDB
    participant Scanner
    participant Claude
    participant Audit

    User->>CLI: archon workflow run --cwd /repo --allow-env-keys
    CLI->>Server: POST /register (allowEnvKeys=true, context='register-cli')
    
    Server->>CodebaseDB: lookupCodebase(/repo)
    CodebaseDB-->>Server: null (new)
    
    Server->>Scanner: scanPathForSensitiveKeys(/repo)
    Scanner-->>Server: { findings: [...] }
    
    Note over Server: allowEnvKeys=true (bypass enabled)
    Server->>Audit: log(env_leak_consent_granted, files, keys, actor=user-cli)
    Audit-->>Server: ✓
    
    Server->>CodebaseDB: createCodebase(..., allow_env_keys=true)
    CodebaseDB-->>Server: Codebase(id=1, allow_env_keys=true)
    Server-->>CLI: 200 OK
    
    User->>Claude: sendQuery(cwd=/repo)
    Claude->>CodebaseDB: findCodebaseByDefaultCwd(/repo)
    CodebaseDB-->>Claude: Codebase(allow_env_keys=true)
    
    Note over Claude: allow_env_keys=true, skip gate
    Claude->>Claude: spawn subprocess
    Claude-->>User: ✓ Success

Loading

sequenceDiagram
    participant CLI
    participant Cleanup
    participant Git
    participant GhCLI
    participant Cache
    participant WorktreeOps

    User->>CLI: archon isolation cleanup --merged --include-closed
    CLI->>Cleanup: cleanupMergedEnvironments(codebaseId, mainPath, {includeClosed:true})
    
    Cleanup->>Cleanup: list merged branches
    
    loop For each branch
        Cleanup->>Git: isBranchMerged(branch, main)
        Git-->>Cleanup: false (not ancestor)
        
        Cleanup->>Git: isPatchEquivalent(branch, main)
        Git-->>Cleanup: true (all commits marked with -)
        
        Note over Cleanup: Squash merge detected ✓
        Cleanup->>WorktreeOps: remove worktree & branch
        WorktreeOps-->>Cleanup: ✓
    end
    
    loop For each closed PR branch
        Cleanup->>Cache: getPrState(branch, cache)
        Cache->>GhCLI: gh pr list --head branch --json state
        GhCLI-->>Cache: {state: CLOSED}
        Cache-->>Cleanup: 'CLOSED'
        
        alt includeClosed=true
            Cleanup->>WorktreeOps: remove(CLOSED branch)
            WorktreeOps-->>Cleanup: ✓ removed
        else includeClosed=false
            Cleanup-->>Cleanup: skip with reason
        end
    end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~75 minutes

Possibly related issues

• #979: Directly implements the build-time constants refactor (adding packages/paths/src/bundled-build.ts, moving BUNDLED_VERSION/BUNDLED_IS_BINARY, updating isBinaryBuild() to use constants, and refactoring the pino logger setup).
• #973: Directly implements the env-leak gate feature across CLI, core, server, and web layers (allowing consent via --allow-env-keys, pre-spawn scanning, PATCH endpoint for consent updates, startup warnings, and comprehensive audit logging).

Possibly related PRs

• #981: Both PRs modify deploy/cloud-init.yml to add an archon user, swapfile configuration, SSH setup, and ownership changes for hardened cloud deployment.

Suggested reviewers

• leex279

Poem

🐰 A leap of seven hundred changes strong,
Where env keys hide and leaks belong—
Gate closed tight, consent grants way,
Merged branches pruned, debris swept away.
Git cherry-picks and PR states align,
A rabbit's work: secure and fine! 🔐✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 55.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title 'Release 0.3.0' is concise, specific, and clearly conveys the primary change—a version release that encompasses multiple improvements documented in the description.
Description check	✅ Passed	The PR description comprehensively covers Added/Changed/Fixed/Security sections, provides sufficient context, though differs from the template structure by using a narrative format that is clear and organized.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch dev

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}