symphony-orchestrator 0.2.3 → 0.2.5

package/README.md

@@ -7,9 +7,13 @@ its own repository-owned Runtime Contract under `.symphony/`.
 
 ## Prerequisites
 
-- GitHub CLI: `gh`
-- A GitHub personal access token available as `GITHUB_TOKEN` or `GH_TOKEN`
 - `codex` CLI available on `PATH` when running real agent sessions
+- For the default GitHub Tracker: GitHub CLI `gh` and a GitHub personal access token available as
+  `GITHUB_TOKEN` or `GH_TOKEN`
+- For the minibeads Local Issue Tracker: the `mb` CLI and a local issue store in the Workspace
+  Repository
+- For the Compozy-backed Local Issue Tracker: a Compozy PRD Run directory under
+  `.compozy/tasks/<task_name>/` in the Workspace Repository
 
 ## Install
 
@@ -48,9 +52,42 @@ Environment files:
 /workspaces/
 ```
 
-Edit `.symphony/settings.json` to set the GitHub owner, Workspace Repository name, GitHub Project
-number, GitHub Project states, and runtime commands. Runtime Settings reference secrets by environment
-variable name; secret values belong only in the Local Environment:
+Edit `.symphony/settings.json` to choose an Issue Tracker, set tracker-specific fields, configure
+status states, and set runtime commands. Runtime Settings reference secrets by environment variable
+name; secret values belong only in the Local Environment.
+
+### Default Terminal Console
+
+Run `symphony` from the Workspace Repository root to start the default read-first Terminal Console.
+It is the foreground surface for normal local orchestration and renders Runtime State snapshots for
+active work, retrying work, task attention, Readiness Gaps, Ordered Queue progress, Logs progress, Agent Worktree details,
+and Task Branch context.
+Compozy PRD Run progress appears when Compozy tracking is selected.
+
+The Terminal Console is safe to keep open while Symphony runs. Its MVP safe local aids are limited to
+refreshing the latest in-memory Runtime State snapshot, navigating and filtering tabs, showing the
+Web Dashboard handoff command, and inspecting validated local paths such as the Workspace Repository
+or Runtime Home. These aids do not retry tasks, pause or resume dispatch, update tracker status, merge
+or push Task Branches, open pull requests, change Runtime Contract files, or otherwise mutate task
+lifecycle state.
+
+Use Web Dashboard mode when browser-level inspection is more useful:
+
+```sh
+symphony --web --port 8080
+```
+
+The Web Dashboard keeps using the Live Dashboard Connection as a Runtime State stream. It is not a
+Terminal Console command channel.
+
+For a non-interactive check, use `symphony --once`; it prints terminal output and exits without
+starting the foreground Terminal Console loop.
+
+### Issue Tracker Selection
+
+GitHub is the default Issue Tracker. It uses GitHub Issues as issue records and GitHub Projects
+status values as dispatch state. Omitted `tracker.kind` values are treated as `"github"`, but new
+Workspace Repositories should set it explicitly:
 
 ```json
 {
@@ -64,37 +101,199 @@ variable name; secret values belong only in the Local Environment:
 }
 ```
 
-Choose the Codex model and reasoning effort in the same file. If omitted, Symphony uses `gpt-5.5`
-with `medium` reasoning:
+Choose minibeads when you want issue records to live in repository-owned Local Issue Files and you do
+not want Symphony issue dispatch or tracker status updates to require GitHub API access. minibeads is
+first-class when explicitly selected, but it is not a migration requirement for existing GitHub
+Tracker users:
 
 ```json
 {
-  "codex": {
-    "command": "codex exec",
-    "model": "gpt-5.5",
-    "reasoningEffort": "medium"
+  "tracker": {
+    "kind": "minibeads",
+    "root": ".beads",
+    "command": "mb"
   }
 }
 ```
 
-PI is not a prerequisite. If you have the `pi` CLI installed and authenticated, you can use it as an
-Agent Harness instead of Codex for selected Stage Agents. Define an `agents.pi` harness and point each
-stage that should use PI at that harness with `harness`:
+`tracker.root` is resolved from the Workspace Repository root and defaults to `.beads`.
+`tracker.command` defaults to `mb`; set it only when the executable name or path differs in your
+environment. Symphony runs minibeads commands from the Workspace Repository root and treats Local
+Issue Files as repository-owned user data.
+
+Choose the Compozy-backed Local Issue Tracker when you want Symphony to run a Compozy PRD Run from
+`.compozy/tasks/<task_name>/` as one user-facing work item. This tracker is opt-in with
+`tracker.kind = "compozy_tasks"`; GitHub remains the default Issue Tracker when the field is omitted
+or set to `"github"`:
 
 ```json
 {
-  "agents": {
+  "tracker": {
+    "kind": "compozy_tasks",
+    "compozy": {
+      "root": ".compozy/tasks",
+      "maxTaskStepRetries": 2
+    }
+  }
+}
+```
+
+`tracker.compozy.root` is resolved from the Workspace Repository root and defaults to
+`.compozy/tasks`. Each direct child directory, such as `.compozy/tasks/compozy-tasks-run-integration/`,
+is treated as one Compozy PRD Run. The `task_NN.md` files inside that directory are Compozy Task Steps
+in the same Agent Worktree and Task Branch; they are not separate Symphony issues. When
+present, `_prd.md` and `_techspec.md` are included in each task-step Agent Prompt.
+
+Symphony persists Compozy Task Step progress in task file frontmatter. During a run, task steps move
+through statuses such as `pending`, `in_progress`, `completed`, `failed`, and `skipped`, with retry
+metadata recorded alongside the status. `tracker.compozy.maxTaskStepRetries` controls how many times
+Symphony retries a failed task step before recording the failed or skipped state and advancing to the
+next runnable task step. Runtime State, the Terminal Console, and the Web Dashboard show the selected
+tracker kind, Compozy PRD Run identifier, current task step, completed count, failed count, skipped
+count, and total count when Compozy tracking is selected.
+
+Compozy tracking has four related status layers:
+
+| Layer | Runtime State field or source | What it answers |
+| --- | --- | --- |
+| Compozy Task Step progress | `current_step`, `completed`, `failed`, `skipped`, `total` from `task_NN.md` frontmatter | Which ordered step is selected and how many steps are terminal. |
+| Compozy PRD Run lifecycle | `lifecycle_state` | What phase the whole run is in from the operator perspective. |
+| Dispatch state | `dispatch_state` and `stage_agent` | Which configured tracker status and Stage Agent routing state Symphony is using. |
+| Compozy PR Readiness | `pr_readiness`, `handoff_status`, and `reason` | Whether the completed run is eligible for one aggregate Batch Pull Request or why it is not. |
+
+Runtime State, the Terminal Console, and the Web Dashboard render these layers from the same
+`compozy_progress` payload. The Terminal Console and Web Dashboard use compact labels such as
+`Lifecycle`, `Dispatch state`, `Stage agent`, `PR readiness`, `Handoff`, and `Reason`, but those
+labels do not merge the layers. Compozy Task Step progress remains the source for current-step and
+count truth; lifecycle and readiness explain the run around that progress.
+
+Compozy PRD Run lifecycle meanings:
+
+| Lifecycle state | Meaning |
+| --- | --- |
+| `pending` | The run exists but has not entered active Stage Agent work. |
+| `in_planning` | Planner-stage work is active. |
+| `in_execution` | Engineer-stage work or active task-step execution is in progress. |
+| `in_review` | Reviewer-stage work is active. |
+| `blocked` | Symphony needs operator attention and the run is not progressing normally. |
+| `completed` | The run completed successfully from the lifecycle perspective. |
+| `failed` | The run ended with failed work and is not ready for a Batch Pull Request. |
+| `skipped` | The run ended with skipped work and is not ready for a Batch Pull Request. |
+| `not_pr_ready` | The run is stopped or terminal but cannot open a Batch Pull Request; this is the not-PR-ready lifecycle and `Reason` explains why. |
+| `pr_handoff` | Batch Pull Request handoff for the aggregate Batch Pull Request is attempting, completed, or failed. |
+
+PR readiness is separate from both lifecycle and task-step counts:
+
+| PR readiness | Meaning |
+| --- | --- |
+| `disabled` | The Pull Request Policy does not enable automatic Batch Pull Requests. |
+| `not_ready` | The run is in the not-ready outcome for a Batch Pull Request; `Reason` describes the broad blocker. |
+| `ready` | The run completed successfully and is eligible for one aggregate Batch Pull Request. |
+| `handoff_attempting` | Symphony is attempting the Batch Pull Request handoff. |
+| `handoff_completed` | Symphony opened, completed, or reused the aggregate Batch Pull Request. |
+| `handoff_failed` | Batch Pull Request handoff failed and may be retried after the cause is fixed. |
+
+Representative Compozy PRD Run examples:
+
+| Scenario | Task-step progress | `lifecycle_state` | `dispatch_state` / `stage_agent` | `pr_readiness` / `handoff_status` | Operator meaning |
+| --- | --- | --- | --- | --- | --- |
+| Review active | Current Compozy Task Step and counts still come from task files. | `in_review` | `In review` / `reviewer` | `not_ready` / none | Reviewer work is active; the run is not ready for Batch Pull Request handoff. |
+| Retrying execution | The current step remains selected while retry context is visible in Runtime State. | `in_execution` | Current configured run state / `engineer` | `not_ready` / none | Retry does not create a new lifecycle value; `Reason` explains the retry. |
+| Blocked attention | Counts may show failed, skipped, or unavailable task-step progress. | `blocked` | `Human attention` / current Stage Agent when known | `not_ready` / none | Operator action is required before normal progress or handoff can continue. |
+| Failed or skipped terminal | Task-step truth shows failed or skipped terminal work. | `failed` or `skipped` | Terminal configured run state | `not_ready` / none | Terminal progress is visible, but it is not Batch Pull Request-ready. |
+| Completed and batch-ready | All task steps completed and final integration is safe. | `completed` | `Done` / current Stage Agent when known | `ready` / none | The Compozy PRD Run is eligible for one aggregate Batch Pull Request when the Pull Request Policy enables batch handoff. |
+| Completed with pull requests disabled | All task steps completed and final integration is safe. | `completed` | `Done` / current Stage Agent when known | `disabled` / none | The run completed, but automatic Batch Pull Requests are disabled by Pull Request Policy. |
+| Handoff failure | The completed run entered aggregate Batch Pull Request handoff. | `pr_handoff` | `Done` / current Stage Agent when known | `handoff_failed` / `handoff_failed` | The run is in handoff phase, and the failed handoff is a readiness outcome with a `Reason`, not successful review readiness. |
+
+Terminal task-step progress does not imply Batch Pull Request readiness. A run with failed, skipped,
+blocked, or otherwise terminal Compozy Task Steps remains `not_ready` unless the Compozy PRD Run
+completed successfully, final integration is safe, and the Pull Request Policy allows handoff.
+In `batch` Pull Request Mode, Compozy tracking preserves aggregate Batch Pull Request behavior:
+Symphony never opens one pull request per Compozy Task Step. At most one Batch Pull Request is
+eligible for the completed Compozy PRD Run, using the Loop-Start Branch as the pull-request head.
+If the completed Compozy Task Steps move the run into another configured Stage Agent state, Symphony
+dispatches that next Stage Agent with completed-run context first. Pull request handoff happens only
+after there is no configured next Stage Agent.
+
+When the selected Issue Tracker is `tracker.kind = "compozy_tasks"`, `--queue` accepts bare Compozy
+PRD Run slugs from `.compozy/tasks/<task_name>/`:
+
+```sh
+symphony --queue compozy-tasks-run-integration,queue-docs-refresh
+```
+
+Symphony keeps those queue identifiers as typed in Runtime State and uses the same raw sequence when
+deciding whether a restart resumes an Ordered Queue. Restarting with canonical selectors such as
+`compozy:compozy-tasks-run-integration,compozy:queue-docs-refresh` starts a different queue run than
+the bare-slug command above, even though dispatch resolves both forms to the same Compozy PRD Runs.
+
+The bare-slug shortcut is only for `--queue` with the Compozy-backed Issue Tracker. If GitHub or
+minibeads tracking is selected, a bare Compozy slug in `--queue` is reported as a startup Readiness
+Gap; use GitHub identifiers such as `20` or `#20`, minibeads identifiers such as `mb-20`, or switch
+Runtime Settings to `tracker.kind = "compozy_tasks"`. Canonical Compozy queue selectors such as
+`--queue compozy:compozy-tasks-run-integration` remain accepted for compatibility, but a single
+Compozy queue must use either bare slugs or canonical selectors, not both.
+
+Where selector-based flows outside the `--queue` shortcut support Compozy tracking, use the stable
+identifier form `compozy:<task_name>`. For example, `.compozy/tasks/compozy-tasks-run-integration/`
+is selected as `compozy:compozy-tasks-run-integration` in Manual Task Merge flows.
+
+Define execution backends under `harnesses` and logical agent roles under `agents`. Harnesses own
+provider commands and loop capability. Logical agents select a Harness and may override model,
+reasoning, and timeout fields for planner, engineer, or reviewer work:
+
+```json
+{
+  "harnesses": {
     "codex": {
       "kind": "codex",
       "command": "codex exec",
-      "model": "gpt-5.5",
-      "reasoningEffort": "medium"
+      "loop": {
+        "enabled": true,
+        "command": "/goal"
+      }
+    },
+    "claude": {
+      "kind": "claude",
+      "command": "claude -p --model <model> --output-format stream-json",
+      "loop": {
+        "enabled": false,
+        "command": ""
+      }
     },
     "pi": {
       "kind": "pi",
       "command": "pi --model <model> --thinking <reasoning> --print --no-session",
-      "model": "openai/gpt-5.5",
-      "reasoningEffort": "medium"
+      "loop": {
+        "enabled": false,
+        "command": ""
+      }
+    }
+  },
+  "agents": {
+    "planner": {
+      "harness": "codex",
+      "model": "gpt-5.5",
+      "reasoningEffort": "medium",
+      "turnTimeoutMs": 3600000,
+      "readTimeoutMs": 5000,
+      "stallTimeoutMs": 300000
+    },
+    "engineer": {
+      "harness": "claude",
+      "model": "opus-4.7",
+      "reasoningEffort": "xhigh",
+      "turnTimeoutMs": 3600000,
+      "readTimeoutMs": 5000,
+      "stallTimeoutMs": 300000
+    },
+    "reviewer": {
+      "harness": "pi",
+      "model": "openai-codex/gpt-5.5",
+      "reasoningEffort": "high",
+      "turnTimeoutMs": 3600000,
+      "readTimeoutMs": 5000,
+      "stallTimeoutMs": 300000
     }
   },
   "stageAgents": {
@@ -102,24 +301,50 @@ stage that should use PI at that harness with `harness`:
     "stages": [
       {
         "states": ["Todo", "To-Do", "In progress", "In Progress"],
-        "agent": "engineer",
-        "harness": "pi"
+        "agent": "engineer"
       }
     ]
   }
 }
 ```
 
-When the `agents` object is present, each configured Stage Agent should select an existing Agent
-Harness with `harness` unless its `agent` name also matches a harness name. PI readiness checks require
-the `pi` executable on `PATH` and provider authentication for the configured model.
+PI and Claude are not prerequisites for Codex-only dispatch. Symphony validates install and
+authentication readiness only for Harnesses selected by enabled Stage Agent routes. A selected PI
+Harness requires the `pi` executable on `PATH` and provider authentication for the configured model. A
+selected Claude Harness requires the `claude` executable and Claude Code authentication, such as
+`ANTHROPIC_API_KEY` or Claude's configured login state. Runtime Settings must reference only
+environment variable names, never secret values.
+
+Legacy settings that place Harness definitions under `agents.*`, such as `agents.pi.kind`, are
+migration input. When the new Runtime Settings shape is in use, Symphony reports a blocking Readiness
+Gap that tells you to move execution fields into `harnesses.*` and keep `agents.*` for logical agent
+definitions. Stage-level `stageAgents.stages[].harness` is also legacy input; move Harness selection to
+`agents.<logical-agent>.harness`.
 
 If setup is incomplete, the Terminal Console still starts and prints Readiness Gaps with remediation
 steps. Dispatch remains disabled until those gaps are resolved.
 
+For the GitHub Tracker, readiness includes the configured owner, Workspace Repository name, GitHub
+Project number, status field, and token environment variable. For Local Issue Tracker runs,
+GitHub owner, repo, Project, and token settings are not required. The local tracker readiness checks
+include tracker-specific local files and commands:
+
+- `tracker.minibeads.command`: install minibeads or update `tracker.command` so Symphony can run the
+  configured command.
+- `tracker.minibeads.store`: create the local issue store at `tracker.root` or update `tracker.root`
+  to the existing minibeads store.
+- `tracker.compozy.root`: create the Compozy tasks root at `tracker.compozy.root` or update the
+  setting to the existing `.compozy/tasks` directory.
+- `tracker.compozy.tasks`: add at least one valid `.compozy/tasks/<task_name>/task_NN.md` file with
+  task-step frontmatter.
+
 ## Project Status Workflow
 
-Symphony moves the configured GitHub Projects `Status` field as work progresses:
+Symphony moves the selected Issue Tracker status as work progresses. With the GitHub Tracker, this is
+the configured GitHub Projects `Status` field. With the minibeads Local Issue Tracker, Symphony maps
+the same Runtime Settings state names to minibeads statuses and writes them through `mb`. With the
+Compozy-backed Local Issue Tracker, the Compozy PRD Run is the work item and Symphony records
+task-step status in each `task_NN.md` file's frontmatter:
 
 - `startStatus`: applied before launching an agent, default `In progress`.
 - `reviewStatus`: applied after the agent exits successfully, default `In review`.
@@ -146,6 +371,7 @@ Configure these in `.symphony/settings.json`:
 
 The token needs GitHub Projects write access for status moves and status option creation. If
 `reviewStatus` is not listed in `activeStates`, completed issues stop being picked up on later polls.
+The token requirement applies to GitHub Tracker runs only.
 
 ## Stage Agents
 
@@ -239,24 +465,31 @@ skill files and does not include Stage Skill Load in Stage Goal Context. Missing
 duplicate skill identifiers are Readiness Gaps; Symphony checks all configured stages before
 dispatch, resolving Workspace Repository skills before Codex Home skills.
 
-Rendered Agent Prompts include GitHub issue comments as issue context in addition to the issue body.
+Rendered Agent Prompts include issue comments as issue context when the selected Issue Tracker
+provides comments. minibeads Local Issue Tracker comments are not included in V1. Compozy-backed
+Local Issue Tracker prompts include the current Compozy Task Step plus `_prd.md` and `_techspec.md`
+from the same Compozy PRD Run when those files exist.
 
-Set `goal.enabled` to `true` on a specific stage to enable Stage Goal Handoff for that stage only.
-When enabled, Symphony sends `/goal` with deterministic Stage Goal Context before the normal Agent
-Prompt. Stage Goal Context includes issue identifier, title, description, comments, URL, current
-GitHub Project status, labels, priority when present, blocker references when present, attempt, and
-stage agent name. It omits issue creation and update timestamps.
+Set `goal.enabled` to `true` on a specific stage to allow Stage Goal Handoff for that stage only.
+The selected Harness decides whether a loop command is actually sent. The Bootstrap default Codex
+Harness has `loop.enabled: true` and `loop.command: "/goal"`, so Codex receives `/goal` with
+deterministic Stage Goal Context before the normal Agent Prompt. The Bootstrap default Claude and PI
+Harnesses have loop disabled, so those Harnesses run the normal prompt even when a stage has
+`goal.enabled: true`. Stage Goal Context includes issue identifier, title, description, comments, URL,
+current tracker status, labels, priority when present, blocker references when present,
+attempt, and stage agent name. It omits issue creation and update timestamps.
 
-Stage Goal Handoff requires Codex goals in `~/.codex/config.toml`:
+Codex loop handoff requires a Codex command that accepts the configured Harness loop command from
+standard input. For Codex goals, enable goals in `~/.codex/config.toml`:
 
 ```toml
 [features]
 goals = true
 ```
 
-If a stage enables goal handoff but Codex goals are not enabled, Symphony reports a Readiness Gap.
-Goal Usage reported by Codex is stored in Runtime State for running, retrying, and attention-needed
-task details when available; missing or unparseable Goal Usage does not fail a task.
+If a selected loop-enabled Codex Harness cannot accept the configured loop command, Symphony reports a
+Readiness Gap. Goal Usage reported by Codex is stored in Runtime State for running, retrying, and
+attention-needed task details when available; missing or unparseable Goal Usage does not fail a task.
 
 Stage commits run after an agent exits successfully and before Symphony moves the issue to the
 stage's `successStatus`. Set `commit.enabled` per stage to control which transitions create commits;
@@ -325,9 +558,10 @@ The `title` and `body` fields are deterministic templates. They support `<head_b
 
 ## GitHub Token Permissions
 
-Symphony Orchestrator reads GitHub Issues and GitHub Projects. Use a **personal access token (classic)**
-when the GitHub Project is owned by a user account, such as `@your-user's Kanban`. GitHub
-fine-grained personal access tokens currently cannot access Projects owned by a user account.
+This section applies to the GitHub Tracker. Symphony Orchestrator reads GitHub Issues and GitHub
+Projects when `tracker.kind` is `"github"`. Use a **personal access token (classic)** when the
+GitHub Project is owned by a user account, such as `@your-user's Kanban`. GitHub fine-grained
+personal access tokens currently cannot access Projects owned by a user account.
 
 Recommended classic PAT scopes:
 
@@ -364,8 +598,12 @@ Symphony still reports Workspace Repository or GitHub Project access gaps, remov
 - `apps/backend`: OCaml service, workflow loader, GitHub tracker boundary, workspace manager, HTTP
   state API, CLI, and tests.
 - `apps/frontend`: ReScript React/Vite dashboard that consumes the backend state API.
+- `apps/tui`: reusable OCaml terminal UI toolkit packaged with Dune/opam as
+  `symphony-orchestrator-tui`. Its
+  `@symphony-orchestrator/tui` package.json is a private pnpm workspace label, not the publishing
+  target.
 - `.github/ISSUE_TEMPLATE`: issue template for work items Symphony can dispatch.
-- `.github/project-tracking.md`: required GitHub Project setup and workflow notes.
+- `.github/project-tracking.md`: GitHub Tracker setup and workflow notes.
 - `WORKFLOW.example.md`: legacy/developer fixture for the earlier root workflow format.
 - `bin/symphony.js`: npm `bin` launcher that runs a packaged platform binary or the local dune
   executable in Product Repository development.
@@ -376,14 +614,16 @@ Product Repository development is separate from Workspace Repository operation.
 actual orchestration belong in the Workspace Repository where `symphony init` is run; this source
 repository keeps code, tests, packaging scripts, fixtures, and documentation.
 
-Product Repository development requires `pnpm` 10.x and an OCaml toolchain with `opam`, `dune`,
-`cmdliner`, `yojson`, and `alcotest`. The local scripts run OCaml commands through `opam exec`, so
-make sure the active opam switch has the required packages installed.
+Product Repository development requires `pnpm` 10.x and an OCaml toolchain with `opam`, OCaml
+`>= 5.1`, Dune `>= 3.19`, `cmdliner`, `yojson`, `alcotest`, the local `apps/tui` package, `uutf`,
+and `toffee`. The local scripts run OCaml commands through `opam exec`, so make sure the active opam
+switch has the required packages installed.
 
 Install dependencies:
 
 ```sh
 pnpm install
+opam install . ./apps/tui --deps-only --with-test --yes
 ```
 
 Run the backend test suite:
@@ -392,6 +632,12 @@ Run the backend test suite:
 pnpm test
 ```
 
+Run documentation validation:
+
+```sh
+pnpm docs:test
+```
+
 Run frontend live-state tests:
 
 ```sh
@@ -429,9 +675,13 @@ pnpm backend:dev
 
 The backend serves:
 
-- Terminal Console/API root: `http://127.0.0.1:8080/`
+- Backend/API root: `http://127.0.0.1:8080/`
 - Runtime state JSON: `http://127.0.0.1:8080/api/v1/state`
-- Tailscale/LAN access: `http://<machine-ip>:8080/` because the backend binds to `0.0.0.0`.
+
+The backend binds to `127.0.0.1` by default. To expose the Web Dashboard on Tailscale or a LAN,
+set `"server": {"host": "0.0.0.0", "port": 8080}` in `.symphony/settings.json`; non-loopback
+binds print a one-time `symphony_auth` URL token and require that token for Runtime State HTTP and
+Live Dashboard Connection access.
 
 Start the Web Dashboard dev server in another terminal:
 
@@ -458,6 +708,7 @@ symphony --web --port 8080
 ```sh
 pnpm install
 pnpm test
+pnpm docs:test
 pnpm frontend:test
 pnpm frontend:build
 pnpm backend:build
@@ -474,8 +725,10 @@ opam exec -- dune exec symphony -- init
 opam exec -- dune exec symphony -- --web --port 8080
 ```
 
-If no GitHub token is configured, the runtime still starts, but readiness gaps report the missing
-token and live issue dispatch is disabled.
+If no GitHub token is configured for the GitHub Tracker, the runtime still starts, but readiness
+gaps report the missing token and live issue dispatch is disabled. For Local Issue Tracker runs,
+dispatch does not require a GitHub token; unresolved minibeads command or local issue store gaps, or
+missing Compozy PRD Run task files, disable dispatch instead.
 
 ## Package Distribution