pitboss.example.toml

# Pitboss — annotated example manifest (v0.9 schema).
#
# This file is a learning aid. Every field in pitboss's manifest schema
# is explained inline below, with notes on when to use what. Copy this
# file, rename it to `pitboss.toml`, edit the fields, then run:
#
#     pitboss validate pitboss.toml    # catches schema / resolution errors
#     pitboss dispatch pitboss.toml    # actually runs it
#     pitboss-tui                      # watch the live floor-view
#     pitboss container-dispatch pitboss.toml  # run dispatch inside a Docker/Podman container (requires a [container] section — see below)
#     pitboss status <run-id>                  # snapshot task table for any run, in-flight or finalized
#
# See README.md for a project overview and AGENTS.md for the full schema
# reference. Ready-to-run examples under examples/:
#
#     examples/v0.4-approval-demo.toml         minimal hierarchical run
#     examples/shared-store-haiku-demo.toml    shared-store demonstration
#     examples/ketchup-p0-execute.toml         real-world refactor run

# ────────────────────────────────────────────────────────────────────────────
# [run] — run-wide infrastructure config (NOT lead-specific).
# Lead-level caps moved to [lead] in v0.9.
# ────────────────────────────────────────────────────────────────────────────

[run]

# Human-readable label used to group related runs in the operational
# console (e.g. "build-db", "nightly-sync"). When unset, the console
# falls back to the manifest filename. The canonical run identifier
# remains the UUIDv7 run_id; this name is purely for cross-run
# grouping.
# name = "example-shared-store"

# Flat-mode concurrency cap. Only meaningful when [[task]] is used (not
# when [lead] is set). Default 4. Overridden by ANTHROPIC_MAX_CONCURRENT.
# Renamed from `max_parallel` in v0.9.
# max_parallel_tasks = 4

# Stop flat-mode runs on first failure. Default false. Ignored in
# hierarchical mode (leads decide their own retry semantics).
# halt_on_failure = false

# Where run artifacts land. Default ~/.local/share/pitboss/runs.
# Override to pin a run to a specific location.
# run_dir = "/tmp/my-pitboss-runs"

# What to do with each worker's git worktree after it finishes:
#   "always"      — always clean up (can't resume)
#   "on_success"  — clean up only if the worker succeeded (DEFAULT)
#   "never"       — keep all worktrees (useful for inspection / resume)
worktree_cleanup = "on_success"

# Write an event stream JSONL (pause / cancel / approval events) alongside
# summary.jsonl. Off by default.
# emit_event_stream = false

# How often (in seconds) the dispatcher samples per-actor RSS / VSZ / CPU%
# and cgroup headroom (#553). `0` disables sampling entirely; default 5.
# Memory-pressure events fire at 70% / 90% of available memory and clear
# at sustained <60%. On macOS host dispatch the sampler is a no-op
# (no /proc); inside `pitboss container-dispatch` the sampler runs in
# the linux VM so macOS hosts still get full pressure visibility.
# resource_sample_secs = 5

# Default action for `request_approval` / `propose_plan` when no TUI is
# attached and no [[approval_policy]] rule matches.
#   "block"        — queue until a TUI connects (DEFAULT)
#   "auto_approve" — immediately approve (useful for CI)
#   "auto_reject"  — immediately reject
# Renamed from `approval_policy` in v0.9 to disambiguate from the rules array.
# default_approval_policy = "block"

# When true, write `shared-store.json` (all /ref/*, /peer/*, /shared/*,
# /leases/*) to <run-dir>/shared-store.json on finalize. Useful for
# post-mortem inspection of cross-worker coordination state.
dump_shared_store = true

# ────────────────────────────────────────────────────────────────────────────
# [defaults] — per-actor inheritable knobs.
# Inherited by every [[task]] and [lead] unless overridden.
# ────────────────────────────────────────────────────────────────────────────

[defaults]

# Claude model. Dated suffixes allowed.
#   claude-haiku-4-5      — cheapest, fastest; bounded refactors, audits
#   claude-sonnet-4-6     — mid-tier; most balanced
#   claude-opus-4-7       — most capable; synthesis, planning, hard design
model = "claude-haiku-4-5"

