dsh-global-todo 0.7.0 → 0.7.2

package/CHANGELOG.md

@@ -1,3 +1,30 @@
+## [0.7.2] — 2026-10-20
+
+The roadmap audited against the tree, and the review feature brought up to the same standard
+as the rest of the panel.
+
+- **`docs/ROADMAP.md` no longer lies.** Six entries claimed things that already exist (due
+  reminders, batch completion/tagging, archive, cross-machine notices, external ingest) — they
+  moved to *Landed* with the function that proves each one, and *Next* is now ordered by value
+  against effort with a "today" line per item.
+- **`/review` has route tests**: a rejected claim reopens and drops its completion record,
+  answering twice is a 400 rather than a silent success, an unknown id is a 404.
+- **The review state is photographed** — a fifth scenario (`panel-review.png`) in the same
+  harness as the others, asserted by `check:render` and indexed in both READMEs.
+- **Bulk confirm in the review view**: selecting several finished-by-agent rows and confirming
+  them in one go, since assigning is not what that view is for.
+
+## [0.7.1] — 2026-10-20
+
+Documentation for the one piece of layout that cannot be "cleaned up".
+
+- **`docs/DESIGN.md` now records why the wide-screen detail card is `position: fixed`**, with the
+  measurements from the failed attempts (an absolute card came out 348×3051 at 1440; container
+  queries make the panel the containing block for fixed descendants), the real cause (the panel
+  scrolls with the host page, not `.gt-groups`), and the rules for changing it safely.
+- `/api/global-todo/review` added to both README route tables (it shipped in 0.7.0 without its
+  row).
+
 ## [0.7.0] — 2026-10-20
 
 An agent's "done" becomes a claim a person confirms, instead of a fact.

package/README.md

@@ -43,6 +43,7 @@ preview and photographed by the same tool:
 | Empty list | [`panel-empty.png`](docs/screenshots/panel-empty.png) |
 | Filter with no match | [`panel-filtered.png`](docs/screenshots/panel-filtered.png) |
 | Inbox (awaiting confirmation) | [`panel-inbox.png`](docs/screenshots/panel-inbox.png) |
+| Awaiting review (agent finished) | [`panel-review.png`](docs/screenshots/panel-review.png) |
 | Due reminder | [`panel-reminders.png`](docs/screenshots/panel-reminders.png) |
 | Selection mode | [`panel-select.png`](docs/screenshots/panel-select.png) |
 
@@ -268,6 +269,7 @@ fence when that service is present, and by a strict loopback check otherwise.
 | POST | `/api/global-todo/status` | `{ id, status, by?: human\|agent }` |
 | POST | `/api/global-todo/remove` | `{ id }` |
 | POST | `/api/global-todo/restore` | `{ todo }` — put a removed record back verbatim (undo) |
+| POST | `/api/global-todo/review` | `{ id, decision: confirm\|reject }` — answer an agent's completion |
 | POST | `/api/global-todo/link` | `{ id, add?: [...], remove?: [value \| index] }` |
 | POST | `/api/global-todo/dispatch` | `{ id, mode?: auto\|bound\|new\|current, sessionId?, dir? }` |
 | POST | `/api/global-todo/assign` | `{ ids, items?, target?, dir? }` — hand several todos over in one call; an id that matches nothing comes back instead of being sent elsewhere |

package/README.zh.md

@@ -39,6 +39,7 @@ DSH 自带的 `todo_write` 属于**某一个 agent 会话**：整表替换、三
 | 清单为空 | [`panel-empty.png`](docs/screenshots/panel-empty.png) |
 | 筛选无结果 | [`panel-filtered.png`](docs/screenshots/panel-filtered.png) |
 | 收件箱（待确认） | [`panel-inbox.png`](docs/screenshots/panel-inbox.png) |
+| 待确认（Agent 完成） | [`panel-review.png`](docs/screenshots/panel-review.png) |
 | 到点提醒 | [`panel-reminders.png`](docs/screenshots/panel-reminders.png) |
 | 批量选择 | [`panel-select.png`](docs/screenshots/panel-select.png) |
 
