duaer-spec 0.13.0 → 0.15.0

package/.duaer/active-job.json

@@ -1,5 +1,6 @@
 {
-  "specDir": ".duaer/specs/032-revise-ux",
-  "branch": "fix/revise-ux",
-  "startedAt": "2026-09-16T03:40:00.000Z"
+  "featureDir": ".duaer/specs/055-release-015",
+  "branch": "feat/release-015",
+  "worktree": ".worktree/feat-release-015",
+  "status": "active"
 }

package/.duaer/memory/testing.md

@@ -1,21 +1,22 @@
 # Testing expectations (project contract)
 
 Agents **must** read this file before marking work verified or accepting a job.
-Replace command examples with the adopting project's real scripts. Keep the
-level model and risk rules unless an ADR documents a change.
+This file is the **duaer-spec** repo contract. Adopters replace command examples
+with their product scripts; keep the level model and risk rules unless an ADR
+documents a change.
 
 ## Levels
 
-| Level | What | Typical commands (replace) | Default owner |
+| Level | What | Typical commands (this repo) | Default owner |
 |---|---|---|---|
-| **L0** | Lint / typecheck / static | `npm run lint`, `tsc --noEmit` | After every implementation pass |
-| **L1** | Unit tests for changed modules | `npm test` (or package subset) | Default for code changes |
+| **L0** | Lint / typecheck / static | `node --check bin/duaer-live.mjs` `node --check web/live-dev/app.js` | After every implementation pass |
+| **L1** | Unit tests for changed modules | `npm test` when unit files exist under `test/` | Default for code changes |
 | **L2** | Integration / product acceptance at changed boundaries | project acceptance or integration suite | When boundaries or core paths change |
-| **L3** | Automated E2E / browser for user-visible paths | `npm run test:e2e` or equivalent **subset** | When UI / protocol UX changes |
+| **L3** | Automated E2E / protocol smoke for user-visible paths | **`npm run test:live`** (live desk shell + `/api/validate` gate; mock LLM, no paid API) | When live desk UI / protocol UX changes |
 | **L4** | Manual account / device path when automation cannot cover auth or real data | documented steps in the Brief | When UI/auth and no automated substitute |
 
 IDE Browser / MCP exploration is **optional discovery**. It does **not** replace
-L3 automation when the project has an E2E suite.
+L3 when `npm run test:live` covers the touched path.
 
 ## Risk table (what to run)
 
@@ -24,12 +25,25 @@ L3 automation when the project has an E2E suite.
 | Docs / comments only | None (note in Brief) |
 | Internal code, same behavior | L0 + L1 for affected packages |
 | API / data / core path | L0 + L1 + L2 (or documented equivalent) |
-| User-visible or protocol-visible UI/UX | L0 + L1 + **L3 subset for touched flows** + update E2E catalog |
+| User-visible or protocol-visible UI/UX (live desk) | L0 + **`npm run test:live` (L3)** + update E2E catalog |
 | Auth / payments / irreversible ops | Above + L4 if L3 cannot cover |
 
 Prefer **targeted subsets** over full monorepo suites. Do not skip a required
 level without an explicit waiver in the feature docs (`tasks.md` or Spec).
 
+## Live desk L3 (`npm run test:live`)
+
+Covers without a paid LLM:
+
+1. Desk shell HTML/CSS/JS markers (three columns, structured confirm fields,
+   `validationAllowsSend`)
+2. Local validate failures (empty / too-short card)
+3. `/api/validate` pass and `/api/validate/fix` via an in-process mock
+   OpenAI-compatible server
+
+Does **not** cover: real model quality, Terminal CLI launch, or full revise
+dispatch. Those stay manual E2E catalog rows or future suites.
+
 ## Opt-in (still need an explicit ask or Spec note)
 
 Mark these in the project table when they are expensive:

package/.duaer/specs/033-agent-detect/delivery.json

@@ -0,0 +1,13 @@
+{
+  "status": "accepted",
+  "acceptedAt": "2026-09-16T04:15:00.000Z",
+  "verification": {
+    "levels": ["docs", "L0", "L3-catalog"],
+    "commands": [
+      "node --check bin/duaer-live.mjs",
+      "PATH=/usr/bin:/bin node -e detectAgents smoke"
+    ],
+    "result": "pass",
+    "e2e": ["E2E-034"]
+  }
+}