# Claude --effort flag. "low" | "medium" | "high".
# effort = "medium"

# Allowed tool surface. Default covers the common set; specify to restrict
# (e.g. a read-only analysis worker gets only [Read, Glob, Grep]).
# Pitboss auto-appends its own MCP tools for leads and workers.
# tools = ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]

# Per-task wall-clock cap. No default — omit for no cap, set for safety.
# timeout_secs = 600

# Git worktree isolation. true by default. Set false for read-only
# analysis runs, or when workers should operate directly in the target.
use_worktree = true

# Env vars passed to the claude subprocess.
# [defaults.env]
# SOME_VAR = "value"

# ────────────────────────────────────────────────────────────────────────────
# [container] — optional; enables `pitboss container-dispatch` (v0.8+).
# ────────────────────────────────────────────────────────────────────────────
#
# When present, `pitboss container-dispatch <manifest>` assembles and execs a
# Docker/Podman `run` command from this section. Task and lead `directory`
# fields become container-side paths; host-filesystem existence is not checked
# at validate time when [container] is set. Omit this section for host-mode
# dispatch — the behavior is then identical to v0.7.
#
# [container]
# image      = "ghcr.io/sds-mode/pitboss-with-claude:latest"  # bundled claude CLI
# runtime    = "auto"              # "docker" | "podman" | "auto" (auto prefers podman)
# workdir    = "/project"          # cwd inside the container; defaults to first mount's container path
# extra_args = []                  # inserted verbatim before the image name
#
# # Declare one [[container.mount]] per bind mount the run needs. Two mounts are
# # auto-injected regardless: ~/.claude → /home/pitboss/.claude (OAuth) and the
# # run artifact directory. The manifest itself is mounted read-only at
# # /run/pitboss.toml. Declare only the project + reference mounts here.
#
# [[container.mount]]
# host      = "~/projects/myproject"   # absolute host path; ~ is expanded
# container = "/project"               # absolute container path
# readonly  = false                    # default false; true for read-only reference material
#
# [[container.mount]]
# host      = "~/reference-docs"
# container = "/ref"
# readonly  = true

# ────────────────────────────────────────────────────────────────────────────
# Task definitions: pick ONE of
#   a) one-or-more [[task]] entries  (flat mode), OR
#   b) exactly one [lead] entry      (hierarchical mode).
# The two are mutually exclusive — a manifest is either flat or hierarchical.
# ────────────────────────────────────────────────────────────────────────────

# ── a) FLAT MODE example (commented out by default) ──
#
# [[task]]
# id = "audit"                                  # unique slug for this task
# directory = "/path/to/repo"                   # must be a git repo if use_worktree
# prompt = "Read src/foo.rs and summarize it."
# branch = "feat/audit"                         # auto-generated if omitted
# # model = "..."    # per-task override of [defaults]
# # tools = [...]    # per-task override
#
# [[task]]
# id = "lint"
# directory = "/path/to/repo"
# prompt = "Run `cargo clippy` and fix any warnings under -D warnings."

# ── b) HIERARCHICAL MODE example (active by default) ──
#
# The lead is a single claude subprocess that receives the operator's
# prompt + the full pitboss MCP toolbelt. It decides how many workers
# to spawn, waits on them, and composes the final output.
#
# Auto-allowed MCP tools for leads (pitboss injects into --allowedTools):
#     spawn_worker worker_status wait_for_worker wait_for_any list_workers
#     cancel_worker pause_worker continue_worker request_approval
#     reprompt_worker
#     kv_get kv_set kv_cas kv_list kv_wait lease_acquire lease_release
#
# Workers get a narrower set: just the 7 kv_* / lease_* tools.

[lead]

# Identity (REQUIRED in v0.9 — both `id` and `directory` are no longer
# defaulted from cwd).
id = "example-lead"
directory = "/tmp/pitboss-example"  # must exist; set use_worktree=false unless it's a git repo
branch = "example/lead"
# model = "claude-opus-4-7"          # override [defaults] for the coordinator

