ask-later 0.1.0

package/lib/messages.mjs

@@ -0,0 +1,125 @@
+// 人とモデルに見せる文言（日本語が正、英語は従）。
+// 状態行・ヘッダ行のように「機械が読む書式」は pending.mjs が持ち、ここには置かない。
+
+const ja = {
+  // --- 注入（additionalContext） ---
+  // 事実の陳述で書く。命令形（「〜すること」「〜せよ」）は Claude Code の prompt-injection 防御を起動し、
+  // 文脈ではなく「埋め込み指示」として人に差し戻される（公式 hooks リファレンス。設計監査 2 巡目 #1 で実測）。
+  // 「どう処理するか」の規律は CLAUDE.md の断片（templates/CLAUDE.snippet.*.md）に置き、ここでは「何がどうなっているか」だけを述べる。
+  ctxOpen: (n, pending) => `【${pending} に未処理の依頼: ${n}件】利用者の判断を待っている項目で、内容は ${pending} にある。`,
+  ctxOpenTail: "これらに依存しない作業は続行できる（このプロジェクトの規律〈CLAUDE.md「非同期キュー」〉）。",
+  ctxInboxHead: (n, inbox) =>
+    `【${inbox} に利用者本人の未読の行: ${n}件】${inbox} は利用者が手で書く連絡ファイルで、次の行は利用者本人が書いたもの（フックが写した）。このプロジェクトの規律（CLAUDE.md「非同期キュー」）では、${inbox} の行は利用者のチャット発言と同じ扱いになる。`,
+  ctxInboxTail: (pending) => [
+    `P-xxx の完了報告は ${pending} の該当項目の解消に対応する。命令・質問・提案は、そのままの意味の発言である。`,
+    "処理済みの行は行頭に ✔ を付けて残す決まりになっている（行は消さない）。",
+  ],
+  ctxWithdrawn: (ids) => `【期限切れで自動取り下げ: ${ids.join(", ")}】状態行が取り下げに書き換わった。実施の有無は INBOX の報告で確定する。`,
+  ctxMalformed: (ids, pending) => `【状態行が無い項目: ${ids.join(", ")}】${pending} の「- [ ] 状態: 未処理」の書式になっておらず、件数に入っていない。`,
+  ctxNoPending: (pending) => `【ask-later】${pending} が無い（フックは動いている）。雛形は npx ask-later init が作る。`,
+  ctxOpenMore: (n) => `  - …ほか ${n} 件（一覧は PENDING にある）`,
+  ctxGarbled: (inbox) => `【注意】${inbox} に UTF-8 として読めない行があり、Shift_JIS として読み直した。その行を書き換えると壊れる。直るのは利用者が ${inbox} を UTF-8 で保存し直したとき（メモ帳: 名前を付けて保存 → 文字コード UTF-8）。`,
+  stopReason: (n, inbox) => `${inbox} に利用者本人の未読の行が ${n} 件残っている。未読が残ったままの停止は、このプロジェクトの規律で差し止められる。`,
+  stopReasonAgain: (k, max) => `（${k} 回目の差し止め。最大 ${max} 回。処理できない行は ✔ を付けて理由を返答に書けば通る）`,
+
+  // --- hook.log ---
+  logInject: (open, unread) => `注入（未処理 ${open}・未読 ${unread}）`,
+  logBlock: (unread, k, max) => `差し止め（未読 ${unread}・${k}/${max} 回目）`,
+  logNone: (open, unread) => `-（未処理 ${open}・未読 ${unread}）`,
+  logUnknown: "知らないイベント。何もしない",
+  logFail: (e) => `失敗（止めない）: ${e}`,
+  logWithdrawn: (ids) => `取り下げ ${ids.join(",")}`,
+  logNotified: "通知",
+  logGarbled: (n) => `UTF-8 でない行 ${n}`,
+
+  // --- 番兵ファイル ---
+  sentinel: ({ n, items, now, pending, inbox }) => [
+    `利用者にお願いしたいことが ${n} 件あります。`,
+    "",
+    `内容      : ${pending} を開いてください`,
+    `完了報告  : ${inbox} に1行書いてください（例: P-003 done）`,
+    "",
+    "未処理の項目:",
+    ...items.map((it) => `  - ${it.id} ${it.title}`),
+    "",
+    "このファイルは自動生成されます。消しても構いません（次回の集計で再生成されます）。",
+    `最終更新: ${now}`,
+  ],
+
+  // --- 通知 ---
+  notifyTitle: (n) => `未処理の依頼 ${n} 件`,
+
+  // --- status の印字 ---
+  statusPending: (n) => `PENDING 未処理: ${n}件`,
+  statusWithdrawn: (id) => `  取り下げ（期限切れ・自動）: ${id}`,
+  statusInbox: (n) => `INBOX 未読: ${n}件`,
+  statusSentinel: (p, open = 0) => `番兵: ${p ?? (open > 0 ? `なし（未処理 ${open} 件。次の集計で作られる）` : "なし（0 件）")}`,
+  statusMissing: (name) => `${name} がありません（npx ask-later init で雛形を作れます）`,
+  statusMalformed: (ids) => `状態行が無い項目（件数に入っていない）: ${ids.join(", ")}`,
+  statusGarbled: (n, inbox) => `注意: ${inbox} に UTF-8 として読めない行が ${n} 行あります（Shift_JIS として読みました）。メモ帳の「名前を付けて保存 → 文字コード UTF-8」で保存し直してください`,
+  statusHookVersion: (copy, pkg) => (copy === pkg ? `フック本体: ${copy}` : `フック本体: ${copy ?? "版が不明（古い写し）"}（このパッケージは ${pkg}。npx ask-later@latest init で更新）`),
+  statusNotified: (r) => `通知: ${r.notified ? "出した" : r.quiet ? "静音時間帯なので翌朝に持ち越し" : "変化なし"}`,
+  warnWrite: (e) => `注意: ${e}`,
+  errWrite: (path) => `書き込めません（権限が無いか、読み取り専用か、別のアプリが開いています）: ${path}`,
+};
+
+const en = {
+  ctxOpen: (n, pending) => `[Open requests to the user in ${pending}: ${n}] Items waiting on the user's decision; the details are in ${pending}.`,
+  ctxOpenTail: "Work that does not depend on these can continue (this project's rule: CLAUDE.md \"Async queue\").",
+  ctxInboxHead: (n, inbox) =>
+    `[${inbox}: ${n} unread line(s) written by the user] ${inbox} is the file the user writes in by hand; the following line(s) are the user's own words (copied by the hook). Under this project's rule (CLAUDE.md "Async queue"), lines in ${inbox} are the user's chat messages.`,
+  ctxInboxTail: (pending) => [
+    `A completion report (P-xxx done) corresponds to resolving the matching item in ${pending}. Instructions, questions and proposals carry their plain meaning.`,
+    "Handled lines are kept with a leading ✔ (lines are never deleted).",
+  ],
+  ctxWithdrawn: (ids) => `[Withdrawn automatically (deadline passed): ${ids.join(", ")}] The status line was rewritten. Whether it was done is settled by the INBOX report.`,
+  ctxMalformed: (ids, pending) => `[Items without a status line: ${ids.join(", ")}] They do not match the "- [ ] status: open" format in ${pending} and are not counted.`,
+  ctxNoPending: (pending) => `[ask-later] ${pending} is missing (the hooks are active). npx ask-later init creates the templates.`,
+  ctxOpenMore: (n) => `  - ...and ${n} more (the full list is in PENDING)`,
+  ctxGarbled: (inbox) => `[Warning] ${inbox} has lines that are not valid UTF-8; they were re-read as Shift_JIS. Editing them corrupts them. It is fixed once the user re-saves ${inbox} as UTF-8.`,
+  stopReason: (n, inbox) => `${inbox} still has ${n} unread line(s) written by the user. Stopping with unread lines is blocked under this project's rule.`,
+  stopReasonAgain: (k, max) => ` (block ${k} of at most ${max}. A line that cannot be acted on gets a ✔ and the reason in the reply; the stop then goes through)`,
+
+  logInject: (open, unread) => `inject (open ${open}, unread ${unread})`,
+  logBlock: (unread, k, max) => `block (unread ${unread}, ${k}/${max})`,
+  logNone: (open, unread) => `- (open ${open}, unread ${unread})`,
+  logUnknown: "unknown event; nothing done",
+  logFail: (e) => `failed (not blocking): ${e}`,
+  logWithdrawn: (ids) => `withdrawn ${ids.join(",")}`,
+  logNotified: "notified",
+  logGarbled: (n) => `non-UTF-8 lines ${n}`,
+
+  sentinel: ({ n, items, now, pending, inbox }) => [
+    `The agent is waiting on you for ${n} item(s).`,
+    "",
+    `What      : open ${pending}`,
+    `To report : write one line in ${inbox} (e.g. P-003 done)`,
+    "",
+    "Open items:",
+    ...items.map((it) => `  - ${it.id} ${it.title}`),
+    "",
+    "This file is generated automatically. You may delete it (it is recreated at the next count).",
+    `Last updated: ${now}`,
+  ],
+
+  notifyTitle: (n) => `${n} open request(s)`,
+
+  statusPending: (n) => `PENDING open: ${n}`,
+  statusWithdrawn: (id) => `  withdrawn (deadline passed, automatic): ${id}`,
+  statusInbox: (n) => `INBOX unread: ${n}`,
+  statusSentinel: (p, open = 0) => `sentinel: ${p ?? (open > 0 ? `none (${open} open; written at the next count)` : "none (0 open)")}`,
+  statusMissing: (name) => `${name} is missing (npx ask-later init creates the templates)`,
+  statusMalformed: (ids) => `items without a status line (not counted): ${ids.join(", ")}`,
+  statusGarbled: (n, inbox) => `warning: ${n} line(s) in ${inbox} are not valid UTF-8 (read as Shift_JIS). Re-save the file as UTF-8`,
+  statusHookVersion: (copy, pkg) => (copy === pkg ? `hook files: ${copy}` : `hook files: ${copy ?? "unknown version (old copy)"} (this package is ${pkg}; run npx ask-later@latest init to update)`),
+  statusNotified: (r) => `notification: ${r.notified ? "sent" : r.quiet ? "quiet hours, deferred to the morning" : "no change"}`,
+  warnWrite: (e) => `warning: ${e}`,
+  errWrite: (path) => `cannot write (no permission, read-only, or open in another app): ${path}`,
+};
+
+export const MESSAGES = { ja, en };
+export const LANGS = Object.keys(MESSAGES);
+
+export function msg(lang) {
+  return MESSAGES[lang] ?? MESSAGES.ja;
+}