package/.duaer/specs/033-agent-detect/spec.md

@@ -0,0 +1,24 @@
+# Feature Specification: Detect CLI agents under launchd PATH
+
+**Feature Branch**: `fix/agent-detect`
+
+**Created**: 2026-09-16
+
+**Status**: Active
+
+## Goal
+
+Live desk must detect installed Cursor Agent / Claude Code even when started
+via LaunchAgent (minimal PATH).
+
+## Problem
+
+LaunchAgent PATH is `/usr/bin:/bin:/usr/sbin:/sbin`, so `which agent|claude`
+fails even though `~/.local/bin` and `/usr/local/bin` have the CLIs.
+
+## Acceptance
+
+1. `ensureCliSearchPath` prepends `~/.local/bin`, `/usr/local/bin`, `/opt/homebrew/bin`
+2. `whichCmd` falls back to those dirs if `which` misses
+3. `/api/agents` reports installed agents when binaries exist there
+4. LaunchAgent plist PATH updated (local handoff) after merge

package/.duaer/specs/033-agent-detect/tasks.md

@@ -0,0 +1,4 @@
+# Tasks
+
+- [x] T001 Expand PATH + whichCmd fallback
+- [x] T002 Docs; accept; merge; reload LaunchAgent

package/.duaer/specs/034-stale-worktree/delivery.json

@@ -0,0 +1,15 @@
+{
+  "status": "accepted",
+  "acceptedAt": "2026-09-16T04:28:30.000Z",
+  "summary": "Live desk recovers Brief/status from product primary after worktree handoff cleanup; revise recreates worktree instead of failing.",
+  "verification": {
+    "levels": ["docs", "L0", "L1-smoke", "L3-catalog"],
+    "commands": [
+      "/usr/local/bin/node --check bin/duaer-live.mjs",
+      "curl -s 'http://127.0.0.1:8792/api/status?jobId=024-job-3l9xtu'"
+    ],
+    "result": "pass",
+    "e2e": ["E2E-035"],
+    "notes": "Smoke: status=accepted, delivery.status=accepted, canRevise=true, handoffCleaned=true, worktreeExists=false, featureDir=/Users/morgan/autotest/.duaer/specs/034-job-3l9xtu, resolvedFrom=primary. LaunchAgent 8787 reloaded after merge."
+  }
+}

package/.duaer/specs/034-stale-worktree/spec.md

@@ -0,0 +1,20 @@
+# Feature Specification: Survive worktree handoff cleanup
+
+**Feature Branch**: `fix/stale-worktree`
+
+**Created**: 2026-09-16
+
+**Status**: Active
+
+## Goal
+
+After the digital employee merges and removes the request worktree, the live
+desk must still show accepted status / preview from the product repo, and
+revise must recreate a worktree instead of erroring「worktree 已不存在」.
+
+## Acceptance
+
+1. Status resolves Brief/delivery from `repoPath` + `specDir` when worktree gone
+2. Preview/artifacts serve from primary checkout when needed
+3. Revise recreates `.worktree/feat-*-rN` from develop and copies Brief
+4. canRevise true when primary Brief exists

package/.duaer/specs/034-stale-worktree/tasks.md

@@ -0,0 +1,5 @@
+# Tasks
+
+- [x] T001 resolveDispatchRoots + recreateWorktreeForRevise
+- [x] T002 status/artifact/revise wiring
+- [x] T003 verify against 024-job-3l9xtu; docs; merge; reload live

package/.duaer/specs/035-revise-card-below/delivery.json

@@ -0,0 +1,10 @@
+{
+  "status": "accepted",
+  "acceptedAt": "2026-09-16T04:40:00.000Z",
+  "verification": {
+    "levels": ["docs", "L0", "L3-catalog"],
+    "commands": ["node --check web/live-dev/app.js"],
+    "result": "pass",
+    "e2e": ["E2E-036"]
+  }
+}

package/.duaer/specs/035-revise-card-below/spec.md

