brindle 0.3.23__tar.gz → 0.4.0__tar.gz

{brindle-0.3.23 → brindle-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: brindle
-Version: 0.3.23
+Version: 0.4.0
 Summary: Run coding agents in parallel, each on its own git branch, with a supervisor that delegates, reviews, and merges
 Project-URL: Homepage, https://pawdelta.com/brindle/
 Project-URL: Documentation, https://pawdelta.com/brindle/docs/recommended-use
@@ -94,7 +94,7 @@ uv tool install --editable ~/Projects/brindle   # or from a local checkout
 brindle drives Claude Code, so you need that too (`npm install -g @anthropic-ai/claude-code`).
 
 `brindle --version` prints the installed version; the tmux status bar of every brindle
-session shows it too (`brindle 0.3.23`). A session started before an upgrade keeps
+session shows it too (`brindle 0.4.0`). A session started before an upgrade keeps
 running the old code, and shows the old number, until you restart it.
 
 ## Quick start
@@ -193,7 +193,7 @@ and you're back at your prompt. The whole session is paused: its
 workers stop too, and everything is kept (branches, worktrees,
 queued messages, and each agent's Claude conversation). `brindle continue` (or
 `brindle -c`) picks up the most recent paused session and lists the others by id
-(`brindle continue <id>`). Plain `brindle` always starts fresh. If a session is still running in that folder, it asks first: open that one, start the new one in its own worktree (branch `brindle/session-N`, cut from what you have checked out, so they run at once without sharing files), or pause it and start fresh. There's no limit: each further `brindle` there can start another session in its own worktree (`brindle/session-2`, `-3`, ...). Without a terminal to ask in, it pauses the old one. `brindle sessions` lists
+(`brindle continue <id>`). Plain `brindle` always starts fresh. If a session is still running in that folder, it asks first: open that one, start the new one in its own worktree (branch `brindle/session-N`, cut from what you have checked out, so they run at once without sharing files), or pause it and start fresh. There's no limit: each further `brindle` there can start another session in its own worktree (`brindle/session-2`, `-3`, ...). Without a terminal to ask in, it pauses the old one. When sessions are running in the repo, in any of its worktrees, that question is a list: one row each with the session's id, goal, branch, age and running workers. Pick one to open it, `n` for a new session in its own worktree, or `p` to pause the picked one and start fresh. With two or more paused sessions, `brindle -c` lists them newest first (Enter resumes the newest). `brindle sessions` lists
 what's paused. brindle keeps the newest 3 paused sessions per repo for up to 7 days;
 cleanup never merges anything or deletes an unmerged branch, and worktrees with uncommitted
 changes are kept.
@@ -288,7 +288,7 @@ or put the goal in `.brindle/goals.md`, and it works like a project manager:
    they keep going until it's met. `assign`/`handoff` take `files` (the
    paths/globs a task expects to touch, checked for overlap against other
    active workers' declared and actually-changed files; refused by default,
-   a warning with `"overlap": "warn"`) and `depends_on` (earlier tasks, by agent id or branch, that must
+   queued behind another session's task, a warning with `"overlap": "warn"`) and `depends_on` (earlier tasks, by agent id or branch, that must
    merge first): a task with unmet dependencies is queued instead of started,
    and starts automatically, cut from the updated base, once
    `merge_workspace` resolves them. `list_tasks` shows what's queued.
@@ -413,6 +413,9 @@ your own status line prints, so what you see doesn't change.
 | `brindle profile new/lint/show` | write a profile file, check every profile (extends chains, rule packs, patterns), or print one as brindle resolves it |
 | `brindle rules suggest/accept/reject` | (brindle Pro) rules suggested from review findings that keep recurring; accept one into `.brindle/rules/learned.md`, or reject it for good |
 | `brindle agent turns AGENT` / `brindle agent rewind AGENT --to N [--profile P] [--note "..."]` | a worker's worktree is snapshotted after every turn that changed files; rewind puts it back as it was after turn N and starts a fresh session there, briefed on the task, turns 1..N and your note (any provider, Codex included). Supervisors have the `agent_turns` and `rewind_agent` tools |
