create-walle 0.10.1 → 0.10.2

package/template/coding-task-manager/lib/visible-revision-watchdog.js

@@ -8,16 +8,13 @@ const DEFAULT_DEADLINES_MS = Object.freeze({
   applied: 100,
   painted: 50,
 });
-const RECOVERY_ACTION = Object.freeze({
-  'frame-sent': 'targeted-keyframe',
-  // Browser main-thread receipt can legitimately exceed this interaction latency
-  // deadline. It is latency evidence, not proof of baseline corruption, so it
-  // must neither fence the diff stream nor inject a replacement keyframe.
-  'socket-received': 'report-only',
-  'apply-started': 'supersede-obsolete',
-  applied: 'supersede-obsolete',
-  painted: 'report-only',
-});
+// Every incident is report-only: a missed boundary deadline is latency evidence, never proof
+// that a frame was lost. Under host load keydown->frame-sent runs 400-800 ms on a healthy
+// session, and the replacement keyframe the 'frame-sent' miss used to force re-delivered a
+// screen the client had already applied (B3: a duplicate full-grid write per late frame). Lost
+// frames are repaired by the delivery path's own seq/baseline checks, not by a clock.
+// (codex-running-composer-latency-round5-2026-08-09 §11 WP-6 rollback: "Return watchdog to
+// report-only; preserve diagnostics".)
 
 function createVisibleRevisionWatchdog(options = {}) {
   const now = options.now || Date.now;
@@ -88,12 +85,11 @@ function createVisibleRevisionWatchdog(options = {}) {
         deadlineMs,
         previousBoundary,
         missingBoundary,
-        recoveryAction: RECOVERY_ACTION[missingBoundary] || 'report-only',
       };
       row.reported = true;
       incidents.push(incident); report(incident);
       recover({ ...incident, scope: row.clientId ? 'client' : 'session' });
-      if (incident.recoveryAction === 'report-only') pending.delete(id);
+      pending.delete(id);
     }
     return incidents;
   }

package/template/coding-task-manager/lib/wake-skip-reasons.js

@@ -0,0 +1,46 @@
+'use strict';
+// WP-3 (§5 D-8): the closed skip-reason vocabulary for the deferred-restore wake pipeline --
+// CamelCase machine tokens (P-3, the K8s-condition convention) that wakeSkips aggregates on; the
+// human sentence lives beside them in a session diagnostic. Closed per release: additive only.
+//
+// Extracted from lib/session-lifecycle.js (which re-exports it) so server.js can name these tokens
+// without growing past its file-size ratchet and so the vocabulary closure test can read the list
+// without pulling in the lifecycle module.
+const WAKE_SKIP_REASONS = Object.freeze([
+  'OwnerRecoveryFence',
+  'BackoffTaskMissingSessionId',
+  'BackoffSessionReplaced',
+  'CapacityRejected',
+  'WakeBlocked',
+  'GateBusy',
+  'ResumeBlocked',
+  'CodexLinkStale',
+  'CodexLinkUnavailable',
+  'CodexLinkBlocked',
+  'LaunchPlanStale',
+  'SessionReplaced',
+  'McpWaitStale',
+  'ResumeStormStale',
+  'LaunchPlanNotSpawning',
+  'RetryNotDeferred',
+  'RetryAlreadyStarting',
+  'RetryNoClients',
+  'DrainPaused',
+  'DrainPressureSkipped',
+  'DrainIneligible',
+  'SourceRecoveryEnvironmentInvalid',
+  'LaunchGenerationUnavailable',
+  'PrepareFailed',
+  'LaunchBlocked',
+  'LeadTransitionTargetOwnerMismatch',
+  'LeadTransitionSourceOwnerMismatch',
+  'LeadTransitionReconciliationFailed',
+  'LeadTransitionReconciliationUnavailable',
+  'LeadSourceRecoveryResumeMismatch',
+  'TranscriptRestoreFailed',
+  'LeadTransitionAttemptIssueRefused',
+  'CreateRollback',
+  'AutoStartNotAttach',
+]);
+
+module.exports = { WAKE_SKIP_REASONS };

