Per-project setup script run on worktree creation

[JVillator0]

Splitting this off from #254, which proposes a broader pre/post-task hook system. This one is narrower: just the pre-task half, as a single optional config field. Cross-linking so the threads don't drift.

The pain

Worktrees give me code isolation but nothing else. The thing that makes this specifically painful in a parallel-agent tool is that there's no per-worktree database isolation — and that breaks the whole "run 3-5 agents at once" promise the moment any of them touches the schema.

Concrete example: Laravel + Sail repo, multiple agents running in parallel on different tasks. They all share one Postgres. As soon as one runs artisan migrate on its branch, every other agent's run is contaminated, and so is the dev DB on main. Same family of problem (different shape) for anyone who needs to copy a .env, run composer install / npm ci in the worktree, generate typed bindings per branch, or spin up a sidecar container per task. Worktree-level isolation is half-done without a place to hang the rest.

The workarounds I tried all feel wrong:

• direnv — couples the contract to direnv being installed and configured.
• A shortcut you click after each new task — needs a human, which is the whole thing we're trying to avoid in a parallel-agent setup.
• Claude SessionStart hooks — only works when the agent is Claude, and Kanban is multi-agent.

What I'd like

One optional string 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"
}

The pattern I'm going for is testing_${WS} — one Postgres database per worktree, named after the worktree. Each parallel agent gets its own isolated DB with the same shape and seeded data, runs migrations freely without stomping on anyone else, and cleanup is trivial when the worktree is torn down.

Behavior:

• Runs after prepareNewTaskWorktree (so after submodule init + ignored-paths sync) and before the agent is launched.
• cwd is the new worktree. A few env vars get injected for the script to use: KANBAN_WORKTREE_PATH, KANBAN_REPO_ROOT, KANBAN_TASK_ID, KANBAN_TASK_TITLE (sanitized), KANBAN_BASE_REF.
• Output streams to the task card terminal with a [setup] prefix so the user sees it.
• Non-zero exit or timeout (default 5 min) fails worktree creation. The existing rollback path tears the partial worktree down. Honors the same cancellation signal the rest of the flow uses.
• Field missing or empty → no behavior change at all.

What I'd leave out of v1

Everything that can be added later without breaking the field: a teardown/post-task hook (covered by #254), per-task overrides, the object form with timeoutMs/shell, Windows support (MVP would be Unix-only and gated on process.platform), and any UI for re-running setup on existing worktrees. Keeping v1 boring on purpose.

Implementation sketch

Roughly ~150 LOC plus tests:

• Schema bump on ProjectConfig in src/config/runtime-config.ts, mirroring the existing shortcuts validation.
• New src/workspace/setup-script-env.ts for the env-var builder + title sanitizer.
• New src/workspace/run-setup-script.ts that spawns the snippet, streams output, handles the timeout (SIGTERM then SIGKILL after a grace period) and cancel.
• One call site in prepareNewTaskWorktree after syncIgnoredPathsIntoWorktree.
• Tests under test/workspace/: happy path, non-zero exit, timeout kill, missing field, env-var forwarding, and the integration assertion that a failed setup leaves no worktree behind.
• README and CHANGELOG entries.

Quick check before I open a PR — is this the kind of thing you'd take during the freeze, or should I wait? Read CONTRIBUTING and didn't want to assume.