Architecture

This chapter covers git-paw’s internal architecture: module structure, data flow, and key design decisions.

It describes the code as it is today. For the structure the code is moving toward — and the rules new code follows — see Target Architecture.

Module Diagram

┌───────────────────────────────────────────────────────────────────────┐
│        main.rs  (entry layer: parse, resolve, prompt, attach)         │
│       commands/  (library use cases: context + options → outcome)     │
├──────────┬──────────────┬──────────────┬─────────────┬────────────────┤
│  cli.rs  │ interactive/ │   config/    │   error.rs  │    dirs.rs     │
│  (clap)  │  (prompts,   │    (TOML)    │  (PawError) │     (XDG)      │
│          │   pickers)   │              │             │                │
├──────────┴──────────────┴──────────────┴─────────────┴────────────────┤
│                                                                       │
│  detect.rs    git.rs       session.rs   logging.rs   agents.rs        │
│  (PATH scan)  (worktrees)  (JSON state) (pane logs)  (AGENTS.md)      │
│                                                                       │
│  surface.rs                                                           │
│  (SessionLayout + SurfaceRole: the reserved-index record)             │
│                                                                       │
│  skills.rs    init.rs      replay.rs    selftest.rs  doctor.rs        │
│  (skill       (project     (log         (smoke       (preflight       │
│   templates)   bootstrap)   playback)    check)       diagnostics)    │
│                                                                       │
│  domain.rs    lock.rs      random.rs    command_runner.rs             │
│  (newtypes)   (add/remove  (UUID v4)    (process-execution seam)      │
│                lock)                                                  │
│                                                                       │
│  static_regex.rs                                                      │
│  (one audited compiler for build-time regex patterns)                 │
│                                                                       │
│  worktree_provision.rs       dashboard.rs + dashboard/                │
│  (env copies, ports, hooks)  (TUI: model, view, log panel)            │
├───────────────────────────────────────────────────────────────────────┤
│  broker/               supervisor/               specs/               │
│  ├── mod.rs            ├── mod.rs                ├── mod.rs           │
│  ├── server.rs         ├── approval_gate.rs      ├── openspec.rs      │
│  ├── messages.rs       ├── branch_refresh.rs     ├── markdown.rs      │
│  ├── delivery.rs       ├── claim.rs              ├── speckit.rs       │
│  ├── conflict.rs       ├── drive.rs              ├── superpowers.rs   │
│  ├── learnings.rs      ├── keys.rs               └── resolve.rs       │
│  ├── watcher.rs        ├── loop_binding.rs                            │
│  └── publish.rs        ├── manual_approvals.rs   opsx/                │
│                        └── permission_prompt.rs  ├── mod.rs           │
│                                                  └── role_guard.rs    │
│                                                                       │
│                                                  coordination/        │
│                                                  ├── mod.rs           │
│                                                  ├── inventory.rs     │
│                                                  └── tell.rs          │
├───────────────────────────────────────────────────────────────────────┤
│  terminal/             tmux/                 mcp/                     │
│  ├── mod.rs  (port)    ├── mod.rs            ├── mod.rs               │
│  ├── tmux.rs (adapter) ├── command.rs        ├── server.rs            │
│  ├── fake.rs           ├── layout.rs         ├── logging.rs           │
│  └── fixtures/         ├── readiness.rs      ├── query/               │
│      (argv goldens)    └── session.rs        └── tools/               │
└───────────────────────────────────────────────────────────────────────┘

Module Responsibilities

src/broker/ modules

src/dashboard.rs (top-level, not inside src/broker/) renders the dashboard pane — the live status table and the optional message-log panel — by polling the broker over HTTP (GET /status, GET /log?since=<seq>). It holds no broker state. The dashboard pane sits at pane index 0 whenever the session has one — in supervisor mode (see the layout diagram below) and in non-supervisor broker mode alike.

The dashboard is structured as Model-View-Update:

The event loop drains crossterm key presses, the per-tick status snapshot, and new broker-log entries into Msg values, routes each through update, and renders the resulting Model via the View — rather than mutating local state inline. The View re-exports keep crate::dashboard::{render_dashboard, format_agent_rows, …} resolving from the parent module.

