brindle 0.3.24__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: brindle
-Version: 0.3.24
+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.24`). 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.24 → 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.24`). 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.24 → brindle-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "brindle"
-version = "0.3.24"
+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.24 → 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:
@@ -2177,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
@@ -2213,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,
@@ -2228,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
 
@@ -2978,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.4.0/src/brindle/assembler.py

@@ -0,0 +1,43 @@
+"""Context assembler: fit prompt blocks under a token cap.
+
+Blocks are kept whole, in priority order; when the total exceeds the cap the
+lowest-priority blocks are dropped. With no cap every non-empty block is kept.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# Lower number = more important.
+TASK_AND_RULES, DECISIONS, OTHER_SESSIONS, DOCUMENT_CHUNKS = range(4)
+
+
+@dataclass(frozen=True)
+class Block:
+    priority: int
+    text: str
+
+
+def estimate_tokens(text: str) -> int:
+    return len(text) // 4
+
+
+def assemble(blocks: list[Block], cap: int | None = None) -> str:
+    """The kept blocks' text joined by blank lines, in the order given.
+
+    Blocks are admitted by priority (ties keep the given order); one that
+    would push the total over ``cap`` tokens is dropped whole, along with
+    every lower-priority block after it."""
+    live = [b for b in blocks if b.text]
+    if cap is not None:
+        used = 0
+        cut = None
+        for b in sorted(live, key=lambda b: b.priority):
+            used += estimate_tokens(b.text)
+            if used > cap:
+                cut = b.priority
+                break
+        if cut is not None:
+            # A priority tier is the unit of dropping; the top tier always stays.
+            top = min(b.priority for b in live)
+            live = [b for b in live if b.priority < cut or b.priority == top]
+    return "\n\n".join(b.text for b in live)

{brindle-0.3.24 → brindle-0.4.0}/src/brindle/autopilot.py

@@ -45,7 +45,7 @@ from dataclasses import dataclass
 from pathlib import Path
 
 from brindle.config import CONFIG_DIR, WEIGHTS, RepoConfig, config_root, load_repo_config
-from brindle import escapes
+from brindle import escapes, knowledge
 from brindle.db import DB, Agent, Autopilot, Milestone, Workspace
 from brindle.profiles import load_profile
 
@@ -674,6 +674,8 @@ def set_goal(db: DB, root_id: str, goal: str,
                             passed_sha=prev.passed_sha)
     db.bump_progress(root_id)
     write_goals_file(db, root_id)
+    knowledge.note(db, root_id, knowledge.INTENT,
+                   {"summary": "\n".join([goal.strip(), *(m[0] for m in milestones)]), "paths": []})
 
 
 CLI_FOR_PROVIDER = {"claude": "claude", "codex": "codex", "antigravity": "agy"}

brindle-0.4.0/src/brindle/builtin_agents/coordinator.md

@@ -0,0 +1,33 @@
+---
+name: coordinator
+description: Coordinates the queued work of every session in a repo, woken on events (brindle Pro; off unless "coordinator" is on in config)
+provider: claude
+model: haiku
+effort: low
+strict_mcp: true
+setting_sources: project,local
+permission_mode: dontAsk  # nobody watches it: refuse anything beyond its brindle tools, never prompt
+---
+You are the coordinator for one repo under brindle. Several supervisor
+sessions work in this repo at once, each with its own workers; you sit above
+them and keep their queued work from colliding. You never write code.
+
+Your prompt says what woke you. Then:
+- Look before acting: `list_tasks` (full=true for briefs) shows queued and
+  held tasks, `who_is_working` the sessions and their files, `decisions` what
+  has been decided.
+- Act only on work that has not started:
+  - `hold_task` a queued task that would collide with, or redo, another
+    session's work; `release_task` it once that is resolved.
+  - `reorder_queue` to make a queued task also wait for another session's
+    worker or branch, so it starts from that work instead of clashing with it.
+- For running work you can only ask: `advise` the owning supervisor (by its
+  session id), saying what you saw and what you suggest. Never ask a
+  supervisor to cancel or replace work that is already running.
+- `propose_decision` when sessions are contradicting each other on how
+  something should be done; a supervisor accepts it by recording it.
+- Every action needs a short, concrete reason: the supervisors are shown it,
+  and a person can undo what you did. When nothing needs doing, do nothing.
+
+Finish by calling `report_result` with what you did and why (or that
+nothing needed doing). brindle wakes a coordinator again on the next event.