pi-pier 0.1.2 → 0.1.4

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

@@ -98,6 +98,76 @@ export function formatSubagentResult(outcome: SubagentOutcome, description: stri
   }
 }
 
+/* ── 探活 + 存活通知（A2/B1 统一出口；纯逻辑，IO 在 adapter） ────── */
+
+/** 探活快照：pane 实时状态 + 会话活动时间（毫秒 epoch；null = 未知）。 */
+export interface AliveProbe {
+  paneExists: boolean;
+  agentStatus: string | null;
+  /** 会话文件 mtime（最新候选）；无文件/不可读 = null。 */
+  lastActivityMs: number | null;
+}
+
+/** 探活判活：pane 在 +（working/blocked 或近期有会话活动）→ 视为还在干活。 */
+export function isAlive(probe: AliveProbe, nowMs: number, staleAfterMs = 120_000): boolean {
+  if (!probe.paneExists) return false;
+  if (probe.agentStatus === 'working' || probe.agentStatus === 'blocked') return true;
+  // idle/unknown：会话 2 分钟内有活动仍算活（写作间隙/刚结算未采集）
+  return probe.lastActivityMs != null && nowMs - probe.lastActivityMs < staleAfterMs;
+}
+
+/** 人话相对时间（"12s ago" / "3m ago"）。 */
+export function agoText(ms: number, nowMs: number): string {
+  const s = Math.max(0, Math.round((nowMs - ms) / 1000));
+  if (s < 60) return `${s}s ago`;
+  if (s < 3600) return `${Math.floor(s / 60)}m ago`;
+  return `${Math.floor(s / 3600)}h ago`;
+}
+
+/**
+ * 存活通知（A2 转后台返回值 与 B1 tool_result 改写 的统一构造出口）：
+ * 两场景同一话术——"它在干活 / 别重做 / 转后台了 / 结算会通知 / list_agents 可查"。
+ * scenario: 'moved-to-bg'（耐心阈值转后台）| 'error-alive'（工具报错但探活判活，兜底改写）。
+ */
+export function buildAliveNotice(
+  opts: { paneId: string; description: string; scenario: 'moved-to-bg' | 'error-alive'; probe: AliveProbe },
+  nowMs: number,
+): string {
+  const { paneId, description, scenario, probe } = opts;
+  const status = probe.agentStatus ?? 'unknown';
+  const activity = probe.lastActivityMs != null ? `, last session activity ${agoText(probe.lastActivityMs, nowMs)}` : '';
+  if (scenario === 'moved-to-bg') {
+    return [
+      `Subagent "${description}" is still running in pane ${paneId} (agent_status=${status}${activity}).`,
+      'The foreground wait has moved it to background so this call returns now.',
+      'Do NOT redo its work. When it settles you will receive a notification with its closing output.',
+      'Use list_agents to check its live state; send_message to give it follow-up work.',
+    ].join(' ');
+  }
+  return [
+    `The subagent "${description}" is ALIVE in pane ${paneId} (agent_status=${status}${activity}) — this "no readable output" result only means its final answer could not be read yet, NOT that the task failed.`,
+    'Do NOT redo its work. It is being moved to background; you will be notified when it settles.',
+    'Use list_agents to check its live state.',
+  ].join(' ');
+}
+
+/**
+ * 人类闸门通知（E1/E2 统一出口）：subagent blocked（ask_user_question 等人类）时
+ * 给 master 的话术——不揽活、引导用户去 pane、授权例外经 send_message 转达。
+ * question 来自 herdr tokens['pi-ask']（子扩展 reportAskFlag 上报）。
+ */
+export function buildBlockedGateNotice(opts: { paneId: string; description: string; question: string | null }): string {
+  const { paneId, description, question } = opts;
+  const q = question ? ` (question: "${question}")` : '';
+  return [
+    `Subagent "${description}" is BLOCKED waiting for a HUMAN decision in pane ${paneId}${q}.`,
+    'It keeps running in background; once the human answers it resumes, and you will be notified when it settles.',
+    'Do NOT take over its work and do NOT answer on the human\'s behalf.',
+    'Tell the user to open that pane in herdr and answer directly.',
+    'Only if the user explicitly authorizes you: relay their decision to the subagent via send_message — do not redo the work yourself.',
+  ].join(' ');
+}
+
 /* ── 子代理注册表（custom 条目持久化） ────────────────────────────── */
 
 export const SUBS_CUSTOM_TYPE = 'pi-herdr.subs';
