diff --git a/CHANGELOG.md b/CHANGELOG.md
index eca5f99..2faf16b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,21 @@ tags:
Notable changes to `@dancingteeth/agent-looper`. Dates are UTC.
+## 0.8.6 — 2026-11-12
+
+DSH 0.2.1 compatibility, and a failed `agent-loop-prompt` run now shows why it failed.
+
+### Fixes
+
+- **DSH credentials preflight accepts layout v1.** DSH 0.2.1 `credentials-local` requires `version: 1` + `refs:` (what `dsh web` writes) and auto-migrates the old flat map. The 0.6.3 preflight still demanded the flat map, so every DSH loop with a `dsh web` store aborted before WORKER. `agent-check dsh` and `agent-loop run` now reject only what DSH itself refuses: a `version` other than unquoted `1`, non-POSIX or non-string `refs`, or a flat map DSH cannot migrate.
+- **DSH loops require `DEEPSEEK_API_KEY` in the environment.** DSH 0.2.1 `--profile headless` mounts no credentials service, so a key stored in `~/.dsh/.credentials.yaml` never reaches the worker and the run died on iteration 1 with `MISSING_CREDENTIAL`. `agent-loop run` / `agent-loop-batch` / `agent-check dsh` now abort up front with an explanation.
+
+### Prompt TUI
+
+- **Done screen shows the failure reason.** On a failed run, `agent-loop-prompt` prints the `AGENT_LOOP_DONE` reason (or the last `failed:` line) and the `prompt-run.log` path, reading only this run's part of the log. `--plain` prints the same on stderr.
+
+[npm](https://www.npmjs.com/package/@dancingteeth/agent-looper) · [tag](https://github.com/dancingteeth/agent-looper/releases/tag/v0.8.6)
+
## 0.8.5 — 2026-11-01
Capable → efficient handoff, after [AgentBaton](https://arxiv.org/abs/2610.35959): start the loop on the strong model, hand off to a cheaper same-runtime model once the harness (not the worker) detects readiness.
diff --git a/CONSUMERS.md b/CONSUMERS.md
index 0456810..2ef2e98 100644
--- a/CONSUMERS.md
+++ b/CONSUMERS.md
@@ -29,7 +29,7 @@ Or in `package.json`:
```json
{
"devDependencies": {
- "@dancingteeth/agent-looper": "^0.8.5",
+ "@dancingteeth/agent-looper": "^0.8.6",
"@cursor/sdk": "^1.0.18"
}
}
diff --git a/README.md b/README.md
index 355ab9a..fff4206 100644
--- a/README.md
+++ b/README.md
@@ -27,7 +27,7 @@ pnpm exec agent-loop run .cursor/loops/my-task
Each runtime also needs its own SDK or CLI and key, e.g. `@cursor/sdk` + `CURSOR_API_KEY` for Cursor, `claude` on PATH for Claude Code, `opencode` for OpenCode. [`docs/runtime-map.md`](./docs/runtime-map.md) lists them all; `pnpm exec agent-check ` confirms one is wired. Flags and the rest are below. You do not need them for a first green run.
-How the loop is shaped: [`README.intro.md`](./README.intro.md). Technical deep dive: [`ARCHITECTURE.md`](./ARCHITECTURE.md) (including §1.1 — the harness is a small control-flow graph; the Ralph loop lives inside the worker node). npm releases: [`docs/releasing.md`](./docs/releasing.md). What shipped: [`CHANGELOG.md`](./CHANGELOG.md) (current **0.8.5**). Embedding this package as a library dependency in another ADE: [`docs/embed-api.md`](./docs/embed-api.md). Reporting a vulnerability: [`SECURITY.md`](./SECURITY.md).
+How the loop is shaped: [`README.intro.md`](./README.intro.md). Technical deep dive: [`ARCHITECTURE.md`](./ARCHITECTURE.md) (including §1.1 — the harness is a small control-flow graph; the Ralph loop lives inside the worker node). npm releases: [`docs/releasing.md`](./docs/releasing.md). What shipped: [`CHANGELOG.md`](./CHANGELOG.md) (current **0.8.6**). Embedding this package as a library dependency in another ADE: [`docs/embed-api.md`](./docs/embed-api.md). Reporting a vulnerability: [`SECURITY.md`](./SECURITY.md).
Supports pluggable **agent SDK** workers (`runtime`) and judges (`reviewRuntime`). Shipped today: **Cursor**, **Cline** (Pass / Credits), **OpenCode** (Go + BYOK), **Pi**, **Codex**, **DSH** (PATH `dsh`), **Muse** (PATH `muse`), **Claude** (PATH `claude`, `--safe-mode`). Defaults and cost notes: [`docs/runtime-map.md`](./docs/runtime-map.md). DSH companion for `dsh web` (skills + scaffold, not a second harness): [`docs/dsh-plugin.md`](./docs/dsh-plugin.md). OpenCode companion plugin (1.x + 2.x: skills, detached `agent_loop_start`, shell guard): [`plugins/opencode-agent-looper/`](./plugins/opencode-agent-looper/). Muse Code: [`docs/muse-runtime.md`](./docs/muse-runtime.md). Claude Code: [`docs/claude-runtime.md`](./docs/claude-runtime.md). To measure cheap-worker claims on a frozen loop: [`docs/runtime-cost-bench.md`](./docs/runtime-cost-bench.md). The judge runs on the worker's runtime when `reviewRuntime` is unset (each runtime has its own judge model, e.g. OpenCode → DeepSeek V4 Pro, Claude → Opus); set `reviewRuntime` + `reviewModel` to pair a cheap worker with a different judge.
@@ -125,7 +125,7 @@ pnpm exec agent-check codex
pnpm exec agent-loop run .cursor/loops/my-task --runtime codex
# DeepSeek Harness (needs `dsh` on PATH; Node ≥ 22.15)
-export DEEPSEEK_API_KEY=… # or DSH credentials-local
+export DEEPSEEK_API_KEY=… # required: DSH headless ignores ~/.dsh/.credentials.yaml
pnpm exec agent-check dsh
pnpm exec agent-loop run .cursor/loops/my-task --runtime dsh
# runtime: docs/dsh-runtime.md — dsh web companion: docs/dsh-plugin.md
diff --git a/docs/dsh-plugin.md b/docs/dsh-plugin.md
index 9881f60..ec24d45 100644
--- a/docs/dsh-plugin.md
+++ b/docs/dsh-plugin.md
@@ -5,6 +5,7 @@ tags:
- agents
- loops
- agentic_ai
+ - type/app
---
# DeepSeek Harness companion plugin
diff --git a/docs/dsh-runtime.md b/docs/dsh-runtime.md
index 238574b..c1573ce 100644
--- a/docs/dsh-runtime.md
+++ b/docs/dsh-runtime.md
@@ -70,7 +70,7 @@ Full Access on the **web** session does not change the headless worker patch: th
```bash
# Node ≥ 22.15 (DSH zlib/zstd). dsh on PATH.
-export DEEPSEEK_API_KEY=… # or DSH credentials-local / settings
+export DEEPSEEK_API_KEY=… # required: DSH headless ignores ~/.dsh/.credentials.yaml
# this checkout:
node dist/cli/check.js dsh
# consumer (agent-looper is a dependency):
@@ -79,9 +79,13 @@ pnpm exec agent-check dsh
## Credentials document
-`$DSH_HOME/.credentials.yaml` (default `~/.dsh/.credentials.yaml`) must be a **flat** `KEY: "string"` map. Current DSH `credentials-local` rejects a wrapped store (`version` / `refs` / `records`) and YAML integers (`version: 1`). Headless still parses that file even when `DEEPSEEK_API_KEY` is in the environment — quoting `version` is not enough.
+`$DSH_HOME/.credentials.yaml` (default `~/.dsh/.credentials.yaml`) uses DSH **layout v1** since DSH 0.2.1: `version: 1` (unquoted integer), `refs:` holding `KEY: "string"` entries, and DSH-owned `records:` (`dsh web` writes a `client-connection/browser-session` record there). DSH still auto-migrates the pre-release flat `KEY: "string"` map. Headless parses the file even when `DEEPSEEK_API_KEY` is in the environment.
-`agent-check dsh` and `agent-loop run` abort **before WORKER** when the document looks wrapped. Flatten it to `DEEPSEEK_API_KEY: "…"`. Do not dump the file. The harness does not rewrite it (`dsh web` may recreate the wrapped schema).
+**The key itself must come from the environment.** DSH 0.2.1 `--profile headless` mounts no credentials service, so a `DEEPSEEK_API_KEY` stored in `refs:` (what the web Models page writes) is invisible to the worker and the run dies with `MISSING_CREDENTIAL` on iteration 1. `agent-loop run` and `agent-check dsh` therefore abort up front unless `DEEPSEEK_API_KEY` is exported (or injected via Doppler).
+
+`agent-check dsh` and `agent-loop run` abort **before WORKER** only when the document would fail DSH boot: a `version` other than unquoted `1` (`version: "1"` fails), non-POSIX or non-string `refs` entries, or a flat map DSH cannot migrate. The scan is structure-only and never echoes values. Do not dump the file. The harness does not rewrite it.
+
+Before agent-looper 0.8.6 the preflight required the flat map and rejected layout v1 — the opposite of what DSH 0.2.1+ needs.
## Defaults
diff --git a/docs/embed-api.md b/docs/embed-api.md
index bf43946..fc42ead 100644
--- a/docs/embed-api.md
+++ b/docs/embed-api.md
@@ -114,7 +114,7 @@ the whole file.
## Public API and what breaks a major
-Current package version: **0.8.5**. Until 1.0, minor bumps may still add fields to `Stable`
+Current package version: **0.8.6**. Until 1.0, minor bumps may still add fields to `Stable`
types (additive, non-breaking for a host that ignores unknown fields) — a major bump is reserved
for anything that removes or renames a field, changes a field's type, or removes an export from
the [Supported surface](#supported-surface-stable-vs-experimental) table above.
diff --git a/docs/muse-runtime.md b/docs/muse-runtime.md
index ca3c23b..e997e2f 100644
--- a/docs/muse-runtime.md
+++ b/docs/muse-runtime.md
@@ -5,6 +5,8 @@ tags:
- muse
- cost
- agents
+ - agentic_ai
+ - type/app
---
# Muse Code worker runtime
diff --git a/docs/runtime-cost-bench.md b/docs/runtime-cost-bench.md
index 84c467f..1b6a766 100644
--- a/docs/runtime-cost-bench.md
+++ b/docs/runtime-cost-bench.md
@@ -5,6 +5,8 @@ tags:
- cost
- agents
- loops
+ - agentic_ai
+ - type/app
---
# Same-task runtime cost bench
diff --git a/llms.txt b/llms.txt
index c008fe4..b39070e 100644
--- a/llms.txt
+++ b/llms.txt
@@ -9,7 +9,7 @@ Start here:
- README.intro.md — product spine (worker / verify / judge / human)
- ARCHITECTURE.md — loop engine, escalation, cache-friendly prompts
- AGENTS.md — working agreements for this repo
-- CHANGELOG.md — shipped versions (current: 0.8.5)
+- CHANGELOG.md — shipped versions (current: 0.8.6)
- SECURITY.md — vulnerability reporting
- docs/embed-api.md — library embed contract (stable vs experimental, frozen shapes)
- docs/claude-runtime.md — PATH `claude -p --safe-mode` worker/judge
@@ -54,4 +54,4 @@ Worker default: composer-2.5. Judge default: grok-4.6 (`reviewModel`). `runtime:
## Package
-npm: `@dancingteeth/agent-looper` **0.8.5**. Layout: src/loop, src/review, src/agents, templates, .cursor/loops. Embed: docs/embed-api.md. Security: SECURITY.md.
+npm: `@dancingteeth/agent-looper` **0.8.6**. Layout: src/loop, src/review, src/agents, templates, .cursor/loops. Embed: docs/embed-api.md. Security: SECURITY.md.
diff --git a/package.json b/package.json
index b221585..a90024a 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "@dancingteeth/agent-looper",
- "version": "0.8.5",
+ "version": "0.8.6",
"description": "Fix-until-green harness for coding agents: frozen goal + verify.sh, a fresh worker each round, optional judge review. Works with Cursor, Claude Code, Codex, OpenCode, Cline, Pi, DSH, and Muse.",
"keywords": [
"agent",
diff --git a/plugins/agent-looper/skills/check-running-loops/SKILL.md b/plugins/agent-looper/skills/check-running-loops/SKILL.md
index 8657408..347524d 100644
--- a/plugins/agent-looper/skills/check-running-loops/SKILL.md
+++ b/plugins/agent-looper/skills/check-running-loops/SKILL.md
@@ -1,15 +1,12 @@
---
name: check-running-loops
-description: >-
- Checks whether agent-loop / agent-loop-batch jobs are actually alive, stale, hung, dead, or done,
- for any worker/judge runtime (Cursor, Cline, OpenCode, Pi, Codex, DSH, Muse, Claude).
- Use when the user asks if loops are ok, stuck, running, healthy, or what the current batch status is;
- when they mention agent-loop, loop-batch, verify.sh harness, or AGENT_LOOP_DONE.
+description: Checks whether agent-loop / agent-loop-batch jobs are actually alive, stale, hung, dead, or done, for any worker/judge runtime (Cursor, Cline, OpenCode, Pi, Codex, DSH, Muse, Claude). Use when the user asks if loops are ok, stuck, running, healthy, or what the current batch status is; when they mention agent-loop, loop-batch, verify.sh harness, or AGENT_LOOP_DONE.
tags:
- agentic_ai
- agents
- documentation
- loops
+ - type/app
---
# Check running loops
diff --git a/plugins/dsh-agent-looper/README.md b/plugins/dsh-agent-looper/README.md
index 104f0b6..3615de1 100644
--- a/plugins/dsh-agent-looper/README.md
+++ b/plugins/dsh-agent-looper/README.md
@@ -5,6 +5,7 @@ tags:
- documentation
- loops
- plugins
+ - type/app
---
# Agent Looper (DSH companion plugin)
diff --git a/plugins/dsh-agent-looper/skills/design-loop/SKILL.md b/plugins/dsh-agent-looper/skills/design-loop/SKILL.md
index 776dfef..a9a5a6b 100644
--- a/plugins/dsh-agent-looper/skills/design-loop/SKILL.md
+++ b/plugins/dsh-agent-looper/skills/design-loop/SKILL.md
@@ -6,6 +6,7 @@ tags:
- agents
- documentation
- loops
+ - type/app
---
# Design a loop
diff --git a/plugins/dsh-agent-looper/skills/install-agent-looper/SKILL.md b/plugins/dsh-agent-looper/skills/install-agent-looper/SKILL.md
index 67a8050..fcf5785 100644
--- a/plugins/dsh-agent-looper/skills/install-agent-looper/SKILL.md
+++ b/plugins/dsh-agent-looper/skills/install-agent-looper/SKILL.md
@@ -6,6 +6,7 @@ tags:
- agents
- documentation
- loops
+ - type/app
---
# Install Agent Looper
diff --git a/plugins/dsh-agent-looper/skills/review-gate/SKILL.md b/plugins/dsh-agent-looper/skills/review-gate/SKILL.md
index 075072a..53db2ae 100644
--- a/plugins/dsh-agent-looper/skills/review-gate/SKILL.md
+++ b/plugins/dsh-agent-looper/skills/review-gate/SKILL.md
@@ -6,6 +6,7 @@ tags:
- agents
- documentation
- loops
+ - type/app
---
# Review gate
diff --git a/site/about/index.html b/site/about/index.html
index 8663ddc..44fc2bc 100644
--- a/site/about/index.html
+++ b/site/about/index.html
@@ -44,7 +44,7 @@ About Agent Looper
Product site
Source
npm
- Changelog — 0.8.5
+ Changelog — 0.8.6
Author
diff --git a/site/about/index.md b/site/about/index.md
index 51f325d..b89f6f0 100644
--- a/site/about/index.md
+++ b/site/about/index.md
@@ -9,5 +9,5 @@ Agent Looper is made by Paul Zgordan (dancingteeth), who also writes at The Vacu
- Product: https://looper.dancingteeth.net/
- Source: https://github.com/dancingteeth/agent-looper
- npm: https://www.npmjs.com/package/@dancingteeth/agent-looper
-- Changelog (0.8.5): https://github.com/dancingteeth/agent-looper/blob/main/CHANGELOG.md
+- Changelog (0.8.6): https://github.com/dancingteeth/agent-looper/blob/main/CHANGELOG.md
- Author: https://dancingteeth.net/
diff --git a/site/docs/index.html b/site/docs/index.html
index 3b95ee8..d13649e 100644
--- a/site/docs/index.html
+++ b/site/docs/index.html
@@ -52,7 +52,7 @@ Agent Looper developer resources
Claude runtime — Claude Code CLI
Embed API — contract for embedding Agent Looper
Security — reporting vulnerabilities
- Changelog — 0.8.5
+ Changelog — 0.8.6
Agent Looper llms.txt
Agent Looper homepage (markdown)
diff --git a/site/docs/index.md b/site/docs/index.md
index 4c8167d..0c380e7 100644
--- a/site/docs/index.md
+++ b/site/docs/index.md
@@ -16,7 +16,7 @@ Agent Looper is the npm package `@dancingteeth/agent-looper` and the CLI `agent-
- Claude runtime (Claude Code CLI): https://github.com/dancingteeth/agent-looper/blob/main/docs/claude-runtime.md
- Embed API (contract for embedding Agent Looper): https://github.com/dancingteeth/agent-looper/blob/main/docs/embed-api.md
- Security (reporting vulnerabilities): https://github.com/dancingteeth/agent-looper/blob/main/SECURITY.md
-- Changelog (0.8.5): https://github.com/dancingteeth/agent-looper/blob/main/CHANGELOG.md
+- Changelog (0.8.6): https://github.com/dancingteeth/agent-looper/blob/main/CHANGELOG.md
- Agent Looper llms.txt: https://looper.dancingteeth.net/llms.txt
- Agent Looper homepage (markdown): https://looper.dancingteeth.net/index.md
diff --git a/site/harnesses/index.html b/site/harnesses/index.html
index 75cd8ba..4a3ce64 100644
--- a/site/harnesses/index.html
+++ b/site/harnesses/index.html
@@ -134,7 +134,7 @@ DSH
Judge: same runtime by default (V4 Pro), override any, optional
pnpm exec agent-loop run .cursor/loops/my-task --runtime dsh --review-gate
- Default worker is deepseek-official/deepseek-flash (DeepSeek-V41-Flash, image-capable). Previous deepseek-official/deepseek-v4-flash stays allowed. Ensure dsh is on PATH. ~/.dsh/.credentials.yaml must be a flat KEY: "string" map — a wrapped store (version / refs / records) or YAML integer fails agent-check dsh and agent-loop run before spawning the worker. Quoting version alone is not enough; the harness does not rewrite that file. DSH companion plugin guard blocks accidental foreground grinds. See docs/dsh-plugin.md and plugins/dsh-agent-looper/.
+ Default worker is deepseek-official/deepseek-flash (DeepSeek-V41-Flash, image-capable). Previous deepseek-official/deepseek-v4-flash stays allowed. Ensure dsh is on PATH. Export DEEPSEEK_API_KEY in the launching shell — DSH 0.2.1 headless ignores the key stored in ~/.dsh/.credentials.yaml, so agent-check dsh and agent-loop run abort before spawning the worker without it. The file itself may be DSH layout v1 (version: 1 + refs:, what dsh web writes) or the old flat map; the harness does not rewrite that file. DSH companion plugin guard blocks accidental foreground grinds. See docs/dsh-plugin.md and plugins/dsh-agent-looper/.
diff --git a/site/harnesses/index.md b/site/harnesses/index.md
index aa1b456..528fe42 100644
--- a/site/harnesses/index.md
+++ b/site/harnesses/index.md
@@ -43,7 +43,7 @@ DeepSeek Harness CLI — worker is `dsh --profile headless`; `dsh-agent-looper`
- Worker: `deepseek-official/deepseek-flash` (4.1 Flash, escalates to `deepseek-official/deepseek-v4-pro`). Previous `deepseek-official/deepseek-v4-flash` stays allowed.
- Judge (optional): same runtime by default (V4 Pro), override any
- Run: `pnpm exec agent-loop run .cursor/loops/my-task --runtime dsh --review-gate`
-- `~/.dsh/.credentials.yaml` must be a flat `KEY: "string"` map — a wrapped store (`version` / `refs` / `records`) or YAML integer fails `agent-check dsh` and `agent-loop run` before spawning the worker. Quoting `version` alone is not enough; the harness does not rewrite that file.
+- Export `DEEPSEEK_API_KEY` in the launching shell — DSH 0.2.1 headless ignores the key stored in `~/.dsh/.credentials.yaml`, so `agent-check dsh` and `agent-loop run` abort before spawning the worker without it. The file itself may be DSH layout v1 (`version: 1` + `refs:`, what `dsh web` writes) or the old flat map; the harness does not rewrite that file.
- DSH companion plugin guard blocks accidental foreground grinds
### Cline (`--runtime cline-pass` · `cline`)
diff --git a/site/index.md b/site/index.md
index 7d0f36f..be0bde4 100644
--- a/site/index.md
+++ b/site/index.md
@@ -105,7 +105,7 @@ Agent Looper is free and MIT-licensed. If it saves you time:
- [llms.txt](https://looper.dancingteeth.net/llms.txt)
- [Harnesses](https://looper.dancingteeth.net/harnesses/)
- [Developer resources](https://looper.dancingteeth.net/docs/)
-- [Changelog (0.8.5)](https://github.com/dancingteeth/agent-looper/blob/main/CHANGELOG.md)
+- [Changelog (0.8.6)](https://github.com/dancingteeth/agent-looper/blob/main/CHANGELOG.md)
- [Embed API](https://github.com/dancingteeth/agent-looper/blob/main/docs/embed-api.md)
- [Security](https://github.com/dancingteeth/agent-looper/blob/main/SECURITY.md)
- [GitHub](https://github.com/dancingteeth/agent-looper)
diff --git a/site/llms.txt b/site/llms.txt
index 636b5ce..3bf65f6 100644
--- a/site/llms.txt
+++ b/site/llms.txt
@@ -6,7 +6,7 @@ When to use Agent Looper: a human wants a feature finished without babysitting C
When not to use Agent Looper: there is no deterministic check (pure taste with no script or vision gate); you need a team-ops factory, shared org cloud, or multi-repo orchestration; you want the model to grade itself as “done.”
-How an agent should call it: install `@dancingteeth/agent-looper`, ask the human what they want, then implement the feature with Agent Looper (set up the loop, write GOAL.md and verify.sh, run until green). Or from the terminal: `pnpm exec agent-loop-setup` (one-screen setup wizard — recap plus current question) then `pnpm exec agent-loop-prompt --out .cursor/loops/` — the scaffold judge stops as soon as frozen GOAL.md and verify.sh pass freeze (10-minute wall, not a long grind) — then `pnpm exec agent-loop run .cursor/loops/ --runtime `. Leave `reviewRuntime` unset and the optional judge runs on the worker's own runtime with that runtime's judge model (OpenCode → `opencode-go/deepseek-v4-pro`, Claude → `opus`, Codex → `gpt-5.6-sol`, DSH → V4 Pro, Muse → PAYG Spark, Cursor → `grok-4.7`; Cline and Pi use the worker model unless `reviewModel` is set) — there is no Cursor default judge. Set `reviewRuntime` to `cursor` to keep a Cursor judge. On `runtime: cursor`, repo defaults that pin OpenCode Go `escalateModel` are not applied. DeepSeek Flash defaults are 4.1: DSH `deepseek-official/deepseek-flash`, OpenCode Go `opencode-go/deepseek-v4.1-flash`, Cline Pass `cline-pass/deepseek-v4.1-flash`; older `deepseek-v4-flash` slugs still parse. DSH headless: `~/.dsh/.credentials.yaml` must be a flat `KEY: "string"` map — a wrapped store (`version` / `refs` / `records`) or YAML integer fails `agent-check dsh` and `agent-loop run` before spawning the worker; quoting `version` alone is not enough (the harness does not rewrite that file). Optional `--review-gate` re-opens the loop only on blocking review findings. If verify fails because the environment is broken, the loop waits instead of burning another worker. After each visit the harness restores frozen specs and removes any frozen basename a worker planted (e.g. `setup.sh`) so it cannot persist. Before tightening `verify.sh` or `REVIEWS.md` between runs, label a diverse sample of `.cursor/loop-exports/` (see docs/unknowns-preflight.md). `runtime: opencode` works with the OpenCode 1.x CLI (`@opencode-ai/sdk`) and 2.x CLI (`@opencode/client`); without the matching client package the loop fails fast with an install hint instead of timing out. `agent-check opencode` handshakes the server so a client/CLI mismatch fails the check, not the first loop. OpenCode 2.x provider keys live in OpenCode’s credential store (add once). Companion plugin `@dancingteeth/opencode-agent-looper` (0.1.6) teaches Agent Looper skills and starts loops in the background via `agent_loop_start` / `agent_loop_status` (so a shell timeout can’t kill them); `agent_loop_start` can launch through the repo’s `agent:loop` script or a `launchPrefix` when keys live in a secrets wrapper; on 2.x install with `opencode plugin add @dancingteeth/opencode-agent-looper`, on 1.x add `"plugin": ["@dancingteeth/opencode-agent-looper"]` to `opencode.json` — alongside the CLI, not instead of it. OpenCode Go and Cline Pass model lists and list prices come from models.dev (sync picks up Gemini 4 Argon (contributor) and the hosted-$0 Cat Jam row, drops deprecated DeepSeek V4 Flash slugs, and again offers priced `opencode-go/kimi-k3`); unknown well-formed slugs warn at start and read `$0` until priced — budget caps still reject unpriced worker, escalate, or handoff models. CLI: `agent-loop`, `agent-loop-prompt`, `agent-loop --version`; unknown flags fail with an error. Current npm: **0.8.5** (supported line **0.8.x**).
+How an agent should call it: install `@dancingteeth/agent-looper`, ask the human what they want, then implement the feature with Agent Looper (set up the loop, write GOAL.md and verify.sh, run until green). Or from the terminal: `pnpm exec agent-loop-setup` (one-screen setup wizard — recap plus current question) then `pnpm exec agent-loop-prompt --out .cursor/loops/` — the scaffold judge stops as soon as frozen GOAL.md and verify.sh pass freeze (10-minute wall, not a long grind) — then `pnpm exec agent-loop run .cursor/loops/ --runtime `. Leave `reviewRuntime` unset and the optional judge runs on the worker's own runtime with that runtime's judge model (OpenCode → `opencode-go/deepseek-v4-pro`, Claude → `opus`, Codex → `gpt-5.6-sol`, DSH → V4 Pro, Muse → PAYG Spark, Cursor → `grok-4.7`; Cline and Pi use the worker model unless `reviewModel` is set) — there is no Cursor default judge. Set `reviewRuntime` to `cursor` to keep a Cursor judge. On `runtime: cursor`, repo defaults that pin OpenCode Go `escalateModel` are not applied. DeepSeek Flash defaults are 4.1: DSH `deepseek-official/deepseek-flash`, OpenCode Go `opencode-go/deepseek-v4.1-flash`, Cline Pass `cline-pass/deepseek-v4.1-flash`; older `deepseek-v4-flash` slugs still parse. DSH headless: export `DEEPSEEK_API_KEY` in the launching shell — DSH 0.2.1 headless ignores the key stored in `~/.dsh/.credentials.yaml`, so `agent-check dsh` and `agent-loop run` abort before spawning the worker without it. The file itself may be DSH layout v1 (`version: 1` + `refs:`, what `dsh web` writes) or the old flat map (the harness does not rewrite that file). Optional `--review-gate` re-opens the loop only on blocking review findings. If verify fails because the environment is broken, the loop waits instead of burning another worker. After each visit the harness restores frozen specs and removes any frozen basename a worker planted (e.g. `setup.sh`) so it cannot persist. Before tightening `verify.sh` or `REVIEWS.md` between runs, label a diverse sample of `.cursor/loop-exports/` (see docs/unknowns-preflight.md). `runtime: opencode` works with the OpenCode 1.x CLI (`@opencode-ai/sdk`) and 2.x CLI (`@opencode/client`); without the matching client package the loop fails fast with an install hint instead of timing out. `agent-check opencode` handshakes the server so a client/CLI mismatch fails the check, not the first loop. OpenCode 2.x provider keys live in OpenCode’s credential store (add once). Companion plugin `@dancingteeth/opencode-agent-looper` (0.1.6) teaches Agent Looper skills and starts loops in the background via `agent_loop_start` / `agent_loop_status` (so a shell timeout can’t kill them); `agent_loop_start` can launch through the repo’s `agent:loop` script or a `launchPrefix` when keys live in a secrets wrapper; on 2.x install with `opencode plugin add @dancingteeth/opencode-agent-looper`, on 1.x add `"plugin": ["@dancingteeth/opencode-agent-looper"]` to `opencode.json` — alongside the CLI, not instead of it. OpenCode Go and Cline Pass model lists and list prices come from models.dev (sync picks up Gemini 4 Argon (contributor) and the hosted-$0 Cat Jam row, drops deprecated DeepSeek V4 Flash slugs, and again offers priced `opencode-go/kimi-k3`); unknown well-formed slugs warn at start and read `$0` until priced — budget caps still reject unpriced worker, escalate, or handoff models. CLI: `agent-loop`, `agent-loop-prompt`, `agent-loop --version`; unknown flags fail with an error. Current npm: **0.8.6** (supported line **0.8.x**).
## Developer resources
@@ -24,7 +24,7 @@ How an agent should call it: install `@dancingteeth/agent-looper`, ask the human
- [Claude runtime](https://github.com/dancingteeth/agent-looper/blob/main/docs/claude-runtime.md): Claude Code CLI (`--safe-mode`)
- [Embed API](https://github.com/dancingteeth/agent-looper/blob/main/docs/embed-api.md): contract for embedding Agent Looper
- [Security](https://github.com/dancingteeth/agent-looper/blob/main/SECURITY.md): reporting vulnerabilities
-- [Changelog](https://github.com/dancingteeth/agent-looper/blob/main/CHANGELOG.md): 0.8.5
+- [Changelog](https://github.com/dancingteeth/agent-looper/blob/main/CHANGELOG.md): 0.8.6
- [Harnesses — Agent Looper worker runtimes](https://looper.dancingteeth.net/harnesses/index.md)
## Optional
diff --git a/src/agents/dshAgent.test.ts b/src/agents/dshAgent.test.ts
index 199ae55..3d2167b 100644
--- a/src/agents/dshAgent.test.ts
+++ b/src/agents/dshAgent.test.ts
@@ -11,7 +11,7 @@ import {
nodeMeetsDshMinimum,
spawnDshHeadless,
} from './dshAgent.js'
-import { DSH_CREDENTIALS_FLAT_HINT } from './dshCredentialsStore.js'
+import { DSH_CREDENTIALS_LAYOUT_HINT } from './dshCredentialsStore.js'
describe('dshAgent', () => {
it('writes a headless patch for model, never-approval, and a matching permission preset', () => {
@@ -54,18 +54,27 @@ describe('dshAgent', () => {
const versionDump =
'dsh: plugin tree failed to load: credentials-local: the value for "version" in /Users/me/.dsh/.credentials.yaml must be a string\nTypeError: credentials-local: the value for "version" in /Users/me/.dsh/.credentials.yaml must be a string\n at parseCredentialsDocument'
expect(formatDshHeadlessFailure(1, versionDump)).toBe(
- `DSH headless failed (exit 1): ${DSH_CREDENTIALS_FLAT_HINT}`,
+ `DSH headless failed (exit 1): ${DSH_CREDENTIALS_LAYOUT_HINT}`,
)
expect(
formatDshHeadlessFailure(
1,
'credentials-local: the value for "refs" in /Users/me/.dsh/.credentials.yaml must be a string',
),
- ).toBe(`DSH headless failed (exit 1): ${DSH_CREDENTIALS_FLAT_HINT}`)
+ ).toBe(`DSH headless failed (exit 1): ${DSH_CREDENTIALS_LAYOUT_HINT}`)
expect(
formatDshHeadlessFailure(1, 'dsh: plugin tree failed to load: EPERM cordis.yml'),
).toBe('DSH headless failed (exit 1): dsh: plugin tree failed to load: EPERM cordis.yml')
})
+
+ it('collapses DSH layout-v1 credential errors to the layout hint', () => {
+ expect(
+ formatDshHeadlessFailure(
+ 1,
+ 'Error: credentials-local: /Users/me/.dsh/.credentials.yaml declares version "1"; this build reads version 1',
+ ),
+ ).toBe(`DSH headless failed (exit 1): ${DSH_CREDENTIALS_LAYOUT_HINT}`)
+ })
})
describe('killProcessGroup', () => {
diff --git a/src/agents/dshAgent.ts b/src/agents/dshAgent.ts
index c344468..9d44c72 100644
--- a/src/agents/dshAgent.ts
+++ b/src/agents/dshAgent.ts
@@ -27,7 +27,7 @@ import {
readDshSessionUsage,
} from './dshSessionUsage.js'
import { formatUsageRecordLog } from '../usage/loopUsage.js'
-import { assertDshCredentialsStore, DSH_CREDENTIALS_FLAT_HINT } from './dshCredentialsStore.js'
+import { assertDshCredentialsStore, DSH_CREDENTIALS_LAYOUT_HINT } from './dshCredentialsStore.js'
export const DSH_SESSION_TIMEOUT_MS = 45 * 60 * 1000
export const DSH_KILL_GRACE_MS = 3000
@@ -38,10 +38,11 @@ export const DSH_MIN_NODE_MINOR = 15
export function formatDshHeadlessFailure(exitCode: number, detail: string): string {
const prefix = `DSH headless failed (exit ${exitCode})`
if (
- /credentials\.yaml must be a string/i.test(detail) ||
- /value for "(version|refs|records)"/i.test(detail)
+ /credentials\.yaml must be a (string|mapping)/i.test(detail) ||
+ /value for "(version|refs|records)"/i.test(detail) ||
+ /credentials-local: .*(declares version|pre-release flat layout|invalid document)/i.test(detail)
) {
- return `${prefix}: ${DSH_CREDENTIALS_FLAT_HINT}`
+ return `${prefix}: ${DSH_CREDENTIALS_LAYOUT_HINT}`
}
const compact = detail
.split('\n')
diff --git a/src/agents/dshCredentialsStore.test.ts b/src/agents/dshCredentialsStore.test.ts
index ea889a9..28b3778 100644
--- a/src/agents/dshCredentialsStore.test.ts
+++ b/src/agents/dshCredentialsStore.test.ts
@@ -3,7 +3,7 @@ import os from 'node:os'
import path from 'node:path'
import { afterEach, describe, expect, it } from 'vitest'
import {
- DSH_CREDENTIALS_FLAT_HINT,
+ DSH_CREDENTIALS_LAYOUT_HINT,
assertDshCredentialsStore,
dshCredentialsDocumentProblem,
} from './dshCredentialsStore.js'
@@ -23,7 +23,7 @@ afterEach(() => {
})
describe('dshCredentialsDocumentProblem', () => {
- it('accepts a flat quoted API key', () => {
+ it('accepts a flat quoted API key (DSH migrates the pre-release layout)', () => {
expect(dshCredentialsDocumentProblem('DEEPSEEK_API_KEY: "sk-test"\n')).toBeUndefined()
})
@@ -32,28 +32,50 @@ describe('dshCredentialsDocumentProblem', () => {
expect(dshCredentialsDocumentProblem('# comment only\n')).toBeUndefined()
})
- it('rejects the wrapped version/refs/records store', () => {
+ it('accepts layout v1 with refs and DSH-owned records (what dsh web writes)', () => {
const text = [
- 'version: "1"',
+ 'version: 1',
'refs:',
' DEEPSEEK_API_KEY: sk-test',
'records:',
' client-connection/browser-session:',
+ ' kind: secret',
' payload:',
' version: 1',
+ ' secret: abc',
'',
].join('\n')
- expect(dshCredentialsDocumentProblem(text)).toBe(DSH_CREDENTIALS_FLAT_HINT)
+ expect(dshCredentialsDocumentProblem(text)).toBeUndefined()
})
- it('rejects an unquoted YAML integer at root', () => {
- expect(dshCredentialsDocumentProblem('version: 1\n')).toBe(DSH_CREDENTIALS_FLAT_HINT)
+ it('accepts version 1 with no refs yet', () => {
+ expect(dshCredentialsDocumentProblem('version: 1\n')).toBeUndefined()
})
- it('rejects a non-POSIX root key', () => {
+ it('rejects a quoted or unknown version', () => {
+ expect(dshCredentialsDocumentProblem('version: "1"\nrefs:\n K: "v"\n')).toBe(
+ DSH_CREDENTIALS_LAYOUT_HINT,
+ )
+ expect(dshCredentialsDocumentProblem('version: 2\n')).toBe(DSH_CREDENTIALS_LAYOUT_HINT)
+ })
+
+ it('rejects non-string or non-POSIX refs', () => {
+ expect(dshCredentialsDocumentProblem('version: 1\nrefs:\n DEEPSEEK_API_KEY: 123\n')).toBe(
+ DSH_CREDENTIALS_LAYOUT_HINT,
+ )
+ expect(dshCredentialsDocumentProblem('version: 1\nrefs:\n bad-key: "x"\n')).toBe(
+ DSH_CREDENTIALS_LAYOUT_HINT,
+ )
+ expect(dshCredentialsDocumentProblem('version: 1\nrefs:\n K:\n nested: "x"\n')).toBe(
+ DSH_CREDENTIALS_LAYOUT_HINT,
+ )
+ })
+
+ it('rejects a flat store DSH cannot migrate', () => {
expect(dshCredentialsDocumentProblem('client-connection/browser-session: "x"\n')).toBe(
- DSH_CREDENTIALS_FLAT_HINT,
+ DSH_CREDENTIALS_LAYOUT_HINT,
)
+ expect(dshCredentialsDocumentProblem('DEEPSEEK_API_KEY: 42\n')).toBe(DSH_CREDENTIALS_LAYOUT_HINT)
})
})
@@ -63,20 +85,22 @@ describe('assertDshCredentialsStore', () => {
expect(() => assertDshCredentialsStore({ filename })).not.toThrow()
})
- it('throws the flatten hint for a wrapped store without echoing values', () => {
- const filename = tmpStore('version: 1\nrefs:\n DEEPSEEK_API_KEY: sk-secret-do-not-leak\n')
+ it('throws the layout hint without echoing values', () => {
+ const filename = tmpStore('version: "1"\nrefs:\n DEEPSEEK_API_KEY: sk-secret-do-not-leak\n')
expect(() => assertDshCredentialsStore({ filename })).toThrow(/aborting before WORKER/)
try {
assertDshCredentialsStore({ filename })
} catch (error) {
const message = error instanceof Error ? error.message : String(error)
- expect(message).toContain(DSH_CREDENTIALS_FLAT_HINT)
+ expect(message).toContain(DSH_CREDENTIALS_LAYOUT_HINT)
expect(message).not.toContain('sk-secret')
}
})
- it('accepts a flat store', () => {
- const filename = tmpStore('DEEPSEEK_API_KEY: "sk-test"\n')
- expect(() => assertDshCredentialsStore({ filename })).not.toThrow()
+ it('accepts a flat store and a v1 store', () => {
+ expect(() => assertDshCredentialsStore({ filename: tmpStore('DEEPSEEK_API_KEY: "sk-test"\n') })).not.toThrow()
+ expect(() =>
+ assertDshCredentialsStore({ filename: tmpStore('version: 1\nrefs:\n DEEPSEEK_API_KEY: sk-test\n') }),
+ ).not.toThrow()
})
})
diff --git a/src/agents/dshCredentialsStore.ts b/src/agents/dshCredentialsStore.ts
index 6d6c922..673a868 100644
--- a/src/agents/dshCredentialsStore.ts
+++ b/src/agents/dshCredentialsStore.ts
@@ -3,12 +3,15 @@ import os from 'node:os'
import path from 'node:path'
import { resolveDshHome } from './dshSessionUsage.js'
-/** Same one-liner for preflight, agent-check, and collapsed headless stderr. */
-export const DSH_CREDENTIALS_FLAT_HINT =
- '~/.dsh/.credentials.yaml must be a flat KEY: "string" map ' +
- '(DEEPSEEK_API_KEY: "…"). A wrapped store (version/refs/records) or YAML integer (version: 1) fails boot.'
-
-const WRAPPED_ROOT_KEYS = new Set(['version', 'refs', 'records'])
+/**
+ * Same one-liner for preflight, agent-check, and collapsed headless stderr.
+ * DSH >= 0.2.1 `credentials-local` reads layout v1 and auto-migrates the
+ * pre-release flat map, so both shapes boot; anything else fails boot.
+ */
+export const DSH_CREDENTIALS_LAYOUT_HINT =
+ '~/.dsh/.credentials.yaml must be DSH layout v1: `version: 1` (unquoted integer) with ' +
+ '`refs:` holding KEY: "string" entries (DEEPSEEK_API_KEY: "…"). ' +
+ 'A flat KEY: "string" map is also accepted (DSH migrates it).'
/** DSH `credentialRef`: POSIX identifier. */
const POSIX_CREDENTIAL_REF = /^[A-Za-z_][A-Za-z0-9_]*$/
@@ -22,22 +25,28 @@ export function dshCredentialsFilename(
return path.join(resolveDshHome(env, homedir), '.credentials.yaml')
}
-function rootKeyName(line: string): string | undefined {
- if (/^[ \t]/.test(line)) return undefined
- const trimmed = line.trimEnd()
- if (trimmed.length === 0 || trimmed.startsWith('#') || trimmed === '---' || trimmed === '...') {
+type KeyLine = { indent: number; key: string; value: string }
+
+function parseKeyLine(raw: string): KeyLine | undefined {
+ const trimmed = raw.trimEnd()
+ const body = trimmed.trimStart()
+ if (body.length === 0 || body.startsWith('#') || body === '---' || body === '...') {
return undefined
}
- const quoted = /^["']([^"']+)["']\s*:/.exec(trimmed)
- if (quoted) return quoted[1]
- const plain = /^([^:#\s][^:]*)\s*:/.exec(trimmed)
- return plain?.[1]?.trim()
+ const indent = trimmed.length - body.length
+ const quoted = /^["']([^"']+)["']\s*:(.*)$/.exec(body)
+ const plain = quoted ? undefined : /^([^:#\s][^:]*?)\s*:(?:\s(.*)|)$/.exec(body)
+ const match = quoted ?? plain
+ if (!match) return undefined
+ const value = (match[2] ?? '').replace(/\s+#.*$/, '').trim()
+ return { indent, key: match[1]!.trim(), value }
}
-function rootValuePrefix(line: string): string {
- const colon = line.indexOf(':')
- if (colon < 0) return ''
- return line.slice(colon + 1).replace(/\s+#.*$/, '').trim()
+/** Value prefix that DSH would not read as a non-empty string scalar. */
+function notAString(value: string): boolean {
+ if (value.length === 0) return true
+ if (value.startsWith('"') || value.startsWith("'")) return /^(""|'')$/.test(value)
+ return UNQUOTED_NON_STRING.test(value)
}
/**
@@ -45,16 +54,42 @@ function rootValuePrefix(line: string): string {
* Absent / empty documents are OK (DSH treats them as an empty store).
*/
export function dshCredentialsDocumentProblem(text: string): string | undefined {
- for (const raw of text.split(/\r?\n/)) {
- const key = rootKeyName(raw)
- if (key === undefined) continue
- if (WRAPPED_ROOT_KEYS.has(key) || !POSIX_CREDENTIAL_REF.test(key)) {
- return DSH_CREDENTIALS_FLAT_HINT
+ const lines = text
+ .split(/\r?\n/)
+ .map(parseKeyLine)
+ .filter((line): line is KeyLine => line !== undefined)
+ const roots = lines.filter((line) => line.indent === 0)
+ if (roots.length === 0) return undefined
+
+ const version = roots.find((line) => line.key === 'version')
+ if (version === undefined) {
+ // Pre-release flat layout: DSH migrates it when every entry is a ref → string.
+ for (const line of roots) {
+ if (!POSIX_CREDENTIAL_REF.test(line.key) || notAString(line.value)) {
+ return DSH_CREDENTIALS_LAYOUT_HINT
+ }
+ }
+ return undefined
+ }
+
+ if (version.value !== '1') return DSH_CREDENTIALS_LAYOUT_HINT
+ let section: string | undefined
+ let childIndent: number | undefined
+ for (const line of lines) {
+ if (line.indent === 0) {
+ section = line.key
+ childIndent = undefined
+ if (section === 'refs' && line.value.length > 0 && line.value !== '{}') {
+ return DSH_CREDENTIALS_LAYOUT_HINT
+ }
+ continue
+ }
+ if (section !== 'refs') continue // records are DSH-owned; other roots are ignored by DSH
+ childIndent ??= line.indent
+ if (line.indent !== childIndent) return DSH_CREDENTIALS_LAYOUT_HINT
+ if (!POSIX_CREDENTIAL_REF.test(line.key) || notAString(line.value)) {
+ return DSH_CREDENTIALS_LAYOUT_HINT
}
- const value = rootValuePrefix(raw)
- if (value.length === 0) continue
- if (value.startsWith('"') || value.startsWith("'")) continue
- if (UNQUOTED_NON_STRING.test(value)) return DSH_CREDENTIALS_FLAT_HINT
}
return undefined
}
@@ -78,5 +113,5 @@ export function assertDshCredentialsStore(options: AssertDshCredentialsStoreOpti
}
const problem = dshCredentialsDocumentProblem(text)
if (problem === undefined) return
- throw new Error(`DSH credentials store is not flat — aborting before WORKER. ${problem}`)
+ throw new Error(`DSH credentials store will not boot — aborting before WORKER. ${problem}`)
}
diff --git a/src/cli/check.ts b/src/cli/check.ts
index 444ec48..2d33e91 100644
--- a/src/cli/check.ts
+++ b/src/cli/check.ts
@@ -1,5 +1,6 @@
#!/usr/bin/env node
import { assertDshCredentialsStore } from '../agents/dshCredentialsStore.js'
+import { DSH_HEADLESS_ENV_KEY_HINT } from '../loop/loopCredentialPreflight.js'
import { OPENCODE_PROVIDER_API_KEY_ENV } from '../agents/opencodeAuth.js'
import {
detectOpencodeMajorVersion,
@@ -253,11 +254,10 @@ async function checkRuntime(runtime: Runtime): Promise {
if (key) {
console.log('[agent-check] DEEPSEEK_API_KEY present (prefix):', `${key.slice(0, 4)}…`)
} else {
- console.log(
- '[agent-check] no DEEPSEEK_API_KEY — will rely on DSH credentials (`dsh` settings / credentials-local)',
- )
+ console.error(`[agent-check] DEEPSEEK_API_KEY is not set. ${DSH_HEADLESS_ENV_KEY_HINT}`)
+ process.exit(1)
}
- console.log('[agent-check] DSH credentials-local: absent or flat KEY: string map')
+ console.log('[agent-check] DSH credentials-local: absent, layout v1, or migratable flat map')
console.log('[agent-check] dsh CLI:', (which.stdout || which.stderr).trim().split('\n')[0])
console.log('[agent-check] shell preflight OK')
diff --git a/src/cli/prompt.ts b/src/cli/prompt.ts
index f5d3db3..ae5852a 100644
--- a/src/cli/prompt.ts
+++ b/src/cli/prompt.ts
@@ -11,6 +11,7 @@ import {
formatRunHandoffCommand,
loadLoopConfigForPrompt,
readDraftSnapshot,
+ readRunFailureReason,
resolvePromptPaths,
runScaffoldAgent,
spawnLoopRun,
@@ -158,7 +159,7 @@ async function executePromptFlow(options: PromptCliOptions): Promise {
}
const config = loadLoopConfigForPrompt(loopDir, await detectLoopRuntimes())
- const { child, logPath, bundleLabel } = spawnLoopRun(loopDir, repoRoot)
+ const { child, logPath, logOffset, bundleLabel } = spawnLoopRun(loopDir, repoRoot)
if (!useInk) {
console.error(`[agent-loop-prompt] watching ${bundleLabel} (log: ${logPath})`)
}
@@ -168,10 +169,19 @@ async function executePromptFlow(options: PromptCliOptions): Promise {
? await watchChildInk(loopDir, child, config.maxIterations)
: await waitForChildExit(child)
+ const failure =
+ exitCode === 0
+ ? undefined
+ : {
+ reason: readRunFailureReason(logPath, logOffset),
+ log: path.relative(repoRoot, logPath) || logPath,
+ }
if (useInk) {
- await showDoneInk(exitCode, exitCode === 0 ? config.preview : undefined)
+ await showDoneInk(exitCode, exitCode === 0 ? config.preview : undefined, failure)
} else {
console.error(`[agent-loop-prompt] run exited ${exitCode}`)
+ if (failure?.reason) console.error(`[agent-loop-prompt] reason: ${failure.reason}`)
+ if (failure) console.error(`[agent-loop-prompt] log: ${failure.log}`)
}
if (exitCode === 0 && config.preview) {
diff --git a/src/cli/promptFlow.spawn.test.ts b/src/cli/promptFlow.spawn.test.ts
index 4de398d..d5085fe 100644
--- a/src/cli/promptFlow.spawn.test.ts
+++ b/src/cli/promptFlow.spawn.test.ts
@@ -5,6 +5,7 @@ import path from 'node:path'
import type { ChildProcess } from 'node:child_process'
import { afterEach, describe, expect, it, vi } from 'vitest'
import {
+ readRunFailureReason,
resolveAgentLoopRunBin,
spawnLoopRun,
spawnPreviewDetached,
@@ -91,6 +92,60 @@ describe('spawnLoopRun', () => {
child.emit('exit', 0)
expect(fs.existsSync(result.logPath)).toBe(true)
})
+
+ it('reports the log offset so earlier runs in the appended log are skipped', () => {
+ const repoRoot = tmpDir()
+ const loopDir = path.join(repoRoot, '.cursor', 'loops', 'task')
+ fs.mkdirSync(loopDir, { recursive: true })
+ const old = 'AGENT_LOOP_DONE {"v":1,"kind":"loop","bundle":"x","complete":false,"exitCode":1,"reason":"old run"}\n'
+ fs.writeFileSync(path.join(loopDir, 'prompt-run.log'), old)
+ const child = fakeChild()
+ spawn.mockReturnValue(child)
+
+ const result = spawnLoopRun(loopDir, repoRoot)
+ child.emit('exit', 1)
+ expect(result.logOffset).toBe(Buffer.byteLength(old))
+ expect(readRunFailureReason(result.logPath, result.logOffset)).toBeUndefined()
+ })
+})
+
+describe('readRunFailureReason', () => {
+ function writeLog(body: string): string {
+ const file = path.join(tmpDir(), 'prompt-run.log')
+ fs.writeFileSync(file, body)
+ return file
+ }
+
+ it('prefers the AGENT_LOOP_DONE reason', () => {
+ const file = writeLog(
+ [
+ '[agent-loop] failed: Error: DSH credentials store will not boot — aborting before WORKER.',
+ ' at assertDshCredentialsStore (file:///x.js:1:1)',
+ '[agent-loop] warn: could not create HITL checkpoint',
+ 'AGENT_LOOP_DONE {"v":1,"kind":"loop","bundle":"b","complete":false,"exitCode":1,"reason":"DSH credentials store will not boot"}',
+ '',
+ ].join('\n'),
+ )
+ expect(readRunFailureReason(file)).toBe('DSH credentials store will not boot')
+ })
+
+ it('falls back to the last failed: line without the log prefix', () => {
+ const file = writeLog('[agent-loop] repo=/r\n[agent-loop] failed: Error: boom\n at x (y:1:1)\n')
+ expect(readRunFailureReason(file)).toBe('boom')
+ })
+
+ it('reads only past the offset and caps length', () => {
+ const head = 'AGENT_LOOP_DONE {"v":1,"kind":"loop","bundle":"b","complete":false,"exitCode":1,"reason":"old"}\n'
+ const file = writeLog(`${head}${'x'.repeat(1000)}\n`)
+ const reason = readRunFailureReason(file, Buffer.byteLength(head))
+ expect(reason).toHaveLength(400)
+ expect(reason?.endsWith('…')).toBe(true)
+ })
+
+ it('returns undefined for a missing or empty log', () => {
+ expect(readRunFailureReason(path.join(tmpDir(), 'nope.log'))).toBeUndefined()
+ expect(readRunFailureReason(writeLog(''))).toBeUndefined()
+ })
})
describe('spawnPreviewDetached', () => {
diff --git a/src/cli/promptFlow.ts b/src/cli/promptFlow.ts
index 5d5560f..b3ccd87 100644
--- a/src/cli/promptFlow.ts
+++ b/src/cli/promptFlow.ts
@@ -23,6 +23,7 @@ import { assertShellConfigTrusted } from '../loop/loopShellTrust.js'
import { StreamCollector } from '../stream/streamCollect.js'
import { formatPreflightMessage, validateGoalPreflight } from '../loop/loopPreflight.js'
import { formatLoopResumeCommand } from '../loop/loopResumeCommand.js'
+import { parseLoopCompletionSignalLine } from '../integrations/loopCompletionSignal.js'
import {
formatVerifyScriptLintMessage,
lintVerifyScript,
@@ -190,11 +191,13 @@ export function resolveAgentLoopRunBin(): string {
export function spawnLoopRun(
loopDir: string,
repoRoot: string,
-): { child: ChildProcess; logPath: string; bundleLabel: string } {
+): { child: ChildProcess; logPath: string; logOffset: number; bundleLabel: string } {
const bundleLabel = path.relative(repoRoot, loopDir) || '.'
const logPath = path.join(loopDir, 'prompt-run.log')
fs.mkdirSync(loopDir, { recursive: true })
const logFd = fs.openSync(logPath, 'a')
+ /** Log is append-only across runs; readers start here to see only this run. */
+ const logOffset = fs.fstatSync(logFd).size
const child = spawn(process.execPath, [resolveAgentLoopRunBin(), 'run', bundleLabel], {
cwd: repoRoot,
stdio: ['ignore', logFd, logFd],
@@ -207,7 +210,7 @@ export function spawnLoopRun(
// log fd may already be closed
}
})
- return { child, logPath, bundleLabel }
+ return { child, logPath, logOffset, bundleLabel }
}
/** Trust-gate preview at the execute site — `agent-loop run` does not exec this shell. */
@@ -245,6 +248,39 @@ export function formatRunHandoffCommand(
return formatLoopResumeCommand(bundleLabel, env)
}
+const RUN_FAILURE_REASON_MAX = 400
+
+/**
+ * Why the spawned run ended, from this run's slice of prompt-run.log:
+ * the `AGENT_LOOP_DONE` reason when present, else the last `failed:` / error line,
+ * else the last non-empty line. One line, capped — the full log stays on disk.
+ */
+export function readRunFailureReason(logPath: string, logOffset = 0): string | undefined {
+ let text: string
+ try {
+ const buf = fs.readFileSync(logPath)
+ text = buf.subarray(Math.min(logOffset, buf.length)).toString('utf8')
+ } catch {
+ return undefined
+ }
+ const lines = text
+ .split(/\r?\n/)
+ .map((line) => line.trim())
+ .filter((line) => line.length > 0)
+ let reason: string | undefined
+ for (let i = lines.length - 1; i >= 0 && reason === undefined; i--) {
+ reason = parseLoopCompletionSignalLine(lines[i]!)?.reason
+ }
+ reason ??= [...lines].reverse().find((line) => /\bfailed:|^(Error|TypeError)\b/.test(line))
+ reason ??= lines.at(-1)
+ if (reason === undefined) return undefined
+ reason = reason.replace(/^\[agent-loop\]\s*(failed:\s*)?(Error:\s*)?/, '').trim()
+ if (reason.length === 0) return undefined
+ return reason.length > RUN_FAILURE_REASON_MAX
+ ? `${reason.slice(0, RUN_FAILURE_REASON_MAX - 1)}…`
+ : reason
+}
+
export async function waitForChildExit(child: ChildProcess): Promise {
if (child.exitCode !== null) return child.exitCode
return await new Promise((resolve) => {
diff --git a/src/cli/promptTui.test.tsx b/src/cli/promptTui.test.tsx
index 947c179..8e2df94 100644
--- a/src/cli/promptTui.test.tsx
+++ b/src/cli/promptTui.test.tsx
@@ -97,6 +97,23 @@ describe('DoneView', () => {
const fail = render(createElement(DoneView, { exitCode: 2 }))
expect(fail.lastFrame()).toMatch(/run exited 2/)
})
+
+ it('shows the failure reason and log path when a run fails', () => {
+ const fail = render(
+ createElement(DoneView, {
+ exitCode: 1,
+ failure: { reason: 'DSH credentials store will not boot', log: '.cursor/loops/demo/prompt-run.log' },
+ }),
+ )
+ expect(fail.lastFrame()).toMatch(/run exited 1/)
+ expect(fail.lastFrame()).toMatch(/DSH credentials store will not boot/)
+ expect(fail.lastFrame()).toMatch(/log: \.cursor\/loops\/demo\/prompt-run\.log/)
+
+ const ok = render(
+ createElement(DoneView, { exitCode: 0, failure: { reason: 'stale', log: 'x.log' } }),
+ )
+ expect(ok.lastFrame()).not.toMatch(/stale|log:/)
+ })
})
describe('MultilinePrompt', () => {
diff --git a/src/cli/promptTui.tsx b/src/cli/promptTui.tsx
index 4625b36..bb29dbc 100644
--- a/src/cli/promptTui.tsx
+++ b/src/cli/promptTui.tsx
@@ -216,12 +216,20 @@ export function FreezeConfirm({ snapshot, onChoose }: FreezeConfirmProps) {
)
}
+export type RunFailureSummary = {
+ /** One-line cause from the run log (`AGENT_LOOP_DONE` reason when present). */
+ reason?: string
+ /** prompt-run.log path, repo-relative when possible. */
+ log: string
+}
+
export type DoneViewProps = {
exitCode: number
preview?: string
+ failure?: RunFailureSummary
}
-export function DoneView({ exitCode, preview }: DoneViewProps) {
+export function DoneView({ exitCode, preview, failure }: DoneViewProps) {
return (
@@ -233,6 +241,12 @@ export function DoneView({ exitCode, preview }: DoneViewProps) {
preview: {preview}
) : null}
+ {exitCode !== 0 && failure?.reason ? {failure.reason} : null}
+ {exitCode !== 0 && failure ? (
+
+ log: {failure.log}
+
+ ) : null}
)
}
@@ -329,9 +343,13 @@ export async function watchChildInk(
})
}
-export async function showDoneInk(exitCode: number, preview?: string): Promise {
+export async function showDoneInk(
+ exitCode: number,
+ preview?: string,
+ failure?: RunFailureSummary,
+): Promise {
await new Promise((resolve) => {
- const instance = render(createElement(DoneView, { exitCode, preview }), {
+ const instance = render(createElement(DoneView, { exitCode, preview, failure }), {
exitOnCtrlC: false,
incrementalRendering: true,
})
diff --git a/src/integrations/loopCompletionSignal.ts b/src/integrations/loopCompletionSignal.ts
index bd64edd..dcc6c2e 100644
--- a/src/integrations/loopCompletionSignal.ts
+++ b/src/integrations/loopCompletionSignal.ts
@@ -41,6 +41,21 @@ export function formatLoopCompletionSignalLine(payload: LoopCompletionSignalPayl
return `${LOOP_COMPLETION_SIGNAL_PREFIX} ${JSON.stringify(payload)}`
}
+/** Inverse of {@link formatLoopCompletionSignalLine}; `undefined` for any other line. */
+export function parseLoopCompletionSignalLine(
+ line: string,
+): LoopCompletionSignalPayload | undefined {
+ const prefix = `${LOOP_COMPLETION_SIGNAL_PREFIX} `
+ if (!line.startsWith(prefix)) return undefined
+ try {
+ const payload = JSON.parse(line.slice(prefix.length)) as Partial
+ if (payload?.v !== 1 || typeof payload.reason !== 'string') return undefined
+ return payload as LoopCompletionSignalPayload
+ } catch {
+ return undefined
+ }
+}
+
/**
* One-line machine-readable completion event on stdout (fd 1).
* Uses writeSync so piped stdout (Cursor background shells) is flushed before process.exit.
diff --git a/src/loop/loopCredentialPreflight.test.ts b/src/loop/loopCredentialPreflight.test.ts
index 3bf96ee..85671ab 100644
--- a/src/loop/loopCredentialPreflight.test.ts
+++ b/src/loop/loopCredentialPreflight.test.ts
@@ -4,6 +4,7 @@ import path from 'node:path'
import { afterEach, describe, expect, it } from 'vitest'
import {
assertLoopCredentials,
+ formatMissingLoopCredentials,
listMissingLoopCredentials,
requiredCredentialNeed,
} from './loopCredentialPreflight.js'
@@ -80,33 +81,45 @@ describe('loopCredentialPreflight', () => {
])
})
- it('does not require env keys for OpenCode / DSH / Codex / Muse', () => {
+ it('requires DEEPSEEK_API_KEY in env for DSH (headless ignores the credentials file)', () => {
+ expect(requiredCredentialNeed('dsh', {})).toBe('DEEPSEEK_API_KEY')
+ expect(requiredCredentialNeed('dsh', { DEEPSEEK_API_KEY: 'sk-x' })).toBeUndefined()
+ const message = formatMissingLoopCredentials(
+ listMissingLoopCredentials({ runtime: 'dsh', reviewRuntime: 'claude', postQualityReview: 'auto' }, {}),
+ )
+ expect(message).toMatch(/worker \(dsh\): DEEPSEEK_API_KEY is not set/)
+ expect(message).toMatch(/does not read ~\/\.dsh\/\.credentials\.yaml/)
+ expect(() =>
+ assertLoopCredentials({ runtime: 'dsh', postQualityReview: false }, { DSH_HOME: '/nonexistent' }),
+ ).toThrow(/DEEPSEEK_API_KEY is not set/)
+ })
+
+ it('does not require env keys for OpenCode / Codex / Muse / Claude', () => {
expect(requiredCredentialNeed('opencode', {})).toBeUndefined()
- expect(requiredCredentialNeed('dsh', {})).toBeUndefined()
expect(requiredCredentialNeed('codex', {})).toBeUndefined()
expect(requiredCredentialNeed('muse', {})).toBeUndefined()
expect(requiredCredentialNeed('claude', {})).toBeUndefined()
})
- it('aborts a DSH worker on a wrapped credentials store before WORKER', () => {
+ it('aborts a DSH worker on a credentials store DSH cannot boot', () => {
const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-loop-creds-'))
tmpHomes.push(dir)
- fs.writeFileSync(
- path.join(dir, '.credentials.yaml'),
- 'version: 1\nrefs:\n DEEPSEEK_API_KEY: sk-secret-do-not-leak\n',
- { encoding: 'utf8', mode: 0o600 },
- )
- expect(() =>
+ const store = path.join(dir, '.credentials.yaml')
+ const run = () =>
assertLoopCredentials(
{ runtime: 'dsh', postQualityReview: false },
- { DSH_HOME: dir },
- ),
- ).toThrow(/aborting before WORKER/)
- expect(() =>
- assertLoopCredentials(
- { runtime: 'dsh', postQualityReview: false },
- { DSH_HOME: dir },
- ),
- ).toThrow(/wrapped store/)
+ { DSH_HOME: dir, DEEPSEEK_API_KEY: 'sk-test' },
+ )
+ fs.writeFileSync(store, 'version: "1"\nrefs:\n DEEPSEEK_API_KEY: sk-secret-do-not-leak\n', {
+ encoding: 'utf8',
+ mode: 0o600,
+ })
+ expect(run).toThrow(/aborting before WORKER/)
+ expect(run).toThrow(/layout v1/)
+ fs.writeFileSync(store, 'version: 1\nrefs:\n DEEPSEEK_API_KEY: sk-test\n', {
+ encoding: 'utf8',
+ mode: 0o600,
+ })
+ expect(run).not.toThrow(/aborting before WORKER/)
})
})
diff --git a/src/loop/loopCredentialPreflight.ts b/src/loop/loopCredentialPreflight.ts
index 37f7568..a4eec91 100644
--- a/src/loop/loopCredentialPreflight.ts
+++ b/src/loop/loopCredentialPreflight.ts
@@ -46,9 +46,12 @@ export function requiredCredentialNeed(
? undefined
: 'OPENROUTER_API_KEY (or ANTHROPIC_API_KEY / OPENAI_API_KEY / GOOGLE_API_KEY)'
}
+ case LOOP_RUNTIME_DSH:
+ // DSH >= 0.2.1 `--profile headless` mounts no credentials service, so a key stored in
+ // ~/.dsh/.credentials.yaml (what the web Models page writes) is invisible to it.
+ return envSet('DEEPSEEK_API_KEY', env) ? undefined : 'DEEPSEEK_API_KEY'
case LOOP_RUNTIME_OPENCODE:
case LOOP_RUNTIME_CODEX:
- case LOOP_RUNTIME_DSH:
case LOOP_RUNTIME_MUSE:
case LOOP_RUNTIME_CLAUDE:
return undefined
@@ -95,14 +98,21 @@ export function listMissingLoopCredentials(
return missing
}
+export const DSH_HEADLESS_ENV_KEY_HINT =
+ 'DSH headless does not read ~/.dsh/.credentials.yaml — export DEEPSEEK_API_KEY in the launching shell'
+
export function formatMissingLoopCredentials(missing: readonly CredentialNeed[]): string {
- return [
+ const lines = [
'Missing credentials — aborting before WORKER.',
...missing.map(
(item) =>
` ${item.role} (${item.runtime}): ${item.need} is not set. Run via doppler or agent-check ${item.runtime}`,
),
- ].join('\n')
+ ]
+ if (missing.some((item) => item.runtime === LOOP_RUNTIME_DSH)) {
+ lines.push(` note: ${DSH_HEADLESS_ENV_KEY_HINT}`)
+ }
+ return lines.join('\n')
}
function configUsesDsh(
diff --git a/src/site/landingAgentReadiness.test.ts b/src/site/landingAgentReadiness.test.ts
index 766273e..21c2a74 100644
--- a/src/site/landingAgentReadiness.test.ts
+++ b/src/site/landingAgentReadiness.test.ts
@@ -85,7 +85,7 @@ describe('landing agent readiness', () => {
}
})
- it('site version labels say 0.8.5 current with no stale 0.7.x as current', () => {
+ it('site version labels say 0.8.6 current with no stale 0.7.x as current', () => {
const versionPaths = [
'about/index.html',
'about/index.md',
@@ -96,14 +96,14 @@ describe('landing agent readiness', () => {
]
for (const file of versionPaths) {
const body = readSite(file)
- expect(body, file).toContain('0.8.5')
+ expect(body, file).toContain('0.8.6')
expect(body, file).not.toMatch(/Current npm: \*\*0\.7\./)
}
const llms = readSite('llms.txt')
- expect(llms).toContain('Current npm: **0.8.5**')
+ expect(llms).toContain('Current npm: **0.8.6**')
expect(llms).toContain('supported line **0.8.x**')
expect(llms).not.toContain('supported line **0.7.x**')
- expect(llms).toMatch(/Changelog.*0\.8\.5/)
+ expect(llms).toMatch(/Changelog.*0\.8\.6/)
})
it('llms.txt follows llmstxt.org v2 and includes when-to-use guidance', () => {
@@ -775,9 +775,9 @@ describe('landing agent readiness', () => {
const grok47Beat = 'grok-4.7'
const codexAstraBeat = 'gpt-6-astra'
const claudeAliasBeat = 'latest-per-family'
- const dshFlatBeat = 'must be a flat'
+ const dshEnvKeyBeat = 'DEEPSEEK_API_KEY'
const dshPreflightBeat = 'agent-check dsh'
- const dshQuoteNotEnoughBeat = 'alone is not enough'
+ const dshLayoutV1Beat = 'layout v1'
const presetsQuestion = faq?.mainEntity?.find(
(q) => q.name === 'How do worker and judge presets work?',
@@ -800,9 +800,9 @@ describe('landing agent readiness', () => {
expect(surface).not.toMatch(/supported line \*\*0\.7\.x\*\*/i)
}
- expect(llms).toContain('Current npm: **0.8.5**')
+ expect(llms).toContain('Current npm: **0.8.6**')
expect(llms).toContain('0.8.x')
- expect(llms).not.toContain('Current npm: **0.8.4**')
+ expect(llms).not.toContain('Current npm: **0.8.5**')
expect(llms).not.toContain('Current npm: **0.7.')
expect(llms).toContain('@dancingteeth/opencode-agent-looper')
expect(llms).toMatch(/no Cursor default judge/i)
@@ -822,7 +822,9 @@ describe('landing agent readiness', () => {
expect(llms).toContain(grok47Beat)
expect(llms).toContain(flash41Slug)
expect(llms).toContain(dshPreflightBeat)
- expect(llms).toContain(dshQuoteNotEnoughBeat)
+ expect(llms).toContain(dshEnvKeyBeat)
+ expect(llms).not.toContain('must be a flat')
+ expect(llms).toContain(dshLayoutV1Beat)
expect(llms).toContain(setupWizardBeat)
expect(llms).toContain(plantBeat)
expect(llms).toContain(modelsDevBeat)
@@ -854,7 +856,7 @@ describe('landing agent readiness', () => {
harnessHtml.match(
/[\s\S]*?<\/article>/,
)?.[0] ?? ''
- expect(dshCard).toContain(dshFlatBeat)
+ expect(dshCard).toContain(dshEnvKeyBeat)
expect(dshCard).toContain(dshPreflightBeat)
expect(dshCard).not.toContain('version: "1"')
expect(dshCard).toContain(flashDefault)
@@ -866,9 +868,9 @@ describe('landing agent readiness', () => {
expect(harnessMd).toContain(grok47Beat)
expect(harnessMd).toContain(codexAstraBeat)
expect(harnessMd).toContain(claudeAliasBeat)
- expect(harnessMd).toContain(dshFlatBeat)
+ expect(harnessMd).toContain(dshEnvKeyBeat)
expect(harnessMd).toContain(dshPreflightBeat)
- expect(harnessMd).toContain(dshQuoteNotEnoughBeat)
+ expect(harnessMd).toContain(dshLayoutV1Beat)
expect(harnessMd).not.toContain('version: "1"')
})
diff --git a/templates/GOAL.visual.template.md b/templates/GOAL.visual.template.md
index 56468b0..8004012 100644
--- a/templates/GOAL.visual.template.md
+++ b/templates/GOAL.visual.template.md
@@ -4,6 +4,8 @@ tags:
- agents
- templates
- frontend
+ - agentic_ai
+ - type/app
---
# TW — Visual / taste: {page or UI}
diff --git a/templates/RESEARCH.example.md b/templates/RESEARCH.example.md
index 02f279a..56f4192 100644
--- a/templates/RESEARCH.example.md
+++ b/templates/RESEARCH.example.md
@@ -3,6 +3,8 @@ tags:
- documentation
- agents
- loops
+ - agentic_ai
+ - type/app
---
# Research — short title