@@ -164,6 +165,7 @@ dsh plugin --profile web remove dsh-global-todo
 | POST | `/api/global-todo/status` | `{ id, status, by?: human\|agent }` |
 | POST | `/api/global-todo/remove` | `{ id }` |
 | POST | `/api/global-todo/restore` | `{ todo }` —— 原样还原被删除的记录（撤销） |
+| POST | `/api/global-todo/review` | `{ id, decision: confirm\|reject }` —— 回答 Agent 的完成声明 |
 | POST | `/api/global-todo/link` | `{ id, add?: [...], remove?: [值 或 下标] }` |
 | POST | `/api/global-todo/dispatch` | `{ id, mode?: auto\|bound\|new\|current, sessionId?, dir? }` |
 | POST | `/api/global-todo/assign` | `{ ids, items?, target?, dir? }`——一次把多条交给 Agent；配不上的 id 原样报回，不擅自送到别处 |

package/docs/DESIGN.md

@@ -60,15 +60,51 @@ $DSH_HOME/global-todo/todos.json     ← { version: 1, todos: [ … ] }
 ## On a wide window, the detail stands beside the list
 
 Expanding a row inline is right on a narrow window and wrong on a wide one: the list jumps, the
-row you were reading slides away, and the rest of the screen sits empty. Above 1100px the open
-row's detail is lifted out of the flow into a card bracketed between the toolbar and the footer
-at the panel's right edge; only the list gives way (the toolbar keeps full width), and the list gets
-padding equal to that card. The card's offsets are measured from the panel's own column on mount
-and on resize — the slot does not always fill the window, so a viewport-derived offset put the card
-over the list inside the real GUI. This is a CSS-only override over unchanged markup
-(`.gt-root[data-wide-detail]` plus one media query) precisely so there is still exactly one
-detail implementation — a second render path for wide screens would drift from the inline one at
-the first field change.
+row you were reading slides away, and the rest of the screen sits empty. When the panel itself is
+at least 960px wide, the open row's detail is lifted out of the flow into a card at the panel's
+right edge; only the list gives way (the header and toolbar keep full width), and the list gets
+360px of right padding equal to the card. The breakpoint follows the **panel's** measured width,
+not the viewport: the slot is ~265px narrower than the window, so a viewport query opened the
+two-column layout while the panel still had no room for it. This is a CSS-only override over
+unchanged markup (`.gt-root[data-wide]` / `[data-wide-detail]`) precisely so there is still
+exactly one detail implementation — a second render path for wide screens would drift from the
+inline one at the first field change.
+
+### Why the card is `position: fixed` and not `sticky`
+
+Three ways to do this were tried; only one survives the host's layout.
+
+1. **`position: sticky`** — the card is a child of the row, so sticky is bounded by the row's
+   box: it never leaves the 72–94px tall item. Moving the card out of the row would mean a second
+   detail render path.
+2. **`position: absolute` inside a positioned wrapper around the list** — measured on
+   2026-10-20: at 1440 the card came out **348 × 3051px**, at 1280 **348 × 3203px**. The card
+   stretched to the full height of the list's *content* and scrolled away with the page. Reason:
+   **the scrolling ancestor of this panel is the host page, not `.gt-groups`** — the panel is a
+   column in someone else's scroller, so `.gt-groups` never scrolls and an absolutely positioned
+   box is bracketed by the whole content column instead of the visible area.
+3. **`container-type: inline-size` + container queries** — wanted, because the breakpoint would
+   then be CSS. But inline-size containment applies `contain: layout`, which makes the panel the
+   containing block for `position: fixed` descendants. The card (and the settings popover) would
+   silently switch from viewport-anchored to panel-anchored and land in the wrong place.
+
+So: **`position: fixed` plus one measurement of the panel and list boxes**, taken when a row
+opens and again on resize (and on a `ResizeObserver` of the column, because collapsing the host
+sidebar changes the panel's width without a window resize). The measured values land in
+`--gt-detail-top/right/bottom`; the CSS fallbacks assume the centred 1040px column, which is what
+the static previews render.
+
+### Changing this safely
+
+- Keep **one** detail implementation: if a change needs different markup for wide screens, it is
+  the wrong change.
+- Keep the breakpoint on the **panel** width (960px). A viewport media query was already shipped
+  once and put a 360px card over a 416px list at 1100.
+- Never let the card cover the list: it is `.gt-groups` padding that reserves the room, and the
+  two numbers (360 padding / 348 card + 12 gap) have to move together.
+- Verify in the real GUI, not the preview, at **1440 / 1280 / 1100**: the card must be ≈348px wide,
+  the list must end before it, and the open row must stay visible next to it. The preview cannot
+  catch this class of bug — it is server-rendered, so no measurement effect ever runs there.
 ## A shared file changes without asking
 
 The list is deliberately portable — a notes repo, a synced folder, a NAS — so another machine

package/docs/ROADMAP.md

@@ -110,95 +110,131 @@ in `skipped[]`, and archived/cancelled rows deliberately do not block a new one.
 counts a disagreement once (`externalChanges`, `lastExternalAt` in `lib/store.js`; surfaced by
 `/health.store`). The panel shows a one-line notice instead of letting a synced folder change the
 list silently.
-**Side detail on wide windows** — above 1100px the open row's detail becomes a card at the
-panel's right edge instead of pushing the list down (CSS-only over the same markup; one detail
-implementation), while narrow windows keep the inline expansion.
+**Side detail on wide windows** — when the panel itself is at least 960px wide, the open row's
+detail becomes a card at the panel's right edge instead of pushing the list down (CSS-only over
+the same markup; one detail implementation), while narrow windows keep the inline expansion. The
+breakpoint follows the panel's measured width, and the card is `position: fixed` with a measured
+anchor — `DESIGN.md` records the two alternatives that were measured and rejected, so this is not
+re-litigated every time someone tries to "clean it up".
 **External ingest with an inbox** — `POST /ingest` takes source-tagged, confidence-scored items
 behind a Bearer token; low-confidence records wait in an `inbox` tag view with 确认 / 丢弃 and a
 seven-day sweep, so an external source cannot silently fill the list.
