dsh-global-todo 0.6.8 → 0.7.1

package/CHANGELOG.md

@@ -1,3 +1,32 @@
+## [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.
+
+- **Completing as an agent now leaves a review mark.** `todo.review = { pending, at, by }` is set
+  by the model whenever the actor is `agent` (both `setStatus … done` and the completion path the
+  tools use); a person finishing something sets none, and anything that leaves `done` clears it.
+- **`POST /api/global-todo/review`** answers it: `confirm` keeps the todo finished and drops the
+  mark, `reject` puts it back on the list with the completion record removed — "not actually done"
+  is the only honest reading of a rejected claim. Answering twice is refused, not silently
+  accepted.
+- **The panel shows it**: a `待确认` chip on the row, a `待确认` filter that is the done list
+  narrowed to pending marks, and `确认完成` / `退回清单` in the row menu. `counts.review` drives the
+  chip and the filter.
+- **Agents see it too**: `presentTodo` carries `review`, so an agent can tell that its completion
+  is still waiting rather than assuming it landed.
+- Two new model tests cover the rule (agent vs person, confirm vs reject, no double answers).
+
 ## [0.6.8] — 2026-10-20
 
 Every conditional state now has a baseline image, and the harness refuses to render a blank

package/README.md

@@ -268,6 +268,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

@@ -164,6 +164,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/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 = 'ui44'
+    const UI_REV = 'ui45'
     /** Last language resolved for the shell; module-level so a fetch failure can be worded too. */
     let activeLang = 'zh'
 
