dsh-global-todo 0.5.1 → 0.5.3

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+## [0.5.3] — 2026-10-20
+
+Settings a person can reach, and reminders that behave like reminders.
+
+- **A settings popover.** Reminders and the external ingest door were both API-only; the header
+  now opens a small panel for the reminder switch, the lead time, the ingest switch, the token
+  (generate a fresh one in place; leave blank to keep the current) and the inbox confidence
+  threshold. The token still never comes back from the host.
+- **Reminders gained a lead time and a switch.** remindersEnabled and reminderLeadMinutes live in
+  settings; the host sweep reads them each tick, announces at dueAt minus lead, and clears the due
+  list when reminders are off.
+- **Browser notifications are opt-in.** When the panel is open and a new deadline becomes due, it
+  fires a system notification if permission was granted; otherwise the due bar offers to ask for
+  permission. The notification is a bonus — the bar is the source of truth.
+
 # Changelog
 
 All notable changes to this project are documented in this file.
@@ -7,6 +22,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.2] — 2026-10-19
+
+Three things the leaders in this category do that we did not.
+
+- **Deadlines now say something.** A 30-second host sweep finds active records whose `dueAt` has
+  passed and that were not announced yet; the panel shows a due bar, clicking an item opens it,
+  and acknowledging clears it. The announced set lives in memory, so a restart re-announces an
+  unacknowledged deadline once — the offline catch-up a reminder should have. A postponed
+  deadline is a new reminder; an announced one stays quiet.
+- **Readable numbers: `#42`.** Records get a stable, human-facing sequence number assigned on
+  create and backfilled in creation order for legacy files; deleting #1 does not renumber #2. It
+  shows in the panel meta, in tool output and in the list line, so "把 #42 交给 Agent" means the
+  same thing to both sides.
+- **Import previews before writing.** The panel runs a dry run first and shows 新增/更新 counts
+  with a confirm button; a wrong file can no longer overwrite by mis-click. The preview is also
+  available as `dryRun` on the route.
 ## [0.5.1] — 2026-10-19
 
 The last two loose ends from the D4 audit.

package/README.md