+**An agent's "done" is a claim** — finishing as an agent sets `review = { pending }`; a person
+confirms or sends it back through `POST /review` (`reviewTodo()` in `lib/model.js`, `review()` in
+`lib/service.js`). Confirming keeps the record finished; rejecting reopens it and drops the
+completion record, because "not actually done" is the only honest reading. The panel shows a
+待确认 chip, a 待确认 filter and 确认完成 / 退回清单; bulk confirm exists in that view.
+`counts.review` drives the chip. Tests: `test/model.test.mjs`, `test/routes.test.mjs`.
+**A design system with guards** — five type sizes (20/14/13/12/11), four control heights, one
+settings inspector, and no JavaScript layout measurement left in the panel. Three guards keep it
+that way: `test/locale.test.mjs` (duplicate keys, zh/en parity, full-width punctuation in English,
+missing `t()` keys), the scenario table in `tools/preview.mjs` (empty, filtered, inbox, review,
+reminder) photographed into `docs/screenshots/` by `npm run screenshots`, and
+`npm run check:render` asserting each state's marker.
 ### Partly landed
 
-- **Batch and multi-select** — the selection mode, its per-row markers and the batch
-  一键分配 are in (`lib/client.js`, `POST /assign` at
-  `lib/routes.js`, `assignMany()` at `lib/dispatch.js`; tests
-  `test/dispatch.test.mjs`). Batch 完成 / 打标签 across a selection do not exist.
-- **Session read-back** — `sessionAlive` is on every listed todo
-  (`lib/routes.js`, `lib/dispatch.js`). Reading what that session last said,
-  and linking to it, is not: `lib/completion.js` reads `assistant/message` only to
-  close a todo this plugin dispatched, and stores one summary in its completion record.
-- **What the agents produced** — the per-todo record with a summary and the changed
-  files landed (`completeTodo()` at `lib/model.js`, 「完成记录」 at
-  `lib/client.js`, the 已完成 filter and group at `lib/client.js`). The
-  cross-todo "what did the sessions finish this week, and what did they touch" view did
-  not.
+- **Session read-back** — `sessionAlive` is on every listed todo (`sessionAlive` in
+  `lib/dispatch.js`, surfaced by `GET /list`). Reading what that session last said, and
+  linking to it, is not: `lib/completion.js` reads `assistant/message` only to close a todo
+  this plugin dispatched, and stores one summary in its completion record.
+- **What the agents produced** — the per-todo record with a summary and the changed files landed
+  (`completeTodo()` in `lib/model.js`, 「完成记录」 in `lib/client.js`, the 已完成 filter and
+  group). The cross-todo "what did the sessions finish this week, and what did they touch" view
+  did not.
+- **Attachment health** — a dead file link is flagged on read, but there is no 「重新挂载」 next
+  to it (`relink` does not exist anywhere in `lib/`), and `annotateLinks()` has no unit test:
+  today the render assertion in `tools/preview.mjs` is the only coverage.
+- **Batch** — selection, 一键分配, 完成 / 归档 / 打标签 and 批量确认（待确认视图）are all in.
+  Nothing here is missing; it is listed because the panel is where the batch surface lives.
 
 ## Next
 
