@felixdotgo/aidlc-kit 0.2.0 → 0.3.0

package/docs/loop-local-run.md

@@ -1,228 +1,124 @@
-# Run the AI-DLC Loop (local) for the aidlc-kit repo
+# Local loop walkthrough
 
-End-to-end guide for running the loop on the `aidlc-kit` repo itself (dogfooding),
-single machine (`local` mode). All lead/workers use **OpenCode**.
+Day-to-day operation of the loop in `local` mode on one machine: start the daemon, add tasks, watch, answer gates, resume. To enable the loop first, follow the [Loop setup runbook](./loop-runbook.md#local-mode).
 
-> **Local loop mode is usable** today; **fleet mode is still under active development**. The loop is **experimental** (pre-1.0): flags, `loop.*` fields, environment variables, and diagnostics can change incompatibly before `1.0.0`.
+> [!WARNING]
+> Experimental, pre-1.0. See [Status and stability](./loop-runbook.md#status-and-stability).
 
-> **npx vs. source.** The run commands below show **both** forms: `npx --package @felixdotgo/aidlc-kit@0.2.0 aidlc-kit …` (the published package — primary for end users) and `node dist/src/cli.js …` (dogfooding the `aidlc-kit` repo from a source checkout, after `npm run build`). Both drive the same installed `loop-entry.mjs`. Gate approval (§5.4) always stays on the trusted terminal via the installed `loop-gate.mjs` script and is never an `npx` command.
+Commands use the published package (`npx --package @felixdotgo/aidlc-kit@0.3.0 aidlc-kit …`) or the installed launcher `./.agents/aidlc/scripts/loop.sh`; both drive the installed `loop-entry.mjs`. Source checkout: [Dogfooding this repository](./development.md#dogfooding-this-repository).
 
----
+## How the loop works
 
-## 1. What the loop is (summary)
+- The **lead** runs `clarify` (gate `G0_confirm`), `plan` (`G1_review`), and `wrap` on the host, no Docker; **workers** run only `build` items (`G2_codereview`), isolated in Docker. Gates: [Operating the workflow](./operating-workflow.md).
+- Each iteration reads `state.mjs task next`, runs one agent turn on the returned `nextAction`, re-reads canonical state, and updates the checkpoint/fingerprint.
+- The loop **stops at every gate** and **never self-approves**; only a human on the trusted terminal or the signed-in dashboard approves.
+- It also stops after the per-run `maxTurns` budget (a resumed run gets a fresh one), after `maxStallTurns` unchanged turns, or at `blocked`/`terminal`/`complete` (`loop.limits`: [Configuration](./configuration.md#optional-loop-configuration)).
+- Config alone runs nothing; only `loop start` or `loop.sh up` runs the loop.
 
-The loop runs an AI-DLC task from start to finish:
+## Prerequisites
 
-- The **lead** agent runs the `clarify`, `plan`, and `wrap` phases (on the host).
-- **Workers** only run build items (in Docker, isolated).
-- Each loop iteration reads `state.mjs task next` → gets `nextAction` → passes context to
-  the agent → runs one turn → re-reads canonical state → updates checkpoint/fingerprint.
-- The loop **stops at every gate** and **never self-approves** — approval happens only
-  through the trusted terminal.
-- The loop also stops on its own when: the per-run `maxTurns` budget is exhausted (it
-  bounds one supervised run, not the task's lifetime — a resumed run gets a fresh budget),
-  `maxStallTurns` consecutive turns show no change, or the state is
-  `blocked`/`terminal`/`complete`. Both limits come from `loop.limits` (see
-  [configuration](./configuration.md#optional-loop-configuration)).
+- Linux host with Docker (`docker info` must pass for the build phase) and a POSIX shell; Node.js ≥ 20.17.
+- Lead provider CLI (`opencode`, `codex`, or `claude`) on the host `PATH`, matching `loop.agents.lead`.
+- If any provider is `opencode`: `AIDLC_OPENCODE_MODEL` naming a model listed by `opencode models`.
+- Worker credentials per provider/model: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or `OPENCODE_API_KEY`. The worker image is built automatically ([Worker Docker image](#worker-docker-image)).
 
-Setting the config alone **does not run anything** — the loop only runs when you call
-`loop start`.
+## Set the environment
 
----
-
-## 2. Current configuration (already set up)
-
-`.agents/config.json`:
-
-```json
-{
-  "loop": {
-    "mode": "local",
-    "agents": {
-      "lead": "opencode",
-      "workers": { "worker-a": "opencode", "worker-b": "opencode" }
-    }
-  }
-}
-```
-
-Quick check:
+Put loop variables in `.agents/loop.env` (installed as a commented template, git-ignored through `.agents/.gitignore`) or `export` them in the shell that starts the daemon; exported values win. `loop start`, `loop up`, and a dashboard-started daemon load the file.
 
 ```sh
-node -e 'const c=JSON.parse(require("fs").readFileSync(".agents/config.json","utf8")); console.log(JSON.stringify(c.loop,null,2))'
+# .agents/loop.env
+# Required for opencode unless "model" is set in opencode.json; use a model from `opencode models`:
+AIDLC_OPENCODE_MODEL=<provider/model>
+# Worker key for the build phase; read from ~/.local/share/opencode/auth.json when unset:
+# OPENCODE_API_KEY=...
 ```
 
----
-
-## 3. Prerequisites
-
-| Item | Requirement | Notes |
-| --- | --- | --- |
-| Linux host | required | Loop/fleet needs Docker + POSIX shell. |
-| Node | ≥ 20.17 | The repo is currently on v24. |
-| Docker engine | for build/worker | `docker info` must pass. |
-| OpenCode CLI | `opencode` on PATH | `opencode --version` (currently v2.2.5). |
-| Valid model | `AIDLC_OPENCODE_MODEL` | **Must be present in `opencode models`.** |
-| Worker image | for build phase | Image containing the real `opencode` CLI (see §7). |
-| Credentials | per model | `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` for workers. |
-
----
-
-## 4. Check configuration & sync
-
-### 4.1 Check for drift (installed `.agents/` vs source `assets/`)
-
 ```sh
-diff -rq assets/aidlc/scripts .agents/aidlc/scripts
+./.agents/aidlc/scripts/loop.sh check   # what the daemon will see; secrets are never printed
 ```
 
-If it produces output → the installed copy is stale. A typical error when drifted:
-
-```
-loop: Isolated local worker dispatcher is not integrated; loop execution is unavailable
-```
-
-### 4.2 Re-sync (human-only — requires a TTY)
-
-```sh
-npm run build
-node dist/src/cli.js upgrade . --dry-run   # preview the plan
-node dist/src/cli.js upgrade .             # apply, type "0.2.0" when prompted
-```
+`AIDLC_LOOP_EVENT_LOG` is set to `.agents/data/loop/ui-events.jsonl` automatically. All variables: [runbook](./loop-runbook.md#step-2--fill-in-agentsloopenv); lookup order: [Command reference](./command-reference.md#loop).
 
-Then re-run `diff -rq ...` (should be empty) and a quick test:
-
-```sh
-node dist/src/cli.js loop status --root . --task-id <task-id>
-```
-
----
-
-## 5. Run the loop end-to-end (local)
-
-### 5.1 Set environment variables
-
-```sh
-# REQUIRED — use a model that is actually in the list:
-export AIDLC_OPENCODE_MODEL=opencode-go/deepseek-v4-pro
-
-# OPTIONAL — required ONLY for the web dashboard live log when you start the
-# daemon manually. Must point at the exact file the UI reads:
-export AIDLC_LOOP_EVENT_LOG="$PWD/.agents/data/loop/ui-events.jsonl"
-
-# No need to set AIDLC_WORKER_DOCKER_IMAGE — the loop builds the image itself (see §7).
-# Only the worker credential is needed when it reaches the build phase:
-# export OPENAI_API_KEY=...   or   export ANTHROPIC_API_KEY=...  (per model)
-```
+> [!IMPORTANT]
+> A running daemon keeps the environment it started with. After editing `.agents/loop.env`, run `loop.sh down`, then `loop.sh up`; `loop up` warns when the file changed after the daemon started.
 
-List available models:
+## Start the daemon and add tasks
 
 ```sh
-opencode models
+./.agents/aidlc/scripts/loop.sh up      # --open launches the browser; --no-ui starts only the daemon
+./.agents/aidlc/scripts/loop.sh status  # daemon, dashboard, environment
+./.agents/aidlc/scripts/loop.sh logs    # follow the daemon log
+./.agents/aidlc/scripts/loop.sh down    # stop both; --now cancels the running turn
 ```
 
-> [!IMPORTANT]
-> Both variables must be exported **in the same shell that starts the daemon** — the
-> daemon and every lead/worker turn it spawns inherit only that process's environment.
-> A daemon started *before* you exported `AIDLC_OPENCODE_MODEL` will keep failing with
-> `opencode provider requires AIDLC_OPENCODE_MODEL` until it is restarted.
-
-### 5.2 Start the daemon, then add tasks
+`Ctrl-C` in the `up` terminal closes only the dashboard. Windows: `.agents\aidlc\scripts\loop.cmd`, same commands.
 
-In **local** mode `loop start` launches the persistent daemon (one per project — a second
-`loop start` fails with `Loop daemon already running (pid N)`). It does **not** read a
-requirement:
+Underneath, `loop start` runs the persistent daemon in the foreground and reads no requirement; one per project (a second fails with `Loop daemon already running (pid N)`):
 
 ```sh
-# via npx (published package):
-npx --package @felixdotgo/aidlc-kit@0.2.0 aidlc-kit loop start --root .
-
-# or from a source checkout (after `npm run build`):
-node dist/src/cli.js loop start --root .
+npx --package @felixdotgo/aidlc-kit@0.3.0 aidlc-kit loop start
 ```
 
-The daemon only runs **loop-owned** tasks — tasks created through loop intake (they have
-`.agents/data/tasks/<id>/loop-intake.json`) or that already have a loop run record. A task
-you create interactively (Claude Code/Codex/OpenCode via `state.mjs task create`) is never
-picked up, so the daemon cannot race an interactive lead on the same task.
+- The daemon runs only **loop-owned** tasks: created through loop intake (`.agents/data/tasks/<id>/runtime/intake.json`) or holding a loop run record (`runtime/run.json`). An interactively created task (`state.mjs task create`) is never picked up, so the daemon cannot race an interactive lead.
+- It runs one bounded run per actionable task in turn and keeps polling after a gate or completion.
 
-Add a loop-owned task in either way:
+Add a loop-owned task:
 
-- **Web dashboard** → **New task** (§5.7): creates the task and starts the daemon if none is
-  running.
-- **Terminal** — the requirement is read from stdin (never an argument), max 8192 bytes; the
-  task id/title are derived from its first line (override with `--task-id`/`--title`):
+- **Dashboard → New task** creates the task and starts the daemon if none is running.
+- **Terminal intake** reads the requirement from stdin (never an argument), at most 8192 bytes; id and title derive from the first line (`--task-id`/`--title` override).
 
   ```sh
-  echo "Add PDF report export" | npx --package @felixdotgo/aidlc-kit@0.2.0 aidlc-kit loop intake --root .
-  echo "Add PDF report export" | node dist/src/cli.js loop intake --root .
-  # or the installed entry point directly:
-  echo "Add PDF report export" | node .agents/aidlc/scripts/loop-entry.mjs intake "" .
+  echo "Add PDF report export" | npx --package @felixdotgo/aidlc-kit@0.3.0 aidlc-kit loop intake
+  echo "Add PDF report export" | node .agents/aidlc/scripts/loop-entry.mjs intake "" .   # installed entry point
   ```
 
-Intake refuses (and creates nothing) while an **interactive** task is actionable; finish or
-pause it first. Other actionable loop-owned tasks are fine — the daemon runs them in turn.
+- Intake refuses (creates nothing) while an **interactive** task is actionable; finish or pause it first.
 
-Stopping the daemon (`Ctrl-C` or `SIGTERM`) is two-stage: the first signal stops after the
-current turn, the second cancels the in-flight agent turn, the third exits immediately. A
-stopped run is recorded as `stopped` (the task is **not** paused) and resumes on the next
-`loop start`. Note that a terminal `Ctrl-C` is also delivered to the agent child process, so
-the in-flight turn usually ends right away even on the first press; it is still recorded as
-`stopped`, not as a transport failure. `aidlc-kit loop start` stays in the foreground for
-the whole shutdown (it forwards `SIGTERM` to the daemon and lets the terminal deliver
-`Ctrl-C`), so the second and third presses still reach the daemon.
+Stopping (`Ctrl-C` or `SIGTERM`) is staged: first signal stops after the current turn, second cancels the in-flight agent turn, third exits immediately.
 
-### 5.3 Watch status
+- A stopped run is recorded as `stopped` (the task is **not** paused) and resumes on the next `loop start`. A terminal `Ctrl-C` also reaches the agent child, so the turn usually ends on the first press; still `stopped`, not a transport failure.
+- `aidlc-kit loop start` stays in the foreground for the whole shutdown (forwards `SIGTERM`, lets the terminal deliver `Ctrl-C`), so later presses reach the daemon.
 
-```sh
-# via npx:
-npx --package @felixdotgo/aidlc-kit@0.2.0 aidlc-kit loop status --task-id <task-id> --root .
+## Watch status
 
-# or from source:
-node dist/src/cli.js loop status --task-id <task-id> --root .
+```sh
+npx --package @felixdotgo/aidlc-kit@0.3.0 aidlc-kit loop status --task-id <task-id>
 ```
 
-Prints `authority`, `record` (run record), and `nextAction`
-(`classification` = `run_phase` / `await_user` / `blocked` / `complete`...).
+Prints `authority`, `record` (the loop run record), and `nextAction` (`classification`: `run_phase`, `await_user`, `blocked`, `complete`, …).
 
-### 5.4 Approve a gate (trusted terminal or dashboard — never the agent)
+## Approve a gate or send feedback
+
+Answer a gate on the trusted host terminal or the signed-in dashboard, never from the lead or a worker, never with piped input:
 
 ```sh
 node .agents/aidlc/scripts/loop-gate.mjs <task-id>
-# type: approve
+# type: approve            -> approves this exact review and advances the phase
+# type: <any other text>   -> feedback: the task stays at this gate
 ```
 
-Never approve from the lead/worker, and never pipe input. The signed-in dashboard (§5.7)
-offers the same approval on the task detail page.
+- Prints the exact review (task, phase, gate, artifact digests, and at `G2_codereview` the integration commit), then prompts `Type approve to approve this exact review, or type feedback to send guidance back to the loop:`.
+- **`approve`** is the only answer that moves the task forward; if the review changes while you type, it fails closed.
+- **Any other text is feedback**: recorded as evidence `Cancelled gate wait at <gate>: <feedback>`; the task returns to `active` at the same gate, and the next lead turn revises the review and re-presents the **same** gate.
+- The dashboard detail page offers the same actions, **Send feedback (stay at gate)** and **✓ Approve** ([dashboard](#use-the-web-dashboard)).
 
-### 5.5 Resume after stopping at a gate / pause
+## Resume after a gate or a pause
 
-There is **no `loop resume`** (in either mode) — the daemon is the only runner,
-and it auto-resumes every task whose derived `nextAction` is `run_phase` (an *actionable*
-task). What you do depends on why the task stopped:
+There is **no `loop resume`** in either mode; the daemon auto-resumes every task whose `nextAction` is `run_phase` (*actionable*).
 
-- **After approving a gate** — nothing to do. Approval moves the task back to `active`, the
-  daemon's next poll sees it as actionable, and it runs the next lead turn automatically.
-- **After a pause** (e.g. an agent transport failure or the per-run turn limit) — the loop
-  marks the task `paused` (`nextAction` becomes `blocked`), which is **not** actionable, so
-  the daemon skips it. Fix the root cause, then set the task back to `active` (or press
-  **resume** on the dashboard, which does exactly this):
+- **After approving a gate**: nothing; the next poll runs the next lead turn.
+- **After a pause** (agent transport failure, per-run turn limit): the task is `paused` (`nextAction` `blocked`) and skipped. Fix the cause, then press **resume** on the dashboard or run the command below; the next poll (default about 5 s) picks it up.
 
   ```sh
-  node .agents/aidlc/scripts/state.mjs task status <task-id> --status active
+  node .agents/aidlc/scripts/state.mjs task status <task-id> --status active   # or: loop-entry.mjs resume-task <task-id> .
   ```
 
-  The daemon picks it up on the next poll (default ~5s).
-
-> `aidlc-kit loop resume`/`loop-entry.mjs resume` fails closed with
-> `loop resume is removed; the daemon auto-resumes actionable tasks — run 'loop start', and re-activate a paused task from the dashboard (resume) or with the task status command`.
-> Use `state.mjs task status --status active` (or `loop-entry.mjs resume-task <task-id> .`)
-> instead of trying to "resume the loop".
+- `aidlc-kit loop resume` and `loop-entry.mjs resume` fail closed with `loop resume is removed; the daemon auto-resumes actionable tasks — run 'loop start', and re-activate a paused task from the dashboard (resume) or with the task status command`.
 
-### 5.6 Streaming log — see what the lead is doing
+## Follow the streaming log
 
-The loop prints progress to **stderr** (stdout remains the final JSON), so you can see
-what the lead is doing during a long turn:
+Progress goes to **stderr** (stdout stays the final JSON):
 
 ```
 ━━ turn 1 · phase clarify · agent opencode ━━
@@ -233,263 +129,100 @@ what the lead is doing during a long turn:
 ━━ turn done ━━
 ```
 
-When the lead reaches a gate, the daemon immediately prints the **gate view** (approval
-instructions) and moves on to the next actionable task; after you approve in a second
-terminal via `loop-gate.mjs <id>` (or on the dashboard), the next poll resumes that task.
-The loop never self-approves.
-
-Streamed events: `turn_start`/`turn_end` (turn boundary + phase + agent), `agent_text`
-(lead text, capped at 4096 chars/chunk), `agent_tool` (tool being used such as
-`grep`/`read`/`glob`/`shell`), `lifecycle_command` (shell result + exit code), and `gate`
-(gate view), plus daemon events `daemon_start`, `daemon_poll`, `daemon_poll_error` (the task
-list could not be read; the daemon keeps polling), `daemon_turn`, `daemon_turn_error`, and
-`loop_stopped`. A task whose run throws, or ends `blocked`/`reconcile`, is retried with
-exponential backoff (poll interval doubled per failure, capped at 10 minutes). In the build
-phase, `build_deferred` names a ready item held back for a later batch (`reason`: overlaps
-another item, a busy path held by an active assignment, an unresolved assignment, or
-`capacity` — at most one item per configured worker per batch). Every event of a run
-carries its `taskId`.
-
-### 5.7 Web dashboard (`aidlc-kit ui`)
+A clarify or plan turn can take minutes without output. At a gate the daemon prints the **gate view** and moves on. Every event carries its `taskId`:
 
-```sh
-# via npx:
-npx --package @felixdotgo/aidlc-kit@0.2.0 aidlc-kit ui .
-
-# or from source:
-node dist/src/cli.js ui .
-```
+| Event | Meaning |
+| --- | --- |
+| `turn_start` / `turn_end` | Turn boundary, with phase and agent. |
+| `agent_text` | Lead text, capped at 4096 characters per chunk. |
+| `agent_tool` | Tool in use (`grep`, `read`, `glob`, `shell`, …). |
+| `lifecycle_command` | Shell result and exit code. |
+| `gate` | Gate view. |
+| `daemon_start`, `daemon_poll`, `daemon_turn`, `loop_stopped` | Daemon lifecycle. |
+| `daemon_poll_error` | The task list could not be read; the daemon keeps polling. |
+| `daemon_turn_error` | A task run threw (or ended `blocked`/`reconcile`); retried with exponential backoff (poll interval doubled per failure, capped at 10 minutes). |
+| `build_deferred` | A ready build item held for a later batch. `reason`: overlaps another item, busy path held by an active assignment, unresolved assignment, or `capacity` (one item per configured worker per batch). |
 
-The dashboard is branded **Loop**. It binds `127.0.0.1:4173` by default and prints a **login
-URL** (`http://127.0.0.1:4173/#token=…`). Open it (or pass `--open` to launch the browser):
-the page stores the token in `localStorage` and strips it from the address bar, so mutating
-actions (new task, resume, gate approve) work without pasting anything. The token is new on
-every start; use `--token-file ~/.aidlc-ui-token` (outside the project, mode `600`, created
-if missing) to keep the browser signed in across restarts. **⚙ Settings** still
-accepts a pasted token. Requests from another origin or with a foreign `Host` header are
-rejected `403` (see [Command reference](./command-reference.md#dashboard-authentication)).
-The header shows the authority (`authority · local`) and whether the daemon is running. The page follows the system light/dark preference
-automatically (Bulma plus the flat `assets/ui/dashboard.css` theme layer) and uses the full
-window width; results of actions appear as toasts in the bottom-right corner. Shortcuts:
-<kbd>N</kbd> new task, <kbd>/</kbd> search, <kbd>Esc</kbd> close the side panel or a dialog.
-
-Where things live (this is the #1 source of confusion):
-
-- **Gate approval button is only on the full task detail page** (`/tasks/<task-id>`), **not
-  on the dashboard**. Tasks waiting at a gate are listed under **Needs your review** at the
-  top of the dashboard; **Open review →** jumps to their detail page. Otherwise click a task to
-  open it in the **side panel** (it slides in from the right and adds `?task=<task-id>` to the
-  URL, so refresh or a shared link reopens it and Back closes it) and press **Open full page ↗**,
-  or ctrl/cmd-click / middle-click the task link. Both the side panel and the detail page show a
-  horizontal **progress** stepper (clarify → plan → build → wrap → done) above the artifacts. On the detail page the **Approve · `<review step>`** panel (approval note + green
-  **✓ Approve** button) appears only while the task is `blocked_on_user`. If the gate's
-  structural checks no longer pass, the page lists the failing checks instead of the gate view.
-- **New task → Create task** runs loop intake (§5.2) and starts the daemon only if none is
-  running (its stderr goes to `.agents/data/loop/daemon.log`). A toast shows the new task id,
-  or the real intake error (for example an actionable interactive task).
-- **Stat cards, search, and the status/risk filters** narrow the Kanban and List views in the
-  browser only; they never call the API or change state.
-- **Task buttons follow the status:** a `paused` task shows **resume** (sets it back to
-  `active`); a `blocked_on_user` task shows **approve**, which opens the detail page.
-- **The live log (bottom of the detail page)** shows only that task's events (on connect, the
-  last 200 of them found in the most recent 256 KB of the file, then live). It reads the fixed file `.agents/data/loop/ui-events.jsonl`, which
-  rotates to `.jsonl.1` at 5 MB. The daemon only writes there when `AIDLC_LOOP_EVENT_LOG`
-  points at that exact path: a daemon started from the dashboard sets it automatically; a
-  **manually started** daemon needs the export from §5.1.
-
-Gate approval stays equally available on the trusted terminal (`loop-gate.mjs`, §5.4), which
-needs no token.
-
----
-
-## 6. Lifecycle (phases / gates)
-
-| Phase | Who runs it | Stops at gate |
-| --- | --- | --- |
-| clarify | lead | `G0_confirm` |
-| plan | lead | `G1_review` |
-| build | workers (Docker) | `G2_codereview` |
-| wrap | lead | → `complete` |
-
-`clarify`, `plan`, `wrap` run on the host, **no Docker needed**.
-Only `build` needs the worker image + credentials (§7).
-
----
-
-## 7. Worker Docker image (build phase only)
-
-The build phase fans workers out into isolated Docker containers and needs an image
-containing the worker provider CLI (`opencode`/`codex`/`claude`). **You no longer need to
-build it by hand following a guide**:
-
-- The official worker image is **shipped with the package**
-  (`assets/aidlc/docker/Dockerfile.<provider>`).
-- Run a single command to build it (default provider `opencode`):
+## Use the web dashboard
 
 ```sh
-npx @felixdotgo/aidlc-kit loop worker-image --provider opencode
-# --provider codex | --provider claude ; default tag aidlc-worker-<provider>:local
+npx --package @felixdotgo/aidlc-kit@0.3.0 aidlc-kit ui .   # loop.sh up starts the same dashboard
 ```
 
-- The build command **records the image name into `.agents/config.json`**
-  (`loop.workerImage`); the supervisor reads it automatically, so you **don't need to
-  `export AIDLC_WORKER_DOCKER_IMAGE`** manually.
-- When the loop reaches the build phase and an image is missing, the supervisor
-  **auto-builds** the image for the right provider before preflight, so you usually don't
-  need to run the command above proactively.
+Branded **Loop**, binds `127.0.0.1:4173` by default and prints `Open: http://127.0.0.1:4173` (or pass `--open`).
 
-The `aidlc-worker-*-test:local` images on your machine **only contain a fake CLI for
-tests**; the real image is built from the shipped Dockerfile (base `node:24-bookworm-slim`,
-CLI installed via `npm install -g`).
+**Access**
 
-Notes:
-- Debian/glibc base because the `opencode` binary is a dynamically linked ELF; the driver
-  runs non-root + `--read-only`, so the CLI must be on the system `PATH` (npm global →
-  `/usr/local/bin`).
-- `opencode` uses `@opencode/cli` (OpenCode 2), **not** `opencode-ai` (OpenCode 1).
-- Worker credentials still need to be exported (per model): `OPENAI_API_KEY` /
-  `ANTHROPIC_API_KEY` / `OPENCODE_API_KEY`.
-- Preflight runs `docker run ... --entrypoint <cli> --version`; a missing or invalid
-  binary fails before any worker starts.
+- There is no login or session token: the dashboard is for a trusted local machine or internal network. Mutating actions (new task, resume, gate feedback, gate approve) work right away from the page.
+- Another origin, a foreign `Host` header, or a request that does not look like the dashboard's own `fetch` gets `403` ([Dashboard access](./command-reference.md#dashboard-access)). Binding to a non-loopback address prints a warning that the dashboard has no authentication.
 
----
+**Header and updates**
 
-## 8. Quick lead-only run (no Docker, no workers)
+- Header: authority (`authority · local`), daemon state, and a bell listing tasks needing review. The daemon pill turns amber (**daemon · N errors**) while a turn or poll keeps failing; hover for messages.
+- Pages poll about every 1.5 s and patch only what changed. An unreachable server shows a **reconnecting…** pill and polling backs off.
+- A new gate updates the bell, the tab title (`(2) Loop`), and a **Review needed** toast; with **Settings → notifications** on, a browser notification too (permission is asked only then).
+- Light/dark follows the system unless pinned in **Settings**. Shortcuts: <kbd>N</kbd> new task, <kbd>/</kbd> search, <kbd>Esc</kbd> close.
 
-Run the loop right away with a single lead, no Docker/workers needed:
-
-```sh
-export AIDLC_OPENCODE_MODEL=opencode-go/deepseek-v4-pro
-
-node .agents/aidlc/scripts/loop.mjs run <task-id> --agent opencode --max-turns 12 --root .
-node .agents/aidlc/scripts/loop.mjs status <task-id> --root .
-node .agents/aidlc/scripts/loop.mjs resume <task-id> --root .
-```
+**Where things live**
 
-JSON output returns `status` ∈ `gate | paused | blocked | complete` with `stopReason` and
-`nextAction`.
+| Where | What |
+| --- | --- |
+| Header bell | Tasks waiting at a gate (5 newest; **Load more**). A `blocked_on_user` card shows **review**, which opens the detail page. |
+| Card | Title only (id on hover and in search). Click opens the side panel and adds `?task=<task-id>` to the URL (or the full page, per **Settings**); ctrl/cmd/middle-click opens the full page in a new tab, shift-click in this tab. |
+| Side panel | Stepper (clarify → plan → build → wrap → done), artifacts, last 20 important log lines, a copy button for the id, **Open full page ↗**; at a gate, **Open review →**. |
+| Detail page `/tasks/<task-id>` | The only place with gate approval and feedback; containers, full live log — the one place to follow everything a task does. |
+| Settings (header ⚙) | Browser-only preferences: theme, live-update interval or pause, browser notifications for reviews, live log defaults, diff wrap / ignore whitespace, container log tail size, card click target. **Reset to defaults** restores them. |
+| Containers (detail page) | Every worker container the loop ran for the task (local or fleet; same layout), newest first: worker, item, turn, `running` / `exited <code>` / `signal`, start time and duration, host when recorded elsewhere. **Log** opens the raw output of that assignment (all turns, stdout and stderr unredacted) with **Follow** while it runs; the tail size comes from Settings. `docker · unavailable` means the state comes from the index only. |
+| Review panel (while `blocked_on_user`) | **Feedback** textarea + **Send feedback (stay at gate)**; **Approve** note + **✓ Approve** (popup; only **Confirm approve** sends). |
+| Approve semantics | The note is audit provenance, never feedback. A moved gate is refused with `409`. After feedback a **feedback pending** pill shows until approval; failing structural checks replace the gate view. |
+| New task (side panel) | Markdown editor. **Create task** runs loop intake and starts the daemon if none runs (stderr → `.agents/data/loop/daemon.log`); a toast shows the id or the intake error. |
+| Search and filters | Browser-only; never call the API. The **done** column shows 8 recent tasks; **Show N more** expands it. |
+| resume | On `paused` tasks; sets them back to `active`. |
+| Live log (detail page) | Lines `time · actor · what happened`, grouped by turn. **Important** (default) hides bookkeeping, **All** shows everything, **Raw JSON** shows the events. |
+| Changes `/tasks/<id>/changes` | Files and diff per work item from the commits workers recorded; otherwise the task range from the task's `baseCommit` to its `finalCommit` (or `HEAD` plus the working tree while open) — so a task driven from the terminal, or a finished task whose worker worktrees are gone, still shows its changes; last resort, the uncommitted working tree. **Wrap lines** and **Ignore whitespace** toggles. |
 
----
+Live log files: the log replays the last 200 events of `.agents/data/tasks/<task-id>/runtime/events.jsonl` (1 MiB, one `.1` generation; a file an older version left in `.agents/data/loop/events/` is read until `loop migrate-data` moves it), then follows live; older tasks fall back to the global `.agents/data/loop/ui-events.jsonl` (rotated to `.jsonl.1` at 5 MB), written only when `AIDLC_LOOP_EVENT_LOG` points at it. Container output is separate: `.agents/data/tasks/<task-id>/runtime/workers/<assignment>.log` (5 MiB, one `.log.1` generation) next to `index.json`, never committed. **Docs** in the header opens these guides.
 
-## 9. Troubleshooting
+## Worker Docker image
 
-### 9.1 Loop stops immediately / no approve prompt
+The build phase runs workers in Docker containers whose image contains the provider CLI (`opencode`, `codex`, or `claude`):
 
-First check the evidence to see why the loop stopped:
+- Dockerfiles ship with the package (`assets/aidlc/docker/Dockerfile.<provider>`); the supervisor **auto-builds** a missing image before preflight and records the name in `.agents/config.json` (`loop.workerImage`), so `AIDLC_WORKER_DOCKER_IMAGE` is not needed.
+- Build ahead of time (default provider `opencode`; default tag `aidlc-worker-<provider>:local`):
 
-```sh
-node .agents/aidlc/scripts/state.mjs task show <task-id>
-```
+  ```sh
+  npx @felixdotgo/aidlc-kit loop worker-image --provider opencode   # or codex | claude
+  ```
 
-In the streaming build (after sync), the error appears directly in `stopReason` instead of
-`opencode exited 1:` (empty stderr). Example — model unavailable:
+- Images named `aidlc-worker-*-test:local` contain only a fake CLI for tests. The real image is `node:24-bookworm-slim` (Debian/glibc, because `opencode` is a dynamically linked ELF) with the CLI from `npm install -g`.
+- Each worker container is started with labels `aidlc.task`, `aidlc.item`, `aidlc.worker`, and `aidlc.assignment` (`docker ps --filter label=aidlc.task=<task-id>` lists a task's workers), and its stdout/stderr are teed unredacted into the task's `runtime/workers/` log while the live log keeps only summaries.
+- The container runs non-root and `--read-only`, so the CLI must be on the system `PATH` (npm global → `/usr/local/bin`). `opencode` uses `@opencode/cli` (OpenCode 2), **not** `opencode-ai` (OpenCode 1).
+- Worker credentials come from the environment, per model: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or `OPENCODE_API_KEY`. Preflight runs `docker run … --entrypoint <cli> --version`; a missing or invalid binary fails before any worker starts.
 
-```
-"agent transport failure: opencode reported an error: Model unavailable: opencode-go/flint-40b-free"
-```
+## Quick lead-only run
 
-→ Wrong/unavailable model. Check `opencode models`, set `AIDLC_OPENCODE_MODEL` again, restart
-the daemon, then re-activate the task (§5.5).
-
-Raw OpenCode log (full stacktrace) if needed:
+A single lead with no Docker or workers, using the installed loop runner directly:
 
 ```sh
-grep -n "ModelUnavailableError\|Failed to drain Session" ~/.local/share/opencode/log/opencode.log | tail -20
-```
-
-> Note: if the lead runs for a long time without output, it is **not hanging** — a
-> clarify/plan turn with a free model can take a few minutes. Streaming (§5.6) now lets
-> you see each tool/text the lead is running.
-
-### 9.2 `Isolated local worker dispatcher is not integrated`
-
-The installed `.agents/` is stale (missing `createIsolatedLocalSupervisor`). Re-sync per
-§4.2.
-
-### 9.3 `Loop requires a configured lead and worker providers`
-
-`loop.mode` is enabled but `loop.agents.lead` or `loop.agents.workers` is missing. Check §2.
-
-### 9.4 `Requested mode does not match configured authority`
-
-The `--mode` passed in differs from `loop.mode` in config. Drop `--mode` to use the config
-value.
+export AIDLC_OPENCODE_MODEL=<provider/model>
 
-### 9.5 `opencode provider requires AIDLC_OPENCODE_MODEL`
-
-`AIDLC_OPENCODE_MODEL` is unset or in the wrong `provider/model[#variant]` format. See §5.1.
-Remember the daemon must be (re)started *after* exporting the variable — a daemon started
-without it keeps failing until restarted.
-
-### 9.6 Web dashboard live log is empty / stuck on "connecting…"
+node .agents/aidlc/scripts/loop.mjs run <task-id> --agent opencode --max-turns 12 --root .
+node .agents/aidlc/scripts/loop.mjs status <task-id> --root .
+node .agents/aidlc/scripts/loop.mjs resume <task-id> --root .
+```
 
-- The live log reads a **fixed** file `.agents/data/loop/ui-events.jsonl`; the daemon only
-  writes there when `AIDLC_LOOP_EVENT_LOG` points at that exact path. A manually started
-  daemon without that export produces no events — see §5.1. Restart the daemon after setting
-  it.
-- The live log is only on the task **detail** page (`/tasks/<id>`), not the dashboard.
-- A stopped daemon produces no events. The dashboard header shows whether it is running;
-  check `.agents/data/loop/daemon.log` for start-up errors.
-- The detail-page log is filtered to that task; daemon-wide events (`daemon_poll`) appear
-  only in the raw file.
-- Check `tail -f .agents/data/loop/ui-events.jsonl` directly: if the file grows with
-  `daemon_poll` lines, the daemon is healthy and only the browser side is stale (hard refresh).
+The JSON output reports `status` (`gate`, `paused`, `blocked`, or `complete`) with `stopReason` and `nextAction`.
 
-### 9.7 Task pauses immediately after I approve a gate; daemon polls `actionable: []`
+## Troubleshooting
 
-Approval moved the task to `active`, the daemon picked it up and tried a lead turn, but the
-turn failed — so the loop re-paused the task (`status: paused`, `nextAction: blocked`), and a
-paused task is not actionable. Diagnose from the evidence:
+- [Loop stops, pauses, or never starts](./troubleshooting.md#loop-stops-pauses-or-never-starts)
+- [Dashboard live log or actions do nothing](./troubleshooting.md#dashboard-live-log-or-actions-do-nothing)
+- [Loop leases, locks and claims](./troubleshooting.md#loop-leases-locks-and-claims) — "already running", unapprovable gate, stuck claims
+- [Build items deferred](./troubleshooting.md#build-items-deferred-or-build-dispatch-failure-unresolved-assignment) — `build_deferred`, `build dispatch failure`
 
-```sh
-node .agents/aidlc/scripts/state.mjs task show <task-id>
-```
+## Related
 
-Look for a `diagnostic` with `Paused while active: …`. For `agent transport failure: …` the
-cause is almost always the missing/invalid `AIDLC_OPENCODE_MODEL` (or an unavailable model).
-For `turn limit reached` the run used its whole per-run `maxTurns` budget without reaching a
-gate; raise `loop.limits.maxTurns` if the phase legitimately needs more turns. Then:
-
-1. Fix the environment (`opencode models`, export `AIDLC_OPENCODE_MODEL`).
-2. Kill and restart the daemon with the corrected environment (§5.1).
-3. Set the task back to actionable:
-
-   ```sh
-   node .agents/aidlc/scripts/state.mjs task status <task-id> --status active
-   ```
-
-### 9.8 Clicking "approve" (or "resume") on the web UI does nothing
-
-- The gate **approve** form exists only on the full detail page `/tasks/<id>`; the
-  dashboard's **approve** button on a `blocked_on_user` card just opens that page.
-- Mutating actions need the session token; without it they return `401` (shown inline under
-  the button). Open the login URL printed by `aidlc-kit ui` (the token changes on every
-  restart unless you use `--token-file`), or paste the token into **Settings**.
-- A `403` means the request was refused before the token check: the page was opened under a
-  different host name than the one the server is bound to (use the printed URL; any loopback
-  name works when bound to loopback), or the request came from another origin.
-- **resume** only applies to a `paused` task; on any other status it returns `409` with the
-  reason (a gate wait must be approved instead). A resumed task runs only if it is
-  loop-owned and a daemon is running (§5.2).
-- If approve does *literally nothing* (no inline result, no error, no reload) and you are on
-  an old build: open the browser DevTools console and look for
-  `SyntaxError: Identifier 'post' has already been declared`. That was a UI bug (the detail
-  page declared `const post` twice, silently disabling the approve handler) fixed in source —
-  rebuild/repack from a checkout that includes the fix, restart `ui`, and hard-refresh
-  (Ctrl+Shift+R) to drop the cached page.
-
-### 9.9 Build items wait (`build_deferred`) or the task pauses with `build dispatch failure`
-
-`build_deferred` is normal: ready items whose owned paths overlap, or that exceed the number
-of workers, run in a later batch. A pause with `build dispatch failure: Unresolved assignment …`
-means an earlier assignment still holds the paths every ready item needs; the loop never
-releases it on its own. See [Troubleshooting](./troubleshooting.md#build-items-deferred-or-build-dispatch-failure-unresolved-assignment).
-
----
-
-## 10. References
-
-- [Loop setup runbook](./loop-runbook.md) — the official runbook.
+- [Loop setup runbook](./loop-runbook.md) — enabling and configuring the loop.
 - [Configuration](./configuration.md#optional-loop-configuration) — `loop.*` fields.
-- [Command reference](./command-reference.md#loop) — full flags & env.
-- [Coordination service](./coordination-service.md) — fleet (multi-machine).
+- [Command reference](./command-reference.md#loop) — all loop flags and environment variables.
+- [AI-DLC Coordination service](./coordination-service.md) — fleet (multi-machine) deployment.