@felixdotgo/aidlc-kit 0.1.0 → 0.2.0

package/docs/development.md

@@ -15,12 +15,23 @@ npm install
 
 Codex, Claude Code, or OpenCode are optional for manually exercising real evaluator drivers. Ordinary build, lint, and unit-test work does not need external model credentials. OpenCode driver runs also need `AIDLC_OPENCODE_MODEL` set to a `provider/model[#variant]` value.
 
+## Platform support
+
+Node.js 20.17 or newer is required on every platform. Linux and macOS are fully supported and tested. Windows is best-effort: win32 path separators are handled in `src/state/guards.ts`, `src/profiles.ts`, and the installed `assets/aidlc/scripts/lib/store.mjs`/`context-runtime.mjs`, and the state lock uses `process.kill(pid, 0)` for liveness; the lock and path handling are not exercised on Windows in CI. Loop and fleet features require Docker and a POSIX shell (`loop-local-workers.mjs` rejects non-Linux hosts).
+
+| Platform | Status | Notes |
+| --- | --- | --- |
+| Linux | Supported | Full CI coverage; Docker worker isolation available. |
+| macOS | Supported | Full test coverage; POSIX shell recipes apply. |
+| Windows | Best-effort | Use WSL or Git Bash for the local build recipe; lock/path code handles win32 separators but is untested. |
+| Loop / fleet | Linux only | Requires Docker + POSIX shell; `AIDLC_TEST_WORKER_IMAGE`/`AIDLC_WORKER_DOCKER_IMAGE` for e2e. |
+
 ## Repository layout
 
 ```text
 assets/aidlc/                Source workflow contracts, schemas, and installed scripts
 skills/                      Source thin phase adapters
-src/                         TypeScript package CLI, installer, lifecycle, profiles, and migrations
+src/                         TypeScript package CLI (src/cli/), installer + shared planning core, lifecycle domain (src/model/, src/state/), profiles, and migrations
 dev/evaluator/               Development-only evaluator harness and runners
 scripts/build-assets.mjs     Bundles workflow assets for package distribution
 test/unit/                   Unit and installed-runtime parity tests
@@ -35,6 +46,7 @@ The asset build copies `assets/aidlc/` and `skills/` into `dist/assets/.agents/`
 | Command | Purpose |
 | --- | --- |
 | `npm run build` | Rebuild bundled workflow assets and compile TypeScript into `dist/`. |
+| `npm run sync-core` | Copy `assets/aidlc/scripts/lib/store.mjs` to `services/aidlc-coordination/src/lifecycle-core.mjs` byte-identically. |
 | `npm run lint` | Type-check without emitting files. |
 | `npm test` | Build, then run every compiled unit test with Node's test runner. |
 | `node --test dist/test/unit/<file>.test.js` | Run a focused compiled test after building. |
@@ -74,7 +86,7 @@ To test the package before release, create its `.tgz` archive and run the local
 
 ```sh
 npm pack
-npx --package felixdotgo-aidlc-kit-0.0.1.tgz -- aidlc-workflow init .
+npx --package felixdotgo-aidlc-kit-0.2.0.tgz -- aidlc-kit init .
 ```
 
 `npx` runs the archive without publishing it. Run the command from the directory containing the archive. Use a disposable project instead of `.` if you do not want the command to write workflow files into the current directory.
@@ -95,6 +107,22 @@ The TypeScript implementation powers the package CLI. Installed projects use a d
 
 Likewise, a public configuration or schema change must update its validator, JSON schema, installed assets, package inventory, documentation, and tests together.
 
+The dual-core sync rule: after editing `assets/aidlc/scripts/lib/store.mjs`, run `npm run sync-core` so `services/aidlc-coordination/src/lifecycle-core.mjs` stays byte-identical.
+
+## Code style and conventions
+
+Adopted as the project baseline (approved decision `D1-convention-standard` on task `refactor-source-readability`):
+
+- **Strict TypeScript, no new dependencies for tooling.** Keep `strict` mode; enforce via `npm run lint` (`tsc --noEmit`). No ESLint/Prettier for now.
+- **File size targets.** Aim for ≤250 lines per source file and ≤60 lines per function; split by domain responsibility when exceeded.
+- **Module boundaries.** One responsibility per module; a facade module may re-export a public API for compatibility (for example `src/state.ts`).
+- **Naming.** Descriptive camelCase for functions/variables, `PascalCase` for types/interfaces, `SCREAMING_SNAKE_CASE` for true constants; file names match their primary export.
+- **Error handling.** Fail with typed, one-line errors; never swallow exceptions silently; validate inputs before I/O.
+- **Dependencies.** Pass dependencies (fetch, clock, environment) explicitly as parameters; avoid module-level mutable state.
+- **Public API.** Document exported symbols with JSDoc when the contract is non-obvious.
+- **Behavior preservation.** Refactors must not change CLI output, state schema, file layout, or installed assets; run parity tests.
+- **Verification.** Run the narrowest relevant test while iterating; `npm test` + `npm run lint` before handing off.
+
 ## Safe implementation rules
 
 - Resolve all project-relative paths through the shared path helpers; reject traversal and symlink escape.
@@ -104,3 +132,14 @@ Likewise, a public configuration or schema change must update its validator, JSO
 - Treat human-gated lifecycle transitions as atomic, auditable state operations.
 
 Read [Architecture](./architecture.md) before changing a module boundary, migration, installed script, or bundle layout.
+
+## Contributing to prompt assets
+
+Prompt assets are the installed workflow contracts under `assets/aidlc/` (notably `orchestrator.md` and `phase-*.md`). They feed the phase packets generated by `context.mjs`.
+
+- Keep them compact: the default phase-packet budget is 16,000 characters (`config.context.maxChars`). Optional rules and diagnostics are omitted first; the next-action contract, full phase contract, approved decisions, safety/spec anchors, task state, and applicable latest evidence are mandatory and are never truncated — if they do not fit, packet generation fails instead.
+- Heading invariants are enforced by `gate-check.mjs`:
+  - Intent (`G0_confirm`): `## 📋 Problem`, `## 🗺️ Affected areas`, `## 💭 Assumptions`, `## ❓ Open questions`, `## 🎯 Scope`.
+  - Design (`G1_review`): `## 🧩 Solution per affected area`, `## 📌 Spec traceability`, `## 🔗 Cross-service contracts`, `## ⚠️ Risks / edge cases`.
+- When changing contracts, run `npm run release:check` (`--adapters opencode`) and the evaluator suite; update docs and tests in the same change.
+- Never duplicate canonical agent instructions in overview docs; point to the installed assets instead. See [Design decisions](./design-decisions.md) (D6) for the compact-style rationale.

