npm - @brokkai/brokk-town - Versions diffs - 0.6.4 → 0.7.0 - Mend

@brokkai/brokk-town 0.6.4 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2) hide show

package/README.md +90 -541
package/package.json +5 -5

package/README.md CHANGED Viewed

@@ -11,599 +11,148 @@ theme is a look, not a lever: it reads the same snapshot, keeps the theme and
 any race chosen for a base in that browser, and never changes what Town does or writes
 to GitHub.
-## Build and run
+- [Install or build](#install-or-build)
+- [First run](#first-run)
+- [Houses and work](#houses-and-work)
+- [Operator reference](#operator-reference)
+- [Independent bot projects](#independent-bot-projects)
+- [Development](#development)
-```sh
-make build
-./bin/bt --demo
-# In another terminal:
-./bin/bt web --demo
-```
-Bare `bt` runs in the foreground and prints its browser URL. The URL carries the
-access key, so it is printed only to a terminal; redirected output and the
-background service's log point to `bt web` instead. Ctrl+C, SIGTERM or
-SIGHUP stops Town, its bots and their agent processes. Closing the browser does
-not stop the service. Demo mode is isolated and never invokes bots, agents or GitHub.
-```sh
-bt -d                     # start in the background instead
-bt status                 # running or stopped, and which towns it serves
-bt web                    # print the running service's browser URL
-bt shutdown               # stop Town and its bots
-```
-Client commands require a running Town and never start one; `bt status` and
-`bt harnesses` also work while it is stopped. There is no login registration,
-automatic service replacement, terminal UI, version polling or in-app installer.
-Use `--state-dir` for an independent installation and `--listen` for a loopback
-address. Each command accepts only its own flags: `bt COMMAND --help` lists them.
-## Independent bot projects
-The `bots/` directories are standalone projects with their own Go modules, CLI
-commands, tests, documentation and packaging:
-| Project | Command |
-|---|---|
-| bug-bot | bbb |
-| feature-bot | bfb |
-| issue-bot | bib |
-| review-bot | brv |
-| release-bot | brb |
-| repo-bot | brp |
-| simplifier-bot | bsb |
-| mayor-bot | bmb |
-Build any bot by running `go build ./cmd/<command>` inside its directory.
-Town never imports bot Go packages. Each module chooses its own released acp-go
-dependency. The only integration boundary is the local worker protocol.
-`bundle.json` records the exact bot versions supported by this Town build and
-original source commits. `make build` builds all nine executables into `bin/`.
-Town resolves its bots beside its own executable and verifies their versions.
-A standalone `go install` of only `bt` is not a complete Town installation.
-## Installation and releases
+## Install or build
 ```sh
 npm install -g @brokkai/brokk-town
-# Or install a published complete native bundle:
+# Or install the native Town executable:
 sh install.sh vX.Y.Z-town
 ```
-Both installation paths include Town and all eight supported bots. To install a
-new version, stop Town, install the complete package, and start Town again.
+Both installation paths install Town only. Node.js/npm (including `npx`) must
+be available on the Town service PATH. Town starts each bot through its separately
+published npm package, resolving `@latest` when a worker starts and using that
+exact version for its lifetime. Restart Town to pick up new bot releases.
+To update Town itself, stop it, install the new package, and start it again.
 The shell installer requires Python 3 and keeps each complete installation in
 its own directory under `INSTALL_DIR/.brokk-town`, with `bt` pointing to it.
 Projects have independent versions and suffix release tags: `vX.Y.Z-town`,
-`vX.Y.Z-issue-bot`, and equivalent tags for the other bots. A Town release bundles
-the versions in its manifest without publishing unchanged standalone bots.
+`vX.Y.Z-issue-bot`, and equivalent tags for the other bots. Bot releases retain
+older versioned worker APIs, so a newer bot continues to serve the API an existing
+Town uses.
 See [RELEASING.md](RELEASING.md) for workflows and publishing configuration.
-## Connect repositories
-Authenticate `gh` and your chosen agent first. Start Town, then add a repository:
-```sh
-bt
-# In another terminal:
-bt add --repo OWNER/REPO
-bt start --repo OWNER/REPO --role issue
-bt settings --max-workers 4
-```
-Each configured town starts all eight bot processes immediately, including paused
-houses. Pausing controls work; it does not remove the process. Agents start only
-when jobs are dispatched. Repo Bot begins with read-only inventory; automation
-houses start paused. Existing concurrency limits and GitHub authority checks apply.
-Deleting a town stops its workers. Ending Town stops every worker. A lost parent
-pipe also stops workers after an unexpected Town exit. An interrupted write remains
-uncertain until repository reconciliation or an explicit retry establishes what
-happened; a restart never blindly repeats it.
-## Town settings, requests, and deletion
-Visit a town and choose **Settings**, then use **Configure agent for** to select
-the bot and configure its agent, model, and reasoning effort independently. Bug,
-feature, issue, review, release, simplifier, and repo bots can each use a different profile. Bots
-without a profile inherit **Town defaults**. Choose **Use town defaults** and save
-to remove a bot's independent profile. Save each changed profile before closing
-Settings. Repo Bot inventories the repository without an agent, then uses its
-configured profile only when repairing a failing branch. Choose **Repo Bot** in
-the profile selector to configure that repair agent.
-**Simplifier decisions** selects `suggest` (the default) or `auto`. Suggest keeps
-the Mayor as decision maker and shows Simplifier Bot's advice on every pending
-arrival. Auto lets the bot's assessment route routine work without a separate
-Mayoral decision, including closing low-value complex issues.
-### What each bot takes on
-Each house can be told what work to accept and how much of it to produce. Every
-setting here is one the bot already supports, and a house refuses a setting it
-cannot honour rather than accepting it and ignoring it:
-| Setting | Flag | Houses |
-| --- | --- | --- |
-| Required labels | `--labels` | bug, feature, issue, review, simplifier |
-| Excluded labels | `--exclude-labels` | issue, review |
-| One selected item | `--only` | issue (an issue number), review (a PR number) |
-| Discovery focus | `--focus` | bug, feature, review |
-| Per-run limit | `--limit` | bug/feature (issues filed), review (findings), simplifier (proposals), repo (repair attempts per revision), hall (bulletin items) |
-| Attempts per item | `--attempts` | bug, feature, issue, review, release |
-| Verification command | `--verify` | every house; overrides the town's `verify` |
-| Release cadence, preflight, required workflows and assets | `--release-*` | release |
-```sh
-./bin/bt settings --repo BrokkAi/my-project --role issue --labels agent-ready --exclude-labels needs-discussion
-./bin/bt settings --repo BrokkAi/my-project --role issue --only 412
-./bin/bt settings --repo BrokkAi/my-project --role bug --focus 'the storage layer' --limit 3
-./bin/bt settings --repo BrokkAi/my-project --role review --verify '["make","review-check"]'
-./bin/bt settings --repo BrokkAi/my-project --role release --release-quiet-seconds 900 --release-burst 10 --release-burst-window-seconds 3600 --release-triage on
-./bin/bt settings --repo BrokkAi/my-project --role issue --clear-policy
-```
-Config-file towns take the same settings under `bot_policies`, keyed by house;
-the example lists every supported field. A town that sets none behaves exactly
-as it did before these settings existed.
-Town applies the same filters to its own queue that it sends to the bot, so the
-queue you read is the queue the house will take from. Filtered work is not
-hidden: each house's inspector states its policy, counts the inventory it holds
-back, and marks each held item, so you can always see what your own filter
-excluded. A house whose bundled bot is too old to read a policy is refused the
-dispatch with the bot and version named, instead of running unfiltered.
-### Agent budgets
-A town can bound how much automation it starts in a repeating accounting period:
+To build from source, use the Go version declared in [go.mod](go.mod):
 ```sh
-./bin/bt settings --repo BrokkAi/my-project --budget-period day --budget-attempts 40 --budget-agent-minutes 600
-./bin/bt settings --repo BrokkAi/my-project --budget-period none
+make build
+export PATH="$PWD/bin:$PATH"
 ```
-The period is `day`, `week`, or `month` on your local clock, and at least one of
-`--budget-attempts` or `--budget-agent-minutes` is required. Config-file towns
-take the same settings as `"budget": {"period": "day", "max_attempts": 40,
-"max_agent_minutes": 600}`.
-Town charges the budget for every attempt that started an agent. A repository
-inventory reads GitHub without one and is never charged; a branch repair is.
-When a ceiling is reached, Town stops dispatching new agent work for that town
-and says so in Town Hall with the time the period resets. Work already running
-finishes normally, cancellation and saved work are untouched, and the repository
-inventory keeps running so uncertain writes can still be reconciled. Other towns
-are unaffected: a budget is per town, not per worker slot.
-**Town cannot cap token or dollar spend.** No bundled agent harness reports usage
-back through the worker protocol -- the acp-go runner hands a bot the agent's
-final text and nothing else -- so Town would be enforcing a limit against numbers
-it never receives. Attempts and agent minutes are what it measures, so those are
-what it enforces. Where usage or cost is missing, Town Hall prints "not
-reported"; it never shows absent telemetry as zero. Attempts whose elapsed time
-never arrived are counted and reported separately rather than billed as free.
-### Quiet hours
-Quiet hours are weekly windows in which Town starts no new agent work and
-makes none of its own GitHub writes: no filing, repairing, reviewing, merging
-or releasing. Set a default for every town, give one town its own windows, or
-opt one town out:
+This builds `bin/bt`. Bot source builds and releases are independent.
-```sh
-# Service default: weeknights and weekends.
-./bin/bt settings --quiet-hours "mon-fri 19:00-07:00; weekends 00:00-24:00"
-./bin/bt settings --quiet-hours none            # remove the service default
-# One town's own windows, none at all, or back to the service default.
-./bin/bt settings --repo BrokkAi/my-project --quiet-hours "daily 12:00-13:00"
-./bin/bt settings --repo BrokkAi/my-project --quiet-hours none
-./bin/bt settings --repo BrokkAi/my-project --quiet-hours default
-```
+## First run
-Each window is `DAYS HH:MM-HH:MM`, joined with `;`. Days are `mon` through
-`sun`, ranges such as `mon-fri` or `fri-mon`, or `daily`, `weekdays` and
-`weekends`, and name the day a window starts. An end at or before the start runs
-past midnight into the next day, and `24:00` ends a window at midnight.
-Overlapping windows count as one. A window with no day, an unknown day, a time
-that is not `HH:MM`, or the same start and end is refused with the reason. The
-browser edits the same schedules: the service default under Capacity, and a
-town's own in Town settings. Config files take `"quiet_hours": [{"days":
-["mon"], "start": "19:00", "end": "07:00"}]` at the top level for the default
-and in a town entry for its own, where `[]` opts the town out.
-Windows are read on the local clock of the machine running Town, by the clock
-on the wall: a window holds through a daylight-saving change, an hour the clock
-skips is never quiet, and an hour it repeats is quiet both times.
-Inside a window, work already running finishes as it would after Pause, and
-the repository inventory keeps running so uncertain writes are still
-reconciled. Town leaves closing declined issues and retired pull requests and
-filing review follow-ups for the first inventory after the window. Issues you
-submit yourself are still posted. Houses stay awake: the browser shows them as
-*quiet* rather than paused, the town header reads "Quiet hours · until …",
-Town Hall explains the hold, and `bt status --json` carries the same `quiet_hours`
-state for each town. When the window ends, scheduling resumes on its own with
-each house's usual cadence; nothing missed is replayed. Pause and quiet hours
-are independent and both survive a restart: a paused house stays paused after
-the window, and a woken one resumes. Release Bot's own release quiet period
-(`--release-quiet-seconds`) is unrelated and keeps working as before.
-For each profile, select any agent from the
-[official ACP registry](https://agentclientprotocol.com/get-started/registry),
-plus **Anvil**, **Muse ACP**, **Draupnir**, or a custom ACP command. The full
-catalog loads from a bundled snapshot or local cache, then refreshes in the
-background when stale. **Refresh registry** checks for new agents and versions;
-failed refreshes preserve the last usable catalog. Demo stays offline.
-Selecting a registry agent saves its version and launch definition with that
-profile. Refreshing the catalog does not upgrade saved profiles. To upgrade, choose
-**Use registry version** in Settings, or pass the version shown by `bt harnesses`
-to `--harness-version`. Active work retains its starting settings.
-Town prepares the registry's distribution on first use: npm packages run through
-`npx --yes`, Python packages through `uvx`, and native archives download into
-Town's private cache. Install Node.js/npm or uv when the selected entry requires
-it. Native installs are shared across workers and check a checksum when the
-registry supplies one. Agents without a distribution for your platform are
-marked unavailable. Provider credentials and login remain the harness's own.
-The additional harnesses use the executable installed on the service's PATH:
-| Harness | Command | Setup |
-| --- | --- | --- |
-| [BrokkAi/anvil](https://github.com/BrokkAi/anvil) | `anvil` | `npm install -g @brokkai/anvil`; configure its model provider. |
-| [BrokkAi/muse-acp](https://github.com/BrokkAi/muse-acp) | `muse-acp` | Install the adapter and Muse Code; authenticate with `muse login`. |
-| [foundev/draupnir](https://github.com/foundev/draupnir) | `draupnir` | Install its release and configure its model provider. |
-These three use your installed versions. Their project links and setup notes
-also appear in Settings. A custom command supports other local ACP agents.
-**Load available choices** prepares and briefly starts the selected bot's harness
-without a work prompt, then lists its advertised models and reasoning efforts.
-Authenticate it in your terminal first. Choose a model before effort: available
-effort levels can depend on it. You can also enter an exact ACP selector value,
-or leave either field blank for the harness default. Unsupported selections fail
-visibly when the worker starts. Switching harnesses clears the previous harness's
-private authentication, command, and mode settings in the selected profile.
-Changing town defaults affects bots that inherit them; independent profiles keep
-their settings. Changes apply to the next worker run.
+Authenticate `gh` and your chosen ACP agent, then start Town:
 ```sh
-./bin/bt harnesses --refresh
-# Without --role, change the town defaults.
-./bin/bt settings --repo BrokkAi/my-project --harness codex
-# Give each bot its own harness and exact selectors from available choices.
-./bin/bt settings --repo BrokkAi/my-project --role review --harness claude --model MODEL_ID --effort EFFORT_ID
-./bin/bt settings --repo BrokkAi/my-project --role issue --harness codex --model MODEL_ID --effort EFFORT_ID
-./bin/bt settings --repo BrokkAi/my-project --role release --harness opencode --model MODEL_ID
-./bin/bt settings --repo BrokkAi/my-project --role bug --harness BrokkAi/anvil
-./bin/bt settings --repo BrokkAi/my-project --role feature --harness custom --agent-command '["my-agent", "--acp"]'
-# Blank selectors use this profile's harness defaults.
-./bin/bt settings --repo BrokkAi/my-project --role review --model '' --effort ''
-# Remove the review profile and follow the town defaults again.
-./bin/bt settings --repo BrokkAi/my-project --role review --inherit
+bt
+# In another terminal:
+bt web
+bt add --repo OWNER/REPO
+bt start --repo OWNER/REPO --role issue
+bt settings --max-workers 4
 ```
-`codex` and `claude` remain aliases for `codex-acp` and `claude-acp`.
-The model and effort IDs above are placeholders: use the exact values advertised
-by the selected harness. An effort such as `xhigh` is available only when that
-harness and model support it.
-For an OpenRouter-backed release bot, select **OpenCode** as its harness,
-authenticate OpenRouter in OpenCode with `/connect`, then load the release bot's
-available choices and select the desired OpenRouter model. OpenCode provides the
-ACP agent and OpenRouter supplies its model. See
-[OpenCode's OpenRouter setup](https://opencode.ai/docs/providers/#openrouter) and
-[ACP support](https://opencode.ai/docs/acp/).
+Open the browser to configure the town's agent profiles and admit work. Repo Bot
+starts enabled to read the repository; the other houses start paused. All eight
+worker processes start when a town is added, but agents start only when jobs are
+dispatched. Repo Bot's configured agent is used only for branch repairs.
-Choose **New request**, select **Feature request** or **Bug report**, and describe
-the work. **Create GitHub issue** posts it to that town's repository and places
-the confirmed issue in the workshop queue. This works while workers are paused;
-start issue-bot when you want implementation to begin. Recent submissions show
-the confirmation status and a link to the issue. Demo submissions stay local.
+For an isolated demo that never invokes bots, agents or GitHub:
 ```sh
-./bin/bt request --repo BrokkAi/my-project --kind feature --title 'Add keyboard navigation' --body-file request.md
-# Use --kind bug for a bug report; --body-file - reads stdin.
-./bin/bt request --repo BrokkAi/my-project --check --request-id SAVED_ID
+bt --demo
+# In another terminal:
+bt web --demo
 ```
-Requests have durable IDs, and the CLI prints the ID before sending. If the
-connection drops, reuse it with `--request-id` and the same content. The browser
-retains the submitted draft in that tab until acknowledgment. An uncertain GitHub
-POST is never automatically repeated: Town looks for its hidden receipt in all
-open and closed issues every five minutes. **Check GitHub for receipt** requests
-an earlier read. Inspect GitHub before manually filing an unconfirmed request again.
-To remove a town, choose **Settings → Delete town** and confirm, or run:
+Bare `bt` runs in the foreground and prints its browser URL. The URL contains the
+access key and is printed only to a terminal; use `bt web` when output is
+redirected. Ctrl+C, SIGTERM or SIGHUP stops Town, its bots and their agents.
+Closing the browser leaves the service running.
 ```sh
-./bin/bt delete --repo BrokkAi/my-project
+bt -d           # start in the background
+bt status       # show whether Town is running and which towns it serves
+bt shutdown     # stop Town and its bots
 ```
-Deletion cancels its workers, cancels queued issue submissions, and removes it
-from the browser and terminal. GitHub repositories, issues, and PRs are preserved.
-Local history, uncertain writes, and private worktrees remain as recovery records.
-Adding the same repository again restores that history and its previous
-settings, with automation paused and the reporter enabled. A merge policy or
-harness/agent choice given with the add replaces the previous one; budgets, work
-policies, bot profiles, funnels and the branch are kept. A deleted town listed in
-`bt --config` is restored with the file's settings, and Town prints a notice. A town
-that already worked on one branch cannot be restored onto another. Deleting a
-town that is already deleted reports `unknown town`. Wait for stopping workers to
-finish before restoring a town.
+Client commands require a running Town and never start one. `bt status` and
+`bt harnesses` also work while it is stopped. Use `--state-dir` for separate state
+and `--listen` for a loopback address. `bt COMMAND --help` lists a command's flags.
+There is no login registration, terminal UI, automatic service replacement,
+version polling, or in-app installer.
-## How work moves
+## Houses and work
 | House | Work and handoff |
 | --- | --- |
 | Bug greenhouse | Runs bug-bot's investigation and verification; observed filed issues travel to issue-bot. |
 | Feature study | Runs feature-bot to discover useful new capabilities, independently review their value and feasibility, and compare existing requests; confirmed feature issues travel to issue-bot. |
 | Simplifier clarifier | Reviews every incoming issue/PR for disproportionate complexity or low value, advises the Mayor, and discovers removal/replacement proposals. |
-| Town Hall (Mayor Bot) | Runs mayor-bot to judge every arrival awaiting a Mayoral decision and to write the town bulletin: the feed of features gained and bugs fixed, written for users. Paused by default; decisions wait for you until it is started. |
+| Town Hall (Mayor Bot) | Runs mayor-bot to judge every arrival awaiting a Mayoral decision and to write the town bulletin: the feed of features gained and bugs fixed, written for users. Also displays Repo Bot reports. Paused by default; decisions wait for you until it is started. |
 | Issue workshop | Runs issue-bot on eligible issues, opens implementation-ready PRs, and repairs Town-owned PR branches from review feedback. |
 | Review observatory | Runs review-bot, independently checks the full change and every retained finding, then returns fixes or waits for merge requirements. |
 | Release depot | Runs release-bot's batching and publishing policy. Confirmed merged/direct commits accumulate here; a published stable release ships only commits proven to be its ancestors. |
 | Repo watchtower | Polls GitHub, reconciles arrivals and revisions, summarizes new commit titles, reports queue growth and blocked work. |
-| Town hall | Stores periodic and event-triggered repo-bot reports. |
-The first complete inventory establishes existing work without a burst of arrival
-animations. Subsequent deliveries follow durable, sequenced state changes.
-Animation never initiates a GitHub write. Reconnecting does not replay previously
-seen deliveries. External PRs receive reviews but their branches are left to their
-authors; only locally recorded Town-created branches enter automatic repair.
-Every new issue and PR first waits at Simplifier Bot (including work filed by
-Bug Bot and Feature Bot and implementation PRs created by Issue Bot). In the
-default **suggest** mode, its bounded assessment is attached to the resulting
-durable Mayoral decision: **Admit** sends the work to Issue Bot or Review Bot;
-**Decline** keeps Town from acting on it. In **auto** mode, Simplifier Bot can
-admit routine work and decline low-value complex work itself; a declined issue is
-closed through Repo-bot, while a contributor's declined PR is ignored rather than
-closed. Town's own declined implementation PR, by either the Mayor or Simplifier
-Bot, is closed like one that failed its second review, and its issue starts over.
-Simplifier Bot's own marked proposals do not recursively pass through intake.
-**Mayor Bot** lives in Town Hall. Start it like any other house and it judges
-every arrival that waits for a Mayoral decision: one worker run per arrival,
-in a detached worktree at the exact revision, from the town's description of
-the item (with Simplifier Bot advice or the Town review attached) and the live
-GitHub source. It answers admit, decline, or, for a bot update, delay, with a
-reason kept on the task; decisions go through the same path as your own clicks
-and are recorded under the Mayor Bot name. A judgment that fails is retried
-twice, fifteen minutes apart, then left for you. The same house writes the
-**town bulletin**, shown in Town Hall under "What changed": after work merges,
-at most every `bulletin_seconds` (default 21600), it summarizes the merged pull
-requests for the people who use the software as features, fixes and
-improvements, each citing its pull requests.
-A review is bound to the exact base, head, PR description, and discussion snapshot. A suppressed
-duplicate comment is still a finding to check. Complete coverage, explicit
-resolution of every concern, and validation evidence are required for a clean
-result. New commits invalidate review readiness.
-Every pull request Town works on ends merged or closed, and nothing waits on a
-person to press retry. The first review sends every finding back to Issue Bot
-for one fix round. If the second review still finds work at or above the town's
-`review_close_severity` (default `P2`, so P1 and P2 close), Town closes the pull
-request, deletes its branch, leaves the findings on the issue, and queues the
-issue for a fresh attempt from the current branch. Findings below the threshold
-are filed as follow-up issues and the pull request merges. A revision gets at
-most two attempts at any step: a reviewer or repair failure earns one more
-attempt after a short delay, and a second failure retires the pull request the
-same way. A contributor's pull request is never closed by Town; it goes to the
-Mayor instead. Review Bot picks pull requests that have never been tried before
-ones that failed, so one bad pull request cannot hold the queue.
-The default merge policy is `bot`: auto-merge eligible Town-created PRs. `manual`
-leaves every merge to the operator; because the current Release Bot protocol cannot
-limit its authority to publish while forbidding its release-preparation PR merges,
-Town pauses Release Bot and rejects attempts to start or retry it under this policy.
-`all` also permits eligible external PRs. Town-managed merges require current clean Town evidence, GitHub mergeability, required checks
-and approvals. Town uses an expected-head squash merge, without admin bypass.
-Change this at any time under **Town Settings → External contributions**, or
-with `./bin/bt settings --repo BrokkAi/my-project --merge-policy manual`.
-Repositories that require a merge queue or prohibit squash merging need manual
-merges for now. GitHub is the final authority at write time.
-## Configuration and recovery
-Copy [docs/config.example.json](docs/config.example.json), edit the repository,
-bot profiles, verification command, and policy, then run:
-```sh
-./bin/bt --config /path/to/towns.json
-```
-Configuration is one JSON object: optional `max_workers` and `quiet_hours` for
-the whole service, and a `towns` array. Each town supplies `repo`, optional `branch` and
-`harness`, `agent`, optional `bot_agents`, optional `verify` argument vector,
-`merge_policy`, `simplifier_mode`, optional `review_close_severity` (`P1`, `P2`
-or `P3`, default `P2`), optional `budget`, optional `bot_policies`,
-`poll_seconds`, `report_seconds`, and `max_cycles`. The example
-lists all required values. A config-file entry gets no defaults for
-`merge_policy`, `poll_seconds`, `report_seconds`, or `max_cycles`: omitting any
-of them rejects the file. The defaults quoted below apply to towns added with
-`bt add` or the browser. When `--config` includes `max_workers`, that value
-overrides the persisted service setting in the same atomic state update; a
-config without it preserves the saved limit. Town
-uses the repository's default branch when omitted, and keeps following it: the
-observed default is recorded as repository state, so renaming it moves the town
-with it and never overwrites a branch you chose. An initialized town's branch
-cannot be changed in place. A town saved by an older Town has the branch observed
-at its first inventory pinned in its configuration; setting `"branch": ""`
-explicitly releases that pin so the town follows the repository default again,
-while omitting the field keeps whatever the town already uses. Omitted towns are retained when loading a config.
-Agent configuration uses acp-go's `command`, `environment`, `auth_method`, `mode`, `model`, and `effort` fields.
-The top-level `harness` and `agent` define town defaults. `bot_agents` maps any of
-`bug`, `feature`, `issue`, `review`, `release`, and `simplifier` to a complete profile containing
-its own `harness` and `agent`, with an optional saved `harness_definition`.
-An absent role follows the town defaults. A configured role is independent:
-blank model or effort uses its harness default, and omitted agent fields do not
-inherit private command, environment, or authentication values from the town.
-The example gives review-bot Claude Code, issue-bot Codex, and release-bot OpenCode;
-bug-bot and feature-bot inherit the town defaults. Select models and efforts after
-authenticating each harness. Verification and scheduling settings remain shared
-at town level.
-Repo-bot and issue/review scheduling use `poll_seconds` (default 60). Quiet reports
-use `report_seconds` (1800). Bug-bot, feature-bot, and simplifier-bot run at most every 30 minutes; mayor-bot
-writes a bulletin at most every `bulletin_seconds` (21600) and only after something merged; release-bot
-checks every five minutes and retains its own quiet window, minimum gap, and
-batching decisions. Each worker attempt, including the repo inventory, has a
-two-hour deadline, and each GitHub call Town makes itself, such as the merge
-gate's read, gives up after one minute. A pull request
-gets one fix round and two attempts per revision at any step; `max_cycles` is
-accepted for compatibility but no longer extends that.
-Feature-bot uses its own effective ACP harness, model, and effort, plus the town's
-optional verifier, with a private workspace and durable publication state.
-It proposes scoped features with user value, repository evidence and acceptance
-criteria. A separate review rejects duplicate, already implemented, rejected or
-uncertain proposals before filing. Its verifier receives `FEATURE_COMMIT` and
-`FEATURE_FINDING`; shared verification commands must support the selected bot's
-environment. New towns keep feature discovery paused until started.
-Town Hall's **Automation outcomes** report separates worker attempts, filed
-findings, submitted implementation PRs, repository-confirmed merges, repair
-rounds, blocked or abandoned work, and verified releases for a selectable
-period. A submitted PR is an artifact rather than an accepted fix. Operators
-can mark each filed finding useful or a false positive only by adding an
-explanation. Records retain task and revision provenance and show elapsed time,
-token usage, and cost as unknown when the worker does not provide them. The CSV
-export includes the repository on every row for comparisons across runs and
-towns.
-Private state defaults to `$XDG_STATE_HOME/brokk-town` or
-`~/.local/state/brokk-town`. `--state-dir` selects another directory; `--demo`
-appends `demo`. A single writer lock, atomic snapshots, per-role bot state, and
-private worktrees keep towns separate. Events, logs, and repo-bot reports have
-bounded recent histories; task, intent, and automation outcome history persists.
-A worker's own log lines and phase changes are committed in batches of at most a
-couple of seconds, because every commit rewrites and fsyncs the whole snapshot;
-the newest line and phase always win, and everything buffered is committed before
-a run's result is.
-Browser access uses a per-service
-local key in a URL fragment. `connection.json` and state snapshots are mode 0600.
-Private agent commands, environment, and authentication configuration are omitted
-from public configuration snapshots for both town defaults and bot profiles;
-each bot's effective harness, model, and effort are visible.
-### Source funnels
-Optional `funnels` make issue intake source-neutral. Each named funnel declares a
-provider, validated location/filter, a local credential reference, explicit
-priority policy, overlap policy, and allowlisted lifecycle mappings. Credential
-references are resolved by adapters at request time; secret values never enter
-Town state, model prompts, events, logs, or public snapshots. Public state shows
-the safe funnel configuration and each normalized item's source identity, URL,
-revision, external state, eligibility, capabilities, priority policy, last sync,
-and typed outcome.
-GitHub funnels support query, `selected_issues`, and comma-separated
-`include_labels`/`exclude_labels`. Focused selections are read by issue identity
-instead of relying on search indexing. `working` and `blocked` mappings translate
-the normalized lifecycle into confirmed label changes. Slack is the second real
-adapter: it reads a configured channel through paginated Web API calls and maps
-configured lifecycle actions to reactions plus bounded thread replies. Slack
-tokens are obtained from a private resolver immediately before each request.
-Read-only funnels and empty per-transition mappings stay visibly unsupported.
-Funnels also recognize provider-native done signals on inbound reads. A Slack
-message with a present `:white_check_mark:` or `:heavy_check_mark:` reaction is
-normalized as **Done**; a GitHub issue whose state is `closed` is normalized as
-**Closed**. Both remain in the durable inventory with their source provenance,
-but become ineligible and leave the worker queue. A GitHub selector must include
-closed issues (for example `is:issue`, not `is:issue is:open`) if Town is to
-observe that transition. Done is based only on an explicit item state or reaction;
-an incomplete or empty inventory never closes missing work by implication.
-Lifecycle mutations use a durable intent before the provider call. A lost
-response remains `uncertain`; reconciliation is read-only and absence of a
-receipt never permits a duplicate label, reaction, comment, or thread reply.
-Incomplete reads, partial discovery, authentication failures, rate limits,
-unsupported actions, and uncertain writes remain distinct outcomes. Funnel
-declaration order is never scheduling priority. Overlapping source identities
-are retained, deduplicated, or rejected only according to the explicit overlap
-policy. Demo and tests use synthetic or fake providers and perform no live source
-or agent automation. See the complete JSON example for GitHub and Slack shapes.
-Local logs and worktrees can contain repository content; keep this directory private.
-If a push or merge response is lost, Town checks GitHub rather than assuming
-success. Inspect the task and its saved intent, then use **Reconcile and retry** or:
-```sh
-./bin/bt retry --repo BrokkAi/my-project --task pr:123
-```
-Retry explicitly permits another attempt after fresh checks. For an uncertain
-repair push, it reuses and verifies the saved commit; it does not rerun the agent.
-If the PR moved, the saved worktree is retained for inspection. A retry also resets
-an exhausted repair budget. Never delete an uncertain intent to force progress.
-Retry clears that one task's block; it never starts a paused house. If the house
-is paused, the task says so and waits for you to start it.
+The browser and CLI use the same committed state. Animation follows recorded
+events and never writes to GitHub. Reviews require evidence tied to the exact
+revision; zero new comments never proves a clean review. Interrupted writes stay
+uncertain until reconciled.
-An uncertain repair is settled by ancestry, not only by an equal revision: once
-the commit Town pushed is proven to be in the pull request's history, the push
-landed, the intent is closed, and the newer revision goes back for review. Town
-never republishes the saved commit over work that built on it.
+See [How work moves](docs/workflow.md) for intake, Mayor decisions, review and
+repair limits, merge authority, release ancestry, and automation outcomes.
-A worktree is kept only while a saved intent still needs it. Repairs that fail
-before anything is pushed release their worktree and its `town-repair-*` branch
-immediately, and the issue house collects worktrees whose intent has since been
-confirmed, so an unattended town does not accumulate them.
+## Operator reference
-When the release house reports that Release Bot's retry budget is exhausted, fix
-the reported failure and ask Town to lift the budget:
+- [Configuration](docs/configuration.md): every bot's agent profile, harnesses,
+  model choices, work policies, budgets, quiet hours, and config-file fields.
+- [Requests and task controls](docs/operations.md): create work, snooze a task,
+  and delete or restore a town.
+- [Recovery and saved work](docs/recovery.md): interrupted workers, uncertain
+  writes, setup diagnostics with `bt doctor`, merge blockers, and explicit task
+  or release retries.
+- [Source funnels](docs/funnels.md): GitHub and Slack intake, credentials,
+  selectors, and source lifecycle guarantees.
+- [Configuration example](docs/config.example.json).
+- [Architecture](docs/ARCHITECTURE.md) and [worker protocol](docs/WORKER_PROTOCOL.md).
-```sh
-./bin/bt retry --repo BrokkAi/my-project --role release
-```
-The next release run first calls the bot's `POST /v1/retry` worker API, which
-resets the pending release's attempt budget in its own workspace, then resumes
-the same release. Unlike a task retry, a release retry also starts the release
-house if it was paused. Town never edits the bot's private state. The pinned Release
-Bot must advertise the `retry` capability; older pins report that plainly.
-Use `bt status --json` to inspect saved details and GitHub to resolve conflicts.
-### Snoozing one task
+## Independent bot projects
-To set one issue or pull request aside without pausing its house, snooze it
-until a chosen time. Open the task in the browser and choose **Snooze…**, or:
+The `bots/` directories are standalone projects with their own Go modules, CLI
+commands, tests, documentation and packaging:
-```sh
-./bin/bt defer --repo BrokkAi/my-project --task pr:123 --until 2d --reason "waiting on the vendor fix"
-./bin/bt defer --repo BrokkAi/my-project --task issue:45 --until 2026-10-01T09:00:00Z
-./bin/bt undefer --repo BrokkAi/my-project --task pr:123
-```
+| Project | Command |
+|---|---|
+| bug-bot | bbb |
+| feature-bot | bfb |
+| issue-bot | bib |
+| review-bot | brv |
+| release-bot | brb |
+| repo-bot | brp |
+| simplifier-bot | bsb |
+| mayor-bot | bmb |
-`--until` takes an RFC 3339 time or a delay from now (`90m`, `4h`, `2d`); the
-resume time must be in the future and within 366 days, and the reason is one
-line of at most 200 characters. The house keeps working the rest of its queue.
-Until the resume time, no agent starts for the snoozed task: Issue, Review and
-Simplifier Bots skip it, Mayor Bot does not judge it, and Town does not merge
-it. A run already under way when you snooze finishes. The Mayor can still decide
-a snoozed arrival by hand.
-The task shows as **Snoozed** with its reason and resume time in the browser
-and in `bt status --json` (`deferred_until`, `defer_reason`). Snoozed is distinct from
-blocked and failed, so a snoozed task does not appear in the inbox. At the
-resume time Town clears the snooze, wakes the house and records the event; the
-snooze is saved state, so it survives a restart and repository reconciliation.
-Resume now (`bt undefer`) makes the task eligible immediately. Finished work
-(merged, closed, declined, or an implemented issue) cannot be snoozed.
-The HTTP listener accepts loopback IPs only (default `127.0.0.1:8099`). Host,
-origin, and bearer key checks protect the local API. A browser supporting WebMCP
-can list towns and navigate to a house through optional page tools. Unsupported
-browsers use the ordinary interface.
+Build any bot by running `go build ./cmd/<command>` inside its directory.
+Town never imports bot Go packages. Each module chooses its own released acp-go
+dependency. The only integration boundary is the local worker protocol.
+Town uses `npx --yes -- @brokkai/PROJECT@latest version` to resolve a bot, then
+starts the exact reported version with `worker --socket PATH`. Protocol ranges,
+required capabilities and the worker identity are checked before dispatch.
+The running version is recorded with each job; a worker never updates mid-job.
+Initial package preparation requires registry access. Bot binaries are held in
+npm's cache, not installed beside `bt`.
 ## Development

package/package.json CHANGED Viewed

@@ -1,5 +1,5 @@
 {
-  "version": "0.6.4",
+  "version": "0.7.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -25,9 +25,9 @@
     "arm64"
   ],
   "optionalDependencies": {
-    "@brokkai/brokk-town-linux-x64": "0.6.4",
-    "@brokkai/brokk-town-linux-arm64": "0.6.4",
-    "@brokkai/brokk-town-darwin-x64": "0.6.4",
-    "@brokkai/brokk-town-darwin-arm64": "0.6.4"
+    "@brokkai/brokk-town-linux-x64": "0.7.0",
+    "@brokkai/brokk-town-linux-arm64": "0.7.0",
+    "@brokkai/brokk-town-darwin-x64": "0.7.0",
+    "@brokkai/brokk-town-darwin-arm64": "0.7.0"
   }
 }