+| `brindle kb add folder PATH` / `kb list` / `kb sync [SOURCE]` / `kb remove SOURCE` | the documents agents can search for this repo (see "Shared knowledge across sessions") |
+| `brindle decisions export [FILE]` | this repo's accepted decisions as Markdown (stdout by default) |
+| `brindle coordinator log [-n N]` / `undo ID` / `stop` | Pro: what the coordinator did, put one action back, or switch it off (see "The coordinator") |
 | `brindle setup [WS]` | re-run the repo's setup commands in a workspace |
 | `brindle mcp` | the MCP server agents talk to (launched for them; you don't run it) |
 
@@ -441,6 +444,9 @@ knowing them helps when you tell the supervisor how to work.
 | `complete_subagent` | supervisor | record the result of a `subagent`-profile task |
 | `set_goal` / `get_progress` / `check_milestone` | supervisor | autopilot's goal, its progress, and running the checks |
 | `record_audit_decision` | supervisor | record acceptance of an audit finding with rationale so subsequent audits respect it |
+| `who_is_working` | supervisor | other sessions in this repo: their goals and running tasks, optionally only those matching `paths` or a `query` |
+| `record_decision` / `decisions` | supervisor (`decisions` also workers) | record a durable decision about the system / list the accepted ones that apply |
+| `kb_search` | supervisor, worker | search the repo's knowledge base and accepted decisions |
 | `need_user` | supervisor | ask you a question (a decision, a denied action, a stalled external job such as a CI run no runner picks up); only the steps that depend on it wait, the rest keeps going; `answered=true` once you've replied |
 | `transfer_to_repo` | supervisor | move a scratch session's work into a repository |
 | `handover` | supervisor | hand the session to a new supervisor on another branch or worktree, with a note |
@@ -511,6 +517,84 @@ reported to the supervisor at 80% of `task_usd` and again at 100%; set
 `"stop": true` to close a worker at 100% instead of only warning. Without the
 Pro `cost` feature budgets do nothing.
 
+## Shared knowledge across sessions
+
+Sessions on one repo share a small store in `~/.brindle/brindle.db`, keyed by
+the repo's remote (two clones of one repo share it). It holds what each session
+plans, the decisions you've recorded and the documents you've added. Nothing
+leaves your machine.
+
+### Other sessions
+
+Each session announces what it's working on when its supervisor sets a goal.
+When a new task's `files` overlap another session's running task, brindle
+never touches that session's work: the task is queued (the default; see
+`overlap` in the repo config), both supervisors get a notice naming the other
+session's goal, and the task starts, cut from the commit holding that session's
+merge, once it merges. Each supervisor also sees an "Other sessions in this
+repo" summary, and the `who_is_working` tool lists their goals and running
+tasks, optionally only those matching some paths. A paused session's goal
+stays visible, marked paused, until retention drops it.
+
+### Decisions
+
+A decision is a fact about the system ("config secrets live in the OS
+keychain"), not a working rule; those stay in learned rules. A supervisor
+records one with `record_decision` (topic, decision, rationale, optional path
+globs) and reads them with `decisions`. Recording one that overlaps an accepted
+decision on the same topic is refused and shows the existing one: it has to
+name it as superseded, so two sessions can't quietly contradict each other.
+Supervisors whose running tasks touch the paths are told. Accepted decisions
+whose paths match a task's `files` go into that worker's brief, and a resumed
+worker gets the brief it started with.
+
+```sh
+brindle decisions export                 # accepted decisions as Markdown on stdout
+brindle decisions export DECISIONS.md    # or into a file you can commit
+```
+
+### Knowledge base
+
+Add the documents a person reads first (ADRs, runbooks, design notes) and
+agents can search them:
+
+```sh
+brindle kb add folder docs/              # Markdown and text files, indexed now
+brindle kb list                          # sources, documents, quarantined chunks
+brindle kb sync                          # pick up changed files, drop deleted ones
+brindle kb remove docs/                  # the source and everything indexed from it
+```
+
+Supervisors and workers search with `kb_search`, which returns the matching
+passages with their source and date, beside the accepted decisions. When
+brindle starts a worker it also searches with the task and its `files` and
+puts the best few passages (about 1,500 tokens) in the brief, under a header
+that marks them as untrusted reference data, never instructions, and labelled
+stale when old. Passages that name functions or classes in the repo's code
+graph come first for tasks touching those files.
+
+Text is checked as it's indexed: strings that look like secrets are redacted,
+and passages that address an AI, hide text or hold instructions in HTML
+comments are quarantined and never returned. Review before merge is unchanged
+for work that used them. The index lives under `~/.brindle`, never in the repo.
+
+### The coordinator (Pro)
+
+Set `"coordinator": true` in `.brindle/config.json` and brindle runs one cheap
+agent per repo above the supervisors. It wakes on events only (a new goal, a
+clash notice, a decision, a task queued over 20 minutes), within your budget.
+It may message supervisors, hold, release or reorder queued tasks from any
+session, and propose decisions; you still accept those. It never cancels or
+pauses running work, merges, accepts a decision or edits code: for running work
+it can only ask the owning supervisor. Every action is logged with its reason
+and shown to the supervisors it affects.
+
+```sh
+brindle coordinator log                  # recent actions and reports, newest first
+brindle coordinator undo 3f9c2a1b        # put one action back (the id is in the notice)
+brindle coordinator stop                 # close it and turn it off for this checkout
+```
+
 ## Provider quota
 
 brindle keeps one place (`~/.brindle/quota.json`) that knows how close each
@@ -577,7 +661,7 @@ Autopilot, merge gates and cleanup:
 | `agy_approvals` | `"prompt"` | `"brindle"`: with the policy on, Antigravity workers run without approval prompts and brindle's hook allows or denies every call (see "Antigravity" under "Permission policy") |
 | `rules` | `[]` | standing rules for the supervisor, e.g. `["Fix review findings without asking", "Validate options before offering them"]`; added to every supervisor's brief. Rules in `~/.brindle/config.json`, the repo's config and `config.local.json` are all kept, so a team's rules and your own add up |
 | `plan_first` | `false` | workers propose a plan (`submit_plan`) and wait for `approve_plan` before editing |
-| `overlap` | `"block"` | a task whose `files` overlap a running task's is refused (`"warn"` starts it with a warning) |
+| `overlap` | unset | a task whose `files` overlap a running task's: `"block"` refuses it, `"warn"` starts it with a warning, `"queue"` queues it until that task merges. Unset, it is refused within a session and queued behind another session's task (both sessions' supervisors are told; the other session's work is never cancelled), and the queued task starts from that task's merge commit |
 | `protected_paths` | `[]` | paths or globs (`"migrations/"`, `"*.lock"`) whose merge conflicts brindle never hands to a worker to resolve: the branch waits for you instead (see "Conflict-aware merging") |
 | `pool_size` | `1` if `setup` is set, else `0` | pre-built worktrees (checked out, files copied, setup run) kept ready so a new worker doesn't wait on `setup`; `0` disables it |
 | `add_dirs` | `[]` | directories outside the worktree that Claude Code agents may use (`--add-dir`; full tool access, see "Directories outside the workspace") |

{brindle-0.3.23 → brindle-0.4.0}/README.md

@@ -63,7 +63,7 @@ uv tool install --editable ~/Projects/brindle   # or from a local checkout
 brindle drives Claude Code, so you need that too (`npm install -g @anthropic-ai/claude-code`).
 
 `brindle --version` prints the installed version; the tmux status bar of every brindle
-session shows it too (`brindle 0.3.23`). A session started before an upgrade keeps
+session shows it too (`brindle 0.4.0`). A session started before an upgrade keeps
 running the old code, and shows the old number, until you restart it.
 
 ## Quick start
@@ -162,7 +162,7 @@ and you're back at your prompt. The whole session is paused: its
 workers stop too, and everything is kept (branches, worktrees,
 queued messages, and each agent's Claude conversation). `brindle continue` (or
 `brindle -c`) picks up the most recent paused session and lists the others by id
-(`brindle continue <id>`). Plain `brindle` always starts fresh. If a session is still running in that folder, it asks first: open that one, start the new one in its own worktree (branch `brindle/session-N`, cut from what you have checked out, so they run at once without sharing files), or pause it and start fresh. There's no limit: each further `brindle` there can start another session in its own worktree (`brindle/session-2`, `-3`, ...). Without a terminal to ask in, it pauses the old one. `brindle sessions` lists
+(`brindle continue <id>`). Plain `brindle` always starts fresh. If a session is still running in that folder, it asks first: open that one, start the new one in its own worktree (branch `brindle/session-N`, cut from what you have checked out, so they run at once without sharing files), or pause it and start fresh. There's no limit: each further `brindle` there can start another session in its own worktree (`brindle/session-2`, `-3`, ...). Without a terminal to ask in, it pauses the old one. When sessions are running in the repo, in any of its worktrees, that question is a list: one row each with the session's id, goal, branch, age and running workers. Pick one to open it, `n` for a new session in its own worktree, or `p` to pause the picked one and start fresh. With two or more paused sessions, `brindle -c` lists them newest first (Enter resumes the newest). `brindle sessions` lists
 what's paused. brindle keeps the newest 3 paused sessions per repo for up to 7 days;
 cleanup never merges anything or deletes an unmerged branch, and worktrees with uncommitted
 changes are kept.
@@ -257,7 +257,7 @@ or put the goal in `.brindle/goals.md`, and it works like a project manager:
    they keep going until it's met. `assign`/`handoff` take `files` (the
    paths/globs a task expects to touch, checked for overlap against other
    active workers' declared and actually-changed files; refused by default,
-   a warning with `"overlap": "warn"`) and `depends_on` (earlier tasks, by agent id or branch, that must
+   queued behind another session's task, a warning with `"overlap": "warn"`) and `depends_on` (earlier tasks, by agent id or branch, that must
    merge first): a task with unmet dependencies is queued instead of started,
    and starts automatically, cut from the updated base, once
    `merge_workspace` resolves them. `list_tasks` shows what's queued.
