dsh-global-todo 0.6.7 → 0.7.0

package/CHANGELOG.md

@@ -1,3 +1,35 @@
+## [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
+one.
+
+- **Four new preview scenarios**: empty list, filter with no match, inbox, and a due reminder.
+  `tools/preview.mjs` grew a `SCENARIOS` table the fake fetch reads, so a state that used to be
+  reachable only by clicking can be rendered and photographed like any other.
+- **`npm run screenshots` writes eight images** (list, detail, selection, settings + the four
+  above). Both READMEs index them in a state table instead of embedding all eight.
+- **`npm run check:render` asserts each state's marker** (`记第一条`, `清除筛选`, the inbox
+  explanation, the reminder title), so a regression shows up as a failing check rather than a
+  silently blank picture.
+
 ## [0.6.7] — 2026-10-20
 
 Copy safety, and the last orphan of the old footer.

package/README.md

@@ -35,6 +35,17 @@ one record:
 
 ![Settings: grouped fields, hints under each label, one save row](docs/screenshots/panel-settings.png)
 
+Every state that only appears under a condition has a fixed baseline image, rendered by the same
+preview and photographed by the same tool:
+
+| State | Image |
+|---|---|
+| 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) |
+| Due reminder | [`panel-reminders.png`](docs/screenshots/panel-reminders.png) |
+| Selection mode | [`panel-select.png`](docs/screenshots/panel-select.png) |
+
 These are produced by `npm run screenshots` (which chains `npm run preview`): the real client
 half is rendered to static HTML with no Host and no dependencies, then photographed at 1280×720
 into `docs/screenshots/`. Playwright is not a dependency — the tool borrows the copy a DSH

package/README.zh.md

@@ -32,6 +32,16 @@ DSH 自带的 `todo_write` 属于**某一个 agent 会话**：整表替换、三
 
 ![设置：分组字段、说明写在标签下方、底部一行保存](docs/screenshots/panel-settings.png)
 
+每个「只在特定情况下出现」的面板状态都有一张固定基线图，由同一套预览渲染、同一支工具拍摄，改样式时可以直接对比：
+
+| 状态 | 图片 |
+|---|---|
+| 清单为空 | [`panel-empty.png`](docs/screenshots/panel-empty.png) |
+| 筛选无结果 | [`panel-filtered.png`](docs/screenshots/panel-filtered.png) |
+| 收件箱（待确认） | [`panel-inbox.png`](docs/screenshots/panel-inbox.png) |
+| 到点提醒 | [`panel-reminders.png`](docs/screenshots/panel-reminders.png) |
+| 批量选择 | [`panel-select.png`](docs/screenshots/panel-select.png) |
+
 图都由 `npm run screenshots`（内部串起 `npm run preview`）生成：先把真实的客户端半区渲染成静态
 HTML（不依赖宿主、零依赖），再以 1280×720 拍进 `docs/screenshots/`。Playwright 不是依赖——工具
 借的是 DSH profile 里已经装好的那份，或 `DSH_PLAYWRIGHT` 指向的那份。

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 = 'ui43'
+    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) },
@@ -2253,7 +2276,8 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
       const [state, setState] = useState({ todos: [], counts: null, health: null, matched: 0, truncated: false })
       const [loading, setLoading] = useState(true)
       const [error, setError] = useState(null)
-      const [filter, setFilter] = useState('active')
+      // The static preview asks for a starting view it cannot click its way into.
+      const [filter, setFilter] = useState(typeof props.initialFilter === 'string' ? props.initialFilter : 'active')
       const [query, setQuery] = useState('')
       // Multi-select for batch assignment. A separate mode, because the round control on
       // each row already means "done".
@@ -2487,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', {
@@ -2501,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,
@@ -3143,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
@@ -3765,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.7'
+export const VERSION = '0.7.0'
 
 /** 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.7",
+  "version": "0.7.0",
   "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",