package/docs/loop-local-run.md

@@ -0,0 +1,495 @@
+# Run the AI-DLC Loop (local) for the aidlc-kit repo
+
+End-to-end guide for running the loop on the `aidlc-kit` repo itself (dogfooding),
+single machine (`local` mode). All lead/workers use **OpenCode**.
+
+> **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`.
+
+> **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.
+
+---
+
+## 1. What the loop is (summary)
+
+The loop runs an AI-DLC task from start to finish:
+
+- 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)).
+
+Setting the config alone **does not run anything** — the loop only runs when you call
+`loop start`.
+
+---
+
+## 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:
+
+```sh
+node -e 'const c=JSON.parse(require("fs").readFileSync(".agents/config.json","utf8")); console.log(JSON.stringify(c.loop,null,2))'
+```
+
+---
+
+## 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
+```
+
+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
+```
+
+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)
+```
+
+List available models:
+
+```sh
+opencode models
+```
+
+> [!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
+
+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:
+
+```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 .
+```
+
+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.
+
+Add a loop-owned task in either way:
+
+- **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`):
+
+  ```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 "" .
+  ```
+
+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.
+
+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.
+
+### 5.3 Watch status
+
+```sh
+# via npx:
+npx --package @felixdotgo/aidlc-kit@0.2.0 aidlc-kit loop status --task-id <task-id> --root .
+
+# or from source:
+node dist/src/cli.js loop status --task-id <task-id> --root .
+```
+
+Prints `authority`, `record` (run record), and `nextAction`
+(`classification` = `run_phase` / `await_user` / `blocked` / `complete`...).
+
+### 5.4 Approve a gate (trusted terminal or dashboard — never the agent)
+
+```sh
+node .agents/aidlc/scripts/loop-gate.mjs <task-id>
+# type: approve
+```
+
+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.
+
+### 5.5 Resume after stopping at a gate / 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:
+
+- **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):
+
+  ```sh
+  node .agents/aidlc/scripts/state.mjs task status <task-id> --status active
+  ```
+
+  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".
+
+### 5.6 Streaming log — see what the lead is doing
+
+The loop prints progress to **stderr** (stdout remains the final JSON), so you can see
+what the lead is doing during a long turn:
+
+```
+━━ turn 1 · phase clarify · agent opencode ━━
+  › tool: grep
+  › tool: read
+  › command completed (exit 0)
+<stream text from the lead>
+━━ 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`)
+
+```sh
+# via npx:
+npx --package @felixdotgo/aidlc-kit@0.2.0 aidlc-kit ui .
+
+# or from source:
+node dist/src/cli.js ui .
+```
+
+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`):
+
+```sh
+npx @felixdotgo/aidlc-kit loop worker-image --provider opencode
+# --provider codex | --provider claude ; default tag aidlc-worker-<provider>:local
+```
+
+- 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.
+
+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`).
+
+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.
+
+---
+
+## 8. Quick lead-only run (no Docker, no workers)
+
+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 .
+```
+
+JSON output returns `status` ∈ `gate | paused | blocked | complete` with `stopReason` and
+`nextAction`.
+
+---
+
+## 9. Troubleshooting
+
+### 9.1 Loop stops immediately / no approve prompt
+
+First check the evidence to see why the loop stopped:
+
+```sh
+node .agents/aidlc/scripts/state.mjs task show <task-id>
+```
+
+In the streaming build (after sync), the error appears directly in `stopReason` instead of
+`opencode exited 1:` (empty stderr). Example — model unavailable:
+
+```
+"agent transport failure: opencode reported an error: Model unavailable: opencode-go/flint-40b-free"
+```
+
+→ 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:
+
+```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.
+
+### 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…"
+
+- 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).
+
+### 9.7 Task pauses immediately after I approve a gate; daemon polls `actionable: []`
+
+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:
+
+```sh
+node .agents/aidlc/scripts/state.mjs task show <task-id>
+```
+
+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.
+- [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).