-### 1. Checklist inside a todo
+Ordered by value against effort, and audited against the tree on 2026-10-20 — "today"
+means what the code actually does, not what the last plan hoped.
 
-Large items ("ship the plugin") are really a list of steps. Proposed: an optional
-`steps[]` on a todo, rendered as checkboxes, and shipped to the agent as a numbered
-plan in the dispatch prompt.
+### 1. Checklist inside a todo — the highest-value gap
 
-- Effort: medium (model + tools + panel + prompt builder).
-- Today: nothing named `steps` exists anywhere in `lib/`, so this is untouched.
-- Why it matters: it removes the need for a separate "plan" plugin, and the dispatch
-  prompt gets materially better.
+Large items ("ship the plugin") are a list of steps wearing a title. Proposed: an optional
+`steps[]` (text + done) per todo, rendered as checkboxes in the row and the detail, and
+shipped to the agent as a numbered plan in the dispatch prompt.
 
-### 2. Session read-back
+- Today: nothing named `steps` exists in `lib/`; `grep -rn steps lib` is empty.
+- Effort: medium — model (create / `applyPatch` / `normalizeStored`), a tool field, the
+  panel, and the prompt builder that already assembles the dispatch text.
+- Why first: it improves the *quality of every hand-off*, not just one screen. A dispatch
+  that arrives as "step 2 of 5" is worth more than one that arrives as a paragraph.
 
-The panel shows whether the bound session is alive (`sessionAlive`). Next: show what
-that session last said — one line of its latest assistant message, and a link to open it
-— so a dispatched todo reports back where the work is.
+### 2. Session read-back — makes hand-off stop being fire-and-forget
 
-- Effort: medium. Needs a host-side read of the bound session (the `sessions` service
-  exists, but this must stay cheap and failure-tolerant).
-- Why it matters: hand-off stops being fire-and-forget.
+`sessionAlive` says a bound conversation still exists. Next: one line of its latest
+assistant message plus a link to open it.
 
-### 3. Due reminders
+- Today: `lib/completion.js` reads `assistant/message` only to close a todo this plugin
+  dispatched; nothing exposes it to the panel.
+- Effort: medium, and it must stay cheap and failure-tolerant: a missing or huge message is
+  a normal case, not an error.
+- Why second: the panel currently cannot answer "did the thing I handed over get anywhere",
+  which is the question people actually ask.
 
-A reminder when a due time passes, in the GUI and optionally to the IM channel this
-deployment already has.
+### 3. Markdown / TaskPaper import and export
 
-- Effort: medium. The plugin has no scheduler today (nothing in `lib/` matches
-  `remind`); the Host's timer service plus a config flag is the smallest version.
-- Careful: **remind only, never auto-dispatch.** The list belongs to the human; starting
-  work stays an explicit act. (Auto-dispatch was rejected in `DESIGN.md` for this
-  reason.)
+JSON round-trips byte for byte; the text formats are what let the list live in a repo and
+diff.
 
