create-walle 0.10.1 → 0.10.3

package/template/coding-task-manager/lib/ws/state-sync.js

@@ -21,6 +21,10 @@ const {
 } = require('../state-sync/nack-classification');
 // WP-0c (composer-freeze-stop-and-wait-emitter-2026-09-16, D-3/D-8): report-only, zero-dependency.
 const { maybePersistFrameApplyReceipt } = require('../state-sync/frame-apply-receipt');
+// WP-4 (§9 S-39, docs/deepseek-harness-acp-agent-2026-10-28.html): an ACP session (dsh) has no
+// terminal to restore, so its snapshot is answered with the empty, not-terminal frame below — the
+// Wall-E history redirect must NOT run for it.
+const { isAcpSession } = require('../session-transport');
 
 let _deps = null;
 
@@ -67,6 +71,9 @@ function _serializeKey(sessionId, cols, rows, scrollbackRows, rolloutHistory) {
 // softMs, hardMs, makeReqId(), buildPost(reqId), refreshCache(entry, resp),
 // scrollbackRows, rolloutHistory }. The last two are KEY inputs (I8) -- every
 // caller must supply them, whether or not it ends up creating the entry.
+// WP-3: the hard timer passes `issuedAt: entry.startedAt` to recordMiss and
+// routes a 'degraded' verdict to a 'host-degraded' diagnostic -- never to
+// _reviveUnresponsiveHost, which only an 'unresponsive' verdict reaches.
 function _attachOrPostSerialize(sessionId, cols, rows, waiter, entryHooks) {
   const key = _serializeKey(sessionId, cols, rows, entryHooks.scrollbackRows, entryHooks.rolloutHistory);
   const existing = _inflightSerialize.get(key);
@@ -98,9 +105,23 @@ function _attachOrPostSerialize(sessionId, cols, rows, waiter, entryHooks) {
     for (const w of entry.waiters) w.onHardTimeout?.(entry);
     // WP-1 (D-1/D-2): the readiness ledger's one deadlined-miss input for a
     // hosted session -- ONE call per coalesced request, never per waiter.
+    // WP-3 (session-stops-mid-job-2026-10-24.html, D-11): `issuedAt` is this
+    // entry's own creation time, so the ledger can tell "this request family
+    // timed out" (readiness) from "the host has said nothing at all" (liveness).
     if (entryHooks.hostId) {
-      const verdictResult = entryHooks.hostHealth?.recordMiss?.(entryHooks.hostId, { sessionId, kind: 'hard', deadlineMs: 60000 });
-      if (verdictResult) {
+      const verdictResult = entryHooks.hostHealth?.recordMiss?.(entryHooks.hostId, { sessionId, kind: 'hard', deadlineMs: 60000, issuedAt: entry.startedAt });
+      if (verdictResult?.verdict === 'degraded') {
+        // D-11: a host that relayed a frame after this request was issued is
+        // talking -- its serialize path is slow/wedged, but it and every agent
+        // in it stay alive. Report once per session for this host; NEVER revive.
+        _deps?.recordSessionDiagnostic?.(sessionId, 'host-degraded', {
+          hostId: entryHooks.hostId,
+          reason: 'serialize-timeout',
+          lastFrameAgoMs: verdictResult.lastFrameAgoMs,
+        });
+      } else if (verdictResult?.verdict === 'unresponsive') {
+        // D-12: only a host that has sent NO frame of any kind since the first
+        // missed request was issued reaches here.
         // Final-review fix C2: this is fire-and-forget from a timer. Without a
         // `.catch`, ANY rejection inside the revive (registry read, crash-cap
         // read, diagnostic write, host shutdown) becomes an unhandled rejection
@@ -360,11 +381,23 @@ function handleAck(ctx, msg) {
     headlessWorker,
   } = _deps;
         if (msg.id) {
+          const ackSeq = Number(msg.seq || 0);
+          // WP-0 (S-10, docs/state-sync-pipelined-deltas-echo-never-waits-for-ack-2026-10-31.html
+          // §5 D-5, §9 S-10): measure the frame's MAIN-side round trip BEFORE noteAckReceived
+          // forgets the ledger's sentAt for this seq. -1 means "no evidence" (a seq the ledger
+          // never recorded, or one already retired), never a fabricated 0 ms.
+          const sentAt = Number(_stateSyncClientLedger.sentAtFor?.({
+            clientId: ctx.ws.clientId || '',
+            socketGeneration: ctx.ws.socketGeneration || 0,
+            sessionId: msg.id,
+            seq: ackSeq,
+          }) || 0);
+          const mainRttMs = sentAt > 0 ? Math.max(0, Date.now() - sentAt) : -1;
           _stateSyncClientLedger.noteAckReceived({
             clientId: ctx.ws.clientId || '',
             socketGeneration: ctx.ws.socketGeneration || 0,
             sessionId: msg.id,
-            seq: Number(msg.seq || 0),
+            seq: ackSeq,
             gridRevision: Number(msg.gridRevision || 0),
           });
           ctx.ws.lastClientHealthBeatAt = Date.now();
@@ -383,6 +416,7 @@ function handleAck(ctx, msg) {
           headlessWorker.postMessage({
             type: 'ack', sessionId: msg.id, seq: Number(msg.seq || 0),
             clientId: ctx.ws.clientId || '', socketGeneration: Number(ctx.ws.socketGeneration || 0),
+            mainRttMs,
           });
           // S-25 (terminal-baseline-single-owner-2026-09-14 WP-4): record the worker-reported
           // ackedSeq for this delivery on the socket itself -- _admitStaleGridServe reads this
@@ -390,7 +424,7 @@ function handleAck(ctx, msg) {
           if (!(ctx.ws._workerAckedSeqBySession instanceof Map)) {
             ctx.ws._workerAckedSeqBySession = new Map();
           }
-          ctx.ws._workerAckedSeqBySession.set(msg.id, Number(msg.seq || 0));
+          ctx.ws._workerAckedSeqBySession.set(msg.id, ackSeq);
         }
         return;
 
@@ -471,6 +505,42 @@ function handleNack(ctx, msg) {
   }
 }
 
+// WP-3 (box-idle-sleep-remote-typing-freezes-2026-11-01.html §5 D-7, §6 WP-3, §8 WP-3, §11 A-5):
+// process-lifetime exit counters for the frame-receipt path. Live measurement on 2026-11-01 showed
+// every hub-typed keystroke reading "unpainted" in the box's typing-latency rollup (731/731, last
+// stage ack-received); the browser's `painted` stamp only ever arrives through handleFrameReceipt,
+// so these counts name the stage a receipt dies at (`received` minus the other buckets = still
+// inside the handler). INSTRUMENTATION ONLY: no receipt is admitted, refused, or shaped differently
+// because of them, and nothing here reads or writes the per-peer rate limiter (server.js owns that
+// refusal diagnostic). Read out through `GET /api/diagnostics/receipt-exits`; reset only by
+// resetFrameReceiptExitCountsForTest().
+const _frameReceiptExitCounts = {
+  // every call into handleFrameReceipt that carries a msg.id.
+  received: 0,
+  // the existing stale-generation early return below.
+  staleGeneration: 0,
+  // receipts whose disposition maps to no trace stage (traceStage === ''), including the
+  // not-in-the-`allowed` set early return, which maps to no stage by definition.
+  noTraceStage: 0,
+  // traceStage set, but msg.interactionIds absent or empty -- no _noteTypingInteraction call issued.
+  noInteractionIds: 0,
+  // traceStage set and at least one _noteTypingInteraction call issued.
+  stamped: 0,
+  // subset of `stamped` whose traceStage is 'painted'.
+  paintedStamped: 0,
+  // subset of `noInteractionIds` whose traceStage is 'painted'.
+  paintedNoInteractionIds: 0,
+};
+
+// Shallow copy: the live object is module-private, so a caller can never write it by accident.
+function getFrameReceiptExitCounts() {
+  return { ..._frameReceiptExitCounts };
+}
+
+function resetFrameReceiptExitCountsForTest() {
+  for (const key of Object.keys(_frameReceiptExitCounts)) _frameReceiptExitCounts[key] = 0;
+}
+
 function handleFrameReceipt(ctx, msg) {
   const {
     recordSessionDiagnostic,
@@ -481,9 +551,11 @@ function handleFrameReceipt(ctx, msg) {
     _observeSessionRuntimePaint,
   } = _deps;
         if (!msg.id) return;
+        _frameReceiptExitCounts.received += 1;
         const receiptSocketGeneration = Number(msg.socketGeneration || 0);
         if (receiptSocketGeneration > 0
             && receiptSocketGeneration !== Number(ctx.ws.socketGeneration || 0)) {
+          _frameReceiptExitCounts.staleGeneration += 1;
           recordSessionDiagnostic(msg.id, 'state-sync-stale-frame-receipt', {
             receiptSocketGeneration,
             socketGeneration: Number(ctx.ws.socketGeneration || 0),
@@ -498,7 +570,13 @@ function handleFrameReceipt(ctx, msg) {
           'rejected-grid', 'rejected-desync', 'reseed', 'rejected-local-restore', 'rejected-dims',
           'rejected-transform-error', 'rejected-apply-error', 'apply-timeout',
         ]);
-        if (!allowed.has(disposition)) return;
+        // WP-3: an unrecognised disposition exits here and produces no trace stage, so it belongs in
+        // the same bucket as the dispositions that map to '' below -- this is exactly the "where did
+        // the receipt die" reading the counters exist for.
+        if (!allowed.has(disposition)) {
+          _frameReceiptExitCounts.noTraceStage += 1;
+          return;
+        }
         const serverReceivedAt = Date.now();
         maybePersistFrameApplyReceipt(msg.id, msg, disposition, recordSessionDiagnostic, serverReceivedAt);
         const reportedClientAt = Number(msg.clientAt || 0);
@@ -548,7 +626,18 @@ function handleFrameReceipt(ctx, msg) {
               ? 'painted'
               : '';
         if (traceStage) {
-          for (const interactionId of (Array.isArray(msg.interactionIds) ? msg.interactionIds : []).slice(0, 16)) {
+          // WP-3: the exact ids the loop below will visit, so the counter reads "a call was issued"
+          // -- a missing/empty interactionIds (or one whose entries all fall past the 16-id cap)
+          // means the receipt reached this stage server-side but named no keystroke to stamp.
+          const interactionIds = (Array.isArray(msg.interactionIds) ? msg.interactionIds : []).slice(0, 16);
+          if (interactionIds.length > 0) {
+            _frameReceiptExitCounts.stamped += 1;
+            if (traceStage === 'painted') _frameReceiptExitCounts.paintedStamped += 1;
+          } else {
+            _frameReceiptExitCounts.noInteractionIds += 1;
+            if (traceStage === 'painted') _frameReceiptExitCounts.paintedNoInteractionIds += 1;
+          }
+          for (const interactionId of interactionIds) {
             _noteTypingInteraction({
               interactionId,
               stage: traceStage,
@@ -567,6 +656,11 @@ function handleFrameReceipt(ctx, msg) {
               activeLoafMs: ledgerEvent.activeLoafMs,
             });
           }
+        } else {
+          // WP-3: a disposition that reached this point but maps to no stage (buffered,
+          // rejected-*, reseed, ...) -- the receipt was admitted and handled, yet can never stamp a
+          // typing-interaction stage, so this is the bucket that explains an unpainted rollup.
+          _frameReceiptExitCounts.noTraceStage += 1;
         }
         // R-2: the worker's WP-2 emitter takes no 'frame-receipt' input (empty case,
         // lib/headless-term-service.js) -- the post is dead, deleted with the sender.
@@ -647,6 +741,10 @@ function handleKeyframeReq(ctx, msg) {
     // and can mismatch the admission ledger's expectedEpoch.
     contentRecoveryEpoch: ctx.ws.frameProtocol === FRAME_PROTOCOL_V2 ? deliveredSurfaceEpoch : 0,
     reason: String(msg.reason || '').slice(0, 48), // WP-0c: report-only
+    // WP-2 (D-6, §9 S-8): forward the client's committed baseline seq ONLY when it is a valid
+    // non-negative safe integer, so "absent" (an old client, served exactly as today) stays
+    // distinguishable from 0 (a current client that genuinely holds no baseline yet).
+    ...(Number.isSafeInteger(msg.haveSeq) && msg.haveSeq >= 0 ? { haveSeq: msg.haveSeq } : {}),
   });
 }
 
@@ -703,6 +801,22 @@ function handleSnapshot(ctx, msg) {
           sendTerminalSessionUnavailableSnapshot(ctx.ws, msg.id, 'snapshot', msg);
           return;
         }
+        if (isAcpSession(_snapSession)) {
+          // §9 S-39: a conv-only ACP session has no PTY and no terminal snapshot. Answer with the
+          // same empty not-terminal frame the Wall-E redirect uses, but WITHOUT the Wall-E history
+          // call (dsh history is CTM's own transcript, delivered by the session stream).
+          if (ctx.ws.readyState === 1) {
+            _wsSend(ctx.ws, JSON.stringify({
+              type: 'snapshot',
+              id: msg.id,
+              data: null,
+              notTerminal: true,
+              restoreSource: 'snapshot-acp-no-terminal',
+              clientRestoreSeq: msg.clientRestoreSeq,
+            }));
+          }
+          return;
+        }
         if (isWalleLikeSession(_snapSession)) {
           recordSessionDiagnostic(msg.id, 'walle-snapshot-history-redirect', {
             source: msg.restoreSource || 'snapshot',
@@ -970,4 +1084,9 @@ module.exports = {
   // applied/painted receipt directly to prove it resets the client-fault episode counter.
   handleFrameReceipt,
   handleAck,
+  // WP-3 (box-idle-sleep-remote-typing-freezes-2026-11-01.html §8 WP-3): process-lifetime
+  // frame-receipt exit counters, read out by GET /api/diagnostics/receipt-exits (no behaviour
+  // change -- pure instrumentation).
+  getFrameReceiptExitCounts,
+  resetFrameReceiptExitCountsForTest,
 };

package/template/coding-task-manager/lib/ws/terminal-attach.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const crypto = require('node:crypto');
+
 const {
   approvalResolveResultIsTerminal,
   publicApprovalResolveBody,
@@ -25,6 +27,22 @@ const {
 // socket reference rewritten to `ctx.ws` inline.
 
 const { registerWsHandlers } = require('../ws-router');
+// WP-2 (docs/remote-machine-hub-sessions-2026-10-22.html §5 D-10, §6.3, §9 S-1): the remote-create
+// seam. Required here (not injected through configure()) so server.js needs no edit for the
+// branch; its production dependencies are resolved LAZILY inside the module, so loading this file
+// still never touches db.js.
+const remoteMachineCreate = require('../remote-machine-create');
+// WP-3 (D-4, S-9): the local create path notes a short in-flight lease so a restart guard
+// (GET /api/instance/update-gate, POST /api/restart/ctm) can see a create that has no session row.
+const { noteCreateIntent } = require('../create-intent-lease');
+// WP-3 (docs/remote-machine-hub-sessions-2026-10-22.html §6.4, S-22): the live-plane relay seam.
+// Loading this file installs lib/remote-machine-link.js's pre-dispatch hook (lib/ws-router.js),
+// which diverts any message naming a MIRROR session to the box and returns false — leaving the
+// local path byte-identical — for every other session. Installed here, at boot, because this file
+// is where the WP-2 remote-create branch already lives; the hook is inert until a mirror session
+// exists, so no server.js edit is needed for it.
+const remoteMachineLink = require('../remote-machine-link');
+remoteMachineLink.installIntercept();
 
 let _deps = null;
 
@@ -50,8 +68,13 @@ function configure({
   _subscribeTerminalTail,
   _unsubscribeTerminalTail,
   _ensureCodexThreadLinkOffThread,
+  remoteCreateDeps,
+  // WP-3: the process error sink, for the one REPORT path this module owns (a bundle session-record
+  // failure must be visible without ever failing a create).
+  errorSink = null,
 } = {}) {
   _deps = {
+    errorSink,
     handleCreatePrepared,
     CTM_WAKE_MANIFEST_ENABLED,
     _subscribeStateSyncClient,
@@ -73,7 +96,13 @@ function configure({
     _subscribeTerminalTail,
     _unsubscribeTerminalTail,
     _ensureCodexThreadLinkOffThread,
+    remoteCreateDeps: remoteCreateDeps && typeof remoteCreateDeps === 'object' ? remoteCreateDeps : null,
   };
+  // WP-0 (docs/relay-per-viewer-delivery-contract-2026-10-27.html §5 D-5, §9 S-3): hand the hub's
+  // session-diagnostics reporter to the relay, so a relayed frame a hub viewer did not get is
+  // recorded as `relay-frame-undelivered` through the SAME sink every other hub diagnostic uses
+  // (server.js already passes `remoteCreateDeps: { recordSessionDiagnostic }` here — no server.js edit).
+  remoteMachineLink.setDiagnosticsSink(remoteCreateDeps && typeof remoteCreateDeps.recordSessionDiagnostic === 'function' ? remoteCreateDeps.recordSessionDiagnostic : null);
 }
 
 function handleWakeResync(ctx, msg) {
@@ -206,6 +235,71 @@ function publicCreateInternalControlPresent(msg) {
   return false;
 }
 
+// ---------------------------------------------------------------------------------------------
+// WP-3 (docs/remote-agent-skills-bundles-2026-10-25.html §5 D-4/D-6, §6.3/§6.5) — the BOX side of
+// "which hub created this session".
+//
+// A create that arrives over a PEER-AUTHENTICATED WebSocket (an authenticated hub forwarding a
+// session) is recorded in the box's bundle store as `sessions/<id>.json` BEFORE the provider process
+// spawns, so WP-4 can resolve the hub's bundle at spawn time (D-7). The identity is the
+// AUTHENTICATED principal (`ctx.ws.auth.peerInstanceId`, the same value lib/api/agent-bundles.js
+// reads as `req.ctmAuth.peerInstanceId`) — never a header, never a body field, which is what makes
+// the record unforgeable by whoever sends the frame.
+// ---------------------------------------------------------------------------------------------
+
+/** The authenticated peer id on this connection, or '' — a loopback/browser create has none. */
+function peerInstanceIdOf(ctx) {
+  // Read through `ctx.` like every other connection access in lib/ws/*.js (tests/ws-router-parity
+  // .test.js forbids a bare connection-closure identifier, and a local here would be one).
+  const peerAuth = ctx && ctx.ws && ctx.ws.auth;
+  return String((peerAuth && (peerAuth.peerInstanceId || peerAuth.peer_instance_id)) || '').trim();
+}
+
+/**
+ * Record `sessions/<id>.json` for a hub-forwarded create. Returns the session id it recorded, or
+ * null when this create did not come from an authenticated peer.
+ *
+ * D-6/D-7: a record failure REPORTS and continues — the create is never failed, delayed past its
+ * spawn, or otherwise changed by bundle bookkeeping.
+ *
+ * The id: `lib/session-create/prepared.js` uses `msg.id || crypto.randomUUID()` as the session id on
+ * the row it writes, so when the frame carries no id this stamps the SAME randomUUID onto `msg`
+ * before the create path runs — the recorded id is then the id the session actually gets, never a
+ * second guess. (The hub always forwards the allowlisted `id`; this branch covers a direct peer
+ * caller that does not.)
+ *
+ * @returns {Promise<string|null>}
+ */
+async function recordHubCreatedSession(ctx, msg, deps = {}) {
+  const hubPeerId = peerInstanceIdOf(ctx);
+  if (!hubPeerId) return null; // a local (browser/loopback) create records nothing
+  if (!msg || typeof msg !== 'object') return null;
+  if (!msg.id) msg.id = crypto.randomUUID();
+  const sessionId = String(msg.id);
+  try {
+    const store = deps.store || require('../agent-bundle/store');
+    const dataDir = deps.dataDir || require('../data-dir').getDataDir();
+    // The hub's CURRENT pointer when it has pushed one; `resolveSpawnBundle` re-reads it at spawn
+    // anyway, so a null (no push yet) is a fine create-time value.
+    const treeHash = await store.currentHubTree(dataDir, hubPeerId);
+    await store.recordSessionHub(dataDir, sessionId, hubPeerId, treeHash);
+    return sessionId;
+  } catch (error) {
+    // REPORT: bundle bookkeeping must never fail or change a create — the session spawns without a
+    // bundle, which is the same outcome as a hub that had never pushed (D-6/D-7).
+    const detail = String((error && error.message) || error || 'agent_bundle_session_record_failed').slice(0, 200);
+    if (deps.errorSink && typeof deps.errorSink.report === 'function') {
+      deps.errorSink.report('terminal-attach:agent-bundle-session-record', Object.assign(
+        new Error(detail),
+        { code: 'agent_bundle_session_record_failed' },
+      ));
+    } else {
+      console.warn(`[agent-bundle] session record failed for ${String(sessionId).slice(0, 12)}: ${detail}`);
+    }
+    return null;
+  }
+}
+
 // Registered handler for the public 'create' type. On refusal it returns
 // without forwarding, so no reservation/preparation/spawn happens even on a
 // closed socket; an open socket gets exactly one bounded frame that names
@@ -225,6 +319,22 @@ async function handleCreate(ctx, msg) {
     }
     return;
   }
+  // WP-2 (S-1): a create naming a REGISTERED REMOTE machine is forwarded to that box instead of
+  // being prepared here. The check is BEFORE the local plan, so nothing local (generation,
+  // prepared plan, PTY) is ever created for it; `machine` absent or naming THIS instance's minted
+  // id falls through to the unchanged local path (S-2 — the local deny list above is untouched
+  // and is never widened for forwarded frames).
+  if (remoteMachineCreate.isRemoteMachineTarget(msg, _deps.remoteCreateDeps || {})) {
+    return remoteMachineCreate.forwardRemoteCreate(ctx, msg, _deps.remoteCreateDeps || {});
+  }
+  // WP-3 (D-4, S-9): the create is about to run HERE, so note the intent on THIS machine's lease —
+  // a restart in the next two minutes would abort it. Deliberately AFTER the forward branch above:
+  // a forwarded create is noted by the box that runs it, never by the hub that passed it on.
+  noteCreateIntent('WS create', ctx);
+  // WP-3 (§6.3/§6.5): a create that arrived from an AUTHENTICATED PEER is recorded BEFORE the
+  // provider process spawns, so WP-4 can resolve this hub's bundle at spawn time. A local create
+  // (no peer principal) records nothing, and the record can never fail the create.
+  await recordHubCreatedSession(ctx, msg, _deps);
   return _deps.handleCreatePrepared(ctx.ws, msg);
 }
 
@@ -250,4 +360,16 @@ function register() {
   });
 }
 
-module.exports = { configure, register };
+module.exports = {
+  configure,
+  register,
+  // WP-3: the box-side record of which hub created a session (and the authenticated-peer read it
+  // is keyed on), exported so the store/hub integration tests can drive it directly.
+  peerInstanceIdOf,
+  recordHubCreatedSession,
+  // Exported for the WP-2 enforcement test (tests/create-forward-allowlist.test.js): the LIVE
+  // deny list and the LIVE §6.3 allowlist, so the test can never drift from either constant.
+  PUBLIC_CREATE_INTERNAL_CONTROLS,
+  REMOTE_CREATE_FORWARD_ALLOWLIST: remoteMachineCreate.REMOTE_CREATE_FORWARD_ALLOWLIST,
+  filterRemoteCreateForward: remoteMachineCreate.filterRemoteCreateForward,
+};

package/template/coding-task-manager/lib/ws-router.js

@@ -77,6 +77,64 @@ class WsRouter {
 
 const _router = new WsRouter();
 
+// ---------------------------------------------------------------------------------------------
+// Pre-dispatch hooks (WP-3, docs/remote-machine-hub-sessions-2026-10-22.html §6.4)
+//
+// The ONE seam a relay needs. A machine-hub session lives on a REMOTE box, not in this process's
+// `sessions` Map (OQ-4), so every message that NAMES such a session must be diverted before a
+// local handler dereferences it. Rather than touch each lib/ws/*.js group, a module registers a
+// hook here and `dispatchWs` offers it every inbound frame first (in registration order):
+//
+//   hook(ctx, msg) -> true   the hook handled it; the local dispatch is SKIPPED
+//   hook(ctx, msg) -> false  not mine; the next hook, then the normal handler, runs
+//
+// Hooks are consulted OUTSIDE `WsRouter.dispatch` on purpose: `dispatch` is the pure registry
+// primitive (unit-tested directly), and a hook is a deployment-level concern of the process's
+// singleton. A hook that throws is REPORTED and treated as "not handled" — one broken relay must
+// never take the whole WS surface down with it.
+// ---------------------------------------------------------------------------------------------
+const _preDispatchHooks = [];
+
+function registerWsPreDispatchHook(name, hook) {
+  if (!name || typeof name !== 'string') {
+    throw new TypeError('registerWsPreDispatchHook: name must be a non-empty string');
+  }
+  if (typeof hook !== 'function') {
+    throw new TypeError(`registerWsPreDispatchHook(${name}): hook must be a function`);
+  }
+  if (_preDispatchHooks.some((entry) => entry.name === name)) {
+    throw new Error(`registerWsPreDispatchHook: duplicate hook name: ${name}`);
+  }
+  const entry = { name, hook };
+  _preDispatchHooks.push(entry);
+  return () => {
+    const at = _preDispatchHooks.indexOf(entry);
+    if (at >= 0) _preDispatchHooks.splice(at, 1);
+  };
+}
+
+// SYNCHRONOUS on purpose: hooks return a plain boolean, so a message no hook claims (every local
+// keystroke) reaches its handler in the same tick it always did — no added microtask.
+function runWsPreDispatchHooks(ctx, msg) {
+  for (const entry of _preDispatchHooks) {
+    let handled = false;
+    try {
+      handled = entry.hook(ctx, msg);
+    } catch (error) {
+      // REPORT, then fall through: the relay is a routing optimization, never a gate — a hook
+      // fault must degrade to the pre-WP-3 behaviour (the local handler), not drop the frame.
+      console.error(`[ws-router] pre-dispatch hook ${entry.name} failed:`, error?.stack || error);
+      handled = false;
+    }
+    if (handled === true) return true;
+  }
+  return false;
+}
+
+function listWsPreDispatchHooks() {
+  return _preDispatchHooks.map((entry) => entry.name);
+}
+
 function registerWsHandler(type, handler) {
   _router.registerOne('_default', type, handler);
 }
@@ -86,6 +144,7 @@ function registerWsHandlers(groupName, handlersByType) {
 }
 
 async function dispatchWs(ctx, msg) {
+  if (runWsPreDispatchHooks(ctx, msg)) return true;
   return _router.dispatch(ctx, msg);
 }
 
@@ -93,4 +152,12 @@ function listRegisteredWsTypes() {
   return _router.list();
 }
 
-module.exports = { registerWsHandler, registerWsHandlers, dispatchWs, listRegisteredWsTypes, WsRouter };
+module.exports = {
+  registerWsHandler,
+  registerWsHandlers,
+  registerWsPreDispatchHook,
+  listWsPreDispatchHooks,
+  dispatchWs,
+  listRegisteredWsTypes,
+  WsRouter,
+};

package/template/coding-task-manager/lib/ws-send-admission.js

@@ -79,15 +79,33 @@ function prepareExactJsonEnvelope(payload, stringify = JSON.stringify) {
   return { encoded, bytes: measuredBytes };
 }
 
-function classifyWsPayload(payload, explicitClass = '') {
+// T1 (docs/walle-turn-lifecycle-delivery-2026-10-26.html §3): the `walle-transcript-append`
+// channel carries BOTH replaceable stream samples and turn LIFECYCLE control notifications —
+// server.js's _recordWalleTranscriptAppend emits recordType=user/assistant rows and bare
+// partType=turn_terminal parts, and the client (public/js/walle-session.js
+// handleTranscriptAppend) flips generating state or forces a refetch on exactly those.
+// Shedding them as replaceable stream samples is what left a live turn reading
+// isGenerating=false while its interactive user echo still arrived. Classification therefore
+// reads the already-resolved channel plus the payload's decoded recordType/partType, normalized
+// exactly like the client's String(value || '').toLowerCase(); every other append stays stream.
+// `explicitChannel` is the caller's already-resolved channel (wsSend's `options.channel`).
+function classifyWsPayload(payload, explicitClass = '', explicitChannel = '') {
   if (['interactive', 'stream', 'bulk'].includes(explicitClass)) return explicitClass;
-  const channel = payloadChannel(payload);
+  const channel = payloadChannel(payload, explicitChannel);
   if (process.env.CTM_WS_SOLICITED_REPLY_INTERACTIVE !== '0' && SOLICITED_REPLY_CHANNELS.has(channel)) {
     return 'interactive';
   }
   if (process.env.CTM_WALLE_WS_CLASS_SPLIT !== '0') {
     if (WALLE_TERMINAL_CHANNELS.has(channel) || channel.startsWith('walle-permission')) return 'interactive';
-    if (WALLE_STREAM_CHANNELS.has(channel)) return 'stream';
+    if (WALLE_STREAM_CHANNELS.has(channel)) {
+      if (channel === 'walle-transcript-append') {
+        const decoded = normalizePayload(payload);
+        const recordType = String(decoded?.recordType || '').toLowerCase();
+        const partType = String(decoded?.partType || '').toLowerCase();
+        if (recordType === 'user' || recordType === 'assistant' || partType === 'turn_terminal') return 'interactive';
+      }
+      return 'stream';
+    }
   }
   if (['frame', 'terminal-tail', 'terminal-dirty', 'session-activity', 'fingerprint'].includes(channel)) return 'stream';
   if (['sessions', 'wake-digest', 'wake-manifest', 'conversation-updated', 'data-changed'].includes(channel)
@@ -133,7 +151,7 @@ function wsSend(ws, payload, options = {}) {
   const state = ws._ctmAdmission || createAdmissionState(options);
   ws._ctmAdmission = state;
   const now = Number(options.now) || Date.now();
-  const trafficClass = classifyWsPayload(payload, options.class);
+  const trafficClass = classifyWsPayload(payload, options.class, options.channel);
   const channel = payloadChannel(payload, options.channel);
   const decision = options.admissionEnabled === false
     ? { result: ws.readyState === 1 ? ADMISSION_RESULTS.SENT : ADMISSION_RESULTS.DROPPED_BACKPRESSURE, reason: 'disabled' }