@@ -0,0 +1,19 @@
+# Feature Specification: Revise card below confirm card
+
+**Feature Branch**: `fix/revise-card-below`
+
+**Created**: 2026-09-16
+
+**Status**: Active
+
+## Goal
+
+Keep the top confirm card unchanged. Put the revise card in the bottom panel
+so users can read it under the dialogue flow without the top card becoming 改进卡.
+
+## Acceptance
+
+1. Confirm card title/labels/styles never switch to revise chrome
+2. Revise fields render in `#revisePanel` below preview
+3. Chat applyCard updates bottom revise fields in revise mode
+4. After revise lock, top still shows original requirements

package/.duaer/specs/035-revise-card-below/tasks.md

@@ -0,0 +1,7 @@
+# Tasks
+
+- [x] T001 Keep top confirm card original; never switch to revise chrome
+- [x] T002 Render revise fields in `#revisePanel` below preview
+- [x] T003 Chat applyCard updates bottom revise fields in revise mode
+- [x] T004 After revise lock, top still shows original requirements
+- [x] T005 Docs E2E-036 + verify (`node --check`) + accept + merge + reload live

package/.duaer/specs/036-progress-cta/delivery.json

@@ -0,0 +1,10 @@
+{
+  "status": "accepted",
+  "acceptedAt": "2026-09-16T04:45:00.000Z",
+  "verification": {
+    "levels": ["docs", "L0"],
+    "commands": ["node --check bin/duaer-live.mjs", "node --check web/live-dev/app.js"],
+    "result": "pass",
+    "e2e": ["E2E-037"]
+  }
+}

package/.duaer/specs/036-progress-cta/spec.md

@@ -0,0 +1,18 @@
+# Feature Specification: Hide product/revise CTAs until accepted
+
+**Feature Branch**: `fix/progress-cta`
+
+**Created**: 2026-09-16
+
+**Status**: Active
+
+## Goal
+
+While progress shows in-progress (e.g. `0/3 · 进行中`), do not show 查看成品
+or 再改一版 / 改进卡. Those appear only after delivery accepted.
+
+## Acceptance
+
+1. Status `dispatched` with open delivery → preview null, canRevise false
+2. Status accepted → preview + revise CTA available
+3. During revising round → preview may stay; revise panel as needed

package/.duaer/specs/036-progress-cta/tasks.md

@@ -0,0 +1,5 @@
+# Tasks
+
+- [x] T001 Gate showPreview/canRevise on accept
+- [x] T002 UI hide preview/revise until productReady
+- [x] T003 Docs; merge; reload live

package/.duaer/specs/037-live-i18n/delivery.json

@@ -0,0 +1,38 @@
+{
+  "schemaVersion": 1,
+  "status": "accepted",
+  "feature": "037-live-i18n",
+  "acceptedAt": "2026-09-16T04:52:00.000Z",
+  "summary": "Live desk zh-CN/en i18n with language switcher, catalogs, DOM data-i18n, and dynamic sync.",
+  "verification": {
+    "commands": [
+      {
+        "command": "node --check web/live-dev/i18n.js",
+        "result": "pass — exit 0 (SYNTAX_OK) 2026-09-16"
+      },
+      {
+        "command": "node --check web/live-dev/app.js",
+        "result": "pass — exit 0 (SYNTAX_OK) 2026-09-16"
+      },
+      {
+        "command": "key parity: every t() key in app.js vs zhCN + en in i18n.js",
+        "result": "pass — no missing keys"
+      },
+      {
+        "command": "grep user-visible Chinese in app.js",
+        "result": "pass — only intentional LLM kickoff string + comments"
+      },
+      {
+        "command": "curl -sS -o /dev/null -w '%{http_code}' http://localhost:8787/",
+        "result": "pass — HTTP 200 (pre-merge; LaunchAgent still on primary develop)"
+      },
+      {
+        "command": "curl -sS -o /dev/null -w '%{http_code}' http://localhost:8787/i18n.js",
+        "result": "expected 404 pre-merge — i18n.js not on develop until merge + kickstart"
+      }
+    ],
+    "e2e": ["E2E-038"],
+    "notes": "T007 smoke: language switch + localStorage persistence covered by code path (initI18n/detectLocale/setLocale + #langSelect). Post-merge handoff: launchctl kickstart live8787 then re-curl /i18n.js."
+  },
+  "tasksCompleted": ["T001", "T002", "T003", "T004", "T005", "T006", "T007", "T008"]
+}

package/.duaer/specs/037-live-i18n/spec.md