-### 4. Batch completion and tagging
+- Today: only `GET /export` / `POST /import` over JSON.
+- Effort: medium — a serializer plus a tolerant parser, both with round-trip tests.
+- Why third: cheap portability, and it is the only way to compare this list with another
+  tool's.
 
-Shift-click to select, then 完成 / 打标签 across the selection — the half of
-multi-select that did not land with batch assignment.
+### 4. The weekly agent report
 
-- Effort: small (one bulk route beside `/assign`, one button beside 一键分配).
+Per-todo completion records already carry a summary and the changed files. A cross-todo
+view — "what did the sessions finish this week, and what did they touch" — turns that into
+something reviewable.
 
-### 5. Import and export beyond JSON
+- Today: the data exists (`completion.artifacts`), the aggregate does not.
+- Effort: small-medium; the honest version is a date-bounded list filtered on
+  `completion.by === 'agent'`, with `review` state beside each row.
 
-Markdown / TaskPaper in and out, so the list can be migrated from (and to) any other
-tool and diffed in a repo.
+### 5. Image attachments
 
-- Effort: medium. JSON is done; the text formats are the remaining work.
+`kind: 'image'` beside `url` / `file`, so a screenshot can be attached instead of a path
+to one.
 
-### 6. What the agents produced
+- Today: `LINK_KINDS = ['url', 'file']` (`lib/links.js`); the link shape is already prepared.
+- Effort: medium — the store must not inline bytes, so this is a path with a preview and a
+  clear "the file is gone" state, which #3-adjacent work already models.
 
-Completions already record a summary and the changed files per todo. A cross-todo view —
-"what did the sessions finish this week, and what did they touch" — would turn that into
-something you can review, and would be the honest way to show that a hand-off did work.
+### 6. Source adapters for the ingest door
+
+`POST /ingest` exists and is fenced by a token; nothing pushes to it.
+
+- Today: the door, the inbox, the confidence threshold and the seven-day sweep are done.
+  There is no mail/notification reader anywhere in the repo.
+- Effort: large, and the mode of the work is different: every adapter is an external
+  dependency with its own failure modes. Do it when a real source exists, not before.
+
+### 7. Small, well-understood items
+
+- `before:` / `after:` date bounds in the search syntax (the parser already walks tokens).
+- 「重新挂载」 next to a dead attachment, plus the `annotateLinks()` unit test it owes.
+- A screen-reader pass over the panel and the group headers; the keyboard path is close.
+
+### Landed after this list was written
+
+Due reminders (0.5.2), batch completion and tagging (`/bulk`), archive instead of
+delete, cross-machine change notices, external ingest with an inbox — all four used to be
+items here. See `Landed since 0.1` above; the entries were removed rather than left to
+mislead.
 
 ## Later
 
 | Idea | Note |
 |---|---|
-| Image attachments | `kind: 'image'` next to `url` / `file`. The shape is already prepared for it, but `LINK_KINDS` is still `['url', 'file']` (`lib/links.js`). |
 | Official `storageDomain` backend | A second store backend behind the same interface; the file stays the default because it is the feature. Today there is one backend and it says so (`kind: 'json'`, `lib/store.js`). |
 | Virtualised list | Only needed past a few hundred rows; measure first. Nothing in `lib/client.js` virtualises today. |
 | Drag to reorder | Manual order is meaningful to some people; it also needs a stable `position` field and a decision about how it interacts with due-date grouping. |
 | Multi-list / projects | A `list` field with one default list; deferred because "global single list" is the current identity. |
