pi-pier 0.1.3 → 0.1.5

package/src/slim-frame.ts

@@ -0,0 +1,219 @@
+/**
+ * D97 窄格静帧（slim frame）：pane 长宽放不下最小可用 TUI 时，用非捕获
+ * 全屏 overlay 盖一张 pane title 同源静帧。
+ *
+ * 动机（用户实证）：热力把非焦点格压窄后，worker 的流式 thinking 在窄格
+ * 里持续整屏重绘 → 闪烁。静帧只在 todo_write / 状态上报时更新（与
+ * formatPaneTitle 同参同源），thinking token 碰不到它 → alt-screen 行级
+ * 差分下 PTY 零输出，闪烁物理消失。
+ *
+ * 前提：worker/master 以 --tui-mode fullscreen 运行（buildLaunchParts 默认
+ * 注入）。regular 主屏的整屏 dump 路径（tui-main-screen firstChanged <
+ * viewportTop → 全量重倒）overlay 盖不住——composite 在文档之上，dump 在
+ * 文档之内。
+ *
+ * 注册闸：仅 herdr pane 内（index.ts 以 env 判定）——普通小终端窗口里盖住
+ * 交互面是事故；herdr 窄格点击聚焦即被热力放大，visible 谓词随 SIGWINCH
+ * 每帧重估，静帧自动消失、真 TUI 原样在底下（agent/会话/widget 从未停）。
+ *
+ * 生命周期：进程内单例，session_start（非 resume）注册一次；overlay 常驻
+ * （done() 永不调用 → Promise 永挂，吞 rejection，绝不 await）。pi 会话
+ * 切换若拆掉 overlay（resetExtensionUI）则静帧自然退场，不影响主流程。
+ * PI_HERDR_SLIM_FRAME=0 逃生口。
+ */
+
+/** TUI 可用下限（pi interactive-mode 布局：editor 3 行 + footer 1 + transcript ≥3 + 间距）。
+ * 任一轴低于此值 → 该格读不了 TUI，画 title 静帧。 */
+export const SLIM_MIN_COLS = 24;
+export const SLIM_MIN_ROWS = 12;
+
+/** 静帧可见性谓词（overlayOptions.visible 每渲染帧回调）。 */
+export function isSlimFrame(cols: number, rows: number): boolean {
+  return cols < SLIM_MIN_COLS || rows < SLIM_MIN_ROWS;
+}
+
+/* ── 宽度感知折行（保守 East Asian 宽度；▶○■✓ 等歧义宽字符按 1 记，仅影响折点位置） ── */
+
+function isWide(cp: number): boolean {
+  return (
+    (cp >= 0x1100 && cp <= 0x115f) // 谚文兼容字母
+    || (cp >= 0x2e80 && cp <= 0xa4cf) // CJK 部首～彝文（含假名）
+    || (cp >= 0xac00 && cp <= 0xd7a3) // 谚文音节
+    || (cp >= 0xf900 && cp <= 0xfaff) // CJK 兼容表意
+    || (cp >= 0xfe30 && cp <= 0xfe4f) // CJK 兼容形式
+    || (cp >= 0xff00 && cp <= 0xff60) // 全角形式
+    || (cp >= 0xffe0 && cp <= 0xffe6)
+  );
+}
+
+export function displayWidth(s: string): number {
+  let w = 0;
+  for (const ch of s) w += isWide(ch.codePointAt(0) ?? 0) ? 2 : 1;
+  return w;
+}
+
+/**
+ * 按可见宽度折行：词折行（行内有空格则退到最后一个空格断，英文短语不腰斩；
+ * CJK 无空格自然硬折）。折行处吞掉断点空格。
+ */
+export function wrapByWidth(text: string, width: number): string[] {
+  const w = Math.max(1, Math.floor(width));
+  const lines: string[] = [];
+  let line = '';
+  let lineW = 0;
+  const push = () => {
+    lines.push(line);
+    line = '';
+    lineW = 0;
+  };
+  for (const ch of text) {
+    const cw = isWide(ch.codePointAt(0) ?? 0) ? 2 : 1;
+    if (lineW + cw > w) {
+      const lastSpace = line.lastIndexOf(' ');
+      if (lastSpace > 0) {
+        lines.push(line.slice(0, lastSpace));
+        line = line.slice(lastSpace + 1) + ch;
+        lineW = displayWidth(line);
+      } else {
+        push();
+        line = ch;
+        lineW = cw;
+      }
+    } else {
+      line += ch;
+      lineW += cw;
+    }
+  }
+  if (line !== '' || lines.length === 0) lines.push(line);
+  return lines;
+}
+
+/**
+ * 静帧行：title 折行 → 垂直居中 → 钳到 rows。每行都补齐到满宽（可见宽度）：
+ * overlay 的合成按行覆盖，空行会让底下的 TUI 透出来（漏 flicker），
+ * 满宽空格行才是真正的不透明冻结。无 title → 居中一枚 `·`（活着、没计划）。
+ */
+export function frameLines(
+  text: string,
+  opts: { width: number; rows: number; colorize?: (s: string) => string },
+): string[] {
+  const width = Math.max(1, Math.floor(opts.width));
+  const rows = Math.max(1, Math.floor(opts.rows));
+  const colorize = opts.colorize ?? ((s: string) => s);
+  const pad = (s: string) => s + ' '.repeat(Math.max(0, width - displayWidth(s)));
+
+  const body = text.trim()
+    ? wrapByWidth(text.trim(), width).slice(0, rows)
+    : ['·'];
+  const top = Math.max(0, Math.floor((rows - body.length) / 2));
+  const out: string[] = [];
+  for (let i = 0; i < rows; i++) {
+    const idx = i - top;
+    out.push(idx >= 0 && idx < body.length ? pad(colorize(body[idx])) : ' '.repeat(width));
+  }
+  return out;
+}
+
+/* ── overlay 组件 + 注册/更新（进程内单例） ─────────────────────────── */
+
+interface FrameTui {
+  requestRender(): void;
+}
+
+class SlimFrameComponent {
+  private text = '';
+  private lastRows = 0;
+  private cache: { width: number; lines: string[] } | null = null;
+  private readonly tui: FrameTui;
+  private readonly colorize: (s: string) => string;
+
+  constructor(tui: FrameTui, colorize: (s: string) => string) {
+    this.tui = tui;
+    this.colorize = colorize;
+  }
+
+  /** visible 谓词每帧回调：顺手记录行数（render(width) 拿不到高度，居中布局靠它）。 */
+  onViewport(cols: number, rows: number): boolean {
+    if (this.lastRows !== rows) {
+      this.lastRows = rows;
+      this.cache = null; // 行数变了 → 居中重排
+    }
+    return isSlimFrame(cols, rows);
+  }
+
+  setText(text: string): void {
+    if (this.text === text) return;
+    this.text = text;
+    this.cache = null;
+    this.tui.requestRender();
+  }
+
+  render(width: number): string[] {
+    if (this.cache && this.cache.width === width) return this.cache.lines;
+    const lines = frameLines(this.text, { width, rows: this.lastRows, colorize: this.colorize });
+    this.cache = { width, lines };
+    return lines;
+  }
+
+  invalidate(): void {
+    this.cache = null;
+  }
+
+  /** pi 拆 overlay（会话切换/退出）时回收模块单例，重注册不被 no-op。 */
+  dispose(): void {
+    if (active === this) active = null;
+  }
+}
+
+
+/** 测试注入点（module state 重置）。 */
+export function resetForTest(): void {
+  active = null;
+}
+
+let active: SlimFrameComponent | null = null;
+
+/**
+ * 注册静帧 overlay（幂等：进程一次）。eventCtx = pi 生命周期事件上下文
+ * （session_start 的 ctx，与 todo widget 的 widgetUi 同来源）。
+ */
+export function registerSlimFrame(eventCtx: unknown): void {
+  if (active) return;
+  if (process.env.PI_HERDR_SLIM_FRAME === '0') return;
+  const ui = eventCtx !== null && typeof eventCtx === 'object' && 'ui' in eventCtx
+    ? eventCtx.ui
+    : null;
+  const custom = ui !== null && typeof ui === 'object' && 'custom' in ui && typeof ui.custom === 'function'
+    ? ui.custom
+    : undefined;
+  try {
+    // overlay: true = 浮层不清屏（pi ctx.ui.custom 默认替换编辑器区，必须显式盖）；
+    // nonCapturing = 键盘仍归编辑器（人点进窄格也能打字，热力放大后静帧自动消失）。
+    const pending = custom(
+      (tui, theme) => {
+        const comp = new SlimFrameComponent(tui, (s) => theme.fg('accent', s));
+        active = comp;
+        return comp;
+      },
+      {
+        overlay: true,
+        overlayOptions: {
+          width: '100%',
+          maxHeight: '100%',
+          anchor: 'top-left',
+          nonCapturing: true,
+          visible: (cols: number, rows: number) => active !== null && active.onViewport(cols, rows),
+        },
+      },
+    );
+    // done() 永不调用 → Promise 永挂（overlay 常驻）；吞 rejection，绝不 await。
+    Promise.resolve(pending).catch(() => {});
+  } catch {
+    /* 无 overlay 能力的 pi 版本静默降级 */
+  }
+}
+
+/** 静帧内容更新（title 与 pane 标题投影同参同源；null = 无计划）。 */
+export function updateSlimFrame(title: string | null): void {
+  active?.setText(title ?? '');
+}