@@ -244,7 +244,8 @@ fence when that service is present, and by a strict loopback check otherwise.
 | GET | `/api/global-todo/dirs` | `path?` — list subdirectories for the panel's built-in folder picker (the shell's own picker is preferred when mounted) |
 | GET | `/api/global-todo/get` | `id` |
 | GET | `/api/global-todo/export` | — (the store's own JSON document, for backup or migration) |
-| POST | `/api/global-todo/import` | `{ doc, mode?: replace\|merge }` — `replace` is an exact round trip, `merge` updates by id and appends (what the panel sends) |
+| POST | `/api/global-todo/import` | `{ doc, mode?: replace\|merge, dryRun? }` — `replace` is an exact round trip, `merge` updates by id and appends (what the panel sends); `dryRun` returns `wouldCreate` / `wouldUpdate` and writes nothing |
+| POST | `/api/global-todo/reminders/ack` | `{ ids }` — stop listing these passed deadlines as due |
 | POST | `/api/global-todo/capture` | `{ sessionId? }` — ask the current conversation to collect its follow-ups |
 | POST | `/api/global-todo/bulk` | `{ ids, status?, addTags?, removeTags? }` — one change across a selection; a stale id lands in `unmatched` instead of failing the batch |
 | POST | `/api/global-todo/ingest` | `{ items: [{ title, source: { kind }, confidence }], dryRun? }` with `Authorization: Bearer <settings.ingestToken>` — external items; below `ingestConfirmBelow` they wait in the inbox |

package/README.zh.md

@@ -140,7 +140,8 @@ dsh plugin --profile web remove dsh-global-todo
 | GET | `/api/global-todo/dirs` | `path?`——列子目录，供面板内置的目录浏览器使用（宿主自己的选择器在时会优先） |
 | GET | `/api/global-todo/get` | `id` |
 | GET | `/api/global-todo/export` | ——（存储用的那份 JSON 文档，用于备份或迁移） |
-| POST | `/api/global-todo/import` | `{ doc, mode?: replace\|merge }`——`replace` 是无损往返，`merge` 同 id 覆盖、新 id 追加（面板用的是这个） |
+| POST | `/api/global-todo/import` | `{ doc, mode?: replace\|merge, dryRun? }`——`replace` 是无损往返，`merge` 同 id 覆盖、新 id 追加（面板用的是这个）；`dryRun` 只返回 `wouldCreate` / `wouldUpdate`，不落盘 |
+| POST | `/api/global-todo/reminders/ack` | `{ ids }`——这些已到期的提醒不再列出来 |
 | POST | `/api/global-todo/note` | `{ id, text }`（追加进展记录） |
 | POST | `/api/global-todo/capture` | `{ sessionId? }`（请当前对话把要跟进的事抓进清单） |
 | POST | `/api/global-todo/bulk` | `{ ids, status?, addTags?, removeTags? }`——一次改一整批；失效的 id 进 `unmatched`，不会让整批失败 |

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 = 'ui32'
+    const UI_REV = 'ui35'
     /** Last language resolved for the shell; module-level so a fetch failure can be worded too. */
     let activeLang = 'zh'
 
@@ -90,6 +90,19 @@ window.__ModuleLoader__.load({
       'action.import': '导入',
       'action.exportHint': '把整份清单导出成 JSON 文件（就是存储用的那份文档）',
       'action.importHint': '从 JSON 文件导入：同 id 覆盖、新 id 追加，不删除现有待办',
+      'settings.title': '设置',
+      'settings.reminders': '到点提醒',
+      'settings.remindersEnable': '开启到点提醒',
+      'settings.lead': '提前（分钟）',
+      'settings.ingest': '外部接入（ingest）',
+      'settings.ingestEnable': '启用外部写入',
+      'settings.token': '访问 token',
+      'settings.tokenSet': '已设置，留空保持不变',
+      'settings.generate': '生成新 token',
+      'settings.confirmBelow': '低于此置信度进收件箱',
+      'settings.save': '保存',
+      'settings.cancel': '取消',
+      'settings.saved': '设置已保存',
       'notice.exported': '已导出 {n} 条待办',
       'notice.imported': '已导入 {n} 条（合并，现有共 {total} 条）',
       'import.badJson': '这个文件不是合法的 JSON',
@@ -136,6 +149,13 @@ window.__ModuleLoader__.load({
       'notice.autoCollectOn': '已开启自动获取：一次人为发言最多自动问一次',
       'notice.autoCollectOff': '已关闭自动获取',
       'notice.externalChange': '清单在别处被改过，已载入最新内容',
+      'reminder.title': '到点提醒（{n}）',
+      'reminder.dismiss': '知道了',
+      'reminder.enableNotifications': '开启系统通知',
+      'reminder.notifyTitle': '待办到点',
+      'import.preview': '将导入 {total} 条：新增 {create}、更新 {update}',
+      'import.confirm': '导入',
+      'meta.seqHint': '给人看的编号',
       'action.exempt': '豁免',
       'action.exemptOn': '已豁免',
       'action.exemptHint': '这个工作区里的对话永不自动获取（再点一下取消）',
@@ -306,6 +326,19 @@ window.__ModuleLoader__.load({
       'action.import': 'Import',
       'action.exportHint': 'Download the whole list as JSON (the document the store keeps)',
       'action.importHint': 'Import a JSON file: same ids are updated, new ids appended, nothing deleted',
+      'settings.title': 'Settings',
+      'settings.reminders': 'Due reminders',
+      'settings.remindersEnable': 'Announce deadlines',
+      'settings.lead': 'Lead time (min)',
+      'settings.ingest': 'External ingest',
+      'settings.ingestEnable': 'Accept external writes',
+      'settings.token': 'Access token',
+      'settings.tokenSet': 'Set — leave blank to keep',
+      'settings.generate': 'New token',
+      'settings.confirmBelow': 'Below this confidence → inbox',
+      'settings.save': 'Save',
+      'settings.cancel': 'Cancel',
+      'settings.saved': 'Settings saved',
       'notice.exported': 'Exported {n} todos',
       'notice.imported': 'Imported {n} (merged; {total} in the list now)',
       'import.badJson': 'That file is not valid JSON',
@@ -352,6 +385,13 @@ window.__ModuleLoader__.load({
       'notice.autoCollectOn': 'Auto-collect on: at most one question per message from you',
       'notice.autoCollectOff': 'Auto-collect off',
       'notice.externalChange': 'The list changed somewhere else; the latest content is loaded',
+      'reminder.title': 'Due now ({n})',
+      'reminder.dismiss': 'Dismiss',
+      'reminder.enableNotifications': 'Enable notifications',
+      'reminder.notifyTitle': 'Todo due',
+      'import.preview': 'Will import {total}: {create} new, {update} updated',
+      'import.confirm': 'Import',
+      'meta.seqHint': 'Human-facing number',
       'action.exempt': 'Exempt',
       'action.exemptOn': 'Exempted',
       'action.exemptHint': 'Never auto-collect in this workspace (click again to undo)',
@@ -995,6 +1035,22 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
 .gt-item-body { flex: 1; display: flex; flex-direction: column; gap: 5px; min-width: 0; }
 .gt-item-title { font-weight: 600; font-size: 13.5px; word-break: break-word; line-height: 1.45; }
 .gt-input-xs { width: 68px; padding: 3px 6px; font-size: 12px; }
+.gt-seq { font-variant-numeric: tabular-nums; color: var(--dsw-alias-label-secondary); }
+.gt-reminders { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; padding: 8px 10px;
+  border: 1px solid var(--dsw-alias-state-warn-primary); border-radius: 10px;
+  background: var(--dsw-alias-bg-layer-1); font-size: 12.5px; }
+.gt-reminders-title { color: var(--dsw-alias-state-warn-primary); font-weight: 600; }
+.gt-reminder-item { border: 1px solid var(--dsw-alias-border-l1); background: var(--dsw-alias-bg-layer-2);
+  color: var(--dsw-alias-label-primary); font: inherit; font-size: 12.5px; padding: 3px 8px;
+  border-radius: 999px; cursor: pointer; max-width: 260px; overflow: hidden; text-overflow: ellipsis;
+  white-space: nowrap; }
+.gt-settings { align-self: flex-end; width: 330px; display: flex; flex-direction: column; gap: 8px;
+  padding: 12px 14px; border: 1px solid var(--dsw-alias-border-l2); border-radius: 12px;
+  background: var(--dsw-alias-bg-layer-1); font-size: 12.5px; }
+.gt-settings-head { font-weight: 650; }
+.gt-check-line { display: flex; align-items: center; gap: 8px; justify-content: space-between;
+  color: var(--dsw-alias-label-primary); }
+.gt-settings-row { display: flex; gap: 8px; align-items: center; flex-wrap: wrap; }
 .gt-inbox { margin-left: 6px; padding: 1px 6px; border-radius: 999px; font-size: 10.5px; font-weight: 600;
   color: var(--dsw-alias-state-warn-primary); border: 1px solid var(--dsw-alias-state-warn-primary);
   vertical-align: 1px; }
@@ -1412,6 +1468,9 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
         draft.due !== toLocalInput(todo.dueAt)
 
       const meta = []
+      if (Number.isInteger(todo.seq) && todo.seq > 0) {
+        meta.push(h('span', { key: 'seq', className: 'gt-seq', title: t('meta.seqHint') }, `#${todo.seq}`))
+      }
       meta.push(
         h('span', { key: 'added', title: new Date(todo.createdAt).toLocaleString() }, `${t('meta.added')} ${absoluteTime(todo.createdAt)}（${ageText(lang, todo.createdAt, now)}）`),
       )
@@ -2017,6 +2076,23 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
       const [bulkTag, setBulkTag] = useState('')
       const [assignBusy, setAssignBusy] = useState(false)
       const [assignAsk, setAssignAsk] = useState(null)
+      // A picked file is previewed first: a merge is not undoable, and "did I pick the right
+      // export" is exactly the kind of question a dry run answers before anything changes.
+      const [importAsk, setImportAsk] = useState(null)
+      // One settings popover: reminders and the external door both need a place a person can
+      // reach without curl.
+      const [settingsOpen, setSettingsOpen] = useState(false)
+      const [tokenDraft, setTokenDraft] = useState('')
+      const [ingestDraft, setIngestDraft] = useState(false)
+      const [belowDraft, setBelowDraft] = useState('0.8')
+      const [remindersDraft, setRemindersDraft] = useState(true)
+      const [leadDraft, setLeadDraft] = useState('0')
+      const [notificationPerm, setNotificationPerm] = useState(
+        typeof window !== 'undefined' && typeof window.Notification === 'function'
+          ? window.Notification.permission
+          : 'unsupported',
+      )
+      const notifiedRef = useRef(new Set())
       const [groupMode, setGroupMode] = useState(() => readStoredGroupMode())
       // A notice may carry an action: after a hand-off the useful next step is
       // to go and look at the conversation the work is actually in.
@@ -2680,17 +2756,31 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
           } catch {
             throw new Error(t('import.badJson'))
           }
-          const data = await call('import', { method: 'POST', body: { doc: parsed, mode: 'merge' } })
+          const preview = await call('import', { method: 'POST', body: { doc: parsed, mode: 'merge', dryRun: true } })
+          setError(null)
+          setImportAsk({ doc: parsed, summary: preview })
+        } catch (failure) {
+          reportFailure('import', { message: failure?.message })
+          setError(failure)
+        } finally {
+          if (input !== undefined && input !== null) input.value = ''
+        }
+      }
+
+      /** The bar from the dry run: this is the step that actually writes. */
+      const confirmImport = async () => {
+        if (importAsk === null) return
+        try {
+          const data = await call('import', { method: 'POST', body: { doc: importAsk.doc, mode: 'merge' } })
           setError(null)
           setNotice({ text: t('notice.imported', { n: data?.imported ?? 0, total: data?.total ?? 0 }), sessionId: '' })
           setTimeout(() => setNotice(null), 6000)
+          setImportAsk(null)
           void reload()
           void refreshHealth()
         } catch (failure) {
           reportFailure('import', { message: failure?.message })
           setError(failure)
-        } finally {
-          if (input !== undefined && input !== null) input.value = ''
         }
       }
 
@@ -2824,6 +2914,58 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
         return undefined
       }
 
+      /** Fill the popover from the host's state, so saving cannot send stale values. */
+      const openSettings = () => {
+        const current = state.health?.settings ?? {}
+        setIngestDraft(current.ingest?.enabled === true)
+        setBelowDraft(String(current.ingest?.confirmBelow ?? 0.8))
+        setRemindersDraft(current.remindersEnabled !== false)
+        setLeadDraft(String(current.reminderLeadMinutes ?? 0))
+        setTokenDraft('')
+        setSettingsOpen(true)
+      }
+
+      const generateToken = () => {
+        const bytes = new window.Uint8Array(24)
+        window.crypto.getRandomValues(bytes)
+        setTokenDraft(Array.from(bytes).map((byte) => byte.toString(16).padStart(2, '0')).join(''))
+        setIngestDraft(true)
+      }
+
+      const saveSettings = async () => {
+        try {
+          await call('settings', {
+            method: 'POST',
+            body: {
+              remindersEnabled: remindersDraft,
+              reminderLeadMinutes: Number(leadDraft),
+              ingestEnabled: ingestDraft,
+              ingestConfirmBelow: Number(belowDraft),
+              ...(tokenDraft.trim() === '' ? {} : { ingestToken: tokenDraft.trim() }),
+            },
+          })
+          setSettingsOpen(false)
+          setTokenDraft('')
+          await refreshHealth()
+          setNotice({ text: t('settings.saved'), sessionId: '' })
+          setTimeout(() => setNotice(null), 5000)
+        } catch (failure) {
+          reportFailure('settings', { message: failure?.message })
+          setError(failure)
+        }
+      }
+
+      /** Acknowledge reminders so the host stops listing them. */
+      const ackReminders = async (ids) => {
+        try {
+          await call('reminders/ack', { method: 'POST', body: { ids } })
+          await refreshHealth()
+        } catch (failure) {
+          reportFailure('reminders', { message: failure?.message })
+          setError(failure)
+        }
+      }
+
       /** Apply one change to the whole selection; a stale id is reported, not fatal. */
       const runBulk = async (change) => {
         const ids = Object.keys(selected)
@@ -2850,6 +2992,31 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
       }
 
       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('|')
+      useEffect(() => {
+        if (typeof window === 'undefined' || typeof window.Notification !== 'function') return
+        for (const item of remindersDue) {
+          const key = `${item.id}:${item.dueAt}`
+          if (notifiedRef.current.has(key)) continue
+          notifiedRef.current.add(key)
+          if (window.Notification.permission !== 'granted') continue
+          try {
+            const note = new window.Notification(t('reminder.notifyTitle'), { body: item.title, tag: item.id })
+            note.onclick = () => {
+              try {
+                window.focus()
+              } catch {
+                /* focus is a nicety */
+              }
+              setExpandedId(item.id)
+            }
+          } catch {
+            /* a notification is a bonus, never a failure */
+          }
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+      }, [dueKey])
       const groups = useMemo(
         () => groupTodos(state.todos, Date.now(), groupMode, sessionTitles, t),
         [state.todos, groupMode, sessionTitles, lang],
@@ -2960,6 +3127,16 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
               },
               t('action.import'),
             ),
+            h(
+              'button',
+              {
+                type: 'button',
+                className: 'gt-btn gt-btn-quiet',
+                'aria-expanded': settingsOpen,
+                onClick: () => (settingsOpen ? setSettingsOpen(false) : openSettings()),
+              },
+              t('settings.title'),
+            ),
             h('input', {
               ref: importRef,
               type: 'file',
@@ -2969,6 +3146,71 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
               onChange: (event) => void importJson(event),
             }),
           ),
+          settingsOpen
+            ? h(
+                'div',
+                { className: 'gt-settings', role: 'dialog', 'aria-label': t('settings.title') },
+                h('div', { className: 'gt-settings-head' }, t('settings.title')),
+                h('div', { className: 'gt-section-title' }, t('settings.reminders')),
+                h(
+                  'label',
+                  { className: 'gt-check-line' },
+                  h('input', { type: 'checkbox', checked: remindersDraft, onChange: (event) => setRemindersDraft(event.target.checked) }),
+                  t('settings.remindersEnable'),
+                ),
+                h(
+                  'label',
+                  { className: 'gt-check-line' },
+                  t('settings.lead'),
+                  h('input', {
+                    type: 'number',
+                    min: 0,
+                    max: 1440,
+                    className: 'gt-input gt-input-xs',
+                    value: leadDraft,
+                    onChange: (event) => setLeadDraft(event.target.value),
+                  }),
+                ),
+                h('div', { className: 'gt-section-title' }, t('settings.ingest')),
+                h(
+                  'label',
+                  { className: 'gt-check-line' },
+                  h('input', { type: 'checkbox', checked: ingestDraft, onChange: (event) => setIngestDraft(event.target.checked) }),
+                  t('settings.ingestEnable'),
+                ),
+                h('input', {
+                  className: 'gt-input',
+                  type: 'password',
+                  value: tokenDraft,
+                  placeholder:
+                    state.health?.settings?.ingest?.tokenSet === true ? t('settings.tokenSet') : t('settings.token'),
+                  autoComplete: 'new-password',
+                  onChange: (event) => setTokenDraft(event.target.value),
+                }),
+                h(
+                  'div',
+                  { className: 'gt-settings-row' },
+                  h('button', { type: 'button', className: 'gt-btn gt-btn-quiet', onClick: generateToken }, t('settings.generate')),
+                  h('button', { type: 'button', className: 'gt-btn gt-btn-brand', onClick: () => void saveSettings() }, t('settings.save')),
+                  h('button', { type: 'button', className: 'gt-btn gt-btn-quiet', onClick: () => setSettingsOpen(false) }, t('settings.cancel')),
+                ),
+                h(
+                  'label',
+                  { className: 'gt-check-line' },
+                  t('settings.confirmBelow'),
+                  h('input', {
+                    type: 'number',
+                    min: 0,
+                    max: 1,
+                    step: 0.05,
+                    className: 'gt-input gt-input-xs',
+                    value: belowDraft,
+                    onChange: (event) => setBelowDraft(event.target.value),
+                  }),
+                ),
+              )
+            : null,
+
           error !== null
             ? h(
                 'div',
@@ -3387,6 +3629,50 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
               )
             : null,
 
+          // Deadlines that passed. The host announces each one once; acknowledging here is
+          // what stops it listing them on the next poll.
+          remindersDue.length === 0
+            ? null
+            : h(
+                'div',
+                { className: 'gt-reminders', role: 'status' },
+                h('span', { className: 'gt-reminders-title' }, t('reminder.title', { n: remindersDue.length })),
+                ...remindersDue.slice(0, 3).map((item) =>
+                  h(
+                    'button',
+                    {
+                      key: item.id,
+                      type: 'button',
+                      className: 'gt-reminder-item',
+                      title: item.title,
+                      onClick: () => {
+                        void ackReminders([item.id])
+                        setExpandedId(item.id)
+                      },
+                    },
+                    `${item.seq > 0 ? `#${item.seq} ` : ''}${item.title}`,
+                  ),
+                ),
+                notificationPerm === 'default'
+                  ? h(
+                      'button',
+                      {
+                        type: 'button',
+                        className: 'gt-btn gt-btn-quiet',
+                        onClick: () => {
+                          void window.Notification.requestPermission().then((permission) => setNotificationPerm(permission))
+                        },
+                      },
+                      t('reminder.enableNotifications'),
+                    )
+                  : null,
+                h(
+                  'button',
+                  { type: 'button', className: 'gt-btn gt-btn-quiet', onClick: () => void ackReminders(remindersDue.map((item) => item.id)) },
+                  t('reminder.dismiss'),
+                ),
+              ),
+
           // Nothing could be worked out for these: the user picks one target for them
           // rather than having them sent somewhere nobody chose.
           assignAsk === null
@@ -3412,6 +3698,32 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
                 ),
               ),
 
+          importAsk === null
+            ? null
+            : h(
+                'div',
+                { className: 'gt-selectbar' },
+                h(
+                  'span',
+                  null,
+                  t('import.preview', {
+                    total: importAsk.summary?.wouldImport ?? 0,
+                    create: importAsk.summary?.wouldCreate ?? 0,
+                    update: importAsk.summary?.wouldUpdate ?? 0,
+                  }),
+                ),
+                h(
+                  'button',
+                  { type: 'button', className: 'gt-btn gt-btn-brand', onClick: () => void confirmImport() },
+                  t('import.confirm'),
+                ),
+                h(
+                  'button',
+                  { type: 'button', className: 'gt-btn gt-btn-quiet', onClick: () => setImportAsk(null) },
+                  t('select.clear'),
+                ),
+              ),
+
           loading && state.todos.length === 0
             ? h('div', { className: 'gt-empty' }, t('loading'))
             : state.todos.length === 0

package/lib/index.js

@@ -28,6 +28,7 @@ import { createDispatcher } from './dispatch.js'
 import { createSettings, explainAutoCollect, idleSessions, retryDelayMs } from './settings.js'
 import { createDiagnostics } from './diagnostics.js'
 import { createMetrics } from './metrics.js'
+import { dueReminders } from './reminders.js'
 import { LIMITS } from './model.js'
 import { ROUTE_BASE, createRoutes } from './routes.js'
 import { createService } from './service.js'
@@ -35,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.5.1'
+export const VERSION = '0.5.3'
 
 /** Plugin id. Also the Loader row id in `cordis.patch.yml`. */
 export const name = 'dsh-global-todo'
@@ -410,6 +411,38 @@ export function apply(ctx, config) {
   const diagnostics = createDiagnostics({ file: path.join(path.dirname(file), 'client-errors.log'), logger })
   const settingsFile = path.join(path.dirname(file), 'settings.json')
   const settings = createSettings({ file: settingsFile, logger })
+  // Deadlines that have passed and were not announced yet. In memory on purpose: a restart
+  // re-announces an unacknowledged deadline once, which is the offline catch-up a reminder
+  // is supposed to have.
+  const reminderState = { due: [], reminded: {} }
+  ctx.effect(() => {
+    const tick = async () => {
+      try {
+        const current = settings.get()
+        if (current.remindersEnabled === false) {
+          reminderState.due = []
+          return
+        }
+        const { todos } = await service.list({ status: 'active' })
+        const due = dueReminders(todos, {
+          now: Date.now(),
+          reminded: reminderState.reminded,
+          leadMs: (current.reminderLeadMinutes ?? 0) * 60_000,
+        })
+        if (due.length === 0) return
+        for (const item of due) reminderState.reminded[item.id] = item.dueAt
+        const known = new Set(reminderState.due.map((item) => item.id))
+        reminderState.due = [...reminderState.due, ...due.filter((item) => !known.has(item.id))]
+      } catch (error) {
+        logger?.warn?.(`dsh-global-todo: reminder sweep failed: ${error?.message ?? error}`)
+      }
+    }
+    void tick()
+    if (typeof setInterval !== 'function') return () => {}
+    const timer = setInterval(() => void tick(), 30_000)
+    if (typeof timer.unref === 'function') timer.unref()
+    return () => clearInterval(timer)
+  }, 'dsh-global-todo: due reminders')
   const autoCollectState = {
     enabled: false,
     asking: false,
@@ -488,6 +521,7 @@ export function apply(ctx, config) {
         target: recentSession,
         settings,
         autoCollect: autoCollectState,
+        reminders: reminderState,
         version: VERSION,
       })
       const disposers = routes.map((definition) => webCtx.webServer.register(definition))

package/lib/model.js

@@ -278,6 +278,9 @@ export function normalizeStored(raw, options = {}) {
 
   const todo = {
     id,
+    // Human-facing number ("把 #42 交给 Agent"). Assigned by the store from creation
+    // order; 0 means "not assigned yet" and is filled in on the next read.
+    seq: Number.isInteger(raw.seq) && raw.seq > 0 ? raw.seq : 0,
     title,
     description: typeof raw.description === 'string' ? raw.description : '',
     status: STATUSES.includes(raw.status) ? raw.status : 'open',

package/lib/reminders.js

@@ -0,0 +1,39 @@
+/**
+ * Due reminders.
+ *
+ * The list already knows `dueAt`; what it never did was say anything when one passed. The rule
+ * is kept pure so the timer can be tested without waiting: a record is due when it is still
+ * active, its deadline is in the past, and this exact deadline has not been announced yet.
+ * Keying on `id → dueAt` means postponing a reminder makes it due again, while an announced one
+ * stays quiet across ticks and restarts (the map lives with the process).
+ *
+ * @module dsh-global-todo/reminders
+ */
+
+/**
+ * @param {object[]} todos
+ * @param {{ now?: number, reminded?: Record<string, string|null> }} [options]
+ * @returns {{ id: string, seq: number, title: string, dueAt: string }[]}
+ */
+export function dueReminders(todos, options = {}) {
+  const now = Number.isFinite(options.now) ? options.now : Date.now()
+  // A lead time turns "at the deadline" into "a little before it": the same rule, shifted.
+  const lead = Number.isFinite(options.leadMs) && options.leadMs > 0 ? options.leadMs : 0
+  const reminded = options.reminded !== null && typeof options.reminded === 'object' ? options.reminded : {}
+  const due = []
+  for (const todo of Array.isArray(todos) ? todos : []) {
+    if (todo === null || typeof todo !== 'object') continue
+    if (todo.status !== 'open' && todo.status !== 'doing') continue
+    if (todo.dueAt === null || todo.dueAt === undefined || typeof todo.dueAt !== 'string') continue
+    const at = Date.parse(todo.dueAt)
+    if (!Number.isFinite(at) || at - lead > now) continue
+    if (reminded[todo.id] === todo.dueAt) continue
+    due.push({
+      id: todo.id,
+      seq: Number.isInteger(todo.seq) ? todo.seq : 0,
+      title: typeof todo.title === 'string' ? todo.title : '',
+      dueAt: todo.dueAt,
+    })
+  }
+  return due
+}

package/lib/routes.js

@@ -354,7 +354,7 @@ export function createRoutes(deps) {
      */
     exact('POST', `${ROUTE_BASE}/import`, async (request) => {
       const body = await readJsonBody(request)
-      return service.importDocument(body.doc ?? body, { mode: body.mode })
+      return service.importDocument(body.doc ?? body, { mode: body.mode, dryRun: body.dryRun === true })
     }),
 
     exact('GET', `${ROUTE_BASE}/health`, async () => {
@@ -417,6 +417,8 @@ export function createRoutes(deps) {
           loadError: settingsInfo.error,
           // The token itself never leaves the settings file; the panel only needs to know
           // whether one is set before it can usefully show the ingest section.
+          remindersEnabled: deps.settings?.get?.().remindersEnabled !== false,
+          reminderLeadMinutes: deps.settings?.get?.().reminderLeadMinutes ?? 0,
           ingest: {
             enabled: deps.settings?.get?.().ingestEnabled === true,
             sources: deps.settings?.get?.().ingestSources ?? [],
@@ -443,6 +445,9 @@ export function createRoutes(deps) {
           lastRetry: deps.autoCollect?.lastRetry ?? null,
           lastDrop: deps.autoCollect?.lastDrop ?? null,
         },
+        // Deadlines that passed and have not been acknowledged. In memory: the host
+        // announces once, the panel acknowledges, a restart re-announces unacknowledged ones.
+        reminders: { due: deps.reminders?.due ?? [] },
         // 「交给 Agent」 resolves its target from the conversation the user last
         // wrote in, so whether that feed attached is worth reporting too.
         target: {
@@ -480,6 +485,18 @@ export function createRoutes(deps) {
       }
     }),
 
+    exact('POST', `${ROUTE_BASE}/reminders/ack`, async (request) => {
+      const body = await readJsonBody(request)
+      const ids = new Set(
+        Array.isArray(body.ids) ? body.ids.filter((id) => typeof id === 'string' && id !== '') : [],
+      )
+      const state = deps.reminders
+      if (state !== undefined && state !== null && Array.isArray(state.due)) {
+        state.due = state.due.filter((item) => !ids.has(item.id))
+      }
+      return { cleared: ids.size }
+    }),
+
     exact('POST', `${ROUTE_BASE}/ingest`, async (request) => {
       const settings = deps.settings?.get?.()
       if (settings?.ingestEnabled !== true) {

package/lib/service.js

@@ -277,6 +277,9 @@ export function createService(options) {
         usedIds: doc.todos.map((candidate) => candidate.id),
         ...(context.origin === undefined ? {} : { origin: context.origin }),
       })
+      // Stable, human-facing number: the store fills gaps on read, the service assigns the
+      // next one on create so "#42" keeps meaning #42.
+      todo.seq = doc.todos.reduce((max, candidate) => Math.max(max, candidate.seq ?? 0), 0) + 1
       doc.todos.push(todo)
       metrics?.recordList?.('created', doc.todos.length)
       logger?.debug?.(`dsh-global-todo: created ${todo.id}`)
@@ -610,6 +613,19 @@ export function createService(options) {
       seen.add(todo.id)
       records.push(todo)
     }
+    if (context.dryRun === true) {
+      const existing = await store.all()
+      const known = new Set(existing.map((todo) => todo.id))
+      const wouldCreate = records.filter((record) => !known.has(record.id)).length
+      return {
+        mode,
+        dryRun: true,
+        wouldImport: records.length,
+        wouldCreate,
+        wouldUpdate: records.length - wouldCreate,
+        total: mode === 'merge' ? existing.length + wouldCreate : records.length,
+      }
+    }
     return store.update((existing) => {
       const todos = mode === 'merge' ? mergeById(existing.todos, records) : records
       metrics?.recordList?.('imports', todos.length)

package/lib/settings.js

@@ -66,6 +66,10 @@ export const SETTINGS_DEFAULTS = Object.freeze({
   ingestSources: [...INGEST_SOURCES],
   /** Items below this confidence wait in the inbox instead of joining the list. */
   ingestConfirmBelow: 0.8,
+  /** Announce deadlines in the panel. On by default; a deadline nobody hears about is just data. */
+  remindersEnabled: true,
+  /** Announce this many minutes before the deadline (0 = at the deadline). */
+  reminderLeadMinutes: 0,
 })
 
 /**
@@ -105,6 +109,7 @@ export function normalizeSettings(raw) {
     sources.push(kind)
   }
   const below = Number(source.ingestConfirmBelow)
+  const lead = Number(source.reminderLeadMinutes)
   return {
     autoCollect: source.autoCollect === true,
     cooldownMinutes: Number.isInteger(minutes) ? Math.min(Math.max(minutes, 5), 24 * 60) : SETTINGS_DEFAULTS.cooldownMinutes,
@@ -117,6 +122,8 @@ export function normalizeSettings(raw) {
     ingestToken: typeof source.ingestToken === 'string' ? source.ingestToken.trim().slice(0, 512) : '',
     ingestSources: sources.length === 0 ? [...INGEST_SOURCES] : sources,
     ingestConfirmBelow: Number.isFinite(below) ? Math.min(Math.max(below, 0), 1) : SETTINGS_DEFAULTS.ingestConfirmBelow,
+    remindersEnabled: source.remindersEnabled !== false,
+    reminderLeadMinutes: Number.isFinite(lead) ? Math.min(Math.max(lead, 0), 24 * 60) : SETTINGS_DEFAULTS.reminderLeadMinutes,
   }
 }
 

package/lib/store.js

@@ -64,7 +64,26 @@ function salvage(value, activityLimit) {
     seen.add(todo.id)
     todos.push(todo)
   }
-  return { version: Number.isInteger(doc.version) ? doc.version : SCHEMA_VERSION, todos }
+  return { version: Number.isInteger(doc.version) ? doc.version : SCHEMA_VERSION, todos: assignSequence(todos) }
+}
+
+/**
+ * Give every record its human-facing number.
+ *
+ * Existing numbers are kept so "把 #42 交给 Agent" stays true after other records are
+ * deleted; records without one are numbered in creation order, and the next write
+ * persists them. A file that never gets written again keeps deriving the same numbers.
+ *
+ * @param {object[]} todos
+ * @returns {object[]}
+ */
+function assignSequence(todos) {
+  let max = 0
+  for (const todo of todos) if (Number.isInteger(todo.seq) && todo.seq > max) max = todo.seq
+  const missing = todos.filter((todo) => !Number.isInteger(todo.seq) || todo.seq <= 0)
+  missing.sort((left, right) => left.createdAt - right.createdAt || left.id.localeCompare(right.id))
+  for (const todo of missing) todo.seq = ++max
+  return todos
 }
 
 /**

package/lib/tools.js

@@ -85,6 +85,7 @@ const COMPLETION_SHAPE = {
 const TODO_SHAPE = {  type: 'object',
   properties: {
     id: { type: 'string' },
+    seq: { type: 'integer', description: '给人看的编号（#42）；0 表示尚未分配' },
     title: { type: 'string' },
     description: { type: 'string' },
     status: { type: 'string', enum: [...STATUSES] },
@@ -144,6 +145,7 @@ export function presentTodo(todo, now = Date.now()) {
   const due = todo.dueAt === null ? Number.POSITIVE_INFINITY : Date.parse(todo.dueAt)
   return {
     id: todo.id,
+    seq: todo.seq ?? 0,
     title: todo.title,
     description: todo.description,
     status: todo.status,
@@ -181,7 +183,8 @@ export function presentTodo(todo, now = Date.now()) {
  */
 export function todoLine(todo) {
   const mark = todo.status === 'done' ? 'x' : todo.status === 'doing' ? '~' : todo.status === 'cancelled' ? '-' : ' '
-  const parts = [`- [${mark}] ${todo.title}  id=${todo.id}`, `加入于 ${new Date(todo.createdAt).toISOString()}`]
+  const label = Number.isInteger(todo.seq) && todo.seq > 0 ? `#${todo.seq} ` : ''
+  const parts = [`- [${mark}] ${label}${todo.title}  id=${todo.id}`, `加入于 ${new Date(todo.createdAt).toISOString()}`]
   if (todo.priority !== 'normal') parts.push(PRIORITY_LABELS[todo.priority] ?? todo.priority)
   if (todo.dueAt !== null) parts.push(`截止 ${todo.dueAt}`)
   if (todo.tags.length > 0) parts.push(todo.tags.map((tag) => `#${tag}`).join(' '))

package/package.json

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