-| Archive instead of delete | Keeps history without cluttering. `POST /remove` deletes for real (`lib/routes.js`); only the panel's short undo brings a record back. |
-| Cross-machine conflict notice | The file is portable (NAS, sync folder). Detect "changed underneath me" and offer a reload instead of a silent overwrite — `store.read` still trusts the file whenever it parses. |
-| Capture from outside the chat | Notifications, mail, announcements — the sources `dsh-todo-list` reads. Needs an ingest path and a policy for deduplication; `POST /capture` only asks a conversation to collect (`lib/routes.js`). |
-| Accessible-only sweep | Full keyboard path is close; a screen-reader pass over the panel and the group headers is still owed. |
 
 ## Explicitly not planned
 

package/lib/client.js

@@ -50,7 +50,7 @@ window.__ModuleLoader__.load({
      * different mechanisms (restart vs. hot reload), so "which one am I looking
      * at" needs an answer that the bundle itself carries.
      */
-    const UI_REV = 'ui45'
+    const UI_REV = 'ui46'
     /** Last language resolved for the shell; module-level so a fetch failure can be worded too. */
     let activeLang = 'zh'
 
@@ -3320,6 +3320,39 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
         }
       }
 
+      // Reviewing is a per-record decision, so it cannot ride on /bulk: answering is not a
+      // status change, and a rejected claim has to clean up its completion record.
+      const runBulkReview = async () => {
+        const ids = Object.keys(selected)
+        if (ids.length === 0) return
+        try {
+          const results = await Promise.all(
+            ids.map((id) =>
+              call('review', { method: 'POST', body: { id, decision: 'confirm' } }).then(
+                () => true,
+                () => false,
+              ),
+            ),
+          )
+          const done = results.filter(Boolean).length
+          setNotice({
+            text:
+              done === ids.length
+                ? t('notice.bulk', { n: done })
+                : t('notice.bulkPartial', { n: done, m: ids.length - done }),
+            sessionId: '',
+          })
+          setTimeout(() => setNotice(null), 6000)
+          setSelected({})
+          setError(null)
+          void reload()
+          void refreshHealth()
+        } catch (failure) {
+          reportFailure('bulk-review', { message: failure?.message })
+          setError(failure)
+        }
+      }
+
       const counts = state.counts ?? { total: 0, open: 0, doing: 0, done: 0, cancelled: 0, archived: 0, overdue: 0, inbox: 0 }
       const remindersDue = Array.isArray(state.health?.reminders?.due) ? state.health.reminders.due : []
       const dueKey = remindersDue.map((item) => `${item.id}:${item.dueAt}`).join('|')
@@ -4062,11 +4095,25 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
                   t('select.clearAll'),
                 ),
                 h('span', { className: 'gt-spacer' }),
+                // In the review view the batch action is confirming, not assigning: every
+                // record on screen is finished and waiting for a word.
+                filter === 'review'
+                  ? h(
+                      'button',
+                      {
+                        type: 'button',
+                        className: 'gt-btn gt-btn-primary',
+                        disabled: Object.keys(selected).length === 0,
+                        onClick: () => void runBulkReview(),
+                      },
+                      t('review.confirm'),
+                    )
+                  : null,
                 h(
                   'button',
                   {
                     type: 'button',
-                    className: 'gt-btn gt-btn-primary',
+                    className: filter === 'review' ? 'gt-btn gt-btn-quiet' : 'gt-btn gt-btn-primary',
                     disabled: assignBusy || Object.keys(selected).length === 0,
                     onClick: () => void runAssign(Object.keys(selected)),
                   },

package/lib/index.js

@@ -36,7 +36,7 @@ import { createStore, resolveStorePath } from './store.js'
 import { createTools } from './tools.js'
 
 /** Must equal `package.json`'s version; `npm run check` enforces that. */
-export const VERSION = '0.7.0'
+export const VERSION = '0.7.2'
 
 /** Plugin id. Also the Loader row id in `cordis.patch.yml`. */
 export const name = 'dsh-global-todo'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-global-todo",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "icon": "./docs/icon.svg",
   "description": "Global, cross-session todos for DeepSeek Harness: one list owned by the human and the agent together, with creation time, attached documents and links, and one-click hand-off to an agent session. 全局待办：跨会话一份清单，记录加入时间，可挂文档与地址，可一键交给 Agent 继续干。",
   "type": "module",