@@ -0,0 +1,43 @@
+# Feature Specification: Live desk i18n (zh-CN + en)
+
+**Feature Branch**: `feat/live-i18n`
+
+**Created**: 2026-09-16
+
+**Status**: Active
+
+## Goal
+
+Live desk UI supports multiple languages. Initial locales: **zh-CN** (default)
+and **en**, with a visible language switcher. Preference persists.
+
+## In scope
+
+- Message catalogs for static + dynamic live UI copy
+- Header language switch (zh-CN / en)
+- Persist locale (`localStorage` key `duaer.live.locale`)
+- Browser language hint on first visit (zh* → zh-CN, else en)
+- Confirm card / revise card / dispatch / preview / revise CTAs translated
+- Do not change confirm-card layout; i18n only for strings
+
+## Out of scope
+
+- Translating agent Terminal prompts (may stay bilingual later)
+- Full localization of every server console log line
+- Translating LLM system prompts used by `/api/chat`
+
+## Acceptance
+
+1. Switching to English updates visible desk copy (static `data-i18n` + dynamic
+   JS strings) without a layout break
+2. Reload keeps the chosen locale via `localStorage` (`duaer.live.locale`)
+3. zh-CN remains default when no preference and browser language is Chinese
+4. Language switcher (`#langSelect`) is visible in the header
+5. E2E catalog note (E2E-038)
+
+## Notes
+
+- Catalogs live in `web/live-dev/i18n.js`; `app.js` imports `t` / `setLocale` /
+  `onLocaleChange`
+- Static files under `web/live-dev/` are served as-is by `bin/duaer-live.mjs`
+  (no whitelist); `i18n.js` needs no server change

package/.duaer/specs/037-live-i18n/tasks.md

@@ -0,0 +1,13 @@
+# Tasks: Live desk i18n
+
+- [x] T001 Add `web/live-dev/i18n.js` with zh-CN + en catalogs, `t`, `setLocale`,
+      `applyDomI18n`, `initI18n`, `onLocaleChange`, `getLocale`
+- [x] T002 Mark static copy in `index.html` with `data-i18n` / placeholders;
+      add `#langSelect` + `.lang-switch` styles
+- [x] T003 Expand catalogs for every user-visible string set from `app.js`
+- [x] T004 Wire `app.js`: import i18n, replace hardcoded UI strings with `t()`,
+      sync dynamic chrome on `onLocaleChange`, bind `#langSelect`
+- [x] T005 Confirm `duaer-live` static serve covers `i18n.js` (directory serve)
+- [x] T006 Spec acceptance + E2E-038 note
+- [x] T007 Smoke-test: open live desk, switch zh-CN ↔ en, reload persists
+- [x] T008 Stamp `delivery.json` accepted (parent verify / merge)

package/.duaer/specs/038-revise-enqueue-style/delivery.json

@@ -0,0 +1,18 @@
+{
+  "schemaVersion": 1,
+  "status": "accepted",
+  "feature": "038-revise-enqueue-style",
+  "acceptedAt": "2026-09-16T05:22:00.000Z",
+  "summary": "Honest revise Terminal enqueue after accepted delivery (fresh session, no false PID reuse) and dark revise card matching panel plate/shadow.",
+  "verification": {
+    "commands": [
+      {
+        "command": "node --check bin/duaer-live.mjs",
+        "result": "pass — exit 0 (SYNTAX_OK) 2026-09-16"
+      }
+    ],
+    "e2e": ["E2E-039"],
+    "notes": "T004: syntax check on duaer-live.mjs; runner heartbeat + isTerminalRunnerHealthy reviewed; revise after accepted uses continueSession=false with Terminal queue; revise-panel CSS uses var(--plate)/var(--shadow) like .panel. Post-merge handoff: launchctl kickstart com.duaer.live8787."
+  },
+  "tasksCompleted": ["T001", "T002", "T003", "T004"]
+}

package/.duaer/specs/038-revise-enqueue-style/spec.md