package/template/coding-task-manager/lib/walle-supervisor.js

@@ -196,6 +196,21 @@ async function listPidsWithPpid() {
   return rows;
 }
 
+// D-8 (WP-5, docs/clock-free-tests-followups-2026-10-23.html §6): proving that ONE pid is ours
+// needs only that pid's row. The whole `ps -axo` table is 82-474 ms and ~1 MB on a busy host; a
+// `ps -p <pid>` read is a single process. Rows are parsed by the SAME parser the whole-table read
+// uses, so ownership (isOwnedRow) sees an identical row shape.
+//   rows  -> ps ran; [] means the pid has no row (not ours, or already gone)
+//   null  -> the probe itself failed; callers must treat that as "not proven owned", never as [].
+async function listPidRow(pid) {
+  const { err, stdout } = await execFileCapture('ps', ['-p', String(pid), '-o', 'pid=,ppid=,command='], {
+    timeout: PS_SNAPSHOT_TIMEOUT_MS,
+    maxBuffer: 1024 * 1024,
+  });
+  if (err) return null;
+  return parsePsWithPpid(stdout);
+}
+
 // WP-P2 orphan reap path signature — a small, pure, directly-testable
 // predicate deliberately kept separate from the exact-title match. A bare
 // `command.includes(rootMarker)` has two failure modes: (1) no path-boundary
