[Feature] Isolated Database Environments for Worktree-Based Task Execution

[theviktor]

Problem

Git worktrees solve code isolation per task, but not database or service isolation. When an agent completes work in a worktree, there's no reliable way to verify it actually runs — because:

• The worktree can't share the main branch's database if the task involves migrations or schema changes (it would break what's running on main)
• You can't use an empty database either — local dev data (test contacts, vendor-provisioned records, S3 references, UI-configured state) can't simply be re-seeded
• So the agent says "done," but you can't validate the work without manually wiring up an isolated environment yourself

This defeats the purpose of agent-driven automation.

Proposed Solution

Use database schema isolation (e.g. Postgres schemas, or the equivalent for a given stack) as part of the worktree lifecycle:

1. Clone the current public schema (structure + data) into a new schema named after the branch
2. Point the worktree's database connection at that new schema
3. Run migrations only against the isolated schema
4. Start the app/tests on a separate port — fully isolated, with all existing dev data intact
5. On merge/cleanup, drop the schema and remove the worktree

External service references (S3 links, vendor IDs, etc.) all still work because the data is identical — just namespaced differently.

Feature Request

Add built-in lifecycle hooks to the orchestrator:

• pre-task: clone schema, configure env vars, allocate a free port
• post-task: drop schema, tear down worktree

This would make every agent-completed task actually testable in a fully isolated environment — not just "code was written to a branch."

[JVillator0]

+1 on this. Hit the same wall and want to share a more concrete shape for the pre-task half, since that's where I'm bleeding right now.

Working on a Laravel + Sail app. The thing that makes this specifically painful in Kanban (vs. a single-agent tool) is parallelism: I want to run 3-5 agents at once, each on its own task. They all share one Postgres. The moment one of them runs a migration on its branch, every other parallel agent's run is contaminated, and so is my own dev DB on main. There's no point in parallel worktrees if the database isn't parallel too.

The pattern I want to land on is one schema/database per worktree, named after the worktree, e.g. testing_${WS}. Then each agent gets a real, isolated DB with the same shape and seeded data, runs migrations freely, and the cleanup is trivial. But there's no native place in Kanban to set that up. I tried direnv (couples the contract to direnv), Claude's SessionStart hook (only works when the agent is Claude), and a manual shortcut you click after each new task (defeats the orchestrator). None feel right.

What would unblock this is one optional field in <repo>/.cline/kanban/config.json:

{
  "shortcuts": [...],
  "setupScript": "vendor/bin/sail up -d && WS=$(basename $KANBAN_WORKTREE_PATH) && vendor/bin/sail psql -U postgres -c \"CREATE DATABASE \\\"testing_${WS}\\\";\" 2>/dev/null; DB_DATABASE=testing_${WS} vendor/bin/sail artisan migrate --force"
}

A shell snippet, cwd = the new worktree, runs after prepareNewTaskWorktree and before the agent starts. A handful of env vars exposed to it: KANBAN_WORKTREE_PATH, KANBAN_REPO_ROOT, KANBAN_TASK_ID, KANBAN_TASK_TITLE, KANBAN_BASE_REF. Output streams to the task card terminal with a [setup] prefix. Non-zero exit or timeout → fail worktree creation; the existing rollback in task-worktree.ts handles teardown. If the field is absent, nothing changes.

Just v1: no post-task, no per-task overrides, no object form with timeoutMs/shell, no Windows. Those can come later. The implementation is small (one runner, one call site, schema bump on ProjectConfig), and it'd unblock the per-worktree DB case end-to-end without preempting the broader hook system you're describing.

I know CONTRIBUTING.md says feature PRs aren't being accepted right now while you focus on stability. Asking before I start on this — is something this contained worth an exception, or do you want me to wait until the freeze lifts? Either way is fine, just want to know before investing the time.

Also opened a separate, narrower Feature Request discussion just for the setupScript field, so this thread can keep its broader scope: #418