src/supervisor/ modules

src/specs/ modules

src/mcp/ modules

The MCP subsystem follows a strict one-way dependency direction — query knows nothing about MCP, tools knows about MCP and query, and server only wires tools onto a transport — so a future HTTP transport stays additive.

src/coordination/ modules

Start Flow

The start command is the primary flow. main.rs resolves supervisor mode and dispatches it to one of three use cases in git_paw::commands: supervisor::supervisor when supervisor mode resolves on (--supervisor or --unattended, else [supervisor] enabled, else an interactive prompt when no [supervisor] section exists; --no-supervisor always wins), start::start_with_specs for a spec-driven launch (--from-all-specs / --specs) without a supervisor, and start::start otherwise. All three run the same existing-session check first, and all three return a LaunchOutcome instead of touching the terminal — main.rs attaches, reattaches or refuses, or runs the unattended drive loop from it. Here’s what start::start does step by step:

git paw start
     │
     ▼
┌─ Validate git repo ──────────────────────────────────────┐
│  git::validate_repo() → repo root path                   │
└──────────────────────────────────────────────────────────┘
     │
     ▼
┌─ Check for existing session ─────────────────────────────┐
│                                                          │
│  Active, tmux session gone?  ──yes──► Invalidate stale   │
│         │ no                           receipt, then     │
│         │                              fresh start       │
│  Paused + tmux alive?        ──yes──► Restart broker,    │
│         │ no                           reattach          │
│  Active + tmux alive?        ──yes──► Reattach           │
│         │ no                                             │
│  Stopped session?            ──yes──► Recover            │
│         │ no                                             │
│  No session                  ──────► Fresh start         │
└──────────────────────────────────────────────────────────┘
     │
     ▼ (fresh start)
┌─ Load config ────────────────────────────────────────────┐
│  config::load_config() → merged PawConfig                │
│  ([supervisor] enabled → hand off to supervisor())       │
└──────────────────────────────────────────────────────────┘
     │
     ▼
┌─ Detect CLIs ────────────────────────────────────────────┐
│  detect::detect_clis() → Vec<CliInfo>                    │
│  (auto-detected + custom, deduplicated)                  │
└──────────────────────────────────────────────────────────┘
     │
     ▼
┌─ Interactive selection ──────────────────────────────────┐
│  interactive::run_selection()                            │
│  → Vec<(branch, cli)> mappings                           │
│  (skipped if --cli + --branches provided)                │
└──────────────────────────────────────────────────────────┘
     │
     ▼
┌─ Create worktrees ───────────────────────────────────────┐
│  git::create_worktree() for each branch                  │
│  → .git-paw/worktrees/<slug>/   (child placement)        │
│    or ../<project>-<slug>/       (sibling placement)     │
│  worktree_provision::provision_worktree()                │
│  → env-file copies, port slot, on_create hook            │
└──────────────────────────────────────────────────────────┘
     │
     ▼
┌─ Build tmux session ─────────────────────────────────────┐
│  TmuxSessionBuilder::new(project)                        │
│    .session_name("paw-project")                          │
│    .mouse_mode(true)                                     │
│    .border_affordances(true)                             │
│    .add_pane(PaneSpec { branch, worktree,                │
│                         cli_command }) × N               │
│    .build() → TmuxSession with command sequence          │
└──────────────────────────────────────────────────────────┘
     │
     ▼
┌─ Pane layout by mode ────────────────────────────────────┐
│  supervisor   → Pane 0 = `git paw __dashboard`           │
│                 Pane 1..N = per-agent CLIs               │
│                 (supervisor() builds it with             │
│                  tmux::build_supervisor_session; the     │
│                  orchestrator runs outside the session)  │
│  broker-only  → Pane 0 = `git paw __dashboard`           │
│                 Pane 1..N = per-branch agent CLIs        │
│  no broker    → Pane 0..N = per-branch agent CLIs        │
│                                                          │
│  With the broker on, the tmux session environment        │
│  carries GIT_PAW_BROKER_URL into every pane, and the     │
│  dashboard pane renders the status table as a client     │
│  of the broker host started next.                        │
└──────────────────────────────────────────────────────────┘
     │
     ▼