package/src/stale-core.ts

@@ -0,0 +1,76 @@
+/**
+ * todo 陈旧度纯核心（反冻结：会话 01a03253 实证）。
+ *
+ * 实证：全完成列表（3✓）冻结 16h / 37 轮，模型持续做新工作但 todo_write 零调用；
+ * 读钩每轮复读死列表反而背书"无事可跟踪"，标题满权重渲染死计数。
+ * 本模块把"列表是否还反映现实"收敛为纯函数，三层消费：
+ *  - stale（A）：open==0 且 ≥ STALE_TURNS 轮未写 → 读钩注入改 stale 警告（限频 + 封顶）；
+ *  - archived（B）：open==0 且墙钟 ≥ STALE_CLOCK_MS 未写 → 按不存在处理
+ *    （注入/投影不再复读明细；条目保留，/todos 可查；会话 JSONL 权威不动）；
+ *  - 标题（D）：archived 时窗格/侧栏渲染 `✓N done <age>`，不再冒充当前状态。
+ *
+ * 有 open 项（pending/in_progress/blocked）的列表永不判 stale——未完成工作
+ * 仍由 agent_settled 提醒兜底；lastWriteAt 未知（旧会话无时间戳）→ 时钟维度
+ * 保守不判 archived，turns 维度不受影响。
+ */
+import { countTodos, type TodoItem } from './vocab.ts';
+
+/** A：turns 维度过期阈值（用户轮次，自上次 todo 写入起算）。 */
+export const STALE_TURNS = 6;
+
+/** B：墙钟维度归档阈值（全完成列表最后一次写入距今）。 */
+export const STALE_CLOCK_MS = 60 * 60 * 1000;
+
+/** A：每次停滞期最多注入的 stale 警告数（防空转噪音；archived 后转归档通知节奏）。 */
+export const STALE_NOTICE_MAX = 3;
+
+export type StalenessKind = 'fresh' | 'stale' | 'archived';
+
+export interface Staleness {
+  kind: StalenessKind;
+  /** open = pending + in_progress + blocked（abandoned 不算未完成）。 */
+  open: number;
+  /** now - lastWriteAt；lastWriteAt 未知 → null。 */
+  ageMs: number | null;
+}
+
+/** open 计数：stale/archived 只对 open==0 的全完成（或全放弃）列表生效。 */
+export function openTodos(items: readonly TodoItem[]): number {
+  const c = countTodos(items as TodoItem[]);
+  return c.pending + c.inProgress + c.blocked;
+}
+
+/**
+ * 陈旧度判定（双条件：turns 维度 → stale；墙钟维度 → archived，时钟优先）。
+ * 空列表 → fresh（空守卫另有归属）；lastWriteAt null → 永不 stale（保守）。
+ */
+export function evaluateStaleness(opts: {
+  items: readonly TodoItem[];
+  lastWriteAt: number | null;
+  turnsSinceWrite: number | null;
+  now: number;
+}): Staleness {
+  const open = openTodos(opts.items);
+  const ageMs = opts.lastWriteAt == null ? null : Math.max(0, opts.now - opts.lastWriteAt);
+  const st: Staleness = { kind: 'fresh', open, ageMs };
+  if (opts.items.length === 0 || open > 0) return st;
+  if (ageMs != null && ageMs >= STALE_CLOCK_MS) st.kind = 'archived';
+  else if (opts.turnsSinceWrite != null && opts.turnsSinceWrite >= STALE_TURNS) st.kind = 'stale';
+  return st;
+}
+
+/** 标题/镜像路径专用（无 turn 信息）：仅墙钟维度的 archived 判定。 */
+export function isArchived(
+  items: readonly TodoItem[],
+  lastWriteAt: number | null,
+  now: number,
+): boolean {
+  return evaluateStaleness({ items, lastWriteAt, turnsSinceWrite: null, now }).kind === 'archived';
+}
+
+/** 年龄显示：<60m → `Nm`；<48h → `Nh`（floor）；否则 `Nd`。 */
+export function formatAge(ms: number): string {
+  if (ms < 60 * 60_000) return `${Math.max(1, Math.floor(ms / 60_000))}m`;
+  if (ms < 48 * 3_600_000) return `${Math.floor(ms / 3_600_000)}h`;
+  return `${Math.floor(ms / 86_400_000)}d`;
+}

