fix: fail local hatch if base data directory already exists

[dvargasfuertes]

Summary

• Checks if the .vellum base data directory already exists before starting a local hatch
• Fails early with a clear error message if the directory is taken, preventing accidental data overwrites
• Suggests setting BASE_DATA_DIR to use a different directory
• Moved baseDataDir computation earlier in hatchLocal() to enable the check before starting the daemon/gateway

Test plan

• All 35 CLI tests pass
• vellum hatch fails with clear error when ~/.vellum already exists
• vellum hatch succeeds on fresh machine with no ~/.vellum
• BASE_DATA_DIR=/tmp/alt vellum hatch works when ~/.vellum exists but /tmp/alt/.vellum doesn't

🤖 Generated with Claude Code

---

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1ac1f8f206

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Narrow base-data-dir existence check before local hatch

This check fails hatch local whenever ~/.vellum already exists, but that directory is also created by unrelated setup paths (for example vellum config set creates ~/.vellum/workspace/config.json in cli/src/commands/config.ts), so users can be blocked from hatching even when no local assistant is running. In practice, a documented pre-hatch config step now causes a hard failure, so the guard should detect active/conflicting local runtime state rather than treating any preexisting directory as an overwrite risk.

Useful? React with 👍 / 👎.

[devin-ai-integration]

Devin Review found 1 potential issue.

View 4 additional findings in Devin Review.

[devin-ai-integration]

🔴 existsSync check on baseDataDir blocks re-hatching after any failed hatch or incomplete cleanup

The new existsSync(baseDataDir) check at line 543 throws an error if ~/.vellum already exists, but this directory is routinely created by the daemon during startLocalDaemon() and is NOT removed by stopLocalProcesses(). This makes vellum hatch permanently broken after any failed hatch attempt.

Detailed failure scenarios and root cause

Scenario 1: Failed hatch recovery is impossible

If a previous hatchLocal() call succeeds at startLocalDaemon() (line 555) but fails at startGateway() (line 559), the error handler at lines 560-565 calls stopLocalProcesses(), which only removes PID and socket files (cli/src/lib/process.ts:85-89) — it does NOT remove the ~/.vellum directory. On the next vellum hatch attempt, the existsSync(baseDataDir) check at line 543 finds the leftover directory and throws, preventing recovery without manual rm -rf ~/.vellum.

Scenario 2: Contradicts stale cleanup code above

The stale process cleanup at lines 529-539 explicitly handles the case where ~/.vellum exists with PID files but no lock file entries — it cleans up stale processes and continues. But the new check at line 543 then immediately throws because the directory still exists after cleanup. The stale cleanup code becomes dead code in practice.

Scenario 3: Desktop daemon creates the directory

In desktop mode, startLocalDaemon() calls mkdirSync(vellumDir, { recursive: true }) at cli/src/lib/local.ts:181. While this happens after the check, any previous daemon run would have created the directory, and stopLocalProcesses() doesn't remove it.

Impact: vellum hatch --remote local is broken for any user who has previously attempted a local hatch that didn't complete cleanly, or whose ~/.vellum directory exists for any reason other than an active assistant. The only workaround is manual rm -rf ~/.vellum.

Prompt for agents

The existsSync check on the entire baseDataDir (~/.vellum) is too broad. This directory is used for PID files, socket files, and other runtime state that persists across hatch/retire cycles. The check should be more targeted — for example, checking for a specific sentinel file that indicates an active assistant is using the directory (e.g., a running daemon's PID file with a live process, or a specific lock/marker file), rather than checking for the directory's mere existence.

In cli/src/commands/hatch.ts, lines 543-549, replace the existsSync(baseDataDir) check with a more targeted check. Options include:
1. Check if there's an active daemon process using isProcessAlive() on the PID file inside baseDataDir
2. Check for a specific marker file that the daemon creates when actively using the directory
3. Remove the check entirely and rely on the existing stale cleanup logic at lines 529-539

The stale cleanup code at lines 529-539 already handles the case of leftover processes with no lock file entries, so the directory existence check is redundant and harmful.

---

Was this helpful? React with 👍 or 👎 to provide feedback.