@@ -308,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

@@ -93,20 +93,31 @@ export function validateTodos(
     const item: TodoItem = { content, status: status as TodoStatus };
     if ('blocker' in entry) {
       const blocker = entry.blocker;
-      if (status !== 'blocked') {
-        return { ok: false, error: `invalid todo: \`blocker\` is only allowed when status is "blocked" (got "${status}")` };
-      }
-      if (typeof blocker !== 'string' || blocker.trim() === '') {
+      // 容忍归一（用户实证修复）：Optional 字段用空串/null 填充是常见模型行为
+      //（grok 实测 9 连拒死循环）；status 是权威——非 blocked 态的 blocker 一律视为
+      // 缺省丢弃（无论是否有值），空值同样丢弃。仅类型畸形仍硬拒。
+      if (blocker != null && typeof blocker !== 'string') {
         return { ok: false, error: 'invalid todo: `blocker` must be a non-empty string' };
       }
-      item.blocker = blocker;
+      if (status === 'blocked') {
+        if (typeof blocker !== 'string' || blocker.trim() === '') {
+          return { ok: false, error: 'invalid todo: `blocker` must be a non-empty string' };
+        }
+        item.blocker = blocker;
+      }
     }
     if ('phase' in entry) {
       const phase = entry.phase;
-      if (typeof phase !== 'string' || phase.trim() === '' || phase.length > PHASE_MAX_LEN) {
+      if (phase != null && typeof phase !== 'string') {
         return { ok: false, error: `invalid todo: \`phase\` must be a non-empty string ≤ ${PHASE_MAX_LEN} chars` };
       }
-      item.phase = phase;
+      // 空串/纯空白 = 缺省（实证循环里 phase:"" 同样是被掩盖的雷）；超长是真实约束仍硬拒
+      if (typeof phase === 'string') {
+        if (phase.length > PHASE_MAX_LEN) {
+          return { ok: false, error: `invalid todo: \`phase\` must be a non-empty string ≤ ${PHASE_MAX_LEN} chars` };
+        }
+        if (phase.trim() !== '') item.phase = phase;
+      }
     }
     if (status === 'in_progress') {
       inProgress++;
@@ -187,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;
@@ -259,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 {
@@ -298,7 +346,7 @@ export function fuzzyFind(items: readonly TodoItem[], query: string): string[] {
   return substr.map((it) => it.content);
 }
 
-/** D39：有界视图选择——先丢 completed、再截断尾部；返回可见条目与摘要。 */
+/** D39：有界视图选择——先丢 completed、再截 open；两端都超额时保最新（尾部切片）。 */
 export interface BoundedView {
   visible: TodoItem[];
   /** 被隐藏的数量按状态计数（completed 单独计，其余合并）。 */
@@ -312,15 +360,18 @@ export function boundedView(items: readonly TodoItem[], budget: number): Bounded
   }
   const completed = items.filter((it) => it.status === 'completed');
   const open = items.filter((it) => it.status !== 'completed');
-  let visible = open.slice(0, budget);
+  // 修正（用户实证）：widget 是头部可见窗口——超预算必须隐最老（丢头部），保最新可见；
+  // 旧实现 slice(0, budget) 保最老，最新任务永远落在窗口外。
+  const visible = open.length > budget ? open.slice(-budget) : open;
   const hiddenOpen = open.length - visible.length;
   let hiddenCompleted = completed.length;
+  let final = visible;
   if (hiddenOpen === 0 && visible.length < budget) {
     const room = budget - visible.length;
-    visible = [...visible, ...completed.slice(0, room)];
+    final = [...visible, ...completed.slice(-room)];
     hiddenCompleted = completed.length - room;
   }
-  return { visible, hiddenCompleted, hiddenOpen };
+  return { visible: final, hiddenCompleted, hiddenOpen };
 }
 
 /** 当前 in_progress 中的第一条（上报 agent 状态时作为 message，供侧边栏显示"正在做什么"）。 */