synapbus/specs/018-dynamic-agent-spawning/spec.md

Feature Specification: Dynamic Agent Spawning

Feature Branch: 018-dynamic-agent-spawning Created: 2026-04-14 Status: Draft Input: Brainstormed and approved design from conversation — a coordinator-driven system where humans give high-level goals as free text, a meta-agent decomposes them into a task tree, proposes spawning specialist sub-agents, obtains human approval, runs the spawned agents on heartbeats, verifies their outputs, requests missing resources from the human, and iterates until the goal is achieved. Doc-gardener is the acceptance-test example.

Assumptions

• Primary actors: (a) a human owner who issues goals and approves spawns, (b) a pre-built "coordinator" meta-agent that decomposes goals and proposes spawns, (c) specialist agents dynamically spawned to do leaf work, (d) optional peer "verifier" agents that check artifacts.
• Bus-first architecture: all agent-to-agent coordination continues to ride on SynapBus channels and DMs. Tasks are a first-class data model but every task state change also posts a system message to a backing #goal-<slug> channel for audit, search, and notifications — the task table is authoritative, the channel is the event log.
• One human owner per goal. No multi-human approval in v1.
• Single-assignee atomic checkout for tasks — no co-working on a single task in v1. Handled by a single-statement optimistic-lock UPDATE on tasks.assignee_agent_id IS NULL.
• Goal ancestry is denormalized as a JSON snapshot on every task, copied at create time. Parent rename does not propagate; ancestry represents the context the task was created under.
• Cost rollup is read-time, via a recursive CTE over the tasks table. Leaf tasks accumulate spent_tokens / spent_dollars_cents; aggregates are computed on demand. No materialized cache, no triggers, in v1.
• Budgets cascade by delegation, not by tree containment alone: when agent A assigns a sub-task to agent B, B's task budget is deducted from A's remaining parent-task budget at assignment time.
• Trust = (human_owner, config_hash, task_domain). config_hash = SHA-256(model + system_prompt + tools + skills + mcp_servers + subagents). The agent's friendly name is a routing label; reputation attaches to the hash. On any config update, the hash changes and reputation restarts from a parent-derived floor (default 70 % of prior), not zero.
• Reputation is append-only. Each observation writes a new ledger row; the "current" reputation is a rolling aggregate (exponentially-weighted by recency) derived from the ledger at read time.
• Autonomy tiers: supervised (every action needs approval), assisted (defined tool scope auto, else ask), autonomous (auto within goal budget). Stored on the agent record, capped server-side at spawn time by the delegation cap rule.
• Delegation cap rule: a child agent's effective grant in any dimension (tool scope, budget, tier) is min(parent's grant in that domain, child's own earned reputation in that domain). Enforced at spawn time and re-checked at every tool call.
• Max spawn depth defaults to 3, configurable per goal. Each spawn increments spawn_depth; over the cap = hard reject.
• Approval gating for dynamic spawning uses the existing reactions workflow from migration 013 (approve / reject reactions on proposal messages posted to #approvals). No new UI primitive.
• Resource requests are a new structured message type sent to #requests. The human sets secrets via CLI (synapbus secrets set) or Web UI. Secrets are stored encrypted at rest under a master key file living next to the attachment store, identical trust model.
• Verification in v1 supports three verifier kinds: (a) a peer agent's verify_task MCP tool, (b) a shell command exit code, (c) auto-approve if no verifier is configured. More sophisticated kinds (consensus, voting, rubric grading) are deferred.
• Coordinator is a pre-built agent shipped with SynapBus. One coordinator per goal, owned by the goal's human owner. Coordinator uses the same subprocess harness as any other agent — it is not a kernel component.
• Heartbeats reuse and extend the existing reactive triggers system from migration 015. Wake sources: task_assignment, task_timer, message_received, verification_requested, manual. Existing coalescing (pending_work flag) applies.
• Migration numbers: new migrations 021_goals_tasks.sql, 022_agent_proposals.sql, 023_agent_trust_model.sql, 024_secrets.sql, 025_harness_runs_task_id.sql. The dormant trust table from migration 014 is dropped and re-created under the new schema in 023.
• SynapBus base URL in the example is http://localhost:18088 (isolated instance, same pattern as cold-topic-explainer).
• No CGO. All new code must cross-compile cleanly for linux/amd64 and darwin/arm64.

User Scenarios & Testing (mandatory)

User Story 1 - Human creates a goal from free text (Priority: P1)

A human owner wants to achieve a high-level outcome (for example, "keep docs.mcpproxy.app accurate against the current source code"). They type a short title and a free-text description, and hand it to SynapBus. SynapBus creates a goal record, auto-creates a #goal-<slug> backing channel, and assigns a pre-built coordinator agent as the goal's meta-agent. The human is now subscribed to the goal channel and sees every subsequent event there.

Why this priority: This is the entry point. Nothing else works without it. It must be demonstrable standalone as "I typed a goal and I got a goal row plus a channel plus a coordinator."

Independent Test: Run create_goal with a title and description. Verify a goals row exists, a #goal-<slug> channel exists, the owner is a member, and the coordinator agent is recorded as the goal's coordinator. No task tree yet.

Acceptance Scenarios:

1. Given a human owner and a free-text description, When the owner calls create_goal with title "Keep docs.mcpproxy.app accurate" and a description blob, Then a goal row is created with status='draft', a channel named #goal-keep-docs-mcpproxy-app-accurate is auto-created, the owner is added as a member, and the coordinator agent is assigned to the goal.
2. Given a goal with a backing channel, When the owner opens the Web UI, Then the goal appears on a new /goals page with title, status, owner, and a link to its channel.
3. Given a goal with status draft, When the coordinator has not yet posted a task tree, Then no specialist agents have been spawned and no tasks exist in the task table.

---

User Story 2 - Coordinator decomposes a goal into a task tree and asks for approval (Priority: P1)

Once a goal exists, the coordinator agent is woken by a goal_created event, reads the goal's description, and produces a structured task tree: a root task, child tasks covering independent lines of work, and leaf tasks tagged with the kind of specialist that should handle them. The coordinator posts the proposed tree as a single structured message to #approvals along with its reasoning. The human reacts with approve or reject (or edits in the UI in a later iteration). On approval, the root task and all child rows are materialized in the tasks table with goal ancestry snapshots, and their statuses are set to approved.

Why this priority: Decomposition is the bridge between "a goal exists" and "work is getting done." Without this step there is nothing to assign, nothing to budget, and nothing to verify.

Independent Test: Create a goal with a description, wait for the coordinator heartbeat, and check that a task_proposal message appears in #approvals. React with approve. Verify all tasks from the proposal are written to the tasks table with correct parent/child links, depth values, and denormalized ancestry JSON.

Acceptance Scenarios:

1. Given a goal with status='draft', When the coordinator runs its first heartbeat, Then it posts a structured task_proposal message to #approvals containing the full proposed tree, the reasoning, and a reference to the goal id.
2. Given a task_proposal message, When the human reacts with approve, Then all proposed tasks are created atomically with parent/child links, depth values, denormalized ancestry_json snapshots, status='approved', and system messages are posted to the goal's backing channel.
3. Given a task_proposal message, When the human reacts with reject and optionally supplies a reason, Then no tasks are created, the proposal message is marked rejected, the coordinator is DMed the reason, and the coordinator may retry with a revised proposal.
4. Given approved tasks, When the Web UI /goals/:id page is opened, Then the full task tree is visible with titles, ancestry, statuses, and budgets.

---

User Story 3 - Coordinator proposes spawning a specialist agent (Priority: P1)

For a leaf task whose specialist does not yet exist, the coordinator calls propose_agent with a desired name, system prompt, tool scope, skills bundle, MCP server list, autonomy tier, and parent task. SynapBus writes an agent_proposals row and posts an approval message to #approvals. The human reviews the proposed configuration, reacts with approve, and SynapBus materializes a real agent: a new agents row with a computed config_hash, a freshly-generated API key, parent_agent_id pointing to the coordinator, spawn_depth one greater than the coordinator's, and an initial reputation snapshot seeded at 70 % of the parent's domain reputation. The new agent's credentials are DMed to the proposer. If the proposed tier or tool scope exceeds the parent's own grant, the proposal is rejected server-side before ever reaching the human.

Why this priority: Dynamic spawning is the heart of the whole feature. Without it, the system is just a prettier task tree. It must be demonstrably gated by human approval, capped by the delegation rule, and stamped with a reproducible config hash.

Independent Test: Given an existing coordinator agent owned by the human, call propose_agent with a valid proposal referencing a leaf task. Verify an agent_proposals row exists and an approval message is in #approvals. React approve. Verify a new agents row exists with computed config_hash, parent_agent_id, spawn_depth=parent.spawn_depth+1, and a seeded reputation row.

Acceptance Scenarios:

1. Given a coordinator at spawn_depth=0, When it calls propose_agent for a leaf task with a system prompt, tool list, and tier assisted, Then an agent_proposals row is created, an approval message is posted to #approvals, and no agents row exists yet.
2. Given a pending agent proposal, When the human reacts approve, Then a new agents row is created with config_hash, parent_agent_id set to the coordinator, spawn_depth=1, autonomy_tier not exceeding the coordinator's, a freshly-generated API key, a seeded reputation ledger row, and a DM is sent to the coordinator with the new agent's credentials.
3. Given a pending agent proposal, When the human reacts reject, Then no agent is created, the proposer is DMed the rejection, and the linked task remains at approved with no assignee.
4. Given a parent agent at spawn_depth=2, When it proposes a child at the default max depth cap of 3, Then the spawn is rejected with ErrSpawnDepthExceeded before the proposal is even written.
5. Given a parent agent with a tool_scope that does not include attachments:write, When it proposes a child whose tool scope includes attachments:write, Then the spawn is rejected server-side with ErrDelegationCapExceeded and no approval message is posted.
6. Given an existing agent, When its configuration is updated (system prompt, tools, or skills changed), Then its config_hash is recomputed and updated, and its reputation is re-seeded from the old hash at 70 %.

---

User Story 4 - Spawned specialist claims a task and runs on a heartbeat (Priority: P1)

After the specialist agent is materialized, the coordinator assigns it to the relevant leaf task (or the specialist claims a task from a pool it is eligible for). Claiming is atomic: a single UPDATE statement sets assignee_agent_id only if the task is still unclaimed. On success, the reactor fires a heartbeat that launches the agent's subprocess run under the harness with full goal ancestry, task description, acceptance criteria, and scoped secrets injected as environment variables. The agent does its work, posts artifacts (messages, attachments, or external links) to the goal channel, and transitions the task to awaiting_verification.

Why this priority: Spawning an agent is useless if it cannot actually run and produce output. This story is the first observable value the user gets from a specialist.

Independent Test: Given an approved leaf task and a matching specialist agent, call claim_task as that agent. Verify the task transitions to claimed and the reactor schedules a heartbeat. Let the subprocess run, then verify the task is at awaiting_verification and an artifact message exists in the goal channel.

Acceptance Scenarios:

1. Given two specialist agents racing to claim the same task, When both call claim_task, Then exactly one claim succeeds and the other receives ErrAlreadyClaimed.
2. Given a successfully claimed task, When the reactor heartbeat fires, Then the harness subprocess is launched with the agent's system_prompt, the task description, the full ancestry_json of the task, scoped secrets, and the OTel trace context.
3. Given a running subprocess, When it completes, Then a harness_runs row is written with task_id set, the leaf task's spent_tokens / spent_dollars_cents are incremented, and the task transitions to awaiting_verification with a completion_message_id pointing at the artifact.
4. Given a task at awaiting_verification, When the goal channel is queried, Then at least one system message describing the completion exists, and the harness run is visible on the agent detail page.

---

User Story 5 - Verification gate before a task is considered done (Priority: P1)

When a task enters awaiting_verification, the reactor reads the task's verifier_config. If set to peer, a peer agent's verify_task MCP tool is invoked; if set to command, a shell command is executed and the exit code determines the verdict; if unset, the task auto-transitions to done. Successful verification moves the task to done and increments the assignee's reputation for the relevant domain; failed verification moves the task to failed, DMs the coordinator, and kicks off iteration.

Why this priority: Artifacts without verification are worthless in the target use cases — the whole motivation is "results must be verified." Verification is what makes the system trustworthy enough to run unattended.

Independent Test: Configure a task with a peer verifier pointing at a specific agent's verify_task tool. Transition the task to awaiting_verification. Verify the peer's tool is invoked, the verdict is recorded, and the task reaches done or failed accordingly.

Acceptance Scenarios:

1. Given a task with verifier_config set to auto-approve, When the task transitions to awaiting_verification, Then it immediately transitions to done without any verifier being called.
2. Given a task with verifier_config set to a peer agent's verify_task tool, When the task transitions to awaiting_verification, Then the peer's verify_task is invoked with the task id, acceptance criteria, and artifact references; the returned verdict is written to the task.
3. Given a task with verifier_config set to a shell command, When the task transitions to awaiting_verification, Then the command runs with the task's context in env vars, and exit code 0 means approve and anything else means reject.
4. Given a task that failed verification, When the coordinator is DMed the failure, Then the coordinator may either respawn the task with a revised configuration or mark the goal stuck for the human to inspect.
5. Given a task that passed verification, When the reputation ledger is inspected, Then a new positive-evidence row is appended for the assignee's config_hash in the task's billing-code-derived domain.

---

User Story 6 - Agent requests a missing resource from the human (Priority: P2)

A specialist agent discovers it needs an API key or credential it does not have (for example, a BREVO_API_KEY to send an email). It calls request_resource with the resource name, type, reason, and task id. SynapBus writes a resource_request row and posts a structured approval message to #requests. The human sets the value via synapbus secrets set BREVO_API_KEY <value> --scope agent:doc-gardener-scanner. On next run, the secret is injected as an env var. The secret's plaintext value is never returned from any MCP tool — only its name and availability are queryable via list_resources.

Why this priority: Real-world specialists will hit credential gaps. Without this protocol, every gap stops the run. It is P2 because the doc-gardener example does not strictly require it — but the OSS-visibility example cannot function without it.

Independent Test: Call request_resource as a specialist. Verify a request message is in #requests. Run synapbus secrets set to provide the value. Restart the agent's heartbeat. Verify the subprocess sees the env var, and list_resources returns the name but never the value.

Acceptance Scenarios:

1. Given a running specialist, When it calls request_resource, Then a resource_requests row is created and a structured message is posted to #requests with {resource_name, resource_type, reason, task_id}.
2. Given a pending resource request, When the human runs synapbus secrets set NAME <value> --scope agent:foo, Then an encrypted secret is stored in the secrets table scoped to the agent, the request is marked fulfilled, and the requester is DMed.
3. Given a scoped secret, When the owning agent's next harness run is launched, Then the secret is injected as an environment variable whose name is sanitized (alphanumeric + underscore, uppercased) and whose value is plaintext only inside the subprocess.
4. Given a scoped secret, When any MCP tool queries secrets, Then only names and availability are returned; plaintext values are never returned via MCP.
5. Given a revoked secret, When a subsequent run is launched, Then the env var is not injected and a warning is posted to the goal channel.

---

User Story 7 - Budget cascade, soft alert, and hard auto-pause (Priority: P2)

Each goal has a total budget in both tokens and dollars. Each task may have its own sub-budget. When a specialist runs and a harness_runs row is written, the leaf task's spend is incremented, and the goal's rollup is recomputed on demand. At 80 % spend against any goal or task budget, SynapBus posts a soft-alert system message to the goal channel. At 100 %, the goal (or task) transitions to paused, the reactor refuses to launch further runs for the affected subtree, and a DM is sent to the human owner.

Why this priority: Without budgets, a runaway coordinator could burn unlimited tokens. P2 because the alert/pause is not strictly required to complete one successful run of the example, but it is required to ship the feature safely.

Independent Test: Create a goal with a budget_dollars_cents=100 and a specialist whose harness runs cost 40 and 45 cents each. Run twice. After run two, verify a soft alert was posted to the goal channel. Run a third time. Verify the new run is refused and the goal is paused.

Acceptance Scenarios:

1. Given a goal with budget $1.00 and cumulative spend under $0.80, When a new harness run writes $0.05, Then no alert is posted and the run proceeds normally.
2. Given cumulative spend crossing $0.80, When the recomputation happens, Then a single soft-alert system message is posted to the goal channel naming the goal and the percentage used (idempotent across runs).
3. Given cumulative spend reaching $1.00, When the next run is attempted, Then the goal transitions to paused, the run is rejected with ErrGoalBudgetExceeded, and the human owner is DMed.
4. Given a paused goal, When the human increases the budget and calls resume_goal, Then the status returns to active and new runs may be scheduled.

---

User Story 8 - Quarantine on low reputation (Priority: P3)

If an agent's rolling reputation (averaged across domains) drops below the default threshold of 0.3, the agent is automatically quarantined: its status is set to quarantined, no new task claims are permitted, existing runs finish, and the owner is DMed. Quarantine survives restarts and must be cleared manually.

Why this priority: A safety net against a broken or hostile agent eating all the budget. P3 because the acceptance test for v1 does not hinge on triggering it — but it must be wired up and testable.

Independent Test: Manually append enough negative-evidence rows to a test agent's reputation ledger to drive its rolling average below 0.3. Trigger the quarantine check (ticker or on-demand). Verify status='quarantined', a DM to the owner, and that subsequent claim_task calls by that agent fail with ErrAgentQuarantined.

Acceptance Scenarios:

1. Given an agent whose rolling reputation is 0.4, When a new negative-evidence row drops it to 0.29, Then the reactor transitions the agent to quarantined within one heartbeat and DMs the owner.
2. Given a quarantined agent, When it tries to claim a task, Then the claim fails with ErrAgentQuarantined and no state changes.
3. Given a quarantined agent with a running subprocess, When the subprocess completes, Then its results are still recorded (reputation updated, artifacts posted), but no new runs are scheduled.
4. Given a quarantined agent, When the human calls unquarantine_agent, Then the agent returns to status='active' and can claim tasks again.

---

User Story 9 - Doc-gardener example runs end-to-end (Priority: P1)

A human runs ./start.sh && ./run_task.sh in the new examples/doc-gardener/ directory. The example creates the goal "Make docs.mcpproxy.app documentation accurate against the current source code", bootstraps a coordinator, lets it decompose into sub-tasks (scan source code for CLI flags, scan deployed docs for mentioned flags, diff them, report gaps), auto-approves the spawning proposals using a pre-set --auto-approve flag on the example script (no human in the loop during the demo), runs the specialists, captures artifacts, and generates an HTML report at examples/doc-gardener/report.html showing the goal tree, spawned agents, spend per billing code, reputation deltas, and a timeline.

Why this priority: This is the acceptance test that proves all other stories work together. If this runs, the feature ships.

Independent Test: In a clean checkout, run the example end-to-end. Verify the HTML report is generated and shows a non-empty task tree, at least one spawned specialist, a non-zero token spend, and a final status of either completed or stuck with reason.

Acceptance Scenarios:

1. Given a clean checkout with no synapbus instance running, When the user runs ./start.sh, Then a fresh synapbus binary is built, a separate instance is launched on port 18088 with a local ./data directory, a user and a coordinator agent are created, and the base #approvals, #requests channels exist.
2. Given a started instance, When the user runs ./run_task.sh --auto-approve, Then a goal is created, the coordinator produces a task tree proposal, the auto-approver approves it, specialist agent proposals are made and auto-approved, specialists are spawned, their heartbeats fire, artifacts are posted to the goal channel, and the run terminates within the default budget.
3. Given a completed run, When the user runs ./report.sh, Then report.html is written containing the goal title, the task tree with statuses, the list of spawned agents with their config_hash and reputation deltas, a cost table broken down by billing code, and a chronological timeline of state transitions.
4. Given a running instance, When the user opens the Web UI at http://localhost:18088/goals, Then the goal appears with its tree, backing channel, and real-time status updates.

---

Edge Cases

• Race on claim: two specialists call claim_task on the same task in the same millisecond. The atomic UPDATE guarantees exactly one wins; the loser receives ErrAlreadyClaimed. Verified by a concurrency integration test.
• Race on spawn: two peer agents simultaneously propose children of the same name. Proposals are independent rows; both proceed to approval. The human picks one; the second should be rejected with ErrAgentNameTaken on materialization — not at proposal time — so the human still sees both alternatives.
• Coordinator dies mid-decomposition: the proposal message is posted but no tasks have been materialized. The goal remains draft. The coordinator is respawned on its next heartbeat; idempotency is provided by the coordinator checking "does an active proposal already exist for this goal?" before posting a new one.
• Budget check races a harness run: the reactor must check goal.status != 'paused' and budget_remaining > 0 inside the same transaction that writes the harness_runs row; otherwise a concurrent two-runs-at-80 %-each could both pass the check and blow the budget. Solved by a compensating adjustment step: if the post-run recomputation pushes total over the budget, the goal is still paused, the alert is still posted, and the over-run is recorded in the ledger.
• Config update for an in-flight agent: an owner edits an agent's system prompt while a run is in progress. The run finishes with the old config; the new config_hash takes effect on the next run; the reputation attributed to the in-flight run belongs to the old hash.
• Resource request posted but no task id: rejected with ErrMissingTaskContext. Every request must cite a task.
• Secret revoked mid-run: the subprocess already has the env var; it continues. On next run the env var is absent and the agent must request it again.
• Ancestry overflow: a pathological 100-level deep decomposition would produce huge ancestry snapshots. Hard cap on ancestry_json length of 16 KB; over-cap tasks must be rejected at creation.
• Reputation divide-by-zero: an agent with zero evidence rows has undefined reputation. Treat as 0.5 (neutral) for gating decisions; do not quarantine an agent that has never been evaluated.
• Goal channel name collision: slug generation normalizes and deduplicates — suffix -2, -3, etc.
• Pause/resume during verification: a task at awaiting_verification when the goal is paused must still complete its verification (so the result is not lost), but the verdict is recorded and the task's state change does not trigger further spawning until the goal resumes.

Requirements (mandatory)

Functional Requirements

Goal and task model

• FR-001: System MUST allow a human owner to create a goal with a title and free-text description, returning a goal id and a backing channel.
• FR-002: System MUST auto-create a #goal-<slug> channel on goal creation, with the owner as a member.
• FR-003: System MUST store tasks in a first-class tasks table with parent/child linkage, denormalized goal ancestry, depth, title, description, acceptance criteria, assignee, status, budgets, and spend fields.
• FR-004: System MUST enforce a task state machine: proposed → approved → claimed → in_progress → awaiting_verification → done | failed, plus cancelled from any state.
• FR-005: System MUST guarantee atomic single-assignee claim via an optimistic-lock UPDATE; a lost race MUST return ErrAlreadyClaimed without side effects.
• FR-006: System MUST snapshot the full root-to-parent ancestry as JSON on each task at creation time and not propagate parent renames.
• FR-007: System MUST support a recursive-CTE cost rollup query from any task node down to all descendants, summing spent_tokens and spent_dollars_cents.
• FR-008: System MUST post a system message to the goal's backing channel on every task state transition with task id, title, old status, new status, and an actor reference.
• FR-009: System MUST extend the harness_runs table with a nullable task_id column, and the reactor MUST write it on every run launched in a task context.

Dynamic spawning and trust

• FR-010: System MUST provide an MCP tool propose_agent that accepts a proposed name, model, system prompt, tool scope, skills, MCP servers, autonomy tier, parent task id, and reason; and writes an agent_proposals row plus an approval message in #approvals.
• FR-011: System MUST reject a proposal at propose_agent time if the caller's spawn_depth + 1 exceeds the goal's max depth (default 3), or if the proposed grant in any dimension exceeds the caller's own grant under the delegation cap rule.
• FR-012: System MUST allow the human owner to reject or approve a proposal via a reaction (approve or reject) on the proposal message.
• FR-013: System MUST, on approval, atomically create a new agent record with a computed config_hash = SHA-256(model + system_prompt + tools + skills + mcp_servers + subagents), parent_agent_id set to the proposer, spawn_depth set to the proposer's + 1, a freshly-generated API key, and an initial reputation ledger row seeded at 70 % of the parent's reputation for the matching domain.
• FR-014: System MUST promote system_prompt to a first-class column on the agents table; existing agents MUST be migrated with their prompt extracted from harness_config_json where present.
• FR-015: System MUST recompute config_hash on every config change and re-seed reputation at 70 % of the prior hash's rolling value.
• FR-016: System MUST support three autonomy tiers (supervised, assisted, autonomous) stored on the agents table and enforced at tool-call time by the harness.
• FR-017: System MUST store reputation as an append-only ledger keyed by (config_hash, task_domain), with each row carrying score_delta, evidence_ref, and created_at.
• FR-018: System MUST expose a rolling-reputation read query that computes the current score with exponential time-decay (half-life configurable, default 30 days).

Budgets and quarantine

• FR-019: System MUST enforce a per-goal token and dollar budget; if a run would push cumulative spend over 100 %, the goal MUST be transitioned to paused and the run rejected.
• FR-020: System MUST post a one-time soft-alert message to the goal's backing channel when cumulative spend first crosses 80 %.
• FR-021: System MUST cascade budgets at delegation: creating a sub-task under a parent task MUST subtract the child's budget from the parent's remaining budget, and fail if the parent cannot cover it.
• FR-022: System MUST support a free-form billing_code column on tasks and a rollup query summing spend by billing code within a goal subtree.
• FR-023: System MUST auto-transition an agent to quarantined when its rolling reputation drops below the configured threshold (default 0.3), and reject claim_task calls from quarantined agents with ErrAgentQuarantined.
• FR-024: System MUST allow a human owner to un-quarantine an agent via a CLI command or Web UI action.

Resource-request protocol and secrets

• FR-025: System MUST provide an MCP tool request_resource that writes a resource_requests row and posts a structured request to #requests.
• FR-026: System MUST store secrets in a new secrets table with {name, value_encrypted, scope_type, scope_id, created_at, revoked_at}.
• FR-027: System MUST encrypt secret values at rest under a local master key file and refuse to start if the master key is missing or malformed.
• FR-028: System MUST inject scoped secrets as environment variables when launching a subprocess harness run, with variable names sanitized to [A-Z0-9_]+ and uppercased.
• FR-029: System MUST provide an MCP tool list_resources that returns only names and availability, never plaintext values.
• FR-030: System MUST provide a CLI command synapbus secrets set <name> <value> --scope <type:id> and a matching synapbus secrets revoke.

Coordinator and verification

• FR-031: System MUST ship a pre-built coordinator agent definition (system prompt, tool scope, default model placeholder) loadable via the example setup script or via synapbus agents create-coordinator <goal_id>.
• FR-032: System MUST provide an MCP tool create_goal callable by the human owner.
• FR-033: System MUST provide an MCP tool propose_task_tree callable by the coordinator, which writes a structured proposal message to #approvals.
• FR-034: System MUST support three verifier kinds in verifier_config: peer, command, and auto. The reactor MUST invoke the configured verifier on task transition into awaiting_verification and write the verdict to tasks.status.
• FR-035: System MUST provide an MCP tool verify_task for peer agents, returning {verdict: approve|reject, reason}.
• FR-036: System MUST, on verification failure, DM the coordinator with the task id, verdict, and reason; the coordinator may respawn the task or mark the goal stuck.

Heartbeats

• FR-037: System MUST extend the reactive trigger engine with wake sources task_assignment, task_timer, verification_requested in addition to the existing message_received.
• FR-038: System MUST reuse the existing pending_work coalescing so overlapping wakeups merge into a single run per agent per task.
• FR-039: System MUST propagate OTel trace context across all heartbeat-launched subprocesses.

Web UI

• FR-040: System MUST ship a new /goals page in the Web UI listing all goals with status, owner, total spend, and link to the backing channel.
• FR-041: System MUST ship a new /goals/:id page showing the task tree, per-task status, per-task spend, assignee, and a real-time event timeline of state transitions.
• FR-042: System MUST render approval messages on the #approvals channel with approve / reject buttons that dispatch the existing reaction workflow.

Doc-gardener example

• FR-043: System MUST ship an example at examples/doc-gardener/ with start.sh, stop.sh, run_task.sh, report.sh, configs/, and README.md, mirroring the layout of examples/cold-topic-explainer/.
• FR-044: The example start.sh MUST launch an isolated synapbus instance on a configurable port (default 18088), create a user, create a coordinator agent, and pre-create the #approvals and #requests channels.
• FR-045: The example run_task.sh MUST support an --auto-approve flag that auto-reacts approve to all proposal messages for the duration of the run.
• FR-046: The example report.sh MUST query the DB and render a Go template to report.html containing the goal tree, spawned agents with config_hash and reputation deltas, cost-per-billing-code table, and a chronological timeline.

Key Entities (include if feature involves data)

• Goal: Represents a human-owned high-level objective. Links to a backing channel, a root task, an owner, and a budget. Has a lifecycle: draft → active → paused → completed | cancelled.
• Task: A node in a goal's task tree. Single-assignee, atomically claimable, carries a denormalized ancestry snapshot, acceptance criteria, budget, billing code, spend counters, heartbeat config, and verifier config. Tracks origin / claim / completion message ids for channel audit.
• AgentProposal: A pending request by an agent to spawn a new sub-agent. References parent agent, parent task, desired name, model, system prompt, tool scope, skills, MCP servers, autonomy tier, and reason. Lifecycle: pending → approved | rejected.
• Agent (extended): Existing entity, with new columns config_hash, parent_agent_id, spawn_depth, system_prompt, autonomy_tier, tool_scope.
• ReputationLedger: Append-only history of evidence rows keyed by (config_hash, task_domain). Rolling score derived at read time with time decay.
• ResourceRequest: A structured request from an agent for a named secret, scoped to a task. Lifecycle: pending → fulfilled | rejected | revoked.
• Secret: A name/value pair with a scope (user / agent / task), encrypted at rest, revocable.
• HarnessRun (extended): Existing entity, with a new nullable task_id column, linking a subprocess run to the task that spawned it.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: A human can create a goal from a free-text description, see it in the Web UI, and see its backing channel, in under 10 seconds from typing create_goal to the UI update — measured wall-clock on a laptop with an empty DB.
• SC-002: The doc-gardener example runs end-to-end from ./start.sh && ./run_task.sh --auto-approve && ./report.sh without human intervention and produces an report.html in under 5 minutes of wall-clock time on a developer laptop.
• SC-003: The generated report.html contains at least one goal, one non-trivial task tree (at least 3 nodes), at least one spawned specialist agent, at least one verified-or-failed task outcome, and a non-zero cost breakdown by billing code.
• SC-004: Two concurrent claim_task calls on the same task produce exactly one success and one ErrAlreadyClaimed, verified by a concurrency integration test, over at least 100 repetitions.
• SC-005: A delegation-cap violation (child proposes a grant exceeding parent's) is rejected server-side in every case, never reaching the human — verified by a unit test over the full autonomy-tier matrix.
• SC-006: A goal whose cumulative spend crosses 80 % receives exactly one soft-alert message, and a goal whose spend reaches 100 % is auto-paused within the same transaction that wrote the over-budget run — verified by a budget-race integration test.
• SC-007: On any agent config change, the config_hash changes and the new hash's reputation equals exactly 70 % (±1 %) of the old hash's rolling value — verified by a reputation-migration unit test.
• SC-008: All new MCP tools (create_goal, propose_task_tree, propose_agent, claim_task, verify_task, request_resource, list_resources) appear in the MCP server's tools/list response and are invocable end-to-end via the MCP transport in an integration test.
• SC-009: All new tables have table-driven unit tests with at least one happy-path and one sad-path case per core method, and the service layer has at least one integration test per user story above.
• SC-010: The binary built from this branch cross-compiles for linux/amd64 and darwin/arm64 with no CGO — verified by GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build ./... and GOOS=darwin GOARCH=arm64 CGO_ENABLED=0 go build ./... in CI.
• SC-011: The Web UI /goals page loads within 1 second for a DB containing 100 goals and 1000 tasks, measured by a light smoke test.
• SC-012: A specialist that requests a resource via request_resource, receives a value via synapbus secrets set, and runs again, sees the env var on its next run in 100 % of cases — verified by an integration test of the full request → set → inject loop.