@@ -223,6 +238,7 @@ const defaultProcessOps = {
   findListeningPidsByExactCommand,
   getProcessUptime,
   listPidsWithPpid,
+  listPidRow,
 };
 
 function isSourceCheckout(rootDir) {
@@ -391,6 +407,13 @@ function createWalleSupervisor({
   // spawned child (see spawnWalle()) — childPid always takes precedence.
   let adoptedPid = null;
   let lastBootAdoption = null; // WP-7 (S-26)
+  // D-7 (WP-5): the status GET's snapshot, declared HERE (not next to getStatusSnapshot())
+  // because killAll/apiStop/restartQuiet — any of which may run before that statement — clear it.
+  // `statusSnapshot` is the last computed status + its timestamp; `statusSnapshotInFlight` is the
+  // single-flight slot concurrent getStatusSnapshot() callers share.
+  let statusSnapshot = null; // { status, at }
+  let statusSnapshotInFlight = null;
+  let statusSnapshotGeneration = 0; // bumped by every invalidation; an older in-flight result is never stored
   // WP-S2 crash-streak/backoff state. crashStreak counts consecutive
   // unexpected exits (reset once the child has stayed ready for
   // restartStreakResetMs — see markChildReady()/childBecameReadyAt).
@@ -1797,6 +1820,7 @@ function createWalleSupervisor({
   // longer childExitWaitMs so a wall-e mid-drain has room to exit cleanly
   // instead of being SIGKILLed out from under itself.
   async function killAll(waitMs = 2000) {
+    invalidateStatusSnapshot();
     artifactAuthorityRegistry.clear('wall_e_stopping');
     const pidSet = await collectManagedPids();
     if (pidSet.size === 0) return waitForPortFree();
@@ -2180,6 +2204,10 @@ function createWalleSupervisor({
     // the failure exactly once — Node can emit `error`, `exit`, or both for a
     // failed spawn depending on platform/failure mode.
     function handleChildFailure({ code = null, signal = null, spawnError = null } = {}) {
+      // D-7 (WP-5): the child is gone — drop any cached status that still says running:true.
+      // Invalidate BEFORE the pid guard below: a duplicate/late exit event for an older pid is
+      // still an exit, and the cached snapshot is stale either way.
+      invalidateStatusSnapshot();
       if (childPid !== myPid) return;
       const failureAuthorityGeneration = childFailureAuthorityGeneration;
       artifactAuthorityRegistry.clear('wall_e_exit');
@@ -2454,9 +2482,33 @@ function createWalleSupervisor({
     // D-3/D-4 (kill authority): adoption (pid-file OR ps-title discovery)
     // requires the SAME ownership check as collectManagedPids() — a
     // same-title pid with a foreign ppid is never adopted and never becomes
-    // pidSource:'discovered'. One ps snapshot is shared by both checks below.
+    // pidSource:'discovered'.
     const myPid = processOps.pid || process.pid;
     const titles = new Set(processTitles());
+
+    // D-8 (WP-5): a live pid-file pid is proven ours by ONE `ps -p <pid>` row, never the
+    // whole ~1 MB table (82-474 ms busy); injected processOps without listPidRow answer from
+    // THEIR table, never a real ps. A null result (probe FAILED) is "not proven owned".
+    if (savedPid && isAlive(savedPid)) {
+      let savedRows = null;
+      try {
+        savedRows = processOps.listPidRow ? await processOps.listPidRow(savedPid) : processOps.listPidsWithPpid
+          ? (await processOps.listPidsWithPpid() || []).filter((row) => row.pid === savedPid) : await listPidRow(savedPid);
+      } catch { /* expected: best-effort per-pid ownership probe; a failure leaves savedRows=null, so the saved pid is never (wrongly) adopted */ }
+      const savedRow = Array.isArray(savedRows) ? indexRowsByPid(savedRows).get(savedPid) : undefined;
+      if (isOwnedRow(savedRow, { titles, myPid })) {
+        // WP-S3 (B11): this pid was NOT spawned by us this process lifetime —
+        // adopt it into the same supervision the interval monitor gives a real
+        // child (arm the monitor if it isn't already, and start tracking it so
+        // a later tick's isAlive(adoptedPid) poll can detect it disappearing).
+        adoptedPid = savedPid;
+        if (!intentionallyStopped) ensureMcpReadinessMonitor(); // R-5: a status read must never re-arm after an intentional stop
+        return statusWithDiagnostics({ running: true, pid: savedPid, pidSource: 'pid_file' });
+      }
+    }
+    if (savedPid) stalePid = savedPid;
+
+    // Discovery branch: the ONE consumer of the whole-table snapshot.
     let rows = null;
     try {
       rows = processOps.listPidsWithPpid ? await processOps.listPidsWithPpid() : await listPidsWithPpid();
@@ -2467,17 +2519,6 @@ function createWalleSupervisor({
     const psFailedFlag = Array.isArray(rows) ? {} : { ps_snapshot_failed: true };
     const owned = (pid) => isOwnedRow(byPid.get(pid), { titles, myPid });
 
-    if (savedPid && isAlive(savedPid) && owned(savedPid)) {
-      // WP-S3 (B11): this pid was NOT spawned by us this process lifetime —
-      // adopt it into the same supervision the interval monitor gives a real
-      // child (arm the monitor if it isn't already, and start tracking it so
-      // a later tick's isAlive(adoptedPid) poll can detect it disappearing).
-      adoptedPid = savedPid;
-      ensureMcpReadinessMonitor();
-      return statusWithDiagnostics({ running: true, pid: savedPid, pidSource: 'pid_file' });
-    }
-    if (savedPid) stalePid = savedPid;
-
     let discovered = [];
     try {
       const titleRowPids = [...byPid.values()]
@@ -2494,7 +2535,7 @@ function createWalleSupervisor({
       const pid = discovered[0];
       // WP-S3 (B11): same adoption as the pid-file branch above.
       adoptedPid = pid;
-      ensureMcpReadinessMonitor();
+      if (!intentionallyStopped) ensureMcpReadinessMonitor(); // R-5: same guard as the pid-file branch above
       return statusWithDiagnostics({
         running: true,
         pid,
@@ -2514,7 +2555,45 @@ function createWalleSupervisor({
     }, { checkNative: true });
   }
 
+  // D-7 (WP-5, docs/clock-free-tests-followups-2026-10-23.html §6): the status GET serves this
+  // snapshot instead of running kill-authority discovery (a whole-table ps) on every request.
+  // A cached status is served only while it is (a) younger than one monitor interval AND
+  // (b) still consistent with the process table — `!running` is trivially consistent, otherwise
+  // one isAlive() syscall (kill(pid, 0), ~5 µs) must pass, so a daemon that died since the
+  // snapshot is never reported as running. Anything else is ONE single-flight getStatus():
+  // concurrent callers share the promise instead of each spawning their own ps.
+  // KILL PATHS MUST NEVER CALL THIS — collectManagedPids/reapOrphans/stop need a fresh, whole
+  // table read taken immediately before they signal (see the anti-goal in the design doc §11).
+  function invalidateStatusSnapshot() { statusSnapshot = null; statusSnapshotInFlight = null; statusSnapshotGeneration += 1; }
+
+  async function getStatusSnapshot() {
+    if (pendingChildFailure) return { running: false, pid: null, pidSource: null, recovering: true, snapshotAgeMs: 0 }; // D-6 (WP-3): never wait on the crash-recovery pipeline (npm install, up to 180 s); this answer is not cached, getStatus() still awaits it.
+    const cached = statusSnapshot;
+    const cacheAgeMs = cached ? Date.now() - cached.at : null;
+    if (cached && cacheAgeMs < mcpMonitorIntervalMs && (!cached.status.running || isAlive(cached.status.pid))) {
+      return { ...cached.status, snapshotAgeMs: cacheAgeMs };
+    }
+    if (!statusSnapshotInFlight) {
+      // A getStatus() that began before an invalidation (stop/start/restart/exit) must not write its
+      // pre-invalidation answer back into the cache: store only if no invalidation happened since.
+      const generation = statusSnapshotGeneration;
+      const inFlight = getStatus().then((status) => {
+        const entry = { status, at: Date.now() };
+        if (generation === statusSnapshotGeneration) statusSnapshot = entry;
+        return entry;
+      });
+      statusSnapshotInFlight = inFlight;
+      // Clear the in-flight slot without turning a rejected getStatus() into an unhandled
+      // rejection: the awaiter below still sees the rejection, and the next call retries.
+      const clear = () => { if (statusSnapshotInFlight === inFlight) statusSnapshotInFlight = null; };
+      void inFlight.then(clear, clear);
+    }
+    const fresh = await statusSnapshotInFlight;
+    return { ...fresh.status, snapshotAgeMs: Date.now() - fresh.at };
+  }
+
   function apiStop(req, res) {
+    invalidateStatusSnapshot();
     intentionallyStopped = true;
     stopGeneration += 1;
     clearRestartTimer();
@@ -2535,6 +2614,7 @@ function createWalleSupervisor({
     }
     starting = true;
     intentionallyStopped = false;
+    invalidateStatusSnapshot();
     appendLifecycleEvent('api_start', { pid: childPid, trigger: 'api_start' });
     // WP-S2 (Req #7): an explicit human-initiated start is a clean slate —
     // same as apiRestart/restartQuiet below.
@@ -2674,6 +2754,7 @@ function createWalleSupervisor({
   }
 
   function restartQuiet() {
+    invalidateStatusSnapshot();
     return ensureNativeDependenciesReady('config_change').then((ready) => {
       if (!ready.ok) {
         console.error(`[setup] Wall-E restart blocked: ${ready.health.message}`);
@@ -2742,6 +2823,7 @@ function createWalleSupervisor({
   }
 
   async function apiRestart(req, res) {
+    invalidateStatusSnapshot();
     restartInFlight = restartInFlight || runRestart().finally(() => { restartInFlight = null; });
     const { status, body } = await restartInFlight;
     return writeJson(res, status, body);
@@ -2846,6 +2928,8 @@ function createWalleSupervisor({
     // last-resort safety-net timer comfortably above it instead of guessing.
     childExitWaitMs,
     getStatus,
+    // D-7 (WP-5): the status-GET snapshot. NEVER call this from a kill path.
+    getStatusSnapshot,
     getNativeDependencyStatus,
     isIntentionallyStopped: () => intentionallyStopped,
     killAll,
@@ -2861,4 +2945,4 @@ function createWalleSupervisor({
   };
 }
 
-module.exports = { createWalleSupervisor: (opts) => require('./walle-restart-settled').withRestartSettled(createWalleSupervisor(opts)), rotateBoundedLog, classifyExit, resolveCrashLogPath, psSnapshotRows, PS_SNAPSHOT_MAX_BUFFER };
+module.exports = { createWalleSupervisor: (opts) => require('./walle-restart-settled').withRestartSettled(createWalleSupervisor(opts)), rotateBoundedLog, classifyExit, resolveCrashLogPath, parsePsWithPpid, psSnapshotRows, PS_SNAPSHOT_MAX_BUFFER };

package/template/coding-task-manager/lib/worker-failure-classify.js

@@ -110,6 +110,18 @@ function nextStepFor({ code = '', klass = '', reason = null } = {}) {
   return CLASS_NEXT_STEPS[klass] || CLASS_NEXT_STEPS.terminal;
 }
 
+/** WP-2 (session-stops-mid-job-2026-10-24.html D-9, §6): the one lead_next_step text on a
+ *  non-terminal wait answer. RC-1's stall was a lead that read a wake with its worker still
+ *  live ("I'm waiting for its report") and ended its turn with no wait in flight, so the text
+ *  names the still-live worker and the two verbs that keep the lead attached to it.
+ *  @param {object} [input] @param {string} [input.workerId] the still-live worker
+ *  @param {string} [input.status] that worker's status string
+ *  @returns {string|null} null when no worker is named (no live worker to wait on) */
+function waitNextStep({ workerId, status } = {}) {
+  if (!workerId) return null;
+  return `Worker ${workerId} is still ${status}. Call walle_worker_wait again to keep waiting -- ending your turn with no wait in flight leaves you idle until your user types -- or walle_stop_worker if you no longer need it.`;
+}
+
 // Worker-session-tree WP-0 ("every worker death gets a name"): an exit-sourced failure used to
 // carry `code: ''` -- exit 129 (SIGHUP) had no field explaining it. This names the signal
 // behind an exit: from `exit.signal` (a node-pty string like 'SIGHUP', or a positive numeric OS
@@ -256,4 +268,4 @@ function classifyFailure({ source, http_status = null, code = '', message = '',
   };
 }
 
-module.exports = { classifyFailure, signalName, extractHttpStatus, extractCode, extractRetryAfterMs, nextStepFor, NEXT_STEPS, CLASS_NEXT_STEPS };
+module.exports = { classifyFailure, signalName, extractHttpStatus, extractCode, extractRetryAfterMs, nextStepFor, waitNextStep, NEXT_STEPS, CLASS_NEXT_STEPS };

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

@@ -67,6 +67,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 +101,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

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

@@ -25,6 +25,19 @@ 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 (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,6 +63,7 @@ function configure({
   _subscribeTerminalTail,
   _unsubscribeTerminalTail,
   _ensureCodexThreadLinkOffThread,
+  remoteCreateDeps,
 } = {}) {
   _deps = {
     handleCreatePrepared,
@@ -73,6 +87,7 @@ function configure({
     _subscribeTerminalTail,
     _unsubscribeTerminalTail,
     _ensureCodexThreadLinkOffThread,
+    remoteCreateDeps: remoteCreateDeps && typeof remoteCreateDeps === 'object' ? remoteCreateDeps : null,
   };
 }
 
@@ -225,6 +240,14 @@ 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 || {});
+  }
   return _deps.handleCreatePrepared(ctx.ws, msg);
 }
 
@@ -250,4 +273,12 @@ function register() {
   });
 }
 
-module.exports = { configure, register };
+module.exports = {
+  configure,
+  register,
+  // 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' }