# IMPORTANT: `prompt =` MUST appear before any [lead.X] subtable in the
# TOML source. A `prompt =` after a subtable header is silently moved to
# that subtable's scope; pitboss validate catches the resulting empty prompt.
prompt = """
This is a minimal hierarchical example that exercises the shared store.

STEP 1: Write a shared configuration value to /ref/config using
mcp__pitboss__kv_set. Use path="/ref/config" and value set to the UTF-8
bytes of "example run, echo your id back".

STEP 2: Spawn three workers in parallel via mcp__pitboss__spawn_worker.
Each worker's prompt should be: "Read /ref/config via
mcp__pitboss__kv_get. Then write a line to /shared/echoes/<your-actor-id>
via mcp__pitboss__kv_set. The line's value: 'worker <N> says: <config content>'.
Exit."

STEP 3: Wait for all three via mcp__pitboss__wait_for_worker.

STEP 4: List /shared/echoes/* via mcp__pitboss__kv_list. Read each entry
via mcp__pitboss__kv_get and print a combined report of all three echoes.

Then exit.
"""

# Lead-level caps (moved from [run] in v0.9).
max_workers = 3                     # 1–16; required when the lead spawns workers
budget_usd = 1.50                   # soft cap on run-wide total (workers + lead + sub-leads); reservation accounting at spawn time
# lead_budget_usd = 0.50            # optional separate cap on lead + sub-lead orchestration cost only (worker spend NOT counted); independent of budget_usd (#253)
lead_timeout_secs = 900             # wall-clock cap on the lead session

# Permission routing (v0.8+, default flipped to path_b in v0.12).
# "path_b" (default) leaves claude's per-tool gate active and wires
# `--permission-prompt-tool mcp__pitboss__permission_prompt`; every
# check the model wants outside its `--allowedTools` routes through
# pitboss with layered enforcement: (1) per-server `[[mcp_server]].tools`
# allowlist, (2) operator `[[approval_policy]]` rules, (3) typed
# profile cap, (4) bridge fallback. Denials are non-terminating —
# claude receives a structured response and adapts.
# "path_a" is the opt-out: sets CLAUDE_CODE_ENTRYPOINT=sdk-ts plus
# --dangerously-skip-permissions, bypassing claude's gate entirely so
# pitboss's [[approval_policy]] rules + bridge are the sole authority.
# permission_routing = "path_b"

# ─── Depth-2 sub-leads (v0.6+) ───
# Uncomment to enable a root lead that may spawn sub-leads.
# allow_subleads = true
# max_subleads = 4                    # cap on total sub-leads
# max_sublead_budget_usd = 5.00       # cap on per-sub-lead budget envelope
# max_total_workers = 16              # cap on total live workers (root + sub-trees)
                                      # Renamed from max_workers_across_tree in v0.9.

# ────────────────────────────────────────────────────────────────────────────
# [sublead_defaults] — top-level (v0.9+, promoted from [lead.sublead_defaults]).
# Optional defaults applied to spawn_sublead calls that omit the corresponding
# parameters. Required when allow_subleads = true (use either explicit
# budget_usd + max_workers, or read_down = true).
# ────────────────────────────────────────────────────────────────────────────
#
# [sublead_defaults]
# budget_usd = 2.00         # per-sub-lead envelope when read_down = false
# lead_budget_usd = 0.50    # per-sub-lead cap on the sub-lead's own token spend (orchestration cost only — its workers' spend NOT counted); analogous to [lead].lead_budget_usd
# max_workers = 4           # per-sub-lead worker pool when read_down = false
# lead_timeout_secs = 1800  # wall-clock cap for the sub-lead session
# read_down = false         # when true, sub-lead shares root's budget + pool

# ────────────────────────────────────────────────────────────────────────────
# [[approval_policy]] — declarative approval rules (v0.6+).
# Zero or more rule blocks; evaluated in declaration order, first match wins.
# ────────────────────────────────────────────────────────────────────────────
#
# # Auto-approve all file-read tool calls within sub-tree S1
# [[approval_policy]]
# match = { actor = "root→S1", category = "tool_use", tool_name = "Read" }
# action = "auto_approve"
#
# # Escalate any cost-category event over $0.50 to the operator.
# # ADVISORY ONLY: cost_estimate is caller-supplied; an actor can pass
# # cost_estimate=0.0 to bypass this threshold. For hard cost gates use
# # [run].budget_usd or auto_reject on tool_name/actor.
# # See book/src/operator-guide/approval-policy-reference.md ("Cost gates: advisory vs hard").
# [[approval_policy]]
# match = { category = "cost", cost_over = 0.50 }
# action = "block"

