dsh-global-todo 0.4.1 → 0.4.3

package/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.3] — 2026-10-19
+
+The list is meant to live in a synced folder; a change from another machine should not be
+something you find out about a day later.
+
+- **A file changed elsewhere is counted and reported.** The store keeps an `mtimeMs:size`
+  fingerprint of the file as this process last read or wrote it; a read that disagrees with it
+  increments `externalChanges` (once per change, not once per poll) and records
+  `lastExternalAt`, both surfaced through `/health.store`. The panel turns a new count into a
+  one-line notice. Reads still trust a file that parses — this process cannot merge two writers'
+  intent — but the person can see that it happened.
+## [0.4.2] — 2026-10-19
+
+Noise is the failure mode that matters for a list other people are asked to trust.
+
+- **Capture decides with a gate, not a title comparison.** The old check compared normalized
+  titles exactly against active rows, which missed the ordinary case — same errand, different
+  wording — and happily re-admitted something finished yesterday. `lib/capture.js` now refuses an
+  item when its normalized title matches a live row, when a close paraphrase (Dice over character
+  bigrams, 0.8) appears within 72 hours, or when the same errand was finished in the last 7 days.
+  Archived and cancelled rows are set-aside history and do not block a new one; every refusal
+  carries its reason in `skipped[]`.
 ## [0.4.1] — 2026-10-19
 
 The half-finished half: the selection could only be assigned, and the only way to get a record out

package/README.md

@@ -227,6 +227,12 @@ produces noise, and a noisy list is worse than an empty one:
 The boundary: it **records, it never starts work**. The list belongs to the human, and
 starting a task stays a human decision (see the non-goals in [ROADMAP](docs/ROADMAP.md)).
 
+
+Capture is not allowed to become noise. Before an item is written, the same normalized title
+(full-width, case, spacing and punctuation folded away), a close paraphrase within the last 72
+hours (Dice similarity over character bigrams, 0.8), and the same errand finished in the last 7
+days are all refused with a reason on the record; archived and cancelled rows do not block a
+new one. The rules live in `lib/capture.js` and are tested on their own.
 ### HTTP API
 
 The panel talks to the host over these routes. They are fenced by the host connection

package/docs/DESIGN.md

@@ -57,6 +57,16 @@ $DSH_HOME/global-todo/todos.json     ← { version: 1, todos: [ … ] }
   version, and a future migration step would run before the first write, keeping the old
   file as a backup.
 
+## A shared file changes without asking
+
+The list is deliberately portable — a notes repo, a synced folder, a NAS — so another machine
+writing the same file is a normal event. It must not be a silent one either: the store keeps a
+`mtimeMs:size` fingerprint of the file as it last read or wrote it, and a read that disagrees
+means somebody else changed it. That is counted once per change (not once per poll, which would
+be noise) and exported through `describe()` as `externalChanges` / `lastExternalAt`; the panel
+turns a new count into a one-line notice. `store.read` still trusts a file that parses, because
+**this process** has no way to merge two writers' intent — but the person can now see that it
+happened instead of discovering it a day later.
 ## Attachments: references, not uploads
 
 An attachment is either an address (`http`/`https`) or an absolute path. Rules:
@@ -157,6 +167,13 @@ rest of the batch — a partial success is reported as a partial success, never
 The ceiling: **capture ends at the list.** Nothing the plugin does starts work by itself;
 "hand it to an agent" is always a human click.
 
+
+The gate has to be narrower than "remember things": a capture run that re-registers what the list
+already holds is how a trusted list becomes noise. So an item is refused, with the reason on the
+record, when its normalized title matches a live row, when a close paraphrase (Dice over character
+bigrams, 0.8) appears in the last 72 hours, or when the same errand was finished within 7 days.
+Archived and cancelled rows are history a person set aside and must not block a new one; the rules
+are pure and live in `lib/capture.js` so they can be tested without a store.
 ## A fallback must never quietly outrank the real rule
 
 The routes are fenced: the Host's connection service decides (`isTrustedApiRequest` against

package/docs/ROADMAP.md

@@ -102,6 +102,14 @@ selection in one request; a stale id is reported in `unmatched` instead of disca
 (`bulk()` in `lib/service.js`, `runBulk` in `lib/client.js`). `archived` joined the statuses, so a
 record can leave the active view without being deleted; the filter chip only appears once something
 is archived, and `global_todo_update` finally accepts `status`.