@@ -0,0 +1,60 @@
+# Feature Specification: Fix revise enqueue + dark revise card
+
+**Feature Branch**: `fix/revise-enqueue-style`
+
+**Created**: 2026-09-16
+
+**Status**: Active
+
+## Goal
+
+Make revise enqueue truthful: when the UI reports「已送入原 Terminal」, an agent
+must actually start. Reuse the same Terminal window and queue when healthy; do
+not treat a dead or stale runner as live (false PID reuse). Avoid `--continue`
+against an ended session. Prefer a fresh agent prompt (no `--continue`) after
+accepted delivery while still enqueueing through the Terminal queue. Restyle
+the revise card to the desk dark plate/panel look (not translucent white).
+
+## Problem
+
+1. UI can show「已送入原 Terminal」while no agent runs
+2. False PID reuse / stale runner makes enqueue look successful
+3. `--continue` after an ended session fails to launch work
+4. Revise card chrome is translucent white and clashes with dark plate/panel desk
+
+## In scope
+
+- Runner liveness: heartbeat (or equivalent) so dead PIDs are not treated as
+  active Terminal targets
+- Enqueue must actually trigger the agent in the intended Terminal when the
+  runner is alive; same window OK
+- After accepted delivery, prefer new agent prompt without `--continue`, still
+  via Terminal queue
+- Do not use `--continue` when the prior session has ended
+- Restyle revise card to dark plate/panel desk style
+
+## Out of scope
+
+- Changing first-dispatch / non-revise launch flows except as needed for shared
+  runner health
+- Redesigning left-chat revise dialogue copy beyond what enqueue honesty needs
+- Remote push / promote to `main`
+
+## Acceptance
+
+1. When UI shows「已送入原 Terminal」after revise confirm, an agent process
+   actually starts (or clearly fails with honest UI — no false success)
+2. A dead/stale runner PID is not reused as a live Terminal target; heartbeat
+   (or equivalent) detects liveness before enqueue success
+3. Same Terminal window may be reused when the runner is alive; enqueue must
+   still trigger the agent
+4. After accepted delivery, revise relaunch prefers a new agent prompt without
+   `--continue`, while still using the Terminal queue
+5. `--continue` is not used against an ended session as the sole launch path
+6. Revise card matches dark plate/panel desk styling (no translucent white card)
+7. E2E catalog note (E2E-039)
+
+## Assumptions
+
+- Terminal queue / desk runner already exists; this job hardens liveness and
+  post-accept launch policy, then restyles the revise card

package/.duaer/specs/038-revise-enqueue-style/tasks.md

@@ -0,0 +1,7 @@
+# Tasks
+
+- [x] T001 Harden revise enqueue: runner heartbeat/liveness, no false PID reuse,
+      no `--continue` after accepted delivery; still use Terminal queue
+- [x] T002 Restyle revise card to dark plate/panel desk (not translucent white)
+- [x] T003 Spec-sync / E2E-039 for honest enqueue + card style
+- [x] T004 Risk-based verify, accept delivery, merge to develop, handoff

package/.duaer/specs/039-desk-scroll-sync/delivery.json

@@ -0,0 +1,18 @@
+{
+  "schemaVersion": 1,
+  "status": "accepted",
+  "feature": "039-desk-scroll-sync",
+  "acceptedAt": "2026-09-16T05:30:00.000Z",
+  "summary": "Viewport-bound desk columns with independent scrolls; right panel auto-focuses active stage in sync with left chat.",
+  "verification": {
+    "commands": [
+      {
+        "command": "node --check web/live-dev/app.js",
+        "result": "ok (exit 0)"
+      }
+    ],
+    "e2e": ["E2E-040"],
+    "notes": "CSS (styles.css) not node-checkable. Layout height 100dvh-minus-header; both columns overflow independently. JS: focusRightPanel on bubbles, revise, dispatch, progress, preview."
+  },
+  "tasksCompleted": ["T001", "T002", "T003", "T004"]
+}

package/.duaer/specs/039-desk-scroll-sync/spec.md