@@ -107,6 +107,12 @@ window.__ModuleLoader__.load({
       'settings.saved': '设置已保存',
       'settings.about': '关于',
       'action.keys': '快捷键',
+      'review.confirm': '确认完成',
+      'review.reject': '退回清单',
+      'review.badge': '待确认',
+      'review.hint': 'Agent 标记完成，等你确认；确认后才算真的完成。',
+      'review.explain': '以下由 Agent 标记完成，确认后才算真的完成。',
+      'filter.review': '待确认',
       'keys.search': '聚焦搜索',
       'keys.new': '开始记一条',
       'keys.save': '保存这条（在标题里）',
@@ -373,6 +379,12 @@ window.__ModuleLoader__.load({
       'settings.saved': 'Settings saved',
       'settings.about': 'About',
       'action.keys': 'Keyboard shortcuts',
+      'review.confirm': 'Confirm done',
+      'review.reject': 'Send back',
+      'review.badge': 'Needs review',
+      'review.hint': 'The agent says this is done; confirm it or send it back.',
+      'review.explain': 'Finished by the agent. Confirm before it counts as done.',
+      'filter.review': 'Review',
       'keys.search': 'Focus the search box',
       'keys.new': 'Start a new todo',
       'keys.save': 'Save it (from the title field)',
@@ -1210,6 +1222,8 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
   overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
 .gt-truncated { color: var(--dsw-alias-state-warn-primary); font-size: 12px; }
 .gt-bulk-tag { flex: 0 1 120px; min-width: 90px; }
+.gt-review { padding: 1px 6px; border-radius: 999px; font-size: 11px; font-weight: 600;
+  color: var(--dsw-alias-state-warn-primary); border: 1px solid var(--dsw-alias-state-warn-primary); }
 .gt-inbox { margin-left: 6px; padding: 1px 6px; border-radius: 999px; font-size: 11px; font-weight: 600;
   color: var(--dsw-alias-state-warn-primary); border: 1px solid var(--dsw-alias-state-warn-primary);
   vertical-align: 1px; }
@@ -1674,6 +1688,9 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
       if (todo.completion !== null && todo.completion !== undefined) {
         meta.push(h('span', { key: 'completed', title: todo.completion.summary }, t('meta.completed', { when: absoluteTime(todo.completion.at) })))
       }
+      if (todo.review?.pending === true) {
+        meta.push(h('span', { key: 'review', className: 'gt-review', title: t('review.hint') }, t('review.badge')))
+      }
       meta.push(h('span', { key: 'by' }, t(`meta.by.${todo.createdBy === 'agent' ? 'agent' : 'human'}`)))
       if (todo.sessionId !== '') {
         const stranded = todo.sessionAlive === true && (todo.sessionDir ?? '') === ''
@@ -1884,6 +1901,12 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
             h(Menu, {
               label: t('action.menu'),
               items: [
+                ...(todo.review?.pending === true
+                  ? [
+                      { key: 'confirmReview', label: t('review.confirm'), icon: 'check', onSelect: () => onAction('review-confirm', todo) },
+                      { key: 'rejectReview', label: t('review.reject'), icon: 'refresh', danger: true, onSelect: () => onAction('review-reject', todo) },
+                    ]
+                  : []),
                 ...(todo.tags.some((tag) => tag.toLowerCase() === 'inbox')
                   ? [
                       { key: 'confirm', label: t('action.confirm'), icon: 'check', onSelect: () => onAction('confirm', todo) },
@@ -2488,8 +2511,9 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
       const reload = useCallback(
         async (next = {}) => {
           const selected = next.filter ?? filter
-          // The inbox is a tag view over active records, not a status of its own.
-          const status = selected === 'inbox' ? 'active' : selected
+          // Two views sit on top of a status instead of being one: the inbox is a tag over
+          // active records, and review is "done, but a person has not agreed yet".
+          const status = selected === 'inbox' ? 'active' : selected === 'review' ? 'done' : selected
           const search = next.query ?? query
           try {
             const data = await call('list', {
@@ -2502,7 +2526,12 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
             if (!mounted.current) return
             setState((current) => ({
               ...current,
-              todos: data.todos,
+              // The review view is the done list narrowed to records whose agent
+              // completion nobody has answered yet.
+              todos:
+                selected === 'review'
+                  ? data.todos.filter((todo) => todo.review?.pending === true)
+                  : data.todos,
               counts: data.counts,
               matched: Number.isInteger(data.matched) ? data.matched : data.todos.length,
               truncated: data.truncated === true,
@@ -3144,7 +3173,15 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
       }
 
       const onAction = (kind, todo, payload) => {
-        if (kind === 'done') return run(todo.id, () => call('status', { method: 'POST', body: { id: todo.id, status: 'done' } }))
+        if (kind === 'done') return run(todo.id, () => call('status', { method: 'POST', body: { id: todo.id, status: 'done', by: 'human' } }))
+        // Answering an agent's completion. Confirming keeps it done; rejecting sends it back
+        // to the list, because "not actually done" is the only honest reading.
+        if (kind === 'review-confirm') {
+          return run(todo.id, () => call('review', { method: 'POST', body: { id: todo.id, decision: 'confirm' } }))
+        }
+        if (kind === 'review-reject') {
+          return run(todo.id, () => call('review', { method: 'POST', body: { id: todo.id, decision: 'reject' } }))
+        }
         if (kind === 'reopen') return run(todo.id, () => call('status', { method: 'POST', body: { id: todo.id, status: 'open' } }))
         if (kind === 'doing') return run(todo.id, () => call('status', { method: 'POST', body: { id: todo.id, status: 'doing' } }))
         // Confirming keeps the record on the list; discarding archives it. Both only remove
@@ -3766,6 +3803,7 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
                 // day one is furniture, not a control.
                 ...(counts.archived > 0 ? [['archived', counts.archived]] : []),
                 ...(counts.inbox > 0 ? [['inbox', counts.inbox]] : []),
+                ...(counts.review > 0 ? [['review', counts.review]] : []),
               ].map(([key, count]) => filterChip(key, key === 'all' ? undefined : count)),
             ),
             h('span', { className: 'gt-divider' }),

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.6.8'
+export const VERSION = '0.7.1'
 
 /** Plugin id. Also the Loader row id in `cordis.patch.yml`. */
 export const name = 'dsh-global-todo'

package/lib/model.js

@@ -217,6 +217,9 @@ export function createTodo(input, options = {}) {
     // beside the status rather than inside it, because "done" alone says
     // nothing about what was done.
     completion: null,
+    // Set when an agent finishes something: the person who owns the list confirms it or
+    // sends it back. An agent's "done" is a claim, not a decision.
+    review: null,
     // An append-only trail of what happened while the todo was open. Unlike the
     // description (the user's own text) this is where an agent reports progress or
     // says it is blocked, so reporting never has to rewrite someone's words.
@@ -312,6 +315,7 @@ export function normalizeStored(raw, options = {}) {
     originSessionId: typeof raw.originSessionId === 'string' ? raw.originSessionId : '',
     lastDispatch: raw.lastDispatch !== null && typeof raw.lastDispatch === 'object' ? raw.lastDispatch : null,
     completion: normalizeCompletion(raw.completion),
+    review: normalizeReview(raw.review),
     notes: normalizeNotes(raw.notes),
     activity: Array.isArray(raw.activity)
       ? raw.activity
@@ -328,6 +332,64 @@ export function normalizeStored(raw, options = {}) {
   return todo
 }
 
+/**
+ * A stored review mark, repaired rather than rejected.
+ *
+ * Only one shape exists today — an agent finished this and the owner has not answered —
+ * so anything else is dropped instead of guessed at.
+ *
+ * @param {unknown} raw
+ * @returns {{ pending: true, at: number, by: string } | null}
+ */
+function normalizeReview(raw) {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return null
+  if (raw.pending !== true) return null
+  return {
+    pending: true,
+    at: Number.isFinite(raw.at) ? Number(raw.at) : Date.now(),
+    by: normalizeActor(raw.by),
+  }
+}
+
+/**
+ * Answer the question an agent left behind.
+ *
+ * Confirm keeps the todo finished and drops the mark; reject puts it back on the list,
+ * because "not actually done" is the only honest reading of a rejected claim.
+ *
+ * @param {object} todo
+ * @param {'confirm' | 'reject'} decision
+ * @param {{ now?: number, by?: 'human' | 'agent', reason?: string }} [options]
+ * @returns {boolean} whether the record changed
+ */
+export function reviewTodo(todo, decision, options = {}) {
+  const now = options.now ?? Date.now()
+  const by = normalizeActor(options.by ?? 'human')
+  const next = normalizeEnum(decision, ['confirm', 'reject'], 'invalid-decision', '决定', 'confirm')
+  if (todo.review === null || todo.review === undefined) return false
+  todo.review = null
+  todo.updatedAt = now
+  todo.updatedBy = by
+  const reason = typeof options.reason === 'string' ? options.reason.trim().slice(0, 120) : ''
+  if (next === 'reject') {
+    todo.status = 'open'
+    todo.doneAt = null
+    todo.completion = null
+    pushActivity(
+      todo,
+      { kind: 'reopened', by, at: now, summary: reason === '' ? '确认未完成，退回清单' : reason },
+      options.activityLimit ?? LIMITS.activity,
+    )
+    return true
+  }
+  pushActivity(
+    todo,
+    { kind: 'reviewed', by, at: now, summary: reason === '' ? '确认完成' : reason },
+    options.activityLimit ?? LIMITS.activity,
+  )
+  return true
+}
+
 /**
  * A stored completion record, repaired rather than rejected.
  *
@@ -428,6 +490,7 @@ export function completeTodo(todo, evidence = {}, options = {}) {
   todo.doneAt = now
   todo.updatedAt = now
   todo.updatedBy = by
+  todo.review = by === 'agent' ? { pending: true, at: now, by } : null
   todo.completion = {
     at: now,
     by,
@@ -546,6 +609,9 @@ export function setStatus(todo, status, options = {}) {
   // A completion record describes a finished job, so reopening clears it: a
   // record that still claims the work is done is worse than no record.
   if (next !== 'done') todo.completion = null
+  // Who finished it decides whether a person still has to agree: an agent's "done" is a
+  // claim, the owner's is a decision. Leaving done drops the mark with the record.
+  todo.review = next === 'done' && by === 'agent' ? { pending: true, at: now, by } : null
   todo.updatedAt = now
   todo.updatedBy = by
   const kind = next === 'done' ? 'done' : next === 'open' ? 'reopened' : 'status'
@@ -666,7 +732,19 @@ export function isOverdue(todo, now = Date.now()) {
  * @returns {{ total: number, open: number, doing: number, done: number, cancelled: number, archived: number, overdue: number }}
  */
 export function counts(todos, now = Date.now()) {
-  const out = { total: todos.length, open: 0, doing: 0, done: 0, cancelled: 0, archived: 0, overdue: 0, inbox: 0 }
+  const out = {
+    total: todos.length,
+    open: 0,
+    doing: 0,
+    done: 0,
+    cancelled: 0,
+    archived: 0,
+    overdue: 0,
+    inbox: 0,
+    // Finished by an agent and not yet confirmed by a person. Counted separately from
+    // done because "the agent says so" is not the same fact as "a person agreed".
+    review: 0,
+  }
   for (const todo of todos) {
     if (todo.status in out) out[todo.status] += 1
     if (isOverdue(todo, now)) out.overdue += 1
@@ -675,6 +753,7 @@ export function counts(todos, now = Date.now()) {
     if ((todo.status === 'open' || todo.status === 'doing') && (todo.tags ?? []).some((tag) => tag.toLowerCase() === 'inbox')) {
       out.inbox += 1
     }
+    if (todo.status === 'done' && todo.review?.pending === true) out.review += 1
   }
   return out
 }

package/lib/routes.js

@@ -578,6 +578,12 @@ export function createRoutes(deps) {
       return { todo: await service.setStatus(body.id, body.status ?? 'done', { by }) }
     }),
 
+    // Answering the mark an agent's completion leaves behind: confirm, or send it back.
+    exact('POST', `${ROUTE_BASE}/review`, async (request) => {
+      const body = await readJsonBody(request)
+      return { todo: await service.review(body.id, body.decision ?? 'confirm', { by: 'human', reason: body.reason }) }
+    }),
+
     exact('POST', `${ROUTE_BASE}/remove`, async (request) => {
       const body = await readJsonBody(request)
       return { todo: await service.remove(body.id, { by: 'human' }) }

package/lib/service.js

@@ -31,6 +31,7 @@ import {
   pushActivity,
   recordDispatch as recordDispatchOn,
   removeLink as removeLinkFrom,
+  reviewTodo,
   setStatus as setStatusOn,
 } from './model.js'
 
@@ -318,6 +319,33 @@ export function createService(options) {
     })
   }
 
+  /**
+   * Answer the review mark an agent's completion left behind.
+   *
+   * Kept separate from {@link setStatus} because it is a different decision: the record is
+   * already done, and the owner is either agreeing or sending it back — not changing a
+   * status that nobody asked about. A record without a pending mark is refused, so the
+   * panel cannot confirm something twice.
+   *
+   * @param {string} id
+   * @param {'confirm' | 'reject'} decision
+   * @param {{ by?: 'human' | 'agent', reason?: string }} [context]
+   * @returns {Promise<object>} the todo after the decision
+   */
+  async function review(id, decision, context = {}) {
+    return store.update((doc) => {
+      const todo = requireTodo(doc, id)
+      if (todo.review?.pending !== true) {
+        throw new TodoError('invalid-status', '这条待办没有等你确认的完成标记')
+      }
+      const changed = reviewTodo(todo, decision, {
+        ...modelOptions(context.by ?? 'human'),
+        reason: context.reason,
+      })
+      return changed ? { next: doc.todos, result: todo } : { result: todo }
+    })
+  }
+
   /**
    * Put a wrongly-finished todo back on the list.
    *
@@ -763,6 +791,7 @@ export function createService(options) {
     create,
     update,
     setStatus,
+    review,
     reopen,
     complete,
     note,

package/lib/tools.js

@@ -162,6 +162,9 @@ export function presentTodo(todo, now = Date.now()) {
     originDir: todo.originDir ?? '',
     originSessionId: todo.originSessionId ?? '',
     notes: (todo.notes ?? []).map((entry) => ({ at: entry.at, by: entry.by, text: entry.text })),
+    // Present so an agent can see it left a claim waiting: a record an agent finished is
+    // not settled until a person confirms it, and saying so beats assuming it landed.
+    review: todo.review?.pending === true ? { pending: true, at: todo.review.at, by: todo.review.by } : null,
     completion:
       todo.completion === null || todo.completion === undefined
         ? null

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-global-todo",
-  "version": "0.6.8",
+  "version": "0.7.1",
   "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",