Queue worktree intents before spawning terminals

[srid]

Queued worktrees can now hold intent before they become terminals, and live terminals can carry editable intent without losing their terminal title. The workflow stays terminal-first: users queue repoPath + optional worktreeName + intent, then decide at spawn time whether the worktree opens as a plain shell or with a recent agent CLI.

The refinement from #828 is now explicit in the UI. Intent is multiline markdown: the first line becomes an attached top-border pill on terminal tiles and workspace cards, while the full rendered markdown appears in the workspace switcher with copy/edit controls. Empty terminals get a titlebar pencil affordance, so creating or editing intent is available from the terminal chrome, command palette, queued cards, and live workspace cards.

How it fits together

Queue worktree -> persisted queuedWorktrees conf cell
               -> workspace switcher / command palette
               -> create worktree terminal with initial.intent
               -> live terminal metadata + saved session

Terminal intent rides with the saved terminal metadata and restores through session restore. Queued worktrees are restored from their own persisted queuedWorktrees conf cell, so backlog items survive app restart even before they become terminals.

Notable details

• Intent surfaces are shared across terminal title bars and workspace switcher cards, so compact first-line pills and full markdown blocks stay visually consistent.
• Markdown is parsed with marked and rendered as Solid nodes, avoiding raw HTML injection while still supporting links, lists, code, tables, and emphasis.
• Queued worktree lifecycle is client-owned in useQueuedWorktrees, so command palette and workspace switcher use the same queue mutation rules.
• Worktree names use the shared schema before being persisted, and the agent command remains a start-time choice rather than queued state.
• Reviewer feedback landed in the implementation: editor state is one session object, child copy/edit controls no longer trigger card selection, and the UX now includes a live markdown preview.

Refs #828.

Verification

• just fmt
• just check (passes; existing Biome warnings remain outside this diff)
• nix develop --accept-flake-config -c pnpm --filter kolu-client test:unit -- src/canvas/workspace-switcher/model.test.ts
• nix develop --accept-flake-config -c pnpm --filter kolu-server test:unit -- src/session.test.ts src/state.test.ts
• nix build --accept-flake-config
• just test-quick features/workspace-switcher.feature:67
• just test-quick features/workspace-switcher.feature
• just ci on 9e5fd73e, plus explicit status cross-check: no missing contexts and no non-success ci/* statuses

Try it locally

nix run github:juspay/kolu/feat/queued-worktree-intent

Generated by /do on Codex (model gpt-5).

[srid]

Hickey/Lowy Analysis

#	Lens	Finding	Disposition
1	Hickey	Workspace switcher queued/live item search was split across parallel concepts	Fixed in this PR
2	Hickey	Queued worktree lifecycle was spread across command palette, app wiring, and switcher callbacks	Fixed in this PR
3	Hickey	Queued worktree worktreeName was half-modeled as an optional plain string	Fixed in this PR
4	Lowy	Initial terminal metadata changes would ripple through each creation path	Fixed in this PR
5	Lowy	Queue lifecycle volatility leaked into presentation components	Fixed in this PR

Hickey rationale

The first pass caught places where the same concept was being represented in separate shapes depending on where it appeared. The workspace switcher now builds a unified item list for search/facets and projects live terminals and queued worktrees back into their rendering lanes, instead of making the search model learn two partially duplicated worlds.

Queue mutation also moved behind useQueuedWorktrees, leaving the command palette and workspace switcher to express user intent rather than persistence and start/remove mechanics. The queued worktreeName now uses the shared WorktreeNameSchema, so persisted queued state does not accept a looser form than the live worktree path.

Lowy rationale

The volatile part of terminal creation is the initial metadata envelope, not each caller's argument list. InitialTerminalMetadata and initialMetadataFromSavedTerminal keep session restore, normal terminal creation, and worktree creation on one metadata contract as future terminal metadata grows.

Queued worktree behavior is likely to evolve independently from presentation, so the final shape keeps lifecycle rules in a small client-side owner and lets UI surfaces consume that owner through simple start/remove/enqueue operations.

[srid]

Evidence

Captured the workspace switcher showing the queued worktree intent.

[srid]

/do results

Step	Status	Duration	Verification
sync	✓	1s	git fetch ok; forge=github; noGit=false
research	✓	4m 39s	mapped persisted intent, queued worktree surface cell, spawn-time agent selection, UI display, and test coverage
branch	✓	4s	created feat/queued-worktree-intent from origin/master
implement	✓	5m 20s	implemented persisted terminal intent, queuedWorktrees surface cell, palette queue/start flows, workspace switcher queued column, and focused unit coverage
check	✓	43s	just check passed (typecheck clean; biome reported existing warnings)
docs	✓	37s	updated README feature/architecture notes and surface inventory for queuedWorktrees and terminal intent
fmt	✓	5s	just fmt ran successfully
commit	✓	11s	committed 920237d and pushed feat/queued-worktree-intent
hickey+lowy	✓	7m 21s	hickey/lowy review completed; committed 074c4d9 centralizing initial metadata and queued worktree lifecycle
police	✓	1m 5s	code-police completed; committed 71d8785 to validate queued worktree names with WorktreeNameSchema
test	✓	3m 50s	unit tests passed; just test-quick features/workspace-switcher.feature features/worktree.feature features/worktree-agent.feature features/command-palette.feature features/session-restore.feature passed
create-pr	✓	26s	draft PR created at #858; hickey/lowy analysis posted
ci	✓	24m 22s	just ci passed on 32a354b; explicit status cross-check found no missing or non-success ci/* contexts
evidence	✓	1m 12s	posted ## Evidence comment with queued-worktree intent screenshot: #858 (comment)
Total		53m 11s

Slowest step: ci (24m 22s)

Optimization suggestions

• CI dominated the run. For follow-up-only fixes on this PR, start from the CI entry point instead of repeating the full workflow.
• Full CI exposed timing flakes in Code tab rendering and agent mock detection; when touching UI/e2e surfaces, run the focused slices before the matrix: features/code-tab.feature, features/codex.feature, and features/opencode.feature.
• Hickey/Lowy took 7m 21s because the first pass found real lifecycle/boundary issues. Future task briefs should name whether queued work is terminal-owned or backlog-owned up front; that reduces structural churn.

Workflow completed at 2026-05-09T23:41:44Z.