feat(config): per-project .fujimoto.yaml worktree setup

[jongracecox]

Summary

Adds an optional, local .fujimoto.yaml in the main clone that describes how to set up a new worktree: files to copy, files to link, and init commands to run when a session launches. Closes the gap where untracked local files (e.g. .env) and per-worktree setup weren't carried into fresh worktrees (#35).

What's included

• Config schema (project_config.py), validated with pydantic:
  • copy: — copy files into the worktree (glob patterns supported)
  • link: — hard link (default) or type: symbolic; hard links fall back to a copy + warning across filesystems
  • init: — shell commands run with sh -x (visible trace), {{ source_dir }} / {{ worktree_dir }} placeholders, per-command continue_on_error
  • on_error: abort | continue — what to do when a non-continue_on_error init command fails
  • Each entry has when: once | always
• When it runs — applied in the parent process before the session attaches, on every worktree connection mode (new, reconnect, resume):
  • once → only the first time the worktree is created (tracked by a .fujimoto/config_once_applied marker)
  • always → every connection
• Config location — read from the main clone (source root), not the worktree checkout, so it can be a local, uncommitted file (recommend .git/info/exclude).
• fujimoto --create-config — scaffolds a fully commented template (shipped as a package resource).
• Validation UX — a malformed .fujimoto.yaml is surfaced in a modal dialog when the TUI opens (non-blocking; you can still launch a session to fix it). Error text is rendered without markup parsing so pydantic's bracketed messages don't crash the UI.

Flow

flowchart TD
    A["Select / create worktree session in TUI"] --> B["main loop: apply config before attach"]
    B --> C{"linked worktree?"}
    C -- no --> L["launch / attach session"]
    C -- yes --> D["read .fujimoto.yaml from main clone"]
    D --> V{"config parses?"}
    V -- no --> L
    V -- yes --> E{"first creation? (no once-marker)"}
    E -- yes --> F["trigger = CREATE (once + always)"]
    E -- no --> G["trigger = LAUNCH (always only)"]
    F --> H["apply copy / link / init"]
    G --> H
    H --> I{"init command failed?"}
    I -- no --> M["mark once-applied (if first creation)"]
    I -- yes --> P["print error + pause for keypress"]
    P --> Q{"on_error = abort?"}
    Q -- yes --> J["reopen TUI, do not launch"]
    Q -- no --> M
    M --> L
    J --> A

Loading

Supporting changes

• config.py: store_session_meta records source_root; config_once_applied / mark_config_once_applied marker helpers.
• git.py: get_main_worktree_root (derives the main clone from a linked worktree).
• Deps: pyyaml, pydantic.
• Docs: README (user guide + --create-config), CLAUDE.md (architecture, design decisions, .venv/uv gotcha), CONTRIBUTING (layout).

Tests

New tests/test_project_config.py plus additions to test_cli.py / test_config.py / test_git.py. Full suite 452 passing; project_config.py and config.py at 100% line coverage.

No database/schema changes.