@@ -0,0 +1,65 @@
+# Feature Specification: Live desk left↔right scroll sync
+
+**Feature Branch**: `feat/desk-scroll-sync`
+
+**Created**: 2026-09-16
+
+**Status**: Active
+
+## Goal
+
+On the live desk, the right column grows long across the job lifecycle
+(confirm → dispatch → progress → preview → revise) while the left chat stays
+anchored at the top. Keep left↔right focus in sync so the content the user
+needs on the right scrolls into view when chat activity or mode changes
+advance the active stage.
+
+## Problem
+
+1. Right-column content stacks tall; the active section (confirm / progress /
+   preview / revise) can sit below the viewport while the user is still
+   talking on the left
+2. Left chat stays at the top by design; without coordinated scroll, users
+   miss the stage that chat just unlocked or updated
+3. Manual scrolling the whole page (or losing independent panel scroll) breaks
+   the two-column desk model
+
+## In scope
+
+- Independent vertical scroll on the right panel (not whole-page scroll as the
+  primary mechanism)
+- Auto-scroll the right panel so the **active section** enters view when chat
+  activity or mode/stage changes make that section the focus:
+  confirm, progress, preview, or revise
+- Optionally scroll the left chat log to the bottom when new bubbles arrive
+  (keep composer / chat chrome usable)
+- Preserve existing confirm-card field layout and copy — no redesign of
+  confirm fields
+
+## Out of scope
+
+- Redesigning confirm-card fields, labels, or structure
+- Redesigning progress / preview / revise card chrome beyond scroll/focus
+- Changing dispatch, agent launch, or revise enqueue semantics
+- Remote push / promote to `main`
+
+## Acceptance
+
+1. Right panel scrolls independently; tall stage stacks do not force the left
+   chat off-screen as the only way to see later stages
+2. When the active stage becomes confirm, progress, preview, or revise (via
+   chat activity or mode change), that section scrolls into view in the right
+   panel without requiring the user to hunt for it
+3. Left chat remains usable at the top of the desk layout; optional auto-scroll
+   of the left log to the latest bubble on new messages does not break typing
+4. Confirm-card fields are unchanged (same fields / structure; scroll-only UX)
+5. E2E catalog note for this behavior (E2E-040)
+
+## Assumptions
+
+- Preferred approach: independent right-panel overflow + `scrollIntoView` (or
+  equivalent) on the active section; left log bottom-scroll on new bubbles is
+  optional polish if not already reliable
+- Existing partial `scrollIntoView` for revise confirm may be extended, not
+  replaced wholesale
+- Implementation deferred; this Brief + tasks only for now

package/.duaer/specs/039-desk-scroll-sync/tasks.md

@@ -0,0 +1,6 @@
+# Tasks
+
+- [x] T001 Right panel independent scroll + viewport-height desk columns
+- [x] T002 Auto-focus active right stage on chat / mode / progress / preview
+- [x] T003 E2E-040 + Spec acceptance
+- [x] T004 Verify, accept, merge to develop, handoff

package/.duaer/specs/040-terminal-queue-wait/active-job.json

@@ -0,0 +1,12 @@
+{
+  "schemaVersion": 1,
+  "feature": "040-terminal-queue-wait",
+  "featureDirectory": ".duaer/specs/040-terminal-queue-wait",
+  "specDir": ".duaer/specs/040-terminal-queue-wait",
+  "branch": "feat/terminal-queue-wait",
+  "worktree": ".worktree/feat-terminal-queue-wait",
+  "startedAt": "2026-09-16T05:40:00.000Z",
+  "updatedAt": "2026-09-16T05:46:00.000Z",
+  "source": "duaer-do",
+  "status": "accepted"
+}

package/.duaer/specs/040-terminal-queue-wait/delivery.json

@@ -0,0 +1,26 @@
+{
+  "schemaVersion": 1,
+  "status": "accepted",
+  "feature": "040-terminal-queue-wait",
+  "acceptedAt": "2026-09-16T05:46:00.000Z",
+  "summary": "Honest Terminal queue wait while runner is busy: busy=running.cmd → queued/busy flags; UI i18n; E2E-041; never interrupt.",
+  "verification": {
+    "commands": [
+      {
+        "command": "node --check bin/duaer-live.mjs",
+        "result": "ok (exit 0)"
+      },
+      {
+        "command": "node --check web/live-dev/app.js",
+        "result": "ok (exit 0)"
+      },
+      {
+        "command": "node --check web/live-dev/i18n.js",
+        "result": "ok (exit 0)"
+      }
+    ],
+    "e2e": ["E2E-041"],
+    "notes": "T004: ESM syntax checks pass. Busy runner detected via running.cmd; API returns queued/busy without interrupt. Post-merge handoff: launchctl kickstart com.duaer.live8787."
+  },
+  "tasksCompleted": ["T001", "T002", "T003", "T004"]
+}