+**A capture gate, not a title comparison** — before `global_todo_capture` writes an item it asks
+`findDuplicate` (`lib/capture.js`): normalized title against live rows, a close paraphrase inside
+72 hours, and the same errand finished in the last 7 days. The decision is pure, the reason lands
+in `skipped[]`, and archived/cancelled rows deliberately do not block a new one.
+**A change made elsewhere is visible** — the store fingerprints the file on every read/write and
+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.
 ### Partly landed
 
 - **Batch and multi-select** — the selection mode, its per-row markers and the batch

package/lib/capture.js

@@ -0,0 +1,104 @@
+/**
+ * Capture quality gate.
+ *
+ * `global_todo_capture` is the one path that can add several records at once, and a capture run
+ * that keeps re-registering what the list already has is how the list turns into noise. The
+ * first version compared normalised titles exactly against the active rows; that misses the
+ * common case — same errand, different wording — and it re-admits something that was finished
+ * yesterday. Both are pure decisions, so they live here and are tested without a store.
+ *
+ * @module dsh-global-todo/capture
+ */
+
+/** Titles closer than this are treated as the same errand. */
+const SIMILARITY = 0.8
+/** Only compare against rows from the last few days; older ones are history, not duplicates. */
+const DEDUPE_WINDOW_HOURS = 72
+/** A finished errand stays done this long before the same title may come back. */
+const DONE_COOLDOWN_DAYS = 7
+
+/**
+ * Fold a title to what it means: width, case, spacing and punctuation are noise.
+ *
+ * Numbers and dates are kept on purpose — "10 月 20 日交" and "10 月 21 日交" are different
+ * errands even though they differ by one character.
+ *
+ * @param {unknown} title
+ * @returns {string}
+ */
+export function normalizeTitle(title) {
+  return String(title ?? '').normalize('NFKC').toLowerCase().replace(/[\s\p{P}\p{S}]+/gu, '')
+}
+
+/** @param {string} text @returns {Set<string>} */
+function bigrams(text) {
+  const chars = [...text]
+  if (chars.length < 2) return new Set(chars)
+  const out = new Set()
+  for (let index = 0; index < chars.length - 1; index += 1) out.add(chars[index] + chars[index + 1])
+  return out
+}
+
+/**
+ * Dice coefficient over character bigrams: 0 when unrelated, 1 when identical.
+ *
+ * @param {unknown} left
+ * @param {unknown} right
+ * @returns {number}
+ */
+export function similarity(left, right) {
+  const a = bigrams(normalizeTitle(left))
+  const b = bigrams(normalizeTitle(right))
+  if (a.size === 0 || b.size === 0) return 0
+  let shared = 0
+  for (const gram of a) if (b.has(gram)) shared += 1
+  return (2 * shared) / (a.size + b.size)
+}
+
+/**
+ * Is this title already on the list, in a way a person would call a duplicate?
+ *
+ * @param {{ title?: unknown, existing?: object[], now?: number, similarity?: number, windowHours?: number, doneCooldownDays?: number }} input
+ * @returns {{ duplicate: boolean, reason?: string, matchId?: string }}
+ */
+export function findDuplicate(input) {
+  const title = input.title
+  const key = normalizeTitle(title)
+  if (key === '') return { duplicate: false }
+  const now = Number.isFinite(input.now) ? input.now : Date.now()
+  const windowMs = (input.windowHours ?? DEDUPE_WINDOW_HOURS) * 60 * 60 * 1000
+  const cooldownMs = (input.doneCooldownDays ?? DONE_COOLDOWN_DAYS) * 24 * 60 * 60 * 1000
+  const threshold = Number.isFinite(input.similarity) ? input.similarity : SIMILARITY
+  for (const todo of Array.isArray(input.existing) ? input.existing : []) {
+    if (todo === null || typeof todo !== 'object' || typeof todo.title !== 'string') continue
+    // Archived is history a person chose to keep out of the way; it must not block the same
+    // errand from being written again. Cancelled is likewise not a live duplicate.
+    if (todo.status === 'cancelled' || todo.status === 'archived') continue
+    const doneAt = Number.isFinite(todo.doneAt)
+      ? todo.doneAt
+      : Number.isFinite(todo.updatedAt) ? todo.updatedAt : 0
+    if (normalizeTitle(todo.title) === key) {
+      if (todo.status === 'done') {
+        if (now - doneAt < cooldownMs) return { duplicate: true, reason: 'recently-done', matchId: todo.id }
+      } else {
+        return { duplicate: true, reason: 'same-active', matchId: todo.id }
+      }
+    }
+    if (todo.status !== 'done') {
+      const created = Number.isFinite(todo.createdAt) ? todo.createdAt : now
+      // A five-day-old item is not evidence that today's wording is a duplicate; only the
+      // recent window is compared for similarity.
+      if (now - created < windowMs && similarity(title, todo.title) >= threshold) {
+        return { duplicate: true, reason: 'similar-active', matchId: todo.id }
+      }
+    }
+  }
+  return { duplicate: false }
+}
+
+/** The sentence a person reads in `skipped[].error`. */
+export const CAPTURE_REASONS = Object.freeze({
+  'same-active': '清单里已有同名的未完成条目，未重复登记',
+  'similar-active': '清单里已有一条很相似的未完成条目，未重复登记',
+  'recently-done': '这条刚完成不久（7 天内），没有重复登记',
+})

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 = 'ui25'
+    const UI_REV = 'ui26'
     /** Last language resolved for the shell; module-level so a fetch failure can be worded too. */
     let activeLang = 'zh'
 