@@ -382,6 +382,9 @@ your own status line prints, so what you see doesn't change.
 | `brindle profile new/lint/show` | write a profile file, check every profile (extends chains, rule packs, patterns), or print one as brindle resolves it |
 | `brindle rules suggest/accept/reject` | (brindle Pro) rules suggested from review findings that keep recurring; accept one into `.brindle/rules/learned.md`, or reject it for good |
 | `brindle agent turns AGENT` / `brindle agent rewind AGENT --to N [--profile P] [--note "..."]` | a worker's worktree is snapshotted after every turn that changed files; rewind puts it back as it was after turn N and starts a fresh session there, briefed on the task, turns 1..N and your note (any provider, Codex included). Supervisors have the `agent_turns` and `rewind_agent` tools |
+| `brindle kb add folder PATH` / `kb list` / `kb sync [SOURCE]` / `kb remove SOURCE` | the documents agents can search for this repo (see "Shared knowledge across sessions") |
+| `brindle decisions export [FILE]` | this repo's accepted decisions as Markdown (stdout by default) |
+| `brindle coordinator log [-n N]` / `undo ID` / `stop` | Pro: what the coordinator did, put one action back, or switch it off (see "The coordinator") |
 | `brindle setup [WS]` | re-run the repo's setup commands in a workspace |
 | `brindle mcp` | the MCP server agents talk to (launched for them; you don't run it) |
 
@@ -410,6 +413,9 @@ knowing them helps when you tell the supervisor how to work.
 | `complete_subagent` | supervisor | record the result of a `subagent`-profile task |
 | `set_goal` / `get_progress` / `check_milestone` | supervisor | autopilot's goal, its progress, and running the checks |
 | `record_audit_decision` | supervisor | record acceptance of an audit finding with rationale so subsequent audits respect it |
+| `who_is_working` | supervisor | other sessions in this repo: their goals and running tasks, optionally only those matching `paths` or a `query` |
+| `record_decision` / `decisions` | supervisor (`decisions` also workers) | record a durable decision about the system / list the accepted ones that apply |
+| `kb_search` | supervisor, worker | search the repo's knowledge base and accepted decisions |
 | `need_user` | supervisor | ask you a question (a decision, a denied action, a stalled external job such as a CI run no runner picks up); only the steps that depend on it wait, the rest keeps going; `answered=true` once you've replied |
 | `transfer_to_repo` | supervisor | move a scratch session's work into a repository |
 | `handover` | supervisor | hand the session to a new supervisor on another branch or worktree, with a note |
@@ -480,6 +486,84 @@ reported to the supervisor at 80% of `task_usd` and again at 100%; set
 `"stop": true` to close a worker at 100% instead of only warning. Without the
 Pro `cost` feature budgets do nothing.
 
+## Shared knowledge across sessions
+
+Sessions on one repo share a small store in `~/.brindle/brindle.db`, keyed by
+the repo's remote (two clones of one repo share it). It holds what each session
+plans, the decisions you've recorded and the documents you've added. Nothing
+leaves your machine.
+
+### Other sessions
+
+Each session announces what it's working on when its supervisor sets a goal.
+When a new task's `files` overlap another session's running task, brindle
+never touches that session's work: the task is queued (the default; see
+`overlap` in the repo config), both supervisors get a notice naming the other
+session's goal, and the task starts, cut from the commit holding that session's
+merge, once it merges. Each supervisor also sees an "Other sessions in this
+repo" summary, and the `who_is_working` tool lists their goals and running
+tasks, optionally only those matching some paths. A paused session's goal
+stays visible, marked paused, until retention drops it.
+
+### Decisions
+
+A decision is a fact about the system ("config secrets live in the OS
+keychain"), not a working rule; those stay in learned rules. A supervisor
+records one with `record_decision` (topic, decision, rationale, optional path
+globs) and reads them with `decisions`. Recording one that overlaps an accepted
+decision on the same topic is refused and shows the existing one: it has to
+name it as superseded, so two sessions can't quietly contradict each other.
+Supervisors whose running tasks touch the paths are told. Accepted decisions
+whose paths match a task's `files` go into that worker's brief, and a resumed
+worker gets the brief it started with.
+
+```sh
+brindle decisions export                 # accepted decisions as Markdown on stdout
+brindle decisions export DECISIONS.md    # or into a file you can commit
+```
+
+### Knowledge base
+
+Add the documents a person reads first (ADRs, runbooks, design notes) and
+agents can search them:
+
+```sh
+brindle kb add folder docs/              # Markdown and text files, indexed now
+brindle kb list                          # sources, documents, quarantined chunks
+brindle kb sync                          # pick up changed files, drop deleted ones
+brindle kb remove docs/                  # the source and everything indexed from it
+```
+
+Supervisors and workers search with `kb_search`, which returns the matching
+passages with their source and date, beside the accepted decisions. When
+brindle starts a worker it also searches with the task and its `files` and
+puts the best few passages (about 1,500 tokens) in the brief, under a header
+that marks them as untrusted reference data, never instructions, and labelled
+stale when old. Passages that name functions or classes in the repo's code
+graph come first for tasks touching those files.
+
+Text is checked as it's indexed: strings that look like secrets are redacted,
+and passages that address an AI, hide text or hold instructions in HTML
+comments are quarantined and never returned. Review before merge is unchanged
+for work that used them. The index lives under `~/.brindle`, never in the repo.
+
+### The coordinator (Pro)
+
+Set `"coordinator": true` in `.brindle/config.json` and brindle runs one cheap
+agent per repo above the supervisors. It wakes on events only (a new goal, a
+clash notice, a decision, a task queued over 20 minutes), within your budget.
+It may message supervisors, hold, release or reorder queued tasks from any
+session, and propose decisions; you still accept those. It never cancels or
+pauses running work, merges, accepts a decision or edits code: for running work
+it can only ask the owning supervisor. Every action is logged with its reason
+and shown to the supervisors it affects.
+
+```sh
+brindle coordinator log                  # recent actions and reports, newest first
+brindle coordinator undo 3f9c2a1b        # put one action back (the id is in the notice)
+brindle coordinator stop                 # close it and turn it off for this checkout
+```
+
 ## Provider quota
 
 brindle keeps one place (`~/.brindle/quota.json`) that knows how close each
@@ -546,7 +630,7 @@ Autopilot, merge gates and cleanup:
 | `agy_approvals` | `"prompt"` | `"brindle"`: with the policy on, Antigravity workers run without approval prompts and brindle's hook allows or denies every call (see "Antigravity" under "Permission policy") |
 | `rules` | `[]` | standing rules for the supervisor, e.g. `["Fix review findings without asking", "Validate options before offering them"]`; added to every supervisor's brief. Rules in `~/.brindle/config.json`, the repo's config and `config.local.json` are all kept, so a team's rules and your own add up |
 | `plan_first` | `false` | workers propose a plan (`submit_plan`) and wait for `approve_plan` before editing |
-| `overlap` | `"block"` | a task whose `files` overlap a running task's is refused (`"warn"` starts it with a warning) |
+| `overlap` | unset | a task whose `files` overlap a running task's: `"block"` refuses it, `"warn"` starts it with a warning, `"queue"` queues it until that task merges. Unset, it is refused within a session and queued behind another session's task (both sessions' supervisors are told; the other session's work is never cancelled), and the queued task starts from that task's merge commit |
 | `protected_paths` | `[]` | paths or globs (`"migrations/"`, `"*.lock"`) whose merge conflicts brindle never hands to a worker to resolve: the branch waits for you instead (see "Conflict-aware merging") |
 | `pool_size` | `1` if `setup` is set, else `0` | pre-built worktrees (checked out, files copied, setup run) kept ready so a new worker doesn't wait on `setup`; `0` disables it |
 | `add_dirs` | `[]` | directories outside the worktree that Claude Code agents may use (`--add-dir`; full tool access, see "Directories outside the workspace") |

{brindle-0.3.23 → brindle-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "brindle"
-version = "0.3.23"
+version = "0.4.0"
 description = "Run coding agents in parallel, each on its own git branch, with a supervisor that delegates, reviews, and merges"
 readme = "README.md"
 requires-python = ">=3.11"

{brindle-0.3.23 → brindle-0.4.0}/src/brindle/agents.py

@@ -21,7 +21,8 @@ import time
 import uuid
 from types import SimpleNamespace
 
-from brindle import cloud_credential, company_identity, company_login, git, keystore, pane_auth, providers, secrets, tmux, workspaces
+from brindle import cloud_credential, company_identity, company_login, git, keystore, knowledge, pane_auth, providers, secrets, tmux, workspaces
+from brindle.assembler import DECISIONS, DOCUMENT_CHUNKS, OTHER_SESSIONS, TASK_AND_RULES, Block, assemble
 from brindle.config import RepoConfig
 from brindle.db import DB, Agent, Workspace
 from brindle.model_availability import ModelAvailabilityChecker, PROVISIONING_TIMEOUT, provisioning_context
@@ -286,15 +287,18 @@ plan is approved; if it comes back with feedback, revise it and call
 
 
 def decorate_worker_prompt(task: str, agent_id: str, ws: Workspace, done_when: str | None,
-                           provider, headless: bool, plan_first: bool = False) -> str:
+                           provider, headless: bool, plan_first: bool = False,
+                           decisions: str = "", chunks: str = "") -> str:
     """The prompt actually sent to a handoff/assign worker's CLI: the raw
-    ``task`` plus its finish line, the WORKER_FOOTER reminder to report, and
-    (for an interactive Claude worker with a finish line) the ``/goal``
-    wrapper. Used at spawn time, and again by ``resume`` to rebuild it when a
-    paused worker's CLI session can't be resumed and must restart fresh."""
+    ``task``, the ``decisions`` block that covers its files, its finish line,
+    the WORKER_FOOTER reminder to report, and (for an interactive Claude
+    worker with a finish line) the ``/goal`` wrapper. Used at spawn time, and
+    again by ``resume`` to rebuild it (decisions from the brief's receipt)
+    when a paused worker's CLI session can't be resumed and must restart fresh."""
     from brindle import autopilot as pilot
 
-    prompt = task
+    prompt = assemble([Block(TASK_AND_RULES, task), Block(DECISIONS, decisions),
+                       Block(DOCUMENT_CHUNKS, chunks)])
     if done_when:
         prompt += f"\n\nFinish line: {done_when.strip()}"
     if plan_first:
@@ -326,9 +330,11 @@ def spawn(
     plan_first: bool = False,
     review_sha: str | None = None,
     claim_goals: bool = True,
+    files: list[str] | None = None,
 ) -> Agent:
     """Start an agent in ``ws``. Workers (handoff/assign) given a ``done_when``
-    finish line run it as a Claude Code ``/goal``. With ``autopilot``, the
+    finish line run it as a Claude Code ``/goal``; their brief carries the
+    accepted decisions covering ``files``. With ``autopilot``, the
     agent is a session root that drives toward a goal (see brindle.autopilot);
     with ``claim_goals`` it claims a hand-written ``.brindle/goals.md``."""
     from brindle import autopilot as pilot
@@ -336,6 +342,10 @@ def spawn(
 
     identity_lock.ensure_workspace(db, ws)   # no new agent in another identity's worktree
     profile = load_profile(profile_name, ws.repo_root)
+    if (profile.name == "coordinator") != (mode == "coordinator"):
+        # Only the sweep starts a coordinator (brindle.coordinator.wake).
+        raise AgentError("the coordinator profile only runs as the repo's coordinator, which "
+                         "brindle starts itself; pick another profile")
     hosted = local_fallback(profile, ws.repo_root)   # its local model isn't up
     if hosted:
         profile_name, profile = hosted, load_profile(hosted, ws.repo_root)
@@ -366,8 +376,12 @@ def spawn(
         full = f"{profile.prompt.strip()}\n\n{rules}".strip() if rules else profile.prompt
         prompt = raw_task = subagent_prompt(full, prompt or "", ws, done_when)
     elif prompt and mode in ("handoff", "assign"):
+        from brindle import codemap
         prompt = decorate_worker_prompt(prompt, agent_id, ws, done_when, provider, headless,
-                                        plan_first=plan_first)
+                                        plan_first=plan_first,
+                                        decisions=knowledge.brief_decisions(db, ws.repo_root, agent_id, files),
+                                        chunks=knowledge.brief_chunks(db, ws.repo_root, agent_id, prompt, files,
+                                                                      codemap.graph_path(ws)))
     elif prompt and mode == "review":
         prompt = raw_task = prompt + REVIEW_FOOTER.format(agent_id=agent_id, branch=ws.branch)
 
@@ -448,8 +462,8 @@ def _profile_for(db: DB, agent: Agent, ws: Workspace, m=_UNREAD):
     # The profile's rule packs: their text joins the prompt here, for every
     # provider; their mechanical rules are checked by brindle.rule_checks.
     # So do its guardrails (write and read scope), which that check enforces.
-    rules = "\n\n".join(p for p in (rules_prompt(load_rule_packs(profile, ws.repo_root)),
-                                    guardrails.scope_prompt(profile)) if p)
+    rules = assemble([Block(TASK_AND_RULES, rules_prompt(load_rule_packs(profile, ws.repo_root))),
+                      Block(TASK_AND_RULES, guardrails.scope_prompt(profile))])
     if rules:
         profile = replace(profile, prompt=f"{profile.prompt.strip()}\n\n{rules}".strip())
     cfg = load_repo_config(ws.repo_root)
@@ -462,15 +476,12 @@ def _profile_for(db: DB, agent: Agent, ws: Workspace, m=_UNREAD):
     if agent.mode == "interactive":
         from brindle import codemap, repos
 
-        note = codemap.guidance(ws)
-        if note:
-            profile = replace(profile, prompt=f"{profile.prompt}\n\n{note}".strip())
         repo_map = codemap.supervisor_map(ws) if autopilot_on or agent.profile == "supervisor" else None
-        if repo_map:
-            profile = replace(profile, prompt=f"{profile.prompt}\n\n{repo_map}".strip())
-        attached = repos.guidance(db, agent.id)   # a session root's attached repos
-        if attached:
-            profile = replace(profile, prompt=f"{profile.prompt}\n\n{attached}".strip())
+        extra = assemble([Block(TASK_AND_RULES, (text or "").rstrip()) for text in (
+            codemap.guidance(ws), repo_map, repos.guidance(db, agent.id))]   # attached repos: a session root's
+            + [Block(OTHER_SESSIONS, knowledge.other_sessions_block(db, knowledge.repo_key(ws.repo_root), agent.id))])
+        if extra:
+            profile = replace(profile, prompt=f"{profile.prompt}\n\n{extra}".strip())
     if agent.headless:
         profile = replace(profile, headless=True)
     # An org's managed models (Enterprise): a profile pointing elsewhere is
@@ -1156,6 +1167,7 @@ def pause(db: DB, root_id: str, *, stop_procs: bool = True,
             tmux.kill_session(session)
     if stop_local_models:
         _stop_local_models(db)
+    knowledge.note(db, root_id, knowledge.PAUSE)
     return paused
 
 
@@ -1253,7 +1265,9 @@ def resume(db: DB, root_id: str, *, watch_pane: bool = True,
             # it gets decorated a second time here; harmless, if redundant.
             prompt = decorate_worker_prompt(
                 a.task, a.id, ws, a.done_when, provider, bool(a.headless),
-                plan_first=bool(a.plan_first) and a.plan_state != "approved") + RESUME_NOTE
+                plan_first=bool(a.plan_first) and a.plan_state != "approved",
+                decisions=knowledge.replay_decisions(db, a.id),
+                chunks=knowledge.replay_chunks(db, a.id)) + RESUME_NOTE
         else:
             prompt = (a.task + RESUME_NOTE) if a.task else None
         if a.dismissed_at is not None:
@@ -1261,6 +1275,8 @@ def resume(db: DB, root_id: str, *, watch_pane: bool = True,
         _launch(db, a, ws, prompt=prompt, resume=ref,
                 watch_pane=watch_pane and a.id == root_id, background_setup=True)
         resumed.append(a)
+    if any(a.id == root_id for a in resumed):
+        knowledge.note(db, root_id, knowledge.RESUME)
     ap = db.get_autopilot(root_id)
     failed_still = [a for a in candidates if db.get_agent(a.id) and db.get_agent(a.id).status == "failed"]
     if ap and ap.state == "blocked" and resumed and not failed_still:
@@ -1358,6 +1374,24 @@ def is_alive(agent: Agent, panes: dict[str, bool] | None = None) -> bool:
     return tmux.window_alive(agent.tmux_window, server=agent.tmux_server or None)
 
 
+LAUNCH_GRACE = 60.0   # seconds a just-spawned agent may go without a window before it counts as dead
+
+
+def alive_or_starting(agent: Agent) -> bool:
+    """``is_alive``, or still being launched: spawn records the agent before
+    its window opens (the launch's checks can take seconds), so one with no
+    window yet is starting, not dead, for LAUNCH_GRACE seconds. A launch known
+    to have failed ends that: spawn deletes the row of one that raised, and
+    launch_health marks one whose CLI died at startup "failed". For the
+    checks that would replace the agent (start another reviewer, forget an
+    auditor), not for ones that talk to its pane."""
+    if is_alive(agent):
+        return True
+    return (runs_process(agent) and not agent.tmux_window and agent.result is None
+            and agent.status not in ("paused", "done", "failed")
+            and time.time() - agent.created_at < LAUNCH_GRACE)
+
+
 def server_of(agent: Agent) -> str | None:
     """The tmux server ``agent``'s window is on (a private socket name, or
     None for the default server), for the ``server`` argument of tmux calls
@@ -1908,12 +1942,17 @@ def _detach(args: list[str]) -> None:
                      stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
 
 
+# A shell that starts the command after it in the background and exits, so the
+# command is nobody's child (see _detach_orphan).
+ORPHANED = ["/bin/sh", "-c", '"$@" </dev/null >/dev/null 2>&1 &', "sh"]
+
+
 def _detach_orphan(args: list[str]) -> None:
     """Start a brindle helper that outlives this process and its agent: a
     shell starts it in the background and exits, so it is nobody's child.
     Stopping an agent stops every process descended from its MCP server
     (brindle.procs), a helper ``_detach`` started there included."""
-    subprocess.run(["/bin/sh", "-c", '"$@" </dev/null >/dev/null 2>&1 &', "sh", *args],
+    subprocess.run([*ORPHANED, *args],
                    start_new_session=True, stdin=subprocess.DEVNULL,
                    stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=False)
 
@@ -2154,12 +2193,16 @@ def delegate(
     branch: str | None = None,
     done_when: str | None = None,
     plan_first: bool | None = None,
+    start: str | None = None,
+    files: list[str] | None = None,
 ) -> tuple[Agent, Workspace]:
     """Start a worker. ``plan_first`` (None: the repo's ``plan_first`` config)
-    makes it get a plan approved before it may edit. With ``isolate``, the worker gets a new worktree whose
+    makes it get a plan approved before it may edit; ``files`` picks the
+    decisions its brief carries. With ``isolate``, the worker gets a new worktree whose
     branch starts from the caller's current branch, so it sees the caller's
-    committed work, and nobody edits the same files. Refuses beyond the
-    repo's ``max_agents`` workers running at once."""
+    committed work, and nobody edits the same files; ``start`` names another
+    commit to start it from (it still merges into the caller's branch).
+    Refuses beyond the repo's ``max_agents`` workers running at once."""
     from brindle import autopilot as pilot
     from brindle import repos
     from brindle.config import load_repo_config
@@ -2190,7 +2233,7 @@ def delegate(
         merge_into = load_repo_config(caller_ws.repo_root).merge_into
         base = merge_into if merge_into and not (caller and caller.parent_id) else caller_ws.branch
         branch = branch or _branch_from_task(profile, task, new_id()[:4])
-        start = base if git.branch_exists(caller_ws.repo_root, base) else "HEAD"
+        start = start or (base if git.branch_exists(caller_ws.repo_root, base) else "HEAD")
         created = workspaces.create(
             db, caller_ws.path, branch, base, fetch=False, start=start,
             reuse_registered=True,
@@ -2205,7 +2248,7 @@ def delegate(
     # the new pane for up to 30 seconds.
     agent = spawn(
         db, ws, profile, prompt=task, parent_id=caller.id if caller else None, mode=mode,
-        done_when=done_when, background_setup=True, plan_first=bool(plan_first),
+        done_when=done_when, background_setup=True, plan_first=bool(plan_first), files=files,
     )
     from brindle import events
 
@@ -2350,7 +2393,7 @@ def _live_reviewer(db: DB, ws: Workspace, sha: str, profile: str | None = None)
     ``profile``, only one running that profile (a second review by another
     profile is not a duplicate)."""
     for a in db.list_agents(ws.id):
-        if a.mode == "review" and a.result is None and is_alive(a) and a.review_sha == sha \
+        if a.mode == "review" and a.result is None and alive_or_starting(a) and a.review_sha == sha \
                 and (profile is None or a.profile == profile):
             return a
     return None
@@ -2386,7 +2429,9 @@ def start_review(db: DB, caller: Agent | None, ws: Workspace, profile: str | Non
         argv += ["--profile", profile]
     if focus:
         argv += ["--focus", focus]
-    _detach(argv)
+    # Nobody's child: the worker reporting here may be closed while the checks
+    # still run, and stopping it would stop this run too, so no reviewer (#190).
+    _detach([*ORPHANED, *argv])
     return None
 
 
@@ -2417,34 +2462,36 @@ def review_after_checks(db: DB, caller_id: str | None, ws: Workspace, profile: s
     a new report (its worker committed again, or merged its moved base in)
     is checked again on its new head, up to ``MOVED_RETRIES`` times, and then
     goes to the supervisor. Raises ``AgentError`` when the reviewer can't
-    start."""
+    start. Holds ``pipeline.review_run`` throughout, so the sweep can tell
+    this run at work (queued for a slot, say) from one that died."""
     from brindle import gates, pipeline
     from brindle.config import load_repo_config
 
     cfg = cfg or load_repo_config(ws.repo_root)
-    since = pipeline.review_claim(db, ws)
-    for _attempt in range(MOVED_RETRIES + 1):
-        sha = gates.head(ws)
-        if _live_reviewer(db, ws, sha, profile):
-            return None
-        try:
-            summary = gates.check_summary(db, ws, cfg, cancel=lambda sha=sha: gates.head(ws) != sha)
-        except gates.Abandoned:
-            summary = None
-        except Exception as e:  # noqa: BLE001 - the review goes ahead, saying so
-            summary = f"(running the checks crashed: {e})"
-        if db.get_workspace(ws.id) is None:
-            return None
-        if gates.head(ws) == sha:
-            break
-        if not pipeline.still_claimed(db, ws, since):
+    with pipeline.review_run(ws.id):
+        since = pipeline.review_claim(db, ws)
+        for _attempt in range(MOVED_RETRIES + 1):
+            sha = gates.head(ws)
+            if _live_reviewer(db, ws, sha, profile):
+                return None
+            try:
+                summary = gates.check_summary(db, ws, cfg, cancel=lambda sha=sha: gates.head(ws) != sha)
+            except gates.Abandoned:
+                summary = None
+            except Exception as e:  # noqa: BLE001 - the review goes ahead, saying so
+                summary = f"(running the checks crashed: {e})"
+            if db.get_workspace(ws.id) is None:
+                return None
+            if gates.head(ws) == sha:
+                break
+            if not pipeline.still_claimed(db, ws, since):
+                return None
+        else:
+            pipeline.on_moved_during_checks(db, ws)
             return None
-    else:
-        pipeline.on_moved_during_checks(db, ws)
-        return None
-    caller = db.get_agent(caller_id) if caller_id else None
-    text = f"Checks for {ws.branch} at {sha[:8]}:\n\n{summary}" if summary else None
-    return request_review(db, caller, ws, profile, focus, cfg, check_summary=text)
+        caller = db.get_agent(caller_id) if caller_id else None
+        text = f"Checks for {ws.branch} at {sha[:8]}:\n\n{summary}" if summary else None
+        return request_review(db, caller, ws, profile, focus, cfg, check_summary=text)
 
 
 def request_review(db: DB, caller: Agent | None, ws: Workspace, profile: str | None = None,
@@ -2469,7 +2516,7 @@ def request_review(db: DB, caller: Agent | None, ws: Workspace, profile: str | N
     cfg = cfg or load_repo_config(ws.repo_root)
     sha = gates.head(ws)
     for old in db.list_agents(ws.id):
-        if old.mode != "review" or old.result is not None or not is_alive(old):
+        if old.mode != "review" or old.result is not None or not alive_or_starting(old):
             continue
         if old.unreported_noted:
             continue   # it stopped without a verdict: not the reviewer of anything
@@ -2951,7 +2998,11 @@ def handle_hook(db: DB, agent_id: str, event: str, payload: dict) -> dict | None
         # Queued messages (worker results) are typed into an idle chat too;
         # only a prompt brindle didn't deliver is the user speaking.
         prompt = str(payload.get("prompt", ""))
-        if agent.mode == "interactive" and not db.recently_delivered(agent_id, prompt):
+        # brindle's own reminders also arrive as prompts, possibly wrapped or
+        # sent without being recorded as delivered (the unread-mail one): any
+        # prompt carrying brindle's tag is not the user speaking.
+        if (agent.mode == "interactive" and "[brindle" not in prompt
+                and not db.recently_delivered(agent_id, prompt)):
             from brindle import autopilot as pilot
 
             pilot.user_spoke(db, agent)

{brindle-0.3.23 → brindle-0.4.0}/src/brindle/antigravity.py

@@ -110,7 +110,9 @@ def binary() -> str:
     explicit = os.environ.get("BRINDLE_AGY_BIN")
     if explicit:
         return explicit
-    return shutil.which("agy") or (BUNDLED if os.path.exists(BUNDLED) else "agy")
+    from brindle.providers import which_cli
+
+    return which_cli("agy") or (BUNDLED if os.path.exists(BUNDLED) else "agy")
 
 
 def tool_names() -> list[str]: