feat: push/pop 上下文栈跨会话持久化 + --list 预览取用户指令 + pop进度条

- 栈随 transcript 持久化（last-wins push-stack entry），--resume 后仍能 /pop
- resume 时 projectPushStackOntoMessages 重新投影，失效标记透明丢弃并通知
- /push --list 预览改取用户最近指令，避免显示空/合成占位消息（No response requested.）
- 更新 push-pop-context-stack.md：跨会话持久化由非目标转为目标，同步预览语义
- /pop 时显示进度条以及前后上下文token数变化

Co-Authored-By: claude-opus-4-8[1m] <noreply@anthropic.com>

Author: universe-hcy

README.md

@@ -21,6 +21,7 @@
 | **🎯 Goal 持续驱动**        | `/goal <objective>` 设定目标后，自动跨轮驱动 agent 直至完成；带 token budget、completion/blocked audit、`pause`/`resume`/`continue`/`clear` 子命令，网络中断自动暂停 | 源码 [`commands/goal/`](./src/commands/goal/) · [`services/goal/`](./src/services/goal/)                                                  |
 | **📦 Artifacts（HTML 上传）** | 复刻 Anthropic 官方 Artifacts：模型把 HTML/数据看板/报告上传到公开 URL（7d/30d 自动过期），`/artifacts` 命令集中管理，Cloudflare Worker + R2 完全开源、可自托管 | [8 小时复刻报告](./docs/blog/2026-06-20-cloud-artifacts-8h-recap.md) · [在线 demo](https://cloud-artifacts.claude-code-best.win/30d/c2jfwi3E-y3fTZ1ors-KE.html) |
 | **🧠 Ultracode 多 Agent 编排** | `/ultracode` 注入 workflow 编排手册 + `Workflow` 工具跑确定性 JS 脚本（`agent`/`pipeline`/`parallel`/`phase`）+ `/workflows` 双栏监控面板；支持 journal 重放、token budget、并发 cap | [文档](https://ccb.agent-aura.top/docs/features/workflow-scripts)                                                                         |
+| **🌿 Push/Pop 上下文栈**    | `/push` 开一个继承完整上下文的讨论旁支，`/pop` 把讨论蒸馏成结构化 digest 回卷主线——讨论噪音不污染主线、只留结论；支持嵌套、`--to #N` 跨层弹出、`--list` 零成本列栈、栈感知 auto-compact 三选（`FEATURE_PUSH_POP=1`） | [设计文档](./docs/features/push-pop-context-stack.md) · 源码 [`commands/push/`](./src/commands/push/) · [`commands/pop/`](./src/commands/pop/) |
 | **Claude 群控技术**         | Pipe IPC 多实例协作：同机 main/sub 自动编排 + LAN 跨机器零配置发现与通讯，`/pipes` 选择面板 + `Shift+↓` 交互 + 消息广播路由 | [Pipe IPC](https://ccb.agent-aura.top/docs/features/uds-inbox) / [LAN](https://ccb.agent-aura.top/docs/features/lan-pipes)                |
 | **ACP 协议一等一支持**      | 支持接入 Zed、Cursor 等 IDE，支持会话恢复、Skills、权限桥接                                                                  | [文档](https://ccb.agent-aura.top/docs/features/acp-zed)                                                                                  |
 | **Remote Control 私有部署** | Docker 自托管远程界面, 可以手机上看 CC                                                                                       | [文档](https://ccb.agent-aura.top/docs/features/remote-control-self-hosting)                                                              |

docs/features/push-pop-context-stack.md

@@ -126,6 +126,79 @@ describe('push stack state', () => {
   })
 })
 
+describe('projectPushStackOntoMessages', () => {
+  const uuid = (n: number) =>
+    `00000000-0000-0000-0000-${String(n).padStart(12, '0')}` as `${string}-${string}-${string}-${string}-${string}`
+  const marker = (id: string, n: number) => ({
+    id,
+    messageUuid: uuid(n),
+    note: id,
+    timestamp: 0,
+    anchorPreview: '',
+  })
+  const userMsg = (n: number) =>
+    ({
+      type: 'user',
+      uuid: uuid(n),
+    }) as unknown as import('../../types/message.js').Message
+  const boundary = (n: number) =>
+    ({
+      type: 'system',
+      subtype: 'compact_boundary',
+      uuid: uuid(n),
+    }) as unknown as import('../../types/message.js').Message
+
+  test('keeps markers whose anchor is still in the active view', async () => {
+    const { projectPushStackOntoMessages } = await import(
+      '../../services/pushStack/state.js'
+    )
+    const { validMarkers, droppedCount } = projectPushStackOntoMessages(
+      [marker('a', 1), marker('b', 2)],
+      [userMsg(1), userMsg(2)],
+    )
+    expect(validMarkers.map(m => m.id)).toEqual(['a', 'b'])
+    expect(droppedCount).toBe(0)
+  })
+
+  test('drops markers carried off before a compact boundary and counts them', async () => {
+    const { projectPushStackOntoMessages } = await import(
+      '../../services/pushStack/state.js'
+    )
+    // Boundary at index 1 → active view is [boundary, msg#3]; the pre-boundary
+    // anchor #1 is gone, mirroring what /pop would reject.
+    const { validMarkers, droppedCount } = projectPushStackOntoMessages(
+      [marker('old', 1), marker('live', 3)],
+      [userMsg(1), boundary(9), userMsg(3)],
+    )
+    expect(validMarkers.map(m => m.id)).toEqual(['live'])
+    expect(droppedCount).toBe(1)
+  })
+
+  test('empty stack returns empty with zero dropped', async () => {
+    const { projectPushStackOntoMessages } = await import(
+      '../../services/pushStack/state.js'
+    )
+    const { validMarkers, droppedCount } = projectPushStackOntoMessages(
+      [],
+      [userMsg(1)],
+    )
+    expect(validMarkers).toEqual([])
+    expect(droppedCount).toBe(0)
+  })
+
+  test('all markers invalid returns droppedCount = N', async () => {
+    const { projectPushStackOntoMessages } = await import(
+      '../../services/pushStack/state.js'
+    )
+    const { validMarkers, droppedCount } = projectPushStackOntoMessages(
+      [marker('a', 1), marker('b', 2)],
+      [userMsg(5)],
+    )
+    expect(validMarkers).toEqual([])
+    expect(droppedCount).toBe(2)
+  })
+})
+
 describe('DIGEST_PROMPT and DIGEST_TEMPLATE', () => {
   test('DIGEST_PROMPT contains required four-section structure', async () => {
     const { DIGEST_PROMPT } = await import(

src/commands/__tests__/pushpop.test.ts

@@ -18,8 +18,8 @@ function renderStackList(stack: readonly PushMarker[]): string {
       style: 'short',
       now,
     })
-    // branchPreview (what the branch is about) wins over anchorPreview
-    // (where it forked from); both are truncated original conversation text.
+    // branchPreview (first message inside the branch) wins over anchorPreview
+    // (the user's instruction at push time); both are truncated conversation text.
     const preview = m.branchPreview || m.anchorPreview || ''
     const note = m.note ? ` · ${m.note}` : ''
     const previewPart = preview ? ` · ${preview}` : ''

src/commands/push/push.ts

@@ -290,6 +290,7 @@ import {
   type CompactStrategyChoice,
   MAX_PUSH_DEPTH,
   setPushStackMirror,
+  projectPushStackOntoMessages,
 } from '../services/pushStack/state.js';
 import { DIGEST_PROMPT, DIGEST_TEMPLATE } from '../services/pushStack/digestPrompt.js';
 import { CompactStrategyDialog } from '../components/pushStack/CompactStrategyDialog.js';
@@ -317,6 +318,7 @@ import {
   isEphemeralToolProgress,
   isLoggableMessage,
   saveWorktreeState,
+  savePushStack,
   getAgentTranscript,
 } from '../utils/sessionStorage.js';
 import { deserializeMessages } from '../utils/conversationRecovery.js';
@@ -1770,6 +1772,10 @@ export function REPL({
   // streaming text_delta. The spinner reads this via its animation timer.
   const responseLengthRef = useRef(0);
   const compactProgressActiveRef = useRef(false);
+  // Pop-specific spinner label (e.g. "Distilling discussion branch #1"). Set by
+  // applyPop before its fire-and-forget digest so the compact_start handler can
+  // show a pop-aware verb instead of the generic "Compacting conversation".
+  const popSpinnerLabelRef = useRef<string | null>(null);
   // API performance metrics ref for ant-only spinner display (TTFT/OTPS).
   // Accumulates metrics from all API requests in a turn for P50 aggregation.
   const apiMetricsRef = useRef<
@@ -1825,6 +1831,11 @@ export function REPL({
 
   const [lastQueryCompletionTime, setLastQueryCompletionTime] = useState(0);
   const [spinnerMessage, setSpinnerMessage] = useState<string | null>(null);
+  // State mirror of compactProgressActiveRef — needed so showSpinner (a
+  // render-time derived value) turns the spinner on during a background compact
+  // that runs outside the query loop (e.g. /pop's fire-and-forget digest, where
+  // isLoading is already false). The ref alone can't trigger a re-render.
+  const [compactProgressActive, setCompactProgressActive] = useState(false);
   const [spinnerColor, setSpinnerColor] = useState<keyof Theme | null>(null);
   const [spinnerShimmerColor, setSpinnerShimmerColor] = useState<keyof Theme | null>(null);
   const [isMessageSelectorVisible, setIsMessageSelectorVisible] = useState(false);
@@ -2061,6 +2072,8 @@ export function REPL({
     (isLoading ||
       userInputOnProcessing ||
       hasRunningTeammates ||
+      // Background compaction running outside the query loop (e.g. /pop digest).
+      compactProgressActive ||
       // Keep spinner visible while task notifications are queued for processing.
       // Without this, the spinner briefly disappears between consecutive notifications
       // (e.g., multiple background agents completing in rapid succession) because
@@ -2344,6 +2357,28 @@ export function REPL({
         // Use a callback to ensure we're not dependent on stale state
         setMessages(() => messages);
 
+        // Hydrate the push/pop stack, re-projecting each marker onto the just-
+        // restored messages: a marker only survives if its anchor is still in
+        // the active context (not carried off by compaction/snip), the same
+        // check /pop performs — so a restored stack can never point at a message
+        // that no longer exists. Dropped markers are surfaced so a persisted
+        // stack is never silently lost. The setAppState below re-triggers the
+        // mirror effect, re-persisting the projected (pruned) stack last-wins.
+        // Skipped for /branch (fork) like worktreeSession: forkLog doesn't carry
+        // the stack.
+        if (feature('PUSH_POP') && entrypoint !== 'fork' && log.pushStack?.length) {
+          const { validMarkers, droppedCount } = projectPushStackOntoMessages(log.pushStack, messages);
+          setAppState(prev => ({ ...prev, pushStack: validMarkers }));
+          if (droppedCount > 0) {
+            addNotification({
+              key: 'push-stack-resume-dropped',
+              text: `${droppedCount} 个 push 点在恢复后已失效（被压缩/snip 卷走），已移除`,
+              priority: 'medium',
+              timeoutMs: 6000,
+            });
+          }
+        }
+
         // Clear any active tool JSX
         setToolJSX(null);
 
@@ -2363,7 +2398,7 @@ export function REPL({
         throw error;
       }
     },
-    [resetLoadingState, setAppState],
+    [resetLoadingState, setAppState, addNotification],
   );
 
   // Lazy init: useRef(createX()) would call createX on every render and
@@ -2918,9 +2953,17 @@ export function REPL({
   );
 
   // Keep the module-level mirror in sync so autoCompactIfNeeded (outside React)
-  // can read the current push stack without needing AppState access.
+  // can read the current push stack without needing AppState access. This is
+  // also the single point that fans in every stack mutation (push/pop/retain),
+  // so it doubles as the persistence trigger: once the stack has been non-empty,
+  // each change (including popping back to empty) is written last-wins so the
+  // transcript always reflects the live stack. The dirty ref keeps sessions that
+  // never push from writing an empty entry.
+  const pushStackDirty = useRef(false);
   useEffect(() => {
     setPushStackMirror(pushStack);
+    if (pushStack.length > 0) pushStackDirty.current = true;
+    if (pushStackDirty.current) savePushStack(pushStack);
   }, [pushStack]);
 
   // Ref holding the stable push/pop callbacks so getToolUseContext can forward-
@@ -3071,14 +3114,24 @@ export function REPL({
               );
               break;
             case 'compact_start':
-              setSpinnerMessage('Compacting conversation');
+              setSpinnerMessage(popSpinnerLabelRef.current ?? 'Compacting conversation');
               compactProgressActiveRef.current = true;
+              setCompactProgressActive(true);
+              // /pop runs its digest outside the query loop, so the normal
+              // loading timer never started — seed it here (when idle) so the
+              // spinner's elapsed-time counter starts from 0 rather than a
+              // stale value from a previous turn.
+              if (!isLoading) {
+                loadingStartTimeRef.current = Date.now();
+                totalPausedMsRef.current = 0;
+              }
               break;
             case 'compact_end':
               setSpinnerMessage(null);
               setSpinnerColor(null);
               setSpinnerShimmerColor(null);
               compactProgressActiveRef.current = false;
+              setCompactProgressActive(false);
               break;
           }
         },
@@ -3247,13 +3300,17 @@ export function REPL({
         ]);
         return;
       }
-      const lastContent =
-        (last as { content?: unknown; message?: { content?: unknown } }).content ??
-        (last as { content?: unknown; message?: { content?: unknown } }).message?.content ??
-        '';
-      const anchorText =
-        getContentText(lastContent as string | import('@anthropic-ai/sdk/resources/index.mjs').ContentBlockParam[]) ??
+      // Preview the user's most recent instruction (what this branch is about)
+      // rather than the raw last message — which is often a tool-only assistant
+      // turn (empty text) or a synthetic "No response requested." placeholder,
+      // neither of which is meaningful in `/push --list` (§4.7).
+      const instruction = msgs.findLast(selectableUserMessagesFilter);
+      const previewSource = instruction ?? last;
+      const previewContent =
+        (previewSource as { content?: unknown; message?: { content?: unknown } }).content ??
+        (previewSource as { content?: unknown; message?: { content?: unknown } }).message?.content ??
         '';
+      const anchorText = getContentText(previewContent as string | ContentBlockParam[]) ?? '';
       const anchorPreview = anchorText.slice(0, 75).trimEnd();
       const marker: PushMarker = {
         id: randomUUID(),
@@ -3354,8 +3411,13 @@ export function REPL({
         // the last main-line message that must stay in the kept prefix (§3
         // off-by-one). The fast-path above guarantees pivotIndex is in range.
         const firstDiscussionUuid = compactMessages[pivotIndex]!.uuid;
+        let compactResult: import('../services/compact/compact.js').CompactionResult | undefined;
+        // Pop-aware spinner label — the compact_start handler reads this so the
+        // digest shows "Distilling discussion branch #N" (with live token count
+        // + elapsed time) instead of the generic "Compacting conversation".
+        popSpinnerLabelRef.current = `\u2442 Distilling discussion branch #${targetIdx + 1}`;
         try {
-          await applyPartialCompactByUuid({
+          compactResult = await applyPartialCompactByUuid({
             pivotUuid: firstDiscussionUuid,
             feedback: DIGEST_TEMPLATE,
             direction: 'from',
@@ -3371,6 +3433,8 @@ export function REPL({
             ),
           ]);
           return;
+        } finally {
+          popSpinnerLabelRef.current = null;
         }
 
         // Pop the stack: plain pop removes top; --to #N removes #N and above.
@@ -3391,9 +3455,17 @@ export function REPL({
         }
 
         const historyShortcut = getShortcutDisplay('app:toggleTranscript', 'Global', 'ctrl+o');
+        // Before → after context size (0 extra API tokens: pre is already
+        // computed during compaction, post is a local message-payload estimate).
+        const pre = compactResult?.preCompactTokenCount;
+        const post = compactResult?.truePostCompactTokenCount;
+        const tokenLine =
+          pre !== undefined && post !== undefined
+            ? ` · Context: ~${formatTokens(pre)} \u2192 ~${formatTokens(post)} tokens`
+            : '';
         addNotification({
           key: `pop-digest-${marker.id}`,
-          text: `\u2442 Discussion branch #${targetIdx + 1} distilled (${historyShortcut} for history)`,
+          text: `\u2442 Discussion branch #${targetIdx + 1} distilled (${historyShortcut} for history)${tokenLine}`,
           priority: 'medium',
           timeoutMs: 8000,
         });

src/screens/REPL.tsx

@@ -1135,6 +1135,16 @@ export async function partialCompactConversation(
       direction === 'up_to'
         ? (summaryMessages.at(-1)?.uuid ?? boundaryMarker.uuid)
         : boundaryMarker.uuid
+    // Message-payload estimate of the resulting context (local, 0 extra API
+    // tokens) — mirrors the full-compact path (see truePostCompactTokenCount
+    // above). Order-independent, so keep/summary interleaving doesn't matter.
+    const truePostCompactTokenCount = roughTokenCountEstimationForMessages([
+      boundaryMarker,
+      ...messagesToKeep,
+      ...summaryMessages,
+      ...postCompactFileAttachments,
+      ...hookMessages,
+    ] as Parameters<typeof roughTokenCountEstimationForMessages>[0])
     return {
       boundaryMarker: annotateBoundaryWithPreservedSegment(
         boundaryMarker,
@@ -1148,6 +1158,7 @@ export async function partialCompactConversation(
       userDisplayMessage: postCompactHookResult.userDisplayMessage,
       preCompactTokenCount,
       postCompactTokenCount,
+      truePostCompactTokenCount,
       compactionUsage,
     }
   } catch (error) {

src/services/compact/compact.ts

@@ -1,4 +1,6 @@
 import type { UUID } from 'crypto'
+import type { Message } from '../../types/message.js'
+import { getMessagesAfterCompactBoundary } from '../../utils/messages.js'
 
 /**
  * Push/Pop context stack (docs/features/push-pop-context-stack.md).
@@ -15,7 +17,7 @@ export type PushMarker = {
   note: string
   /** Epoch ms at push time (for relative-time display in `/push --list`). */
   timestamp: number
-  /** Snapshot of the last message text at push time (where the branch forked from). */
+  /** Preview of the user's most recent instruction at push time (what the branch is about). */
   anchorPreview: string
   /** First user message after push (what the branch is about); backfilled lazily. */
   branchPreview?: string
@@ -65,3 +67,25 @@ export function getPushStackMirror(): readonly PushMarker[] {
 export function setPushStackMirror(stack: readonly PushMarker[]): void {
   pushStackMirror = [...stack]
 }
+
+/**
+ * Projects a persisted push stack back onto the live message sequence at resume
+ * time. A marker only survives if its anchor message (`messageUuid`) is still in
+ * the active context — i.e. not carried off by compaction or history-snip. This
+ * mirrors the validation `/pop` performs (REPL) so a restored marker can never
+ * point at a message that no longer exists. Dropped markers are counted so the
+ * caller can transparently notify the user (never silently lose a stack marker).
+ */
+export function projectPushStackOntoMessages(
+  persisted: readonly PushMarker[],
+  messages: Message[],
+): { validMarkers: PushMarker[]; droppedCount: number } {
+  const activeUuids = new Set(
+    getMessagesAfterCompactBoundary(messages).map(m => m.uuid),
+  )
+  const validMarkers = persisted.filter(m => activeUuids.has(m.messageUuid))
+  return {
+    validMarkers,
+    droppedCount: persisted.length - validMarkers.length,
+  }
+}