┌─ Start the broker host (broker on) ──────────────────────┐
│  helpers::start_broker_host()                            │
│  → detached window `broker` (outside window 0's grid)    │
│    running `git paw __broker --session <name>            │
│                              --log-path <log>`           │
│  → wait ≤10s for GET /status (git_paw + repo_root);      │
│    a host that exits or never answers fails the launch   │
│    naming the port, before any receipt is saved          │
│  helpers::register_agents_with_host()                    │
│  → POST /watch per agent (agent id, worktree, CLI,       │
│    spec id)                                              │
└──────────────────────────────────────────────────────────┘
     │
     ▼
┌─ Save session state ─────────────────────────────────────┐
│  session::save_session() → atomic JSON write             │
│  + per-repo discovery file (.git-paw/sessions/)          │
└──────────────────────────────────────────────────────────┘
     │
     ▼
┌─ Attach (entry layer, from LaunchOutcome::Attach) ───────┐
│  attach_or_print_hint() → user enters tmux session       │
│  (prints an attach hint when stdin is not a TTY)         │
└──────────────────────────────────────────────────────────┘

Per-repo session discovery file

Alongside the global receipt under ~/.local/share/git-paw/sessions/, git paw start writes a per-repo discovery file at <repo>/.git-paw/sessions/<session>.json. This is the surface the bundled sweep.sh supervisor helper reads to find the active session and its agent roster from inside the repo (without reaching into the XDG state dir). git paw add / remove rewrite it with the updated roster; purge removes it.

Every path that creates or rebuilds the session’s panes (re)writes it, not just the first launch — the bare launch, the spec-driven launch with or without supervisor mode, the supervisor launch, recovery of a stopped session, and restart of a paused session. The last two matter because they change the layout: recovery rebuilds every pane from the saved receipt, and a resume splits a fresh dashboard pane into the live session at whatever index tmux assigns. A file left by the original launch would then record pane indices that no longer describe the session. Recovery rewrites it from the offsets of the layout it just rebuilt; the resume path reads each agent’s pane index back from the running session (list-panes matched on pane_current_path) rather than assuming the launch-time offsets.

Its shape — stable for sweep.sh and forward-compatible (consumers ignore unknown keys):

{
  "session_name": "paw-myproject",
  "agents": [
    {
      "branch_id": "feat-add-auth",
      "worktree_path": "/abs/path/to/myproject/.git-paw/worktrees/feat-add-auth",
      "cli": "claude",
      "pane_index": 1
    }
  ]
}

branch_id is the broker agent id (slugified branch); pane_index is the agent’s tmux pane within the session window. When the file is absent (e.g. a supervisor attached to a pre-existing paw-* session), sweep.sh falls back to resolving the session name from $TMUX / tmux display-message -p '#S', so the file never needs to be hand-authored.

The agents roster lists coding agents only. No orchestrator entry is written: the orchestrator runs outside the session, so no pane is its own. A file written by an earlier release may still carry one; it deserializes with #[serde(default)], so such a file loads unchanged, and sweep.sh — which reads agents and session_name by name — ignores it.

Broker Architecture

When [broker] enabled = true, the broker runs in its own process, git paw __broker, in a detached service surface of the session — on tmux, a window named broker, outside window 0’s pane grid, so pane indices are untouched. The launcher hands it the session name and the per-session log path on argv (a fresh launch saves its receipt only after the panes exist); when a saved receipt with that name exists (recovery, restart from pause) the host seeds its watch targets, the agent → spec mapping, and the broker port and bind from it. On a fresh launch the agents arrive through POST /watch instead, each with its spec id. The dashboard pane runs git paw __dashboard, a thin client that polls the host over HTTP; closing it never affects the broker.

Broker host process (git paw __broker, window `broker`):
├── tokio runtime (background threads)
│   ├── axum HTTP server on 127.0.0.1:9119 (default [broker] bind / port)
│   │   ├── POST /publish
│   │   ├── POST /watch   (register a worktree as a live watch target,
│   │   │                  optionally with the agent's spec id)
│   │   ├── GET /messages/:agent_id?since=N
│   │   ├── GET /status
│   │   └── GET /log?since=N[&wait=S]   (full message log, cursor-paged and
│   │       long-pollable; read by the dashboard, the drive loop and the MCP server)
│   ├── Worktree watchers (src/broker/watcher.rs), one task per worktree
│   │   └── `git status --porcelain` + `git rev-parse HEAD` every 2s; publishes
│   │       agent.status on change; marks wave progress on a moved branch tip;
│   │       prunes a vanished worktree
│   └── Conflict detector (src/broker/conflict.rs), supervisor mode only
│       └── Forward / in-flight / ownership shapes
├── Log flush thread (std::thread, 5s interval)
│   └── Appends new messages to <session_name>.broker.log
├── Learnings flush thread (std::thread; opt-in via [supervisor] learnings = true)
│   └── Flushes the aggregator (src/broker/learnings.rs), fed on every publish,
│       to .git-paw/session-learnings.md (default every 60s, plus once at shutdown)
└── Main thread
    └── waits for SIGHUP, reparent-to-init, or its terminal hanging up

Dashboard pane process (git paw __dashboard, pane 0):
└── ratatui dashboard (800ms idle tick; a keystroke wakes it immediately)
    └── each tick: GET /status + GET /log?since=<cursor> through BrokerClient

Verdict authority. POST /publish refuses a verdict — any agent.verified, and any agent.feedback whose from is supervisor — unless the request’s X-Paw-Authority header matches the session’s authority credential (constant-time compare; 403 {"error":"authority required"}, no state change). The launcher mints the credential, persists it in the user-data Session (0600) with the receipt, and hands it to the host through a one-shot 0600 file in the sessions directory (never argv or env); the host reads it from there, else from the saved Session, and back-fills one only for a session saved before the credential existed. BrokerState holds it as an Option — None accepts no verdict. In-process publishers (conflict detector, role guard) are not gated; root-side HTTP publishers (the drive loop, sweep.sh verdict verbs via git paw __authority) attach the header. See Security Posture.

The host renders nothing and needs no $TMUX. It exits — dropping BrokerHandle, so the final broker-log flush and the learnings flush run — on SIGHUP (tmux kills its window on pause and every window on stop), on reparent-to-init (getppid() == 1, Unix only), or when a terminal it was given hangs up. It ignores SIGINT, sends no keystrokes to any surface, and a bind or probe failure exits non-zero with a diagnostic naming the port rather than retrying.

The dashboard’s render loop is bound to the session’s lifecycle the same way: a single exit gate checked every iteration (on all paths, including the degraded branch) terminates it on reparent-to-init or when the controlling terminal is gone (a poll error or a failed terminal write — catching reparent-to-a-lingering-shell). An unreachable broker is never an exit condition: the dashboard keeps the last snapshot, shows “broker unreachable” in its status line, and reconnects on its own. See the Dashboard chapter for the user-facing description.

Broker state

The broker state is an Arc<BrokerState> defined in src/broker/mod.rs: an RwLock around the agent records, inboxes, and message log, plus a lock-free AtomicU64 sequence counter. Lock guards are never held across an .await (the clippy::await_holding_lock lint is set to deny). The state is shared between the axum server handlers, the watchers, the conflict detector, and the learnings aggregator, all inside the broker host. The server validates incoming messages (src/broker/server.rs) and hands them to src/broker/delivery.rs, which sequences, logs, and routes them; the dashboard reads the latest snapshot over GET /status each tick.

The log flush thread periodically appends new messages to the session’s broker log in the session-state directory (~/.local/share/git-paw/sessions/<session_name>.broker.log, recorded as broker_log_path in the session file — one log per session, so two repositories never write to or purge the same file), one human-readable line per message ([seq] <unix-seconds> [agent_id] <summary>). This runs on a plain std::thread to avoid contention with the tokio runtime.

Environment injection

When the broker is enabled, git-paw sets GIT_PAW_BROKER_URL=http://<bind>:<port> (default http://127.0.0.1:9119) in the tmux environment for the session when it builds it. Each agent pane inherits this variable and can use it to communicate with the broker.

Supervisor Mode Layout

When --supervisor is active (or [supervisor] enabled = true), the tmux session is laid out as the dashboard in a full-width top row plus a row-major agent grid below. No pane runs an orchestrator CLI.

┌─────────────────────────────────────────────────────┐
│  pane 0: dashboard                                  │
├──┬──┬──┬──┬──┬──────────────────────────────────────┤
│ 1│ 2│ 3│ 4│ 5│  agent grid (row 1)                  │
├──┴──┴──┴──┴──┤                                      │
│ 6│..│..│..│ N│  agent grid (row 2..M)               │
└──┴──┴──┴──┴──┴──────────────────────────────────────┘

Pane 0 always hosts the dashboard; pane indices 1 onwards host one CLI per agent. The orchestrator runs outside the tmux session — the operator’s own agent session, pointed at the repo-root sidecar .git-paw/AGENTS.local.md that the launch writes and names. It drives the run through the broker, the bundled helpers (.git-paw/scripts/sweep.sh, broker.sh) or the MCP server; the dashboard reads the same broker state for its status table.

A live session saved by an earlier release (orchestrator CLI at pane 0, dashboard at pane 1, agents from 2) keeps resolving until it ends: every consumer derives the first agent pane from the recorded dashboard_pane (n → agents from n + 1), and neither of that session’s first two panes is ever treated as a coding agent. Recovering such a session rebuilds the layout above.

One layout for every session

There is a single pane layout. Bare start, spec-driven start and supervisor-mode start — and the recovery of any of them — all build the grid above through one routine, so the geometry never depends on how the session was launched. With the broker disabled there is no dashboard: the agent rows start at pane 0 and share the full window height instead of the 50% the dashboard row leaves.

This is why git paw add and git paw remove work on every session. The grid is laid out by explicit split-window + resize-pane calls with predictable, stable pane indices, which is what lets it be re-tiled incrementally for a new agent count. Bare sessions were previously laid out with tmux’s whole-window select-layout tiled / main-horizontal layouts, which cannot be extended in place; those layouts are no longer used for coding agents anywhere.

Each session records the layout it was built with (Session.layout), so a live session started by an earlier binary — which recorded none, and for a bare session therefore was tiled — is refused by add / remove rather than re-tiled under the user. Recovery rebuilds such a session as a grid and records it.

Row-height proportions

The top row is always half the session height — the dashboard spans its full width — and the agent rows share the remaining 50% evenly, each taking 50 / agent_rows percent. This is a fixed rule rather than a per-agent-count table: adding agents shrinks the agent rows, never the top row.

Pane order

Every agent’s pane index is its row-major position: agent i is pane first_agent + i. That holds because every split targets the session’s last pane, and tmux places a split’s new pane right after its target in the pane list: a sibling in the current row is split-window -h off the previous pane, and a new row is a full-width split-window -v -f off the previous pane, so the row spans the window below the rows above it. Splitting a new row off the previous row’s first pane instead would put the new pane mid-list and shift every later pane by one, so each launch command and prompt typed by index would land in the wrong agent’s pane. git paw add uses the same two splits, so an added agent takes the next index without renumbering any existing pane.

Equal-width agent columns

Agent panes are spliced into a row by successive tmux split-window -h, and each -h split halves the current pane — so a row populated by raw splits renders unequal widths (a 3-agent row would render 50/25/25, not equal thirds). select-layout tiled is deliberately not used for the whole window because it would scramble the predictable pane-index ordering the rest of the system relies on. Instead, after the panes for a row exist, git-paw rebalances that row to equal width: tmux::rebalance_agent_rows queries the live window width and issues tmux resize-pane -x <cols> so each pane in the row gets an equal column share (the last pane absorbs the rounding remainder), leaving the row equal-width within a one-column tolerance. The rebalance runs on every path that changes the grid — git paw start (bare, spec-driven and supervised, and the recovery of each), git paw add, and git paw remove — so an incrementally-built grid matches a start-time grid of the same agent count. It never touches the full-width dashboard row nor the per-row vertical heights. No agent row exceeds five panes (SUPERVISOR_AGENTS_PER_ROW), bounding the smallest equal-width target to ~20% of the window. src/surface.rs and the rebalance in src/tmux/layout.rs are the source of truth.

Launch-readiness gate

Before injecting an agent’s boot block (the initial prompt, paste-handling notes, and the task prose; the spec format’s workflow entry point follows later, as its own message once the pane is idle) into a pane, git-paw verifies the pane’s CLI has actually reached an interactive state rather than relying on a fixed wall-clock sleep. tmux::gate_pane_for_injection polls the pane with tmux capture-pane for a CLI-readiness marker; only once the marker appears is the boot block injected. If the readiness budget elapses while the pane is still a bare shell (the CLI never started), git-paw relaunches the CLI command into that pane and polls again, up to a small relaunch budget, before falling back to injection. The gate is conservative: an unrecognised CLI whose UI matches no known marker simply falls back to injecting after the budget, so launch behaviour is never worse than the previous fixed-sleep launch. This prevents the multi-line boot block from being typed into a bare shell, where it would be interpreted line-by-line as failing commands. The same gate also recognises a first-run trust/bypass acceptance dialog and fails the launch loudly rather than risk a blind Enter accepting it. The gate guards every pane that receives an injected prompt: bare git paw start (with the broker enabled), a spec-driven launch (--specs / --from-all-specs, with or without --supervisor), and git paw add. Session recovery and a broker-less bare launch spawn panes without ever calling the gate — harmless, since neither path injects anything into them.

Non-Supervisor Layout

When supervisor mode is OFF and the broker is on, the dashboard occupies pane 0 and the agent CLIs occupy panes 1 onwards in a single row-major grid (no top row):

┌───────────────────────────────────────────────────────┐
│  pane 0: dashboard                                    │
├──┬──┬──┬──┬──┬────────────────────────────────────────┤
│ 1│ 2│ 3│ 4│ 5│  agent grid (row 1)                   │
├──┴──┴──┴──┴──┤                                       │
│ 6│..│..│..│ N│  agent grid (row 2..M)                │
└──┴──┴──┴──┴──┴───────────────────────────────────────┘

When the broker is disabled too, every pane (0..N) is an agent CLI and there is no dashboard pane.

Worktree Lifecycle

Git worktrees are the foundation of git-paw’s parallel workflow.

Creation

Where a worktree goes is set by worktree_placement in the config (git::worktree_path_for). git paw init writes worktree_placement = "child", which nests worktrees inside the repo. For a project named my-app and branches feature/auth-flow and feat/api:

my-app/                             ← main repo (current directory)
└── .git-paw/worktrees/
    ├── feature-auth-flow/          ← worktree (created by git-paw)
    └── feat-api/                   ← worktree (created by git-paw)

A child worktree is named by the branch slug: slashes become hyphens and characters outside [A-Za-z0-9._-] are dropped.

A config with no worktree_placement key resolves to "sibling", the earlier layout, which creates worktrees beside the main repo directory:

my-app/                         ← main repo (current directory)
my-app-feature-auth-flow/       ← worktree (created by git-paw)
my-app-feat-api/                ← worktree (created by git-paw)

The sibling naming convention is <project>-<sanitized-branch>, where every non-alphanumeric character becomes a hyphen.

Lifecycle states

create_worktree()          stop              start (recover)
     │                      │                     │
     ▼                      ▼                     ▼
  [exists on disk]  →  [still on disk]  →  [reused as-is]
                                                  │
                                            purge │
                                                  ▼
                                          [removed from disk]

Key points:

• Stop preserves worktrees — uncommitted work survives
• Recover reuses existing worktrees — no data loss
• Purge removes worktrees — per worktree it runs the configured [worktree.hooks] on_remove command, then git worktree remove --force, then decides the branch’s fate. There is no prune step. The branch is deleted only when git-paw created it and git merge-base --is-ancestor refs/heads/<branch> refs/heads/<target> succeeds for the default branch or for the branch recorded as the worktree’s base; otherwise it is kept and printed with its tip SHA and a resume/discard hint. Each step is best-effort: a failure is reported as a warning: and never aborts the teardown.
• Start prunes stale worktree registrations (git worktree prune) before creating new worktrees

Session State

Session state is persisted as JSON under ~/.local/share/git-paw/sessions/ (~/Library/Application Support/git-paw/sessions/ on macOS):

{
  "session_name": "paw-my-app",
  "repo_path": "/home/you/projects/my-app",
  "project_name": "my-app",
  "created_at": "2025-01-15T10:30:00Z",
  "status": "active",
  "worktrees": [
    {
      "branch": "feat/auth",
      "worktree_path": "/home/you/projects/my-app/.git-paw/worktrees/feat-auth",
      "cli": "claude",
      "branch_created": true
    },
    {
      "branch": "feat/api",
      "worktree_path": "/home/you/projects/my-app/.git-paw/worktrees/feat-api",
      "cli": "codex",
      "branch_created": false
    }
  ],
  "broker_port": 9119,
  "broker_bind": "127.0.0.1",
  "broker_log_path": "/home/you/.local/share/git-paw/sessions/paw-myproject.broker.log",
  "mode": "bare",
  "dashboard_pane": 0
}

status is active, paused, or stopped. broker_port, broker_bind, broker_log_path, and dashboard_pane are present only when the broker is enabled; git paw status uses the bind and port to probe the broker, and git paw purge uses broker_log_path to clean up that session’s broker log. mode (bare or supervisor) records the pane layout so recovery rebuilds the same shape. branch_created records whether git-paw created the branch (rather than reusing an existing one). A worktree entry can also carry base_branch (the branch a git-paw-created branch started from, so teardown can tell an already-merged branch from an unmerged one), pending_boot_prompt, runtime_slot, cli_session_id, and spec_id (the id of the spec the agent was launched from, absent for a bare git paw start or a git paw add without --from-spec); each is omitted when unset.

Atomic writes

Session state is written atomically: write to a temporary file, then rename. This prevents corruption if the process is killed mid-write.

Effective status

The on-disk status may not reflect reality (e.g., tmux was killed externally). git-paw checks the actual tmux state:

For an active receipt, “alive” also requires at least one agent pane running something other than a bare shell once the session is past a ~30-second launch grace period; a session whose every agent CLI has exited is treated as Stopped and recovered.

Tmux Builder Pattern

The tmux module uses a builder pattern that accumulates operations as data structures rather than immediately executing shell commands. This enables:

• Testability — generate commands without executing them
• Dry run — render the plan (command_strings()) without side effects
• Atomicity — validate the full plan before running anything

#![allow(unused)]
fn main() {
TmuxSessionBuilder::new("my-app")
    .session_name(resolved_name)   // e.g. "paw-my-app"
    .mouse_mode(true)
    .border_affordances(true)
    .set_environment("GIT_PAW_BROKER_URL", &broker_url)
    .add_pane(PaneSpec { branch, worktree, cli_command })
    .add_pane(PaneSpec { ... })
    .build()?
    // → TmuxSession { name, commands: Vec<TmuxCommand> }
}

The built TmuxSession can be inspected (command_strings()) or executed (execute()). Supervisor-mode sessions are assembled the same way by tmux::build_supervisor_session; git paw add splices a pane in with build_add_agent_commands and git paw remove retiles with build_remove_retile_commands — all in src/tmux/command.rs.

CLI-launch robustness

Supervisor-mode sessions and panes hot-added by git paw add are created with shell auto-update prompts suppressed (new-session/session env set DISABLE_AUTO_UPDATE=true and DISABLE_UPDATE_PROMPT=true) so an interactive framework prompt (e.g. oh-my-zsh’s Would you like to update? [Y/n]) cannot fire as the pane’s shell reads its rc and swallow the first keystroke of the CLI-launch command. As a second layer, those builders send a C-u line-clear immediately before each CLI-launch command, so any stray pending input cannot corrupt it. Every headless new-session canvas is sized (480×140) to tile a supervisor session with several agents when no client is attached; a real terminal resizes the session on attach.

Error Strategy

All errors flow through PawError (defined with thiserror). Each variant carries an actionable message telling the user what went wrong and how to fix it. No panics in non-test code — all Result propagation.

Exit codes:

• 0 — success
• 1 — operational error
• 2 — user cancelled