package/lib/notify.mjs

@@ -0,0 +1,51 @@
+// OS 通知。補助手段であり、すべて best-effort（出せない環境でも番兵ファイルは既に置いてある）。
+//   Windows  PowerShell の toast（WinRT）。powershell.exe は .exe なのでシェル無しで起動できる
+//   macOS    osascript の display notification
+//   Linux    notify-send（無ければ何もしない）
+import { execFile } from "node:child_process";
+
+function run(cmd, args, { timeoutMs = 10000 } = {}) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = execFile(cmd, args, { timeout: timeoutMs, windowsHide: true }, (err, stdout, stderr) => {
+        resolve({ ok: !err, error: err ? (stderr || err.message).toString().trim().split("\n")[0] : null });
+      });
+    } catch (e) {
+      resolve({ ok: false, error: e.message });
+    }
+    if (child && child.unref) child.unref();
+  });
+}
+
+const psQuote = (s) => `'${String(s).replace(/'/g, "''")}'`;
+const asQuote = (s) => `"${String(s).replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+
+export async function notify({ title, body, platform = process.platform }) {
+  const t = String(title ?? "").slice(0, 120);
+  const b = String(body ?? "").slice(0, 200);
+  try {
+    if (platform === "win32") {
+      const script = [
+        "[void][Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime]",
+        "$tmpl = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent([Windows.UI.Notifications.ToastTemplateType]::ToastText02)",
+        '$nodes = $tmpl.GetElementsByTagName("text")',
+        `$nodes.Item(0).AppendChild($tmpl.CreateTextNode(${psQuote(t)})) | Out-Null`,
+        `$nodes.Item(1).AppendChild($tmpl.CreateTextNode(${psQuote(b)})) | Out-Null`,
+        "$toast = [Windows.UI.Notifications.ToastNotification]::new($tmpl)",
+        "$appId = '{1AC14E77-02E7-4E5D-B744-2EB1AE5198B7}\\WindowsPowerShell\\v1.0\\powershell.exe'",
+        "[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier($appId).Show($toast)",
+      ].join("; ");
+      const r = await run("powershell.exe", ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", script]);
+      return { ...r, method: "toast" };
+    }
+    if (platform === "darwin") {
+      const r = await run("osascript", ["-e", `display notification ${asQuote(b)} with title ${asQuote(t)}`]);
+      return { ...r, method: "osascript" };
+    }
+    const r = await run("notify-send", [t, b]);
+    return { ...r, method: "notify-send" };
+  } catch (e) {
+    return { ok: false, method: null, error: e.message };
+  }
+}

package/lib/pending.mjs

@@ -0,0 +1,115 @@
+// PENDING.md の解析。機械が読むのは 3 行だけ:
+//   見出し   "## [P-003] タイトル"
+//   状態行   "- [ ] 状態: 未処理" / "- [x] 状態: 完了 (2026-09-10)" / "- [x] 状態: 取り下げ（理由）"
+//            英語版は "- [ ] status: open" / "- [x] status: done" / "- [x] status: withdrawn (...)"
+//   期限行   "- 期限: 2026-09-11 21:30"（"- due:" / "- deadline:" も可）
+//            過ぎていれば自動で「取り下げ」に書き換える。動けなくなった項目を数え続けると番兵の件数の意味が薄まるため。
+// コードブロック（``` / ~~~）の中は見ない（雛形の書き方の例が項目として数えられないように）。
+import { splitLines, parseLocalDateTime, formatLocal } from "./text.mjs";
+
+const HEADING = /^\s*##\s*\[([^\]]+)\]\s*(.*)$/;
+// 箇条書きの記号は - のほか * と + も可（Markdown と同じ）。### 以下の見出しは項目にならない（## だけ）
+const STATUS = /^(\s*[-*+]\s*)\[([ xX])\](\s*)(状態|status)(\s*[:：]\s*)(.*)$/i;
+// 状態行らしき行（チェックボックス付きの箇条書き）。これがあるのに STATUS に一致しなければ「崩れている」。
+// 無ければ、その見出しは依頼ではない（例: 状態を持たない「報告」の見出し ## [R-010] …）
+const CHECKBOX = /^\s*[-*+]\s*\[[^\]]*\]/;
+const DEADLINE = /^\s*-\s*(期限|due|deadline)\s*[:：]\s*(\d{4}-\d{2}-\d{2})(?:[ T](\d{1,2}:\d{2}))?/i;
+const FENCE = /^\s*(```|~~~)/;
+const HEADER_JA = /^未処理: .*$/m;
+const HEADER_EN = /^Open: .*$/m;
+
+export function parsePending(text) {
+  const lines = splitLines(text ?? "");
+  const items = [];
+  let cur = null;
+  let inFence = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (FENCE.test(line)) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+    const h = HEADING.exec(line);
+    if (h) {
+      cur = {
+        id: h[1].trim(),
+        title: h[2].trim(),
+        headingIndex: i,
+        statusIndex: -1,
+        hasCheckbox: false,
+        open: false,
+        statusKey: null,
+        statusText: "",
+        deadline: null,
+        deadlineText: null,
+      };
+      items.push(cur);
+      continue;
+    }
+    if (!cur) continue;
+    if (cur.statusIndex < 0) {
+      const s = STATUS.exec(line);
+      if (s) {
+        cur.statusIndex = i;
+        cur.open = s[2] === " ";
+        cur.statusKey = s[4];
+        cur.statusText = s[6].trim();
+        continue;
+      }
+      if (CHECKBOX.test(line)) cur.hasCheckbox = true;
+    }
+    if (!cur.deadline) {
+      const d = DEADLINE.exec(line);
+      if (d) {
+        const dt = parseLocalDateTime(d[2], d[3] ?? "23:59");
+        if (dt) {
+          cur.deadline = dt;
+          cur.deadlineText = formatLocal(dt);
+        }
+      }
+    }
+  }
+  return {
+    lines,
+    // 依頼（状態行がある、または状態行らしき行がある）
+    items: items.filter((it) => it.statusIndex >= 0 || it.hasCheckbox),
+    // 状態行らしき行はあるが書式が違う項目。件数に入らないので、人に知らせる
+    malformed: items.filter((it) => it.statusIndex < 0 && it.hasCheckbox).map((it) => it.id),
+    // 状態を持たない見出し（報告など）。数えず、警告もしない
+    notes: items.filter((it) => it.statusIndex < 0 && !it.hasCheckbox).map((it) => it.id),
+  };
+}
+
+export function openItems(parsed) {
+  return parsed.items.filter((it) => it.statusIndex >= 0 && it.open).map(({ id, title, deadline }) => ({ id, title, deadline }));
+}
+
+// 期限切れの未処理を「取り下げ」に書き換える。返り値の lines は新しい配列（元は変えない）。items の open は更新する
+export function expireDeadlines(parsed, { now = new Date() } = {}) {
+  const lines = parsed.lines.slice();
+  const withdrawn = [];
+  for (const it of parsed.items) {
+    if (it.statusIndex < 0 || !it.open || !it.deadline) continue;
+    if (now.getTime() <= it.deadline.getTime()) continue;
+    const m = STATUS.exec(lines[it.statusIndex]);
+    const isEn = /^status$/i.test(it.statusKey);
+    const body = isEn
+      ? `withdrawn (deadline ${it.deadlineText} passed; automatic. Whether it was done is settled by the INBOX report)`
+      : `取り下げ（期限 ${it.deadlineText} を過ぎたため自動。実施の有無は INBOX の報告で確定する）`;
+    lines[it.statusIndex] = `${m[1]}[x]${m[3]}${m[4]}${m[5]}${body}`;
+    it.open = false;
+    it.statusText = body;
+    withdrawn.push(it.id);
+  }
+  return { lines, withdrawn };
+}
+
+// ヘッダ行「未処理: N件 / INBOX未読: M件 / 最終集計: …」があれば更新する。無ければそのまま
+export function updateHeader(text, { open, unread, now = new Date() }) {
+  if (text == null) return text;
+  const stamp = formatLocal(now);
+  if (HEADER_JA.test(text)) return text.replace(HEADER_JA, `未処理: ${open}件 / INBOX未読: ${unread}件 / 最終集計: ${stamp}`);
+  if (HEADER_EN.test(text)) return text.replace(HEADER_EN, `Open: ${open} / INBOX unread: ${unread} / Last count: ${stamp}`);
+  return text;
+}

package/lib/queue.mjs

@@ -0,0 +1,147 @@
+// 集計。PENDING の未処理と INBOX の未読を数え、番兵ファイルとヘッダ行を更新し、必要なら通知する。
+// フック（hook.mjs）と CLI（status）の両方がここを通る。
+import { join } from "node:path";
+import { readText, readTextLenient, writeTextAtomic, detectEol, isDirectory } from "./text.mjs";
+import { parsePending, openItems, expireDeadlines, updateHeader } from "./pending.mjs";
+import { unreadLines, signatureOf } from "./inbox.mjs";
+import { updateSentinel, findSentinel } from "./sentinel.mjs";
+import { notify } from "./notify.mjs";
+import { loadState, saveState, isQuietHour } from "./config.mjs";
+import { msg } from "./messages.mjs";
+
+// 権限・ロックの失敗は生の Node 文（EPERM: operation not permitted, rename '…' -> '…'）でなく人向けの 1 行にする
+export function humanError(e, lang = "ja") {
+  // rename の失敗は e.path が一時ファイル側（PENDING.md.1234.tmp）で e.dest が本当のファイル。dest を先に見る（設計監査 2 巡目 #7）
+  if (e && ["EACCES", "EPERM", "EROFS", "EBUSY"].includes(e.code)) return msg(lang).errWrite(e.dest ?? e.path ?? "");
+  return e?.message ?? String(e);
+}
+
+// lenient=true なら UTF-8 でない行を Shift_JIS として読み直す（INBOX。人がメモ帳の ANSI で追記することがある）
+function readOrNull(path, { lenient = false } = {}) {
+  try {
+    if (isDirectory(path)) return { text: null, error: "ディレクトリです / is a directory", garbled: 0 };
+    if (lenient) {
+      const r = readTextLenient(path);
+      return { text: r?.text ?? null, error: null, garbled: r?.garbled ?? 0 };
+    }
+    return { text: readText(path), error: null, garbled: 0 };
+  } catch (e) {
+    return { text: null, error: e.message, garbled: 0 };
+  }
+}
+
+// 読むだけ（expire=true なら期限切れの取り下げを lines に反映するが、ファイルには書かない）
+export function collect(root, config, { now = new Date(), expire = false } = {}) {
+  const pendingPath = join(root, config.pending);
+  const inboxPath = join(root, config.inbox);
+  const p = readOrNull(pendingPath);
+  const ib = readOrNull(inboxPath, { lenient: true });
+
+  const parsed = parsePending(p.text ?? "");
+  let withdrawn = [];
+  let pendingText = p.text;
+  let pendingChanged = false;
+  if (expire && p.text != null) {
+    const r = expireDeadlines(parsed, { now });
+    if (r.withdrawn.length) {
+      withdrawn = r.withdrawn;
+      pendingText = r.lines.join(detectEol(p.text));
+      pendingChanged = true;
+    }
+  }
+  const open = openItems(parsed);
+  const inboxLines = unreadLines(ib.text);
+
+  return {
+    root,
+    pendingPath,
+    inboxPath,
+    pendingExists: p.text != null,
+    inboxExists: ib.text != null,
+    pendingError: p.error,
+    inboxError: ib.error,
+    pendingText,
+    pendingChanged,
+    openCount: open.length,
+    openItems: open,
+    withdrawn,
+    malformed: parsed.malformed,
+    inboxUnread: inboxLines.length,
+    inboxLines,
+    inboxGarbled: ib.garbled ?? 0,
+    signature: signatureOf(inboxLines),
+  };
+}
+
+// 集計して副作用を行う。write=false なら何も書かない（status --dry 等）。
+//   expire   期限切れの自動取り下げを PENDING に書き戻す
+//   notify   通知を出す（静音時間帯なら持ち越し。同じ集合には繰り返さない）
+export async function summarize(root, config, { now = new Date(), expire = true, notify: doNotify = false, write = true } = {}) {
+  const c = collect(root, config, { now, expire: expire && write });
+  const result = { ...c, sentinel: null, sentinelError: null, notified: false, quiet: false, deferred: false, writeErrors: [] };
+
+  if (write) {
+    if (c.pendingChanged) {
+      try {
+        writeTextAtomic(c.pendingPath, c.pendingText);
+      } catch (e) {
+        result.writeErrors.push(`${config.pending}: ${humanError(e, config.lang)}`);
+      }
+    }
+    if (c.pendingExists) {
+      const cur = c.pendingChanged ? c.pendingText : readOrNull(c.pendingPath).text;
+      const upd = updateHeader(cur, { open: c.openCount, unread: c.inboxUnread, now });
+      if (upd != null && upd !== cur) {
+        try {
+          writeTextAtomic(c.pendingPath, upd);
+        } catch (e) {
+          result.writeErrors.push(`${config.pending}: ${humanError(e, config.lang)}`);
+        }
+      }
+    }
+    const s = updateSentinel(root, { items: c.openItems, config, now });
+    result.sentinel = s.path;
+    result.sentinelError = s.error;
+  } else {
+    // 読むだけ（status --dry-run）でも、今ある番兵は今あるものとして報告する
+    result.sentinel = findSentinel(root, config.sentinelPrefix);
+  }
+
+  // 通知。前回通知した集合と同じなら鳴らさない。静音時間帯は持ち越す
+  const state = loadState(root);
+  const signature = c.openItems.map((it) => it.id).sort().join(",");
+  const lastSig = typeof state.lastNotifiedSignature === "string" ? state.lastNotifiedSignature : "";
+  let deferred = state.deferred === true;
+  const quiet = isQuietHour(now, config.quietHours);
+  const isNew = signature !== "" && signature !== lastSig;
+  let notified = false;
+  // ASK_LATER_NO_NOTIFY=1 で OS 通知を止められる（テスト・CI・鳴らしたくない端末）
+  if (doNotify && config.notify && !process.env.ASK_LATER_NO_NOTIFY && (isNew || deferred) && c.openCount > 0) {
+    if (quiet) deferred = true;
+    else {
+      const m = msg(config.lang);
+      let body = c.openItems.map((it) => `${it.id} ${it.title}`).join(" / ");
+      if (body.length > 120) body = body.slice(0, 117) + "...";
+      const r = await notify({ title: m.notifyTitle(c.openCount), body });
+      notified = r.ok;
+      deferred = false;
+      result.notifyError = r.error ?? null;
+    }
+  }
+  if (write) {
+    if (notified || signature === "") state.lastNotifiedSignature = signature;
+    state.deferred = deferred;
+    state.openCount = c.openCount;
+    state.inboxUnread = c.inboxUnread;
+    state.updatedAt = now.toISOString();
+    try {
+      saveState(root, state);
+    } catch (e) {
+      result.writeErrors.push(`state.json: ${humanError(e, config.lang)}`);
+    }
+  }
+  result.notified = notified;
+  result.quiet = quiet;
+  result.deferred = deferred;
+  return result;
+}

package/lib/sentinel.mjs

@@ -0,0 +1,65 @@
+// 番兵ファイル。名前そのものが件数（"!pending_3.txt"）。
+// エクスプローラ／Finder でプロジェクトを開くだけで目に入る。音も光も出さないので夜間でも安全であり、
+// これが第一の通知手段である。0 件なら消す（ルートを汚さない）。
+import { readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { writeTextAtomic, formatLocal } from "./text.mjs";
+import { msg } from "./messages.mjs";
+
+export function sentinelName(n, prefix = "!pending_") {
+  return `${prefix}${n}.txt`;
+}
+
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function sentinelNames(root, prefix) {
+  const re = new RegExp(`^${escapeRe(prefix)}\\d+\\.txt$`);
+  try {
+    return readdirSync(root).filter((n) => re.test(n));
+  } catch {
+    return [];
+  }
+}
+
+// 今ある番兵のパス（無ければ null）。読むだけ
+export function findSentinel(root, prefix = "!pending_") {
+  const names = sentinelNames(root, prefix);
+  return names.length ? join(root, names[0]) : null;
+}
+
+// 自分が作った番兵だけを消す（<prefix><数字>.txt に一致するもの）
+export function removeSentinels(root, prefix = "!pending_") {
+  const removed = [];
+  for (const name of sentinelNames(root, prefix)) {
+    try {
+      rmSync(join(root, name), { force: true });
+      removed.push(name);
+    } catch {
+      /* 開かれている等。次回に持ち越す */
+    }
+  }
+  return removed;
+}
+
+// 返り値: 作った番兵のパス（0 件なら null）。失敗しても例外にしない（{ path: null, error }）
+export function updateSentinel(root, { items, config, now = new Date() }) {
+  const prefix = config.sentinelPrefix;
+  const removed = removeSentinels(root, prefix);
+  if (!items.length) return { path: null, removed, error: null };
+  const path = join(root, sentinelName(items.length, prefix));
+  const body = msg(config.lang).sentinel({
+    n: items.length,
+    items,
+    now: formatLocal(now, { seconds: true }),
+    pending: config.pending,
+    inbox: config.inbox,
+  });
+  try {
+    writeTextAtomic(path, body.join("\n") + "\n");
+    return { path, removed, error: null };
+  } catch (e) {
+    return { path: null, removed, error: e.message };
+  }
+}

package/lib/text.mjs

@@ -0,0 +1,151 @@
+// 小さな共通部品。ファイルは UTF-8（BOM を除いて読み、BOM 無しで書く）。
+// PowerShell 5.1 が BOM 無しを CP932 として読む罠（この道具の移植元の記録）を、Node 側では作らない。
+import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync, rmSync, statSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { dirname } from "node:path";
+
+// 無ければ null。読めない（ディレクトリ等）は例外（呼び出し側が「読めない」として扱う）
+export function readText(path) {
+  if (!existsSync(path)) return null;
+  let s = readFileSync(path, "utf8");
+  if (s.charCodeAt(0) === 0xfeff) s = s.slice(1);
+  return s;
+}
+
+// UTF-8 として読めない行（Notepad の ANSI＝CP932 で追記された行など）を行単位で Shift_JIS として読み直す。
+// 返り値 { text, garbled }。garbled は「UTF-8 でなかった行」の数（0 なら全行 UTF-8）。Shift_JIS でも読めなければ U+FFFD のまま残す。
+// ファイル全体を一括で再解釈しないのは、雛形（UTF-8）と追記（CP932）が混在したファイルで一括変換が失敗するため。
+export function readTextLenient(path) {
+  if (!existsSync(path)) return null;
+  let buf = readFileSync(path);
+  if (buf.length >= 3 && buf[0] === 0xef && buf[1] === 0xbb && buf[2] === 0xbf) buf = buf.subarray(3);
+  const strict = tryDecode(buf, "utf-8");
+  if (strict != null) return { text: strict, garbled: 0 };
+  const parts = [];
+  let garbled = 0;
+  let start = 0;
+  for (let i = 0; i <= buf.length; i++) {
+    if (i === buf.length || buf[i] === 0x0a) {
+      const line = buf.subarray(start, i);
+      let s = tryDecode(line, "utf-8");
+      if (s == null) {
+        garbled++;
+        s = tryDecode(line, "shift_jis") ?? line.toString("utf8");
+      }
+      parts.push(s);
+      start = i + 1;
+    }
+  }
+  return { text: parts.join("\n"), garbled };
+}
+
+function tryDecode(buf, encoding) {
+  try {
+    return new TextDecoder(encoding, { fatal: true }).decode(buf);
+  } catch {
+    return null;
+  }
+}
+
+// JSON を書き戻すときに元ファイルの体裁（字下げ幅・改行コード・末尾改行）を写す。元が無ければ 2 スペース・LF・末尾改行あり
+export function detectJsonFormat(raw) {
+  if (raw == null) return { indent: 2, eol: "\n", trailingNewline: true };
+  const m = /^\r?\n?([ \t]+)"/m.exec(raw) ?? /\n([ \t]+)\S/.exec(raw);
+  const indent = m ? (m[1].includes("\t") ? "\t" : m[1].length) : 2;
+  return { indent, eol: detectEol(raw), trailingNewline: /\r?\n$/.test(raw) };
+}
+
+export function formatJson(value, { indent = 2, eol = "\n", trailingNewline = true } = {}) {
+  let s = JSON.stringify(value, null, indent);
+  if (eol !== "\n") s = s.replace(/\n/g, eol);
+  return trailingNewline ? s + eol : s;
+}
+
+export function isDirectory(path) {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export function detectEol(text) {
+  return /\r\n/.test(text ?? "") ? "\r\n" : "\n";
+}
+
+export function splitLines(text) {
+  return String(text ?? "").split(/\r?\n/);
+}
+
+// 一時ファイルに書いてから置き換える（途中で切れても元のファイルが半端にならない）
+export function writeTextAtomic(path, text) {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, text, "utf8");
+  try {
+    renameSync(tmp, path);
+  } catch (e) {
+    rmSync(tmp, { force: true });
+    throw e;
+  }
+}
+
+export function sha256(text) {
+  return createHash("sha256").update(String(text), "utf8").digest("hex");
+}
+
+export const pad2 = (n) => String(n).padStart(2, "0");
+
+// ローカル時刻 "YYYY-MM-DD HH:MM"（人が読む用。ファイルに書く）
+export function formatLocal(d = new Date(), { seconds = false } = {}) {
+  const s = `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())} ${pad2(d.getHours())}:${pad2(d.getMinutes())}`;
+  return seconds ? `${s}:${pad2(d.getSeconds())}` : s;
+}
+
+// "2026-09-11" + "21:30" → ローカル時刻の Date。読めなければ null
+export function parseLocalDateTime(dateStr, timeStr = "23:59") {
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(dateStr ?? "");
+  const t = /^(\d{1,2}):(\d{2})$/.exec(timeStr ?? "");
+  if (!m || !t) return null;
+  const d = new Date(+m[1], +m[2] - 1, +m[3], +t[1], +t[2], 0, 0);
+  if (Number.isNaN(d.getTime())) return null;
+  // 2026-02-31 のような存在しない日付は Date が繰り上げるので、戻して比べる
+  if (d.getMonth() !== +m[2] - 1 || d.getDate() !== +m[3] || d.getHours() !== +t[1]) return null;
+  return d;
+}
+
+// 標準入力を最後まで読む。TTY（人が直接叩いた）なら読まない。timeoutMs で諦める（フックを固めない）
+export function readStream(stream, { timeoutMs = 3000 } = {}) {
+  return new Promise((resolve) => {
+    if (!stream || stream.isTTY) return resolve("");
+    let data = "";
+    let done = false;
+    const finish = () => {
+      if (done) return;
+      done = true;
+      try {
+        stream.pause();
+      } catch {
+        /* ignore */
+      }
+      resolve(data);
+    };
+    const timer = setTimeout(finish, timeoutMs);
+    if (typeof timer.unref === "function") timer.unref();
+    try {
+      stream.setEncoding("utf8");
+      stream.on("data", (c) => (data += c));
+      stream.on("end", () => {
+        clearTimeout(timer);
+        finish();
+      });
+      stream.on("error", () => {
+        clearTimeout(timer);
+        finish();
+      });
+    } catch {
+      clearTimeout(timer);
+      finish();
+    }
+  });
+}