package/.duaer/specs/040-terminal-queue-wait/spec.md

@@ -0,0 +1,85 @@
+# Feature Specification: Terminal busy-queue honesty
+
+**Feature Branch**: `feat/terminal-queue-wait`
+
+**Created**: 2026-09-16
+
+**Status**: Active
+
+## Goal
+
+When the user revises or re-dispatches while the Terminal runner is already
+busy (`running.cmd` present and healthy), **wait for the current task to
+finish** — do not interrupt it. Still enqueue via `pending.cmd`. Return
+honest API flags (`queued` / `busy` / `reused` or equivalent) so the UI does
+**not** claim the agent has already started. Show clear zh-CN / en copy that
+the work is queued and will run after the current task ends.
+
+## Problem
+
+1. Busy-runner enqueue can look like an immediate start (e.g.「已送入原
+   Terminal」/「数字员工已启动」) even though the new prompt only sits in
+   `pending.cmd` until `running.cmd` finishes
+2. API reuse success (`reused: true` / `mode: "terminal-reuse"`) does not
+   distinguish idle reuse from busy queue-wait
+3. Users may think the revise already interrupted or replaced the in-flight
+   task
+
+## User decision (frozen)
+
+- **Wait** for the current Terminal task to finish; **do not** interrupt
+- Keep writing `pending.cmd` (queue)
+- Make enqueue honesty explicit in API **and** UI
+
+## In scope
+
+- Detect busy runner: `running.cmd` present **and** runner healthy
+  (heartbeat / PID liveness as already used for reuse)
+- On revise / re-dispatch into that runner: write `pending.cmd`; do not kill
+  or replace `running.cmd`
+- API response must expose queue honesty, e.g.:
+  - `queued: true`
+  - `busy: true`
+  - `reused: true` (same Terminal / runner)
+  - (or equivalent fields the UI can rely on without implying “started now”)
+- Live desk UI: when those flags indicate busy-queue, do **not** use “agent
+  already started” / immediate-reuse success copy
+- i18n zh-CN / en message along the lines of:
+  - zh-CN:「已排入原 Terminal，当前任务结束后自动跑」
+  - en: equivalent (“Queued in the existing Terminal; runs after the current
+    task finishes”)
+- Preserve post-accept revise policy from prior jobs: **no false `--continue`**
+  after accepted delivery; this job is about **busy-queue honesty**, not
+  reopening the continue-session debate
+- E2E catalog note **E2E-041**
+
+## Out of scope
+
+- Interrupting, preempting, or cancelling the in-flight `running.cmd` task
+- Changing first-dispatch / cold-open Terminal flows except shared response
+  fields needed for honesty
+- Redesigning revise card chrome (038) or desk scroll (039)
+- Remote push / promote to `main`
+
+## Acceptance
+
+1. When runner is healthy and `running.cmd` is present, revise / re-dispatch
+   writes `pending.cmd` and does **not** interrupt the current task
+2. API returns honesty flags such that `queued` + `busy` (and `reused` when
+   same Terminal) are true in that case — UI can tell “queued, waiting” from
+   “started now”
+3. UI does **not** claim the agent already started solely because reuse
+   succeeded; shows the queued/wait message (zh-CN + en)
+4. Idle healthy runner reuse (no busy `running.cmd`) remains truthful; still
+   may reuse the same Terminal without the busy-wait message
+5. After accepted delivery, revise still avoids false `--continue` (unchanged
+   policy; not regressed by this job)
+6. E2E-041 documents busy-queue wait + honest UI/API
+
+## Assumptions
+
+- Runner already serializes: finish current → pick next `pending.cmd`; this
+  job makes that behavior **visible and honest**, not a new interrupt model
+- Shared launch path in `bin/duaer-live.mjs` + `web/live-dev` i18n/UI are the
+  primary touch points
+- Implementation deferred; Brief + tasks only for now

package/.duaer/specs/040-terminal-queue-wait/tasks.md

@@ -0,0 +1,6 @@
+# Tasks
+
+- [x] T001 API: detect busy runner (`running.cmd`), return `queued`/`busy`/`reused`; never interrupt
+- [x] T002 UI + i18n honest「已排入原 Terminal，当前任务结束后自动跑」
+- [x] T003 E2E-041
+- [x] T004 Verify, accept, merge, handoff