package/src/subagent-core.ts

@@ -378,3 +378,33 @@ export function planTabPlacement(opts: {
   const tabName = nextTaskTabName(base, new Set(known.keys()));
   return { mode: 'new', tabName, tabId: null };
 }
+
+/* ── D97：worker 启动参数（纯逻辑，可单测） ───────────────────────── */
+
+/** launchLine 的运行时三要素（master 侧探测：node 解释器 / pi cli / 本扩展入口）。 */
+export interface LaunchRuntime {
+  nodePath: string;
+  cliPath: string;
+  extPath: string;
+}
+
+/**
+ * worker 启动裸 argv。`--tui-mode fullscreen`（D97 静帧前提）：
+ * alt-screen 行级差分——窄条静帧不变 → PTY 零输出，流式 thinking 不再整屏
+ * dump 闪烁；regular 主屏改动在视口上方即全量重倒（pi tui-main-screen
+ * firstChanged < viewportTop 路径），overlay 盖不住。
+ * `PI_HERDR_TUI=regular` 回退旧行为（逃生口）。
+ */
+export function buildLaunchParts(
+  runtime: LaunchRuntime,
+  opts: { resumeFile?: string | null; roleModel?: string | null; approve?: boolean } = {},
+  env: Pick<NodeJS.ProcessEnv, 'PI_HERDR_TUI'> = process.env,
+): string[] {
+  const parts = [runtime.nodePath, runtime.cliPath];
+  if (opts.approve) parts.push('-a');
+  parts.push('-e', runtime.extPath);
+  if (env.PI_HERDR_TUI !== 'regular') parts.push('--tui-mode', 'fullscreen');
+  if (opts.roleModel) parts.push('--provider', opts.roleModel.split('/')[0], '--model', opts.roleModel.split('/')[1] ?? opts.roleModel);
+  if (opts.resumeFile) parts.push('--session', opts.resumeFile);
+  return parts;
+}

package/src/todo-core.ts

@@ -198,6 +198,8 @@ export function makeSnapshot(items: TodoItem[]): TodoSnapshot {
 export interface BranchEntryLike {
   /** pi 会话条目：type 为 'message' 的消息条目或 'custom' 的自定义条目。 */
   type?: string;
+  /** 会话 JSONL 顶层时间戳（ISO 字符串或 epoch ms；重建 lastWriteAt 用）。 */
+  timestamp?: unknown;
   message?: {
     role?: string;
     toolName?: string;
@@ -270,21 +272,56 @@ function extractEditPayload(data: unknown): TodoEditPayload | null {
  *  - custom(pi-herdr.todo-edit) → 在当前列表上应用 edits（人类编辑）。
  * 分支正确性 = 沿分支路径顺序折叠。
  */
-export function foldLatestTodos(entries: readonly BranchEntryLike[]): TodoItem[] | null {
+export interface FoldedTodos {
+  items: TodoItem[];
+  /** 产生该列表的最后一个条目时间戳（epoch ms）；条目无时间戳 → null。 */
+  writtenAt: number | null;
+}
+
+function entryTimestamp(entry: BranchEntryLike): number | null {
+  const ts = entry.timestamp;
+  if (typeof ts === 'number') return ts;
+  if (typeof ts === 'string') {
+    const parsed = Date.parse(ts);
+    return Number.isNaN(parsed) ? null : parsed;
+  }
+  return null;
+}
+
+/**
+ * 从 pi 会话分支条目里折叠出最新 todo 列表（D38 双源）：
+ *  - toolResult(todo_write) → 快照替换（last-wins）；
+ *  - custom(pi-herdr.todo-edit) → 在当前列表上应用 edits（人类编辑）。
+ * 分支正确性 = 沿分支路径顺序折叠。writtenAt = 最后一次触碰该列表的条目时间戳
+ * （无时间戳的旧条目 → null，陈旧度判定保守判 fresh）。
+ */
+export function foldLatestTodosMeta(entries: readonly BranchEntryLike[]): FoldedTodos | null {
   let found: TodoItem[] | null = null;
+  let writtenAt: number | null = null;
   for (const entry of entries) {
     if (entry.type === 'message') {
       const msg = entry.message;
       if (typeof msg !== 'object' || msg === null) continue;
       if (msg.role !== 'toolResult' || msg.toolName !== TODO_TOOL_NAME) continue;
       const snapshot = extractSnapshotFromDetails(msg.details);
-      if (snapshot) found = snapshot.items.map((it) => ({ ...it }));
+      if (snapshot) {
+        found = snapshot.items.map((it) => ({ ...it }));
+        writtenAt = entryTimestamp(entry);
+      }
     } else if (entry.type === 'custom' && entry.customType === TODO_EDIT_CUSTOM_TYPE) {
       const payload = extractEditPayload(entry.data);
-      if (payload && found) found = applyTodoEdits(found, payload.edits);
+      if (payload && found) {
+        found = applyTodoEdits(found, payload.edits);
+        writtenAt = entryTimestamp(entry) ?? (payload.ts > 0 ? payload.ts : writtenAt);
+      }
     }
   }
-  return found;
+  return found ? { items: found, writtenAt } : null;
+}
+
+/** foldLatestTodosMeta 的条目-only 视图（兼容既有调用方）。 */
+export function foldLatestTodos(entries: readonly BranchEntryLike[]): TodoItem[] | null {
+  return foldLatestTodosMeta(entries)?.items ?? null;
 }
 
 export function extractSnapshotFromDetails(details: unknown): TodoSnapshot | null {

package/src/todo-read-hook.ts

@@ -1,14 +1,33 @@
 /**
  * D69：todo 阅读钩子规划（before_agent_start + display:false）。
+ * 反冻结（stale-core）：全完成列表过期后不再复读——
+ *  - stale（turns 维度）→ 警告 + 旧条目（供改写参照），每 N 轮一次、封顶；
+ *  - archived（墙钟维度）→ 按不存在处理，归档通知与空列表共用守卫节奏。
  */
 import { boundedView, currentActivity, type TodoItem } from './todo-core.ts';
 import { countTodos } from './vocab.ts';
+import { STALE_NOTICE_MAX, evaluateStaleness, formatAge } from './stale-core.ts';
 
+/** 空守卫 / stale 警告 / 归档通知共用的注入节奏（每 N 轮）。 */
 export const EMPTY_GUARD_EVERY_N = 4;
 export const TODO_READ_CUSTOM_TYPE = 'pi-herdr.todo-read';
 
+export type TodoReadEffect =
+  | 'recite' // 正常复读（列表新鲜）
+  | 'empty-guard' // 空列表守卫
+  | 'stale-notice' // A：turns 维度过期警告
+  | 'archive-notice' // B：墙钟维度归档通知
+  | 'none'; // 限频/封顶跳过
+
 export interface TodoReadPlan {
   inject: boolean;
+  effect: TodoReadEffect;
+  /** 当前归档态（与 inject 无关；调用方据此刷新 widget/title 投影）。 */
+  archived: boolean;
+  /** R1：归档通知本次注入即清空内存列表（调用方执行 todos.replace([]) + rm 全量
+   * 落 JSONL——死列表挡住空守卫的 before-stopping 驱动，01a03c0d 实证归档后
+   * 2h 多步工作零跟踪）。 */
+  clearArchived: boolean;
   message: {
     customType: string;
     content: string;
@@ -16,39 +35,122 @@ export interface TodoReadPlan {
   };
 }
 
+const MARKS: Record<TodoItem['status'], string> = {
+  pending: '○',
+  in_progress: '▶',
+  completed: '✓',
+  blocked: '■',
+  abandoned: '✗',
+};
+
 export function planTodoReadHook(opts: {
   items: readonly TodoItem[];
   turn: number;
   lastEmptyGuardTurn: number | null;
+  /** stale-core 时钟锚点（TodosService.lastWriteAt）。 */
+  lastWriteAt: number | null;
+  /** 距上次 todo 写入的轮数（本进程内已知时）。 */
+  turnsSinceWrite: number | null;
+  now: number;
+  /** 本停滞期已注入的 stale 警告数。 */
+  staleNotices: number;
+  lastStaleGuardTurn: number | null;
 }): TodoReadPlan {
-  const empty = opts.items.length === 0;
-  if (empty) {
-    const due = opts.lastEmptyGuardTurn == null
-      || opts.turn - opts.lastEmptyGuardTurn >= EMPTY_GUARD_EVERY_N;
+  const msg = (content: string) => ({
+    customType: TODO_READ_CUSTOM_TYPE,
+    content,
+    display: false as const,
+  });
+  const guardDue = opts.lastEmptyGuardTurn == null
+    || opts.turn - opts.lastEmptyGuardTurn >= EMPTY_GUARD_EVERY_N;
+
+  if (opts.items.length === 0) {
+    return {
+      inject: guardDue,
+      effect: 'empty-guard',
+      clearArchived: false,
+      archived: false,
+      message: msg(
+        guardDue
+          ? 'Your todo list is empty. If the current work needs tracking, call todo_write before stopping.'
+          : '',
+      ),
+    };
+  }
+
+  const st = evaluateStaleness({
+    items: opts.items,
+    lastWriteAt: opts.lastWriteAt,
+    turnsSinceWrite: opts.turnsSinceWrite,
+    now: opts.now,
+  });
+
+  if (st.kind === 'archived') {
+    const c = countTodos(opts.items as TodoItem[]);
+    const age = st.ageMs == null ? '' : ` ${formatAge(st.ageMs)} ago`;
+    // R2：重写窗口——本停滞期还没给过任何 stale 警告时，先给一次带旧条目参照的
+    // 重写机会（idle 期不消耗 turn，墙钟先到 1h 而 turns 警告从未触发，
+    // 01a03c0d 实证：回来后直接吃终态通知，todo_write 5 次被无视）。
+    if (opts.staleNotices === 0 && guardDue) {
+      const lines = opts.items.map((it) => `  ${MARKS[it.status]} ${it.content}`);
+      const head = `todos ✓${c.completed} (all completed, last updated${age}) — about to be archived`;
+      const warn = 'One rewrite window before archiving: if the work you are doing now is multi-step, rewrite the full list with todo_write to track it (old entries below as reference — reuse what still applies). Single-step Q&A may skip tracking. If the list stays untouched, it will be archived and cleared on the next reminder.';
+      return {
+        inject: true,
+        effect: 'stale-notice',
+        archived: true,
+        clearArchived: false,
+        message: msg([head, ...lines, warn].join('\n')),
+      };
+    }
+    // B + R1/R3：终态通知——明细不再注入，本次注入即清空；去掉 [] 豁免出口，
+    // 多步工作必须建清单（单步问答明确放行）。
+    return {
+      inject: guardDue,
+      effect: 'archive-notice',
+      archived: true,
+      clearArchived: guardDue,
+      message: msg(
+        guardDue
+          ? `Your previous todo list (${c.completed} completed entries, last updated${age}) has been archived and cleared from tracking; the list is now empty. If the current work is multi-step, call todo_write with a fresh list now — multi-step work must be tracked. Single-step answers may proceed without a list.`
+          : '',
+      ),
+    };
+  }
+
+  if (st.kind === 'stale') {
+    // A：复读改警告；保留旧条目行供模型改写参照。封顶 STALE_NOTICE_MAX。
+    const staleDue = opts.lastStaleGuardTurn == null
+      || opts.turn - opts.lastStaleGuardTurn >= EMPTY_GUARD_EVERY_N;
+    if (!staleDue || opts.staleNotices >= STALE_NOTICE_MAX) {
+      return { inject: false, effect: 'none', archived: false, clearArchived: false, message: msg('') };
+    }
+    const c = countTodos(opts.items as TodoItem[]);
+    const head = `todos ▶${c.inProgress} ○${c.pending} ■${c.blocked} ✓${c.completed}`
+      + ` · unchanged for ${opts.turnsSinceWrite} turns, nothing open`;
+    const lines = opts.items.map((it) => `  ${MARKS[it.status]} ${it.content}`);
+    const warn = 'This list no longer reflects the work you are doing. Rewrite the full list with todo_write to match current work, or send [] to clear it.';
     return {
-      inject: due,
-      message: {
-        customType: TODO_READ_CUSTOM_TYPE,
-        content: 'Your todo list is empty. If the current work needs tracking, call todo_write before stopping.',
-        display: false,
-      },
+      inject: true,
+      effect: 'stale-notice',
+      clearArchived: false,
+      archived: false,
+      message: msg([head, ...lines, warn].join('\n')),
     };
   }
+
+  // fresh：原有每轮复读。
   const c = countTodos(opts.items);
   const view = boundedView(opts.items, 6);
-  const lines = view.visible.map((it) => {
-    const mark = it.status === 'in_progress' ? '▶' : it.status === 'blocked' ? '■' : it.status === 'completed' ? '✓' : '○';
-    return `${mark} ${it.content}`;
-  });
-  const activity = currentActivity(opts.items as TodoItem[]);
+  const lines = view.visible.map((it) => `${MARKS[it.status]} ${it.content}`);
+  const activity = currentActivity(opts.items);
   const head = `todos ▶${c.inProgress} ○${c.pending} ■${c.blocked} ✓${c.completed}`
     + (activity ? ` · ${activity}` : '');
   return {
     inject: true,
-    message: {
-      customType: TODO_READ_CUSTOM_TYPE,
-      content: [head, ...lines].join('\n'),
-      display: false,
-    },
+    effect: 'recite',
+    clearArchived: false,
+    archived: false,
+    message: msg([head, ...lines].join('\n')),
   };
 }

package/src/todos-service.ts

@@ -6,7 +6,7 @@
 import { EventEmitter } from 'node:events';
 import {
   applyTodoEdits,
-  foldLatestTodos,
+  foldLatestTodosMeta,
   type TodoEdit,
   type TodoItem,
 } from './todo-core.ts';
@@ -20,6 +20,11 @@ export interface TodosConfig {
 
 export class TodosService extends EventEmitter {
   items: TodoItem[] = [];
+  /**
+   * 列表最后一次真实变更时间（epoch ms）；分支重建取自条目时间戳，无则 null。
+   * 陈旧度判定（stale-core）的时钟锚点；null → 保守永不判 stale。
+   */
+  lastWriteAt: number | null = null;
   readonly config: TodosConfig;
 
   constructor(config: TodosConfig) {
@@ -38,6 +43,7 @@ export class TodosService extends EventEmitter {
   replace(items: readonly TodoItem[]): void {
     const before = this.items;
     this.items = items.map((it) => ({ ...it }));
+    this.lastWriteAt = Date.now();
     this.emitCompletedTransitions(before, this.items);
     this.emit('todo.updated', { items: this.items });
   }
@@ -45,6 +51,7 @@ export class TodosService extends EventEmitter {
   applyEdits(edits: readonly TodoEdit[]): void {
     const before = this.items;
     this.items = applyTodoEdits(this.items, edits);
+    this.lastWriteAt = Date.now();
     this.emitCompletedTransitions(before, this.items);
     this.emit('todo.edited', { edits, items: this.items });
     this.emit('todo.updated', { items: this.items });
@@ -59,8 +66,11 @@ export class TodosService extends EventEmitter {
   rebuild(entries: readonly unknown[]): void {
     // 与 v1.x rebuildFromBranch 同语义：分支上折叠不到快照时保留现值
     //（重建失败不影响主流程；下次 todo_write 会重新锚定）。
-    const folded = foldLatestTodos(entries as Parameters<typeof foldLatestTodos>[0]);
-    if (folded) this.items = folded;
+    const folded = foldLatestTodosMeta(entries as Parameters<typeof foldLatestTodosMeta>[0]);
+    if (folded) {
+      this.items = folded.items;
+      this.lastWriteAt = folded.writtenAt;
+    }
     this.emit('todo.updated', { items: this.items, reason: 'rebuild' });
   }
 }