@brokkai/brokk-town 0.6.2 → 0.6.4

package/README.md

@@ -4,6 +4,13 @@ Brokk Town is a local service that coordinates independent repository bots throu
 private worker processes. Use the browser to watch and control work, or the CLI
 for scripts. Everything runs on your machine.
 
+The browser has two themes. The default is the town; Frontline draws every
+repository as a base flying one of three armies — humans, humanoid aliens or a
+swarm — and every committed delivery as a strike between its installations. The
+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
 
 ```sh
@@ -13,21 +20,24 @@ make build
 ./bin/bt web --demo
 ```
 
-Bare `bt` runs in the foreground and prints its browser URL. Ctrl+C, SIGTERM or
+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                     # explicitly start in the background
-bt service status
+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 service stop           # stop Town and its bots
+bt shutdown               # stop Town and its bots
 ```
 
-Client commands require a running service. There is no login registration,
+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.
-`bt serve` is an explicit alias for foreground operation. Use `--state-dir` for
-an independent installation and `--listen` for a loopback address.
+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
 
@@ -81,7 +91,7 @@ bt
 # In another terminal:
 bt add --repo OWNER/REPO
 bt start --repo OWNER/REPO --role issue
-bt capacity --max-workers 4
+bt settings --max-workers 4
 ```
 
 Each configured town starts all eight bot processes immediately, including paused
@@ -177,6 +187,51 @@ 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:
+
+```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
+```
+
+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
@@ -254,7 +309,7 @@ the confirmation status and a link to the issue. Demo submissions stay local.
 ```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 check-request --repo BrokkAi/my-project --request-id SAVED_ID
+./bin/bt request --repo BrokkAi/my-project --check --request-id SAVED_ID
 ```
 
 Requests have durable IDs, and the CLI prints the ID before sending. If the
@@ -273,8 +328,13 @@ To remove a town, choose **Settings → Delete town** and confirm, or run:
 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. Wait for stopping workers to
+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.
 
 ## How work moves
@@ -303,7 +363,9 @@ 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 declined PR is ignored rather than closed.
+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
@@ -343,7 +405,8 @@ limit its authority to publish while forbidding its release-preparation PR merge
 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**.
+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.
 
@@ -353,19 +416,21 @@ Copy [docs/config.example.json](docs/config.example.json), edit the repository,
 bot profiles, verification command, and policy, then run:
 
 ```sh
-./bin/bt serve --config /path/to/towns.json
+./bin/bt --config /path/to/towns.json
 ```
 
-Configuration is a JSON array for town-only files. Each entry supplies `repo`, optional `branch` and
+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. To persist global capacity alongside the town list,
-use the object form `{"max_workers": 2, "towns": [...]}`; the legacy array form
-remains accepted. When `serve --config` includes `max_workers`, that value
-overrides the persisted service setting in the same atomic state update; an
-array config without it preserves the saved limit. Town
+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
@@ -390,7 +455,9 @@ Repo-bot and issue/review scheduling use `poll_seconds` (default 60). Quiet repo
 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 has a two-hour deadline. A pull request
+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.
 
@@ -500,9 +567,37 @@ the reported failure and ask Town to lift the budget:
 
 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. Town never edits the bot's private state. The pinned Release
+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` to inspect saved details and GitHub to resolve conflicts.
+Use `bt status --json` to inspect saved details and GitHub to resolve conflicts.
+
+### Snoozing one task
+
+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:
+
+```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
+```
+
+`--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

package/licenses/THIRD_PARTY_NOTICES.txt

@@ -8,9 +8,9 @@ Node.js and Python interpreters are installed separately and are not bundled.
 
 ==============================================================================
 
-github.com/BrokkAi/acp-go v0.1.0
+github.com/BrokkAi/acp-go v0.8.1
 License: Apache-2.0
-Source: https://github.com/BrokkAi/acp-go/tree/v0.1.0
+Source: https://github.com/BrokkAi/acp-go/tree/v0.8.1
 
 ==============================================================================
 
@@ -221,6 +221,25 @@ Source: https://github.com/BrokkAi/acp-go/tree/v0.1.0
 
 ==============================================================================
 
+--- github.com/BrokkAi/acp-go/NOTICE ---
+
+acp-go
+Copyright 2026 Brokk.ai and contributors
+
+This project is licensed under the Apache License, Version 2.0.
+See LICENSE for the full terms. Third-party terms and attribution are
+provided in licenses/THIRD_PARTY_NOTICES.txt.
+
+Originally developed as part of BrokkAi/release-bot.
+
+The pinned Agent Client Protocol JSON Schema artifacts in schema/
+(schema.json, meta.json, VERSION) are distributed by the ACP project
+(https://github.com/agentclientprotocol/agent-client-protocol) under the
+Apache License 2.0. The generated code in schema/*_gen.go derives from
+those artifacts.
+
+==============================================================================
+
 Go runtime and standard library (BSD-3-Clause)
 Source: https://go.googlesource.com/go/+/refs/tags/go1.27.1/LICENSE
 

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.6.2",
+  "version": "0.6.4",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -25,9 +25,9 @@
     "arm64"
   ],
   "optionalDependencies": {
-    "@brokkai/brokk-town-linux-x64": "0.6.2",
-    "@brokkai/brokk-town-linux-arm64": "0.6.2",
-    "@brokkai/brokk-town-darwin-x64": "0.6.2",
-    "@brokkai/brokk-town-darwin-arm64": "0.6.2"
+    "@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"
   }
 }