cc-viewer 1.9.18 → 1.9.19

package/server/lib/v2/live-feed.js

@@ -74,6 +74,12 @@ export function readNewLines(cursor, chunkBytes = READ_CHUNK_BYTES, maxLineBytes
   } catch {
     return []; // not created yet
   }
+  // Suppressed-seed cap: while seeding history, read only up to the byte size
+  // the feed last observed (cursor._limit). Bytes past it are read live on the
+  // follow-up pass. The cap compares BEFORE the shrink check so a file that
+  // grew past the cap reads exactly to it (offset === capped size ⇒ no-op);
+  // the partial-line carry already tolerates a cap landing mid-line.
+  if (cursor._limit != null) size = Math.min(size, cursor._limit);
   if (size < cursor.offset) return null;
   if (size === cursor.offset) return [];
   if (cursor._pendBufs === undefined) {
@@ -194,6 +200,15 @@ export class V2LiveFeed {
     this._clientFilter = typeof opts.clientFilter === 'function' ? opts.clientFilter : null;
     this._sessions = new Map(); // dir → cursor bundle
     this._seenDirs = new Map(); // dir → last observed journal mtimeMs (attached or not)
+    // dir → { journal, responses, conv: Map<path,size> } — per-file byte sizes
+    // captured at the feed's last observation of the dir (initial scan, attach,
+    // eviction, safety scan). A suppressed re-attach seeds only UP TO these
+    // offsets and reads everything past them live: bytes appended after the
+    // last observation (a resumed history session's new turn) are genuinely
+    // new, not history the cold-load channel owns. Without this the suppressed
+    // seed swallowed them (offset advanced past, never re-read → the new
+    // message only reappeared on a cold reload).
+    this._seenSizes = new Map();
     this._discardGated = new Set(); // dirs refused by the discard gate — first real attach must NOT suppress history
     this._sessionsRoot = null;
     this._rootWatcher = null;
@@ -245,6 +260,7 @@ export class V2LiveFeed {
     for (const cur of this._sessions.values()) this._closeCursor(cur);
     this._sessions.clear();
     this._seenDirs.clear();
+    this._seenSizes.clear();
     this._discardGated.clear();
     this._sessionsRoot = null;
   }
@@ -263,7 +279,10 @@ export class V2LiveFeed {
       // must be seeded suppressed, or the re-attach replays the whole session
       // through the broadcast path (the exact OOM this module was fixed for).
       // Only a genuinely never-seen dir emits from byte 0.
-      cur = this._attach(sessionDir, { suppressExisting: this._seenDirs.has(sessionDir) });
+      cur = this._attach(sessionDir, {
+        suppressExisting: this._seenDirs.has(sessionDir),
+        suppressUpTo: this._seenSizes.get(sessionDir) || null,
+      });
       if (!cur) {
         if (_retries < TICK_RETRY_MAX) {
           setTimeout(() => this.tick(sessionDir, _retries + 1), TICK_RETRY_MS);
@@ -319,11 +338,15 @@ export class V2LiveFeed {
       const dir = join(this._sessionsRoot, name);
       const mtime = this._journalMtime(dir);
       this._seenDirs.set(dir, mtime);
+      // Record the byte watermark NOW (before any attach) so a later suppressed
+      // re-attach of this pre-existing dir seeds only up to here and reads any
+      // post-observation append live.
+      this._seenSizes.set(dir, this._snapshotSizes(dir));
       // Pre-existing dirs with recent activity are live producers that predate
       // this feed (mid-run server start / workspace switch): follow them but
       // suppress their history — the cold reload channel covers it.
       if (mtime > 0 && this._now() - mtime <= ATTACH_RECENT_MS) {
-        this._attach(dir, { suppressExisting: true });
+        this._attach(dir, { suppressExisting: true, suppressUpTo: this._seenSizes.get(dir) });
       }
     }
   }
@@ -346,6 +369,8 @@ export class V2LiveFeed {
     if (mtime === 0) return; // no journal yet — the next event/tick retries
     const seenBefore = this._seenDirs.has(dir);
     this._seenDirs.set(dir, mtime);
+    const suppressUpTo = this._seenSizes.get(dir) || this._snapshotSizes(dir);
+    this._seenSizes.set(dir, suppressUpTo);
     if (!seenBefore) {
       // Genuinely new session dir: everything in it is new — emit from byte 0
       // when it was born after the feed started, otherwise treat as history.
@@ -358,7 +383,7 @@ export class V2LiveFeed {
           return !(bt > 0) || bt >= this._startedAt - 1000;
         } catch { return true; }
       })();
-      this._attach(dir, { suppressExisting: !bornAfterStart });
+      this._attach(dir, { suppressExisting: !bornAfterStart, suppressUpTo });
     }
   }
 
@@ -366,9 +391,33 @@ export class V2LiveFeed {
     try { return statSync(join(dir, 'journal.jsonl')).mtimeMs; } catch { return 0; }
   }
 
+  /** Snapshot the current byte size of every file a cursor reads (journal,
+   *  responses, and every conv epoch file) — the watermark a later suppressed
+   *  re-attach seeds up to. A missing file (ENOENT) sizes 0 (all of it is new);
+   *  any OTHER stat error sizes MAX_SAFE_INTEGER so a transient failure
+   *  (Windows AV/EBUSY/EPERM) never zeroes the watermark and re-arms a
+   *  full-history replay on the next attach (same error direction as
+   *  _seekCursorsToEof). */
+  _snapshotSizes(dir) {
+    const sizeOf = (p) => {
+      try { return statSync(p).size; } catch (err) {
+        if (err && err.code === 'ENOENT') return 0;
+        reportSwallowed('v2-live.snapshot-stat', err);
+        return Number.MAX_SAFE_INTEGER;
+      }
+    };
+    const conv = new Map();
+    for (const { path } of this._enumerateConvFiles(dir)) conv.set(path, sizeOf(path));
+    return {
+      journal: sizeOf(join(dir, 'journal.jsonl')),
+      responses: sizeOf(join(dir, 'responses.jsonl')),
+      conv,
+    };
+  }
+
   // ── per-session cursors ────────────────────────────────────────────────────
 
-  _attach(dir, { suppressExisting }) {
+  _attach(dir, { suppressExisting, suppressUpTo = null }) {
     if (this._sessions.has(dir)) return this._sessions.get(dir);
     if (!existsSync(join(dir, 'journal.jsonl'))) return null;
     // Multi-window isolation: a dir exclusively claimed by ANOTHER live ccv
@@ -470,7 +519,39 @@ export class V2LiveFeed {
       } catch (err) {
         reportSwallowed('v2-live.session-watch', err);
       }
-      this._readCursor(cur); // seed (suppressed history or brand-new content)
+      // Seed read. When suppressing with a known watermark, cap each cursor at
+      // the last-observed size so the seed swallows ONLY bytes that predate the
+      // feed's last look; anything past it was appended after and is genuinely
+      // new (a resumed history session's fresh turn), not cold-load history.
+      const cappedSeed = cur.suppress && suppressUpTo;
+      if (cappedSeed) {
+        cur.journal._limit = suppressUpTo.journal;
+        cur.responses._limit = suppressUpTo.responses;
+        for (const { path } of this._enumerateConvFiles(dir)) {
+          const fc = { key: null, path, offset: 0 };
+          // A conv file in the watermark caps at its observed size. A conv file
+          // NOT in the watermark did not exist at the last look (a new conv key
+          // or a post-/clear epoch minted by the resumed turn), so its content
+          // is entirely new — cap at 0 so the suppressed seed reads NONE of it
+          // and the follow-up (suppress=false) reads + forwards it live. Leaving
+          // it uncapped here would let the suppressed seed consume it silently:
+          // the follow-up would then find the offset at EOF and the wire-v3
+          // client would assemble the new turn with empty messages.
+          fc._limit = (suppressUpTo.conv && suppressUpTo.conv.has(path)) ? suppressUpTo.conv.get(path) : 0;
+          cur.convFiles.set(path, fc);
+        }
+      }
+      try {
+        this._readCursor(cur); // seed (suppressed history or brand-new content)
+      } finally {
+        // Always drop the caps: a leaked _limit clamps every later read to
+        // size===offset, permanently freezing the cursor.
+        if (cappedSeed) {
+          delete cur.journal._limit;
+          delete cur.responses._limit;
+          for (const fc of cur.convFiles.values()) delete fc._limit;
+        }
+      }
     } else {
       // No per-dir watcher either: a promote can bring hundreds of dead dirs
       // at once and each fs.watch costs an fd. The safety poll's unconditional
@@ -479,6 +560,15 @@ export class V2LiveFeed {
       this._seekCursorsToEof(cur);
     }
     cur.suppress = false;
+    // Follow-up live read: bytes appended after the watermark but before the
+    // per-dir watcher was armed (a resumed history session whose first new turn
+    // raced this attach) sit past the capped offsets with no watcher event to
+    // deliver them — read them now so the new turn broadcasts instead of
+    // waiting for the next append / safety poll (and never arriving if the
+    // conversation goes quiet). No-op when nothing new is on disk.
+    if (!convertOrigin && suppressUpTo) this._readCursor(cur);
+    // Refresh the watermark to the post-attach state for any later re-attach.
+    this._seenSizes.set(dir, this._snapshotSizes(dir));
     return cur;
   }
 
@@ -788,6 +878,7 @@ export class V2LiveFeed {
       // ownership release (owner exits) plus new activity re-attaches through
       // the normal mtime-bump path below.
       if (this._isForeignLiveOwned(cur.dir)) {
+        this._seenSizes.set(cur.dir, this._snapshotSizes(cur.dir)); // watermark before detach
         this._closeCursor(cur);
         this._sessions.delete(cur.dir);
         this._seenDirs.set(cur.dir, this._journalMtime(cur.dir));
@@ -799,6 +890,7 @@ export class V2LiveFeed {
       if (this._idleEvictMs > 0 && cur.openReqs.size === 0) {
         const mtime = this._journalMtime(cur.dir);
         if (mtime > 0 && this._now() - mtime > this._idleEvictMs) {
+          this._seenSizes.set(cur.dir, this._snapshotSizes(cur.dir)); // watermark before eviction
           this._closeCursor(cur);
           this._sessions.delete(cur.dir);
           this._seenDirs.set(cur.dir, mtime);
@@ -826,9 +918,18 @@ export class V2LiveFeed {
         this._maybeAttachNew(dir);
       } else if (mtime > seen) {
         // A dir skipped at the initial scan (stale then) has resumed activity:
-        // follow it now, history suppressed (it predates this feed).
+        // follow it now. Seed suppressed ONLY up to the last-observed byte
+        // watermark (captured at scan/eviction — the mtime bump proves new
+        // bytes landed past it); the resumed turn itself is read live, not
+        // swallowed with the history it predates this feed alongside. A missing
+        // watermark means the feed never observed this dir's pre-activity state,
+        // so there is no safe boundary — fall back to suppress-to-EOF (null)
+        // rather than snapshotting NOW (which would cap ABOVE the new bytes and
+        // re-introduce the swallow).
+        const suppressUpTo = this._seenSizes.get(dir) || null;
         this._seenDirs.set(dir, mtime);
-        this._attach(dir, { suppressExisting: true });
+        if (suppressUpTo) this._seenSizes.set(dir, suppressUpTo);
+        this._attach(dir, { suppressExisting: true, suppressUpTo });
       }
     }
   }

package/server/lib/v2/meta-rows.js

@@ -193,7 +193,9 @@ const _coldBundleFlight = new SingleFlight({ ttlMs: 500 });
 
 /**
  * The complete v3 cold read for one /events connection: windowed rows +
- * native conv/responses payloads, single-flighted per (dir, window).
+ * native conv/responses payloads, single-flighted per (dir, window). The
+ * returned `native.convSeqs` is the conv coverage the /events attach buffer
+ * uses to avoid double-replaying conv lines (see attach-buffer.js).
  */
 export function readV2ColdBundle(sessionDir, { limit = 0, since = null } = {}) {
   const key = `bundle:${sessionDir}|${limit}|${since || ''}`;
@@ -217,8 +219,12 @@ export function readV2ColdBundle(sessionDir, { limit = 0, since = null } = {}) {
  *
  * @param {string} sessionDir - leader dir (teammate dirs folded like the rows)
  * @param {object[]} rows - the window rows (readV2RequestsMeta output)
- * @returns {Promise<{convPayloads: string[], respPayloads: string[]}>}
- *   pre-serialized JSON payloads for `v3_conv` / `v3_resp` SSE frames
+ * @returns {Promise<{convPayloads: string[], respPayloads: string[],
+ *   convSeqs: Map<string, {seqs: Set<number>, baseSeq: number}>}>}
+ *   pre-serialized JSON payloads for `v3_conv` / `v3_resp` SSE frames, plus the
+ *   conv-line coverage keyed `${sessionId}\x00${channel}` — used by the /events
+ *   attach buffer to skip replaying a v3_conv frame the cold bundle already
+ *   carried (client conv replay is NOT idempotent; see attach-buffer.js).
  */
 export async function readV2NativeCold(sessionDir, rows) {
   const yieldLoop = () => new Promise((resolve) => setImmediate(resolve));
@@ -238,6 +244,7 @@ export async function readV2NativeCold(sessionDir, rows) {
 
   const convPayloads = [];
   const respPayloads = [];
+  const convSeqs = new Map();
   for (const dir of dirs) {
     const dirMeta = readMeta(dir);
     const sessionId = (dirMeta && dirMeta.sessionId) || basename(dir);
@@ -270,6 +277,30 @@ export async function readV2NativeCold(sessionDir, rows) {
         if (i % 2000 === 1999) await yieldLoop();
       }
       const windowRaws = raws.slice(start);
+      // Record every conv line the cold bundle is about to send so the /events
+      // attach buffer can skip replaying it. baseSeq = the smallest seq in the
+      // window (the snapshot baseline is the first in seq order) — a replayed seq
+      // below it was already reflected in the cold assembly and must not be
+      // re-consumed either. Only lines that PARSE are recorded: a torn trailing
+      // line (writer mid-append, no newline yet) is NOT in coverage — its seq is
+      // re-sent complete by the live feed once the newline lands, and the replay
+      // must not skip it (a skipped snapshot would corrupt the client's assembler).
+      {
+        const covKey = `${sessionId}\x00${key}`;
+        let cov = convSeqs.get(covKey);
+        if (!cov) { cov = { seqs: new Set(), baseSeq: Infinity }; convSeqs.set(covKey, cov); }
+        for (const raw of windowRaws) {
+          let seq = null;
+          try {
+            const ev = JSON.parse(raw);
+            if (Number.isInteger(ev && ev.seq)) seq = ev.seq;
+          } catch { /* torn line: not covered — the live re-send must not be skipped */ }
+          if (seq === null) continue;
+          cov.seqs.add(seq);
+          if (seq < cov.baseSeq) cov.baseSeq = seq;
+        }
+        if (cov.baseSeq === Infinity) cov.baseSeq = 0;
+      }
       // Cap each frame at ~512KB of lines: a multi-MB single SSE event forces
       // one giant synchronous JSON.parse on the client's main thread (no
       // paint, no rAF — the loading UI freezes). Small frames are macrotask
@@ -287,7 +318,7 @@ export async function readV2NativeCold(sessionDir, rows) {
     await yieldLoop();
     pushChunked(respPayloads, respRaws, (linesJson) => `{"sessionId":${JSON.stringify(sessionId)},"lines":[${linesJson}]}`);
   }
-  return { convPayloads, respPayloads };
+  return { convPayloads, respPayloads, convSeqs };
 }
 
 const NATIVE_FRAME_BUDGET = 512 * 1024;

package/server/routes/events.js

@@ -10,6 +10,7 @@ import { sseHead, sseWrite, needsDrain, wireEnd, awaitWireDrain, isWireV3Enabled
 import { scopeKeyForProducer } from '../lib/scope-router.js';
 import { readV2ColdBundle } from '../lib/v2/meta-rows.js';
 import { readV2SingleEntry } from '../lib/v2/adapter.js';
+import { createAttachBufferClient, flushAttachBuffer } from '../lib/attach-buffer.js';
 import { resolveSessionDirName, latestMainSessionDir } from '../lib/v2/session-select.js';
 import { sanitizePathComponent, normalizeSessionCwd } from '../lib/v2/layout.js';
 import { listLivePtys } from '../pty-manager.js';
@@ -213,12 +214,29 @@ export async function serveEventStream(sink, params, deps) {
   const registrable = sink.registrable;
   let closed = false;
   let pingTimer = null;
+  // Attach buffer (2026-10): a stand-in client registered in deps.clients during
+  // the cold load so live v2 deltas landing in the cold-load→push gap are queued
+  // (not broadcast to the not-yet-registered real client, and lost). Replayed
+  // through the real sink after load_end, then swapped for the registrable.
+  // Declared BEFORE dispose: sink.onClose may fire dispose synchronously on
+  // registration, so the variable must be initialized before that hook exists.
+  let attachBufferClient = null;
+  // Conv coverage of the v3 cold bundle (`native.convSeqs`), used to skip
+  // replaying a v3_conv frame the bundle already carried. Stays null on the
+  // legacy wire or when the cold read fails → flush fails open (replays all).
+  let coldConvCoverage = null;
   const dispose = () => {
     if (closed) return;
     closed = true;
     if (pingTimer) { clearInterval(pingTimer); pingTimer = null; }
     const idx = deps.clients.indexOf(registrable);
     if (idx !== -1) deps.clients.splice(idx, 1);
+    if (attachBufferClient) {
+      const bi = deps.clients.indexOf(attachBufferClient);
+      if (bi !== -1) deps.clients.splice(bi, 1);
+      try { attachBufferClient.end(); } catch (err) { reportSwallowed('sse.attach-buffer.dispose', err); }
+      attachBufferClient = null;
+    }
   };
   // Register the close hook at the ENTRY (not after the history stream): a client that
   // disconnects mid-cold-load must still clear the pingTimer and never be pushed — the
@@ -240,6 +258,13 @@ export async function serveEventStream(sink, params, deps) {
   // 否则 streamRawEntriesAsync 的 setImmediate yield 间隙会让 watcher 的
   // sendToClients 向该客户端推送 live entry，而 load_end 的 setState 会覆盖这些
   // 已处理的 live entry，导致 对话条目"显示→消失→重现"闪烁。
+  //
+  // Attach buffer (2026-10): the client registered into deps.clients during the
+  // cold load is NOT the real res — it is a buffer proxy that never writes the
+  // socket. It carries the same view stamps as the registrable, queueing the live
+  // deltas owed to this connection while the cold load runs. The real res still
+  // receives its first data only after load_end (the anti-flicker invariant is
+  // unchanged); the queued frames are replayed at the flush below.
 
   // SSE 心跳保活：每 30s 发送 ping 事件，防止连接被 OS/代理/浏览器静默断开
   pingTimer = setInterval(() => {
@@ -319,6 +344,26 @@ export async function serveEventStream(sink, params, deps) {
   // else the bound project. Stamped onto the sink registrable so per-project feeds can
   // route live entries to exactly the clients viewing that project.
   const viewedProject = projectParam || (_projectName || '');
+  // Attach buffer: register the stand-in client NOW, in the synchronous segment
+  // before the first await (readV2ColdBundle / streamRawEntriesAsync). From here
+  // until the flush-and-swap at registration, any live v2 delta routed to this
+  // view scope is queued on the proxy instead of being lost to the gap. The
+  // proxy carries the same project/instance stamps the registrable will get
+  // below, so filterClientsByViewProject/Instance deliver it exactly this
+  // connection's frames — no cross-project / cross-instance bleed.
+  if (!closed) {
+    attachBufferClient = createAttachBufferClient({
+      project: viewedProject || undefined,
+      instance: instanceParam || undefined,
+      maxBytes: deps.attachBufferMaxBytes,
+      // Overflow = the cold-load window's increments are dropped, i.e. the original
+      // lost-render bug resurfaces for THIS connection. reportSwallowed is gated behind
+      // CCV_DEBUG, so it is invisible in production — log unconditionally, or the most
+      // likely residual failure of this fix would be undiagnosable.
+      onOverflow: (bytes) => console.warn(`[events] attach buffer overflowed at ${bytes} bytes; this connection may miss live updates until reconnect`),
+    });
+    deps.clients.push(attachBufferClient);
+  }
   const resolveColdSource = () => {
     if (sidParam) {
       const project = projectParam || _projectName;
@@ -525,6 +570,10 @@ export async function serveEventStream(sink, params, deps) {
         limit: useLimit ? effectiveLimit : 0,
         since: useIncremental ? sinceParam : null,
       });
+      // Conv coverage for the attach buffer flush: replayed v3_conv frames whose
+      // seq the cold bundle already carried are skipped (client conv replay is
+      // not idempotent). On a read error this stays null → flush fails open.
+      coldConvCoverage = (native && native.convSeqs) || null;
       // Build every payload BEFORE load_start so it can carry the exact byte
       // total — the client renders a real received/total progress (the legacy
       // wire's per-entry count-up has no per-frame granularity here).
@@ -637,7 +686,21 @@ export async function serveEventStream(sink, params, deps) {
   if (instanceParam) registrable._ccvViewInstance = instanceParam;
   // Push-guard: a client whose close fired mid-cold-load (dispose already ran via the
   // entry-registered onClose hook) must NOT be re-added to the broadcast list.
-  if (!closed) deps.clients.push(registrable);
+  //
+  // Attach buffer flush + swap: replay every live delta queued during the cold
+  // load (in emission order, conv-covered frames skipped), then swap the proxy
+  // for the real registrable. This whole block is synchronous — no broadcast can
+  // interleave between the replay and the swap, so nothing is double-sent or
+  // lost. After this point the connection receives live frames directly.
+  if (!closed) {
+    flushAttachBuffer(sink, attachBufferClient, coldConvCoverage);
+    if (attachBufferClient) {
+      const bi = deps.clients.indexOf(attachBufferClient);
+      if (bi !== -1) deps.clients.splice(bi, 1);
+    }
+    deps.clients.push(registrable);
+  }
+  attachBufferClient = null;
 
   // 任务清单快照补推：内存态不在冷加载数据里，页面刷新/重连后横条要等下一次
   // 任务事件才恢复 —— 连接建立即推一份当前快照（空列表也推，清掉客户端残留）。

package/server/server.js

@@ -3005,7 +3005,9 @@ async function setupTerminalWebSocket(httpServer) {
                 { project: (typeof msg.project === 'string' && msg.project) || null, instance: (typeof msg.instanceKey === 'string' && msg.instanceKey) || null },
                 _projectName || '',
               );
-              _setTurnActive(false, null, qScope);
+              // Web Stop = user interrupt: the loop ends NOW (no Stop hook fires on
+              // interrupt), so emit the immediate agent_loop_end alongside the clear.
+              _setTurnActive(false, null, qScope, 'interrupted');
             }
           } else if (msg.type === 'image-remove-notify' || msg.type === 'image-upload-notify') {
             // Security: only allow paths within upload directories, reject traversal
@@ -3163,6 +3165,7 @@ let _lastSdkActive = false;
 // Per-scope CLI streaming edge state ('' = bound — the legacy single flag).
 const _lastCliActiveByScope = new Map();
 let _onTurnEndBroadcastForTests = null;
+let _onAgentLoopBroadcastForTests = null;
 
 function _normalizeKey(sessionId) {
   return (typeof sessionId === 'string' && sessionId) ? sessionId : null;
@@ -3230,6 +3233,14 @@ function _emitTurnEnd(sessionId, ts, transcriptPath = null, scope = null) {
   const sid = _normalizeKey(sessionId);
   const t = ts || Date.now();
   const sc = scope || { project: '', instance: null };
+  // PTY loop end rides the debounced boundary (the Stop hook is query()-level, so an
+  // immediate frame would ring mid-loop on user-role injections). SDK mode already
+  // emitted its authoritative per-result end — emitting here too would double-fire.
+  // Emitted BEFORE turn_end so the client can suppress the legacy voice when the new
+  // agentLoopEnd cue actually played (same boundary ts on both frames).
+  if (!isSdkMode) {
+    _emitAgentLoopBoundary('end', { sessionId: sid, ts: t, scope: sc, mode: 'pty', reason: 'stop-hook', transcriptPath });
+  }
   try {
     if (clients.length > 0 && sendEventToClients) {
       const target = sc.project
@@ -3253,6 +3264,61 @@ function _emitTurnEnd(sessionId, ts, transcriptPath = null, scope = null) {
   }
 }
 
+// ── Agent-loop boundary frames (agent_loop_start / agent_loop_end) ─────────────
+// Authoritative per-turn loop lifecycle, uniform across modes:
+//   SDK: emitted by sdk-manager at push-accept (start) and the turn's real result /
+//        settlement (end) — immediate, per-turn correlated (turnId + turnStartedAt),
+//        bypassing the turn_end debounce entirely (task-notification pseudo results
+//        are filtered upstream and never reach here).
+//   PTY: start on the UserPromptSubmit rising edge in _setTurnActive; end from
+//        _emitTurnEnd (post-debounce, 'stop-hook') or the web Stop clear
+//        ('interrupted'). PTY's end stays debounced on purpose — see the
+//        SUNSET-MARKER block above.
+// Every emission also fires the matching plugin parallel hook (onAgentLoopStart /
+// onAgentLoopEnd) so plugins observe the same lifecycle as SSE clients.
+function _emitAgentLoopBoundary(phase, { sessionId = null, ts = Date.now(), scope = null, mode, turnId = null, turnStartedAt = null, reason = null, transcriptPath = null } = {}) {
+  if (_isStopping) return;
+  const sc = scope || { project: '', instance: null };
+  const payload = {
+    sessionId: _normalizeKey(sessionId), ts,
+    project: sc.project || (_projectName || ''), instance: sc.instance || null,
+    mode,
+    turnId: turnId || null, turnStartedAt: turnStartedAt || null,
+    ...(reason ? { reason } : {}),
+    ...(transcriptPath ? { transcriptPath } : {}),
+  };
+  if (clients.length > 0 && sendEventToClients) {
+    try {
+      const target = sc.project
+        ? filterClientsByScope(clients, sc.project, sc.instance, _projectName || '')
+        : _filterClientsByViewProject(clients, _projectName || '');
+      sendEventToClients(target, phase === 'start' ? 'agent_loop_start' : 'agent_loop_end', payload);
+    } catch (err) { reportSwallowed('agent-loop.broadcast', err); }
+  }
+  // Fire-and-forget: a plugin failure must never affect the SSE/turn pipeline.
+  runParallelHook(phase === 'start' ? 'onAgentLoopStart' : 'onAgentLoopEnd', payload).catch(() => {});
+  if (typeof _onAgentLoopBroadcastForTests === 'function') {
+    try { _onAgentLoopBroadcastForTests({ phase, payload }); }
+    catch (e) { if (process.env.NODE_ENV === 'test') throw e; /* never let a test stub pollute prod */ }
+  }
+}
+
+// SDK-mode entries (cli.js wires sdk-manager's per-turn callbacks here). The cwd
+// routes the frame to that workspace's scope, mirroring broadcastTurnEnd; instanceKey
+// narrows same-basename twins.
+export function broadcastAgentLoopStart(p = {}) {
+  const scope = p.cwd
+    ? normalizeProducerScope({ project: projectKeyForCwd(p.cwd) || '', instance: p.instanceKey || null }, _projectName || '')
+    : null;
+  _emitAgentLoopBoundary('start', { ...p, scope, mode: 'sdk' });
+}
+export function broadcastAgentLoopEnd(p = {}) {
+  const scope = p.cwd
+    ? normalizeProducerScope({ project: projectKeyForCwd(p.cwd) || '', instance: p.instanceKey || null }, _projectName || '')
+    : null;
+  _emitAgentLoopBoundary('end', { ...p, scope, mode: 'sdk' });
+}
+
 function _scheduleTurnEndBroadcast(sessionId, ts, transcriptPath = null, scope = null) {
   if (_isStopping) return;
   const sid = _normalizeKey(sessionId);
@@ -3435,7 +3501,10 @@ function _broadcastTurnActive(active, sessionId, scope = null) {
 // turn-end entry points and would otherwise emit duplicate frames). The heartbeat
 // is armed/disarmed here so it tracks the flag exactly. Scope defaults to bound
 // ('') — the legacy single-workspace behavior is byte-identical.
-function _setTurnActive(active, sessionId, scope = null) {
+// `source` distinguishes clear paths: only 'interrupted' (web Stop / queue-suppress)
+// emits an immediate agent_loop_end — the ordinary Stop-hook clear defers to the
+// debounced end in _emitTurnEnd so user-role injection loops don't ring mid-loop.
+function _setTurnActive(active, sessionId, scope = null, source = 'hook') {
   const sc = scope || { project: '', instance: null };
   const key = scopeKeyOf(sc.project, sc.instance);
   const bucket = turnStateFor(key);
@@ -3446,6 +3515,11 @@ function _setTurnActive(active, sessionId, scope = null) {
   if (next) _turnSessionIdByScope.set(key, sessionId || null);
   if (activeTurnScopes().length > 0) _armTurnActiveHeartbeat(); else _clearTurnActiveHeartbeat();
   _broadcastTurnActive(next, sessionId, sc);
+  if (next) {
+    _emitAgentLoopBoundary('start', { sessionId, ts: Date.now(), scope: sc, mode: 'pty' });
+  } else if (source === 'interrupted') {
+    _emitAgentLoopBoundary('end', { sessionId, ts: Date.now(), scope: sc, mode: 'pty', reason: 'interrupted' });
+  }
 }
 
 // 统一的 streaming-state 观察入口。production polling 和 SDK push 都调它，测试也走它，
@@ -3480,19 +3554,21 @@ export const __testing = (process.env.NODE_ENV === 'test') ? {
     _lastCliActiveByScope.clear();
     _stoppingPromise = null;
     _onTurnEndBroadcastForTests = null;
+    _onAgentLoopBroadcastForTests = null;
     setTurnActive(false);
     _clearTurnActiveHeartbeat();
     _turnSessionIdByScope.clear();
     clearScopeState();
   },
   onBroadcast(fn) { _onTurnEndBroadcastForTests = fn; },
+  onAgentLoopBroadcast(fn) { _onAgentLoopBroadcastForTests = fn; },
   getPendingKeys() { return [..._pendingTurnEndTimers.keys()]; },
   setIsStopping(v) { _isStopping = !!v; },
   observeStreamingTick(activeNow, mode = 'cli', scopeKey = BOUND_SCOPE) { return _observeStreamingTick(activeNow, mode, scopeKey); },
   scheduleTurnEnd(sessionId, ts, scope = null) { _scheduleTurnEndBroadcast(sessionId, ts, null, scope); },
   getDebounceMs() { return TURN_END_DEBOUNCE_MS; },
   getPtyTurnActive(scopeKey = BOUND_SCOPE) { return turnStateFor(scopeKey).active; },
-  setPtyTurnActive(v, sessionId = null, scope = null) { _setTurnActive(v, sessionId, scope); },
+  setPtyTurnActive(v, sessionId = null, scope = null, source = 'hook') { _setTurnActive(v, sessionId, scope, source); },
   // Routes the payload through the SAME predicate the deps.onTaskEvent closure
   // uses, so tests exercise the production gate rather than a mirror of it.
   notifyTaskEvent(payload) {
@@ -3512,6 +3588,7 @@ export const __testing = (process.env.NODE_ENV === 'test') ? {
 } : Object.freeze({
   reset() {},
   onBroadcast() {},
+  onAgentLoopBroadcast() {},
   getPendingKeys() { return []; },
   setIsStopping() {},
   observeStreamingTick() { return false; },