@@ -134,6 +134,7 @@ window.__ModuleLoader__.load({
       'autoCollect.reason.turn': '轮次没有干净结束（{kind}）',
       'notice.autoCollectOn': '已开启自动获取：一次人为发言最多自动问一次',
       'notice.autoCollectOff': '已关闭自动获取',
+      'notice.externalChange': '清单在别处被改过，已载入最新内容',
       'action.exempt': '豁免',
       'action.exemptOn': '已豁免',
       'action.exemptHint': '这个工作区里的对话永不自动获取（再点一下取消）',
@@ -344,6 +345,7 @@ window.__ModuleLoader__.load({
       'autoCollect.reason.turn': 'the turn did not end cleanly ({kind})',
       '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',
       'action.exempt': 'Exempt',
       'action.exemptOn': 'Exempted',
       'action.exemptHint': 'Never auto-collect in this workspace (click again to undo)',
@@ -2125,6 +2127,9 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
           : []
       const conversations = [...pinnedEntry, ...labelled]
       const mounted = useRef(true)
+      // The store counts file changes made outside this process (another machine, a sync
+      // client). A new count means the panel's view was stale a moment ago; say so once.
+      const externalRef = useRef(null)
       const titleRef = useRef(null)
       const searchRef = useRef(null)
       const undoTimer = useRef(null)
@@ -2165,11 +2170,18 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
       const refreshHealth = useCallback(async () => {
         try {
           const data = await call('health')
-          if (mounted.current) setState((current) => ({ ...current, health: data }))
+          if (!mounted.current) return
+          const external = Number(data?.store?.externalChanges) || 0
+          if (externalRef.current !== null && external > externalRef.current) {
+            setNotice({ text: translate(lang, 'notice.externalChange'), sessionId: '' })
+            setTimeout(() => setNotice(null), 8000)
+          }
+          externalRef.current = external
+          setState((current) => ({ ...current, health: data }))
         } catch {
           /* the health mirror is not worth an error banner */
         }
-      }, [])
+      }, [lang])
 
       useEffect(() => {
         mounted.current = true

package/lib/index.js

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

package/lib/store.js

@@ -19,7 +19,7 @@
  * @module dsh-global-todo/store
  */
 
-import { open, mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { open, mkdir, readFile, rename, stat, writeFile } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import path from 'node:path'
 
@@ -79,6 +79,46 @@ export function createStore(options) {
   /** Serializes every mutation; also lets `update` await the writes before it. */
   let chain = Promise.resolve()
 
+  /**
+   * Fingerprint of the file as this process last read or wrote it.
+   *
+   * The file is meant to be portable — a synced folder, a NAS — so another machine changing it
+   * is a normal event, not an error. It must not be silent either: a read that sees a different
+   * `mtimeMs:size` than the last one this process established is reported through `describe()`
+   * so the panel can say the list changed elsewhere. One increment per external change, not per
+   * poll, which is why `known` is updated as the change is noticed.
+   */
+  let known = null
+  let externalChanges = 0
+  let lastExternalAt = null
+
+  /** @param {{ mtimeMs: number, size: number } | null} info */
+  function remember(info) {
+    if (info === null) {
+      known = null
+      return
+    }
+    known = `${info.mtimeMs}:${info.size}`
+  }
+
+  /** Note a read that disagrees with what this process last saw. */
+  function observe(info) {
+    if (info === null) {
+      if (known !== null) {
+        externalChanges += 1
+        lastExternalAt = now()
+      }
+      known = null
+      return
+    }
+    const fingerprint = `${info.mtimeMs}:${info.size}`
+    if (known !== null && known !== fingerprint) {
+      externalChanges += 1
+      lastExternalAt = now()
+    }
+    known = fingerprint
+  }
+
   /**
    * Read the document. A missing file is an empty list; an unparseable file is
    * an error, never a silent reset — overwriting a mangled-but-recoverable file
@@ -91,9 +131,15 @@ export function createStore(options) {
     try {
       text = await readFile(file, 'utf8')
     } catch (error) {
-      if (error?.code === 'ENOENT') return { version: SCHEMA_VERSION, todos: [] }
+      if (error?.code === 'ENOENT') {
+        // The file this process knew about is gone: somebody else removed or moved it.
+        observe(null)
+        return { version: SCHEMA_VERSION, todos: [] }
+      }
       throw new TodoError('store-unwritable', `读不到待办文件 ${file}：${error?.message ?? error}`)
     }
+    // Compare before parsing: a corrupt write from elsewhere is still a change worth naming.
+    observe(await stat(file).catch(() => null))
     if (text.trim() === '') return { version: SCHEMA_VERSION, todos: [] }
 
     let parsed
@@ -147,6 +193,8 @@ export function createStore(options) {
     } catch {
       /* ignore */
     }
+    // This write is the new baseline, so the next read does not report our own change.
+    remember(await stat(file).catch(() => null))
   }
 
   /**
@@ -206,7 +254,18 @@ export function createStore(options) {
         logger?.warn?.(`dsh-global-todo: 无法统计 ${file}：${error?.message ?? error}`)
       }
     }
-    return { kind: 'json', file, exists, bytes, todos, schemaVersion: SCHEMA_VERSION }
+    return {
+      kind: 'json',
+      file,
+      exists,
+      bytes,
+      todos,
+      schemaVersion: SCHEMA_VERSION,
+      // How many times the file changed under this process (another machine, a sync client).
+      // In memory: it describes this process, and a restart is entitled to forget it.
+      externalChanges,
+      lastExternalAt,
+    }
   }
 
   return { kind: 'json', file, read, write, update, all, describe }

package/lib/tools.js

@@ -13,6 +13,7 @@
  * @module dsh-global-todo/tools
  */
 
+import { CAPTURE_REASONS, findDuplicate } from './capture.js'
 import { asTodoError } from './errors.js'
 import { formatLink } from './links.js'
 import { LIMITS, PRIORITIES, PRIORITY_LABELS, STATUSES } from './model.js'
@@ -384,27 +385,30 @@ export function createTools(service, options = {}) {
         const origin = originOf(exec)
         const todos = []
         const skipped = []
-        // A capture run that keeps re-registering what is already on the list is how the
-        // list fills with near-duplicates. One lookup, then skip by normalised title.
+        // The quality gate decides per item: exact title, a close paraphrase within the
+        // recent window, or the same errand finished days ago. One lookup of everything —
+        // done and archived rows matter too, which the active-only lookup used to miss.
         let existing = []
         try {
-          existing = (await service.list({ status: 'active' })).todos
+          existing = (await service.list({ status: 'all', limit: 1000 })).todos
         } catch {
           existing = []
         }
-        const keyOf = (title) =>
-          String(title ?? '').trim().toLowerCase().replace(/\s+/g, '')
-        const seen = new Set(existing.map((todo) => keyOf(todo.title)))
+        const nowMs = now()
         for (const item of items) {
-          const itemKey = keyOf(item?.title)
-          if (itemKey !== '' && seen.has(itemKey)) {
-            skipped.push({ title: String(item?.title ?? '(无标题)'), error: '清单里已有同名的未完成条目，未重复登记' })
+          const verdict = findDuplicate({ title: item?.title, existing, now: nowMs })
+          if (verdict.duplicate === true) {
+            skipped.push({
+              title: String(item?.title ?? '(无标题)'),
+              error: CAPTURE_REASONS[verdict.reason] ?? '清单里已有重复条目，未重复登记',
+            })
             continue
           }
           const outcome = await attempt(() => service.create(item ?? {}, { by: 'agent', origin }))
           if (outcome.ok === true) {
-            if (itemKey !== '') seen.add(itemKey)
             todos.push(presentTodo(outcome.value, now()))
+            // Later items in the same batch must see this one as existing.
+            existing.push(outcome.value)
           }
           else skipped.push({ title: String(item?.title ?? '(无标题)'), error: outcome.error })
         }

package/package.json

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