# ────────────────────────────────────────────────────────────────────────────
# [[mcp_server]] — external MCP server injection (v0.9+).
# Servers declared here are injected into every actor's --mcp-config
# (lead, sub-leads, and workers) at dispatch time, unless narrowed by
# `scope` (v0.12) or further capped by `tools` (v0.12).
# ────────────────────────────────────────────────────────────────────────────
#
# [[mcp_server]]
# id      = "context7"
# command = "npx"
# args    = ["-y", "@upstash/context7-mcp"]
#
# # `scope = "type:<id>"` (v0.12) narrows injection: this server only
# # appears in actors spawned with `worker_type = "writer"` or
# # `sublead_type = "writer"`. Untyped actors (no profile arg on spawn)
# # never receive scoped servers. Useful for separating side-effecting
# # servers (filesystem writes, network calls) from analysis-only roles.
# [[mcp_server]]
# id      = "fs-writer"
# command = "/usr/local/bin/fs-writer-mcp"
# scope   = "type:writer"
# # `tools = [...]` (v0.12) caps which tools this server may admit.
# # Enforced at three layers (most-restrictive-wins): (1) manifest validate
# # rejects any actor surface referencing `mcp__fs-writer__X` for an X
# # not in this list; (2) spawn-time argv drops non-allowlisted entries
# # from --allowedTools (Path B); (3) runtime permission_prompt denies
# # any routed mcp__fs-writer__X call where X isn't in the allowlist.
# # `tools = []` is rejected as self-defeating. Unset = no per-tool cap.
# tools   = ["Read", "Write", "Edit"]
#
# [[mcp_server]]
# id      = "my-tool"
# command = "/usr/local/bin/my-mcp-server"
# args    = ["--port", "3000"]
# env     = { MY_TOKEN = "abc" }

# ────────────────────────────────────────────────────────────────────────────
# [[worker_type]] / [[sublead_type]] — typed actor profiles (v0.12+, #252).
# Declarative capability caps the dispatcher enforces at spawn time.
# A `spawn_worker(worker_type = "<id>")` call is rejected when its
# `tools` arg is not a subset of the profile's allowlist, when its
# `model` is not in `allowed_models`, or when its `timeout_secs` exceeds
# `max_timeout_secs`. Sub-leads add the same clamp on `budget_usd`.
# Profiles are belt-and-suspenders: even if the lead's prompt drifts or
# is hijacked, the dispatcher will not honour an off-policy spawn.
# ────────────────────────────────────────────────────────────────────────────
#
# [[worker_type]]
# id               = "extraction"
# tools            = ["Read", "Glob", "Grep"]
# allowed_models   = ["claude-haiku-4-5", "claude-sonnet-4-6"]
# max_timeout_secs = 900
#
# [[worker_type]]
# id    = "writer"
# tools = ["Read", "Glob", "Grep", "Write", "Edit"]
#
# [[sublead_type]]
# id             = "planner"
# tools          = ["Read", "Glob", "Grep"]
# allowed_models = ["claude-opus-4-7"]
# max_budget_usd = 2.00

# `require_actor_type = true` (v0.12+) forces every spawn_worker /
# spawn_sublead call to name a declared profile. Type-less spawns are
# rejected. Default false for back-compat with pre-#252 manifests.
# require_actor_type = true

# Path-B-only behavior for un-typed callers reaching permission_prompt
# (only meaningful when require_actor_type = false, i.e. some actors
# are still type-less). "bridge" (default) routes those callers to the
# operator approval queue, preserving pre-#252 semantics. "block"
# synthesizes an empty profile so anything outside --allowedTools
# auto-denies via denied_by_profile — the strict counterpart for
# headless production runs once every actor's profile is declared.
# untyped_actor_policy = "bridge"