create-walle 0.10.1 → 0.10.2

package/template/coding-task-manager/lib/session-host-manager.js

@@ -5,7 +5,6 @@ const { dispatchOwnedInputAck } = require('./host-input-ack');
 const { EventEmitter } = require('node:events');
 const { fork } = require('node:child_process');
 const fs = require('node:fs');
-const net = require('node:net');
 const path = require('node:path');
 const crypto = require('node:crypto');
 const { resolveRealNode } = require('./real-node'); const { hostDiagnosticFrame } = require('./host-diagnostic-frame');
@@ -18,13 +17,14 @@ const {
   isProcessAlive,
   probeHostAliveDetailed,
 } = require('./host-registry');
-const { CONTROL_CONNECTION_ROLE, encodeFrame, createFrameDecoder, PROTOCOL_VERSION, FLOOR_VERSION, HOST_HANDOFF_EXIT_CODE } = require('./host-control-protocol');
+const { HOST_HANDOFF_EXIT_CODE } = require('./host-control-protocol');
+const { dialControlSocketWithRetry: _dialControlSocketWithRetry } = require('./host-control-dial');
+const { postSocketFrameObserved, postIpcFrameObserved, postSelectedSocket, notePostRefusal, withAdapterPostObservation, forwardPostObservation, observeAdapterWrite } = require('./hosted-input-dispatch');
 const { isHostedAdapterLive, isHostedHeadlessLive, isHostedSessionStateAdoptable } = require('./hosted-adapter-liveness');
-const { hostRuntimeCompatibilityDecision } = require('./host-runtime-compatibility');
 const { hashClosureFiles } = require('./host-closure-hash');
 const { headlessMissingReplies } = require('./headless-missing-reply');
-const { resolveDialRetryDeadline, DIAL_MAX_STALL_EXTENSION_RATIO } = require('./host-dial-stall-clock');
 const { redialAdoptedHost } = require('./adopted-host-redial');
+const { sanitizeSessionOps, createOverdueEdgeTrigger } = require('./headless-inflight-ops'); // WP-0 (D-6/S-12): frame sessionOps + one-shot overdue edge
 const { dialHostState, shutdownHostSession } = require('./host-adopt-dial');
 const handoffOrchestrator = require('./host-handoff-orchestrator');
 const { applyModelHostReceipt, applyStartedModelHostReceipt } = require('./model-host-receipt');
@@ -49,162 +49,10 @@ function _openHostLogFd(dataDir, hostId) {
   }
 }
 
+// A1: the wire leaf (guard, encode, write, swallowed-failure boundary) moved to
+// lib/hosted-input-dispatch.js, where it observes its own outcome; this stays VOID for callers.
 function _writeFrame(conn, obj) {
-  if (!conn || conn.destroyed) return;
-  try { conn.write(encodeFrame(obj)); } catch { /* expected: connection may already be gone */ }
-}
-
-// Dial a host control socket within a stall-aware deadline. The first state frame
-// is judged by hostRuntimeCompatibilityDecision (a differing closure hash is adoptable); later frames
-// route to onFrame, while onState exposes adoptable session metadata.
-function _dialControlSocketWithRetry(socketPath, {
-  serverBootId, onFrame, onState, timeoutMs = 5000, retryDelayMs = 200,
-  protocolVersion = PROTOCOL_VERSION,
-} = {}) {
-  return new Promise((resolve, reject) => {
-    const budgetMs = Math.max(0, Number(timeoutMs) || 5000);
-    // Stall-aware, not fixed wall clock: see lib/host-dial-stall-clock.js for the incident where
-    // this deadline drained during the server's OWN boot freeze and a healthy pooled host was
-    // SIGTERM'd (taking its live sessions with it). `deadline` is reassigned as stall is credited
-    // back; `_stallExtendedMs` is the running total and is capped, so a permanently stalled
-    // server still times out rather than waiting forever.
-    let deadline = Date.now() + budgetMs;
-    let _stallExtendedMs = 0;
-    const maxStallExtensionMs = budgetMs * DIAL_MAX_STALL_EXTENSION_RATIO;
-    let settled = false;
-    let retryTimer = null, deadlineTimer = null, activeConn = null;
-    function finishOk(conn) {
-      if (settled) return;
-      settled = true;
-      clearTimeout(deadlineTimer);
-      resolve(conn);
-    }
-    function finishFail(err) {
-      if (settled) return;
-      settled = true;
-      clearTimeout(retryTimer); clearTimeout(deadlineTimer);
-      try { activeConn?.destroy(); } catch { /* expected: connection may already be gone */ }
-      reject(err || new Error('control socket dial failed'));
-    }
-    function armDeadlineWatchdog(scheduledAt = Date.now()) {
-      const delayMs = Math.max(1, deadline - scheduledAt);
-      deadlineTimer = setTimeout(() => {
-        const firedAt = Date.now();
-        const credited = resolveDialRetryDeadline({ deadline, scheduledAt, firedAt, retryDelayMs: delayMs,
-          extendedMs: _stallExtendedMs, maxExtensionMs: maxStallExtensionMs });
-        deadline = credited.deadline; _stallExtendedMs = credited.extendedMs;
-        if (firedAt < deadline) armDeadlineWatchdog(firedAt); else finishFail(new Error(`control socket handshake timed out after ${timeoutMs}ms`));
-      }, delayMs);
-      deadlineTimer.unref?.();
-    }
-    function scheduleRetry() {
-      if (settled) return;
-      if (Date.now() >= deadline) {
-        finishFail(new Error(
-          `control socket dial timed out after ${timeoutMs}ms`
-          + (_stallExtendedMs > 0 ? ` (+${_stallExtendedMs}ms credited for main-loop stall)` : ''),
-        ));
-        return;
-      }
-      const scheduledAt = Date.now();
-      retryTimer = setTimeout(() => {
-        // A retry that fires far later than it was armed for means OUR event loop was starved --
-        // that time is not evidence about the child, so give it back before re-testing the
-        // deadline above. Bounded by maxStallExtensionMs.
-        const credited = resolveDialRetryDeadline({
-          deadline,
-          scheduledAt,
-          firedAt: Date.now(),
-          retryDelayMs,
-          extendedMs: _stallExtendedMs,
-          maxExtensionMs: maxStallExtensionMs,
-        });
-        deadline = credited.deadline;
-        _stallExtendedMs = credited.extendedMs;
-        attempt();
-      }, retryDelayMs);
-      retryTimer.unref?.();
-    }
-    function attempt() {
-      if (settled) return;
-      // Do NOT dial before the host has created its socket. A connect to a missing unix socket
-      // makes node build an ExceptionWithHostPort and capture its stack, and this loop runs every
-      // retryDelayMs across every concurrent dial (pool + per-session + registry probes). Measured
-      // 2026-08-23 with the server's own auto-CPU-profiler, during a boot where a pooled host was
-      // being started:
-      //   top self-time frames: ExceptionWithHostPort (errors:765) 3290ms
-      //                       | defaultPrepareStackTrace (errors:95) 3256ms
-      //                       | (garbage collector) 752ms | checkError (destroy:33) 512ms
-      //                       | scheduleRetry (session-host-manager.js:89) 192ms
-      // i.e. ~6.5s of main-loop CPU spent building the retry loop's OWN connection errors. That
-      // block (`[perf-lag] Event loop blocked 6102ms`) is what then starved the very handshake it
-      // was polling for, until the dial "timed out" and the manager SIGTERM'd a healthy pooled
-      // host, killing its live sessions. A self-inflicted starvation loop.
-      //
-      // fs.access (async -- never sync I/O on the main loop) is a cheap stat that produces no
-      // exception object. This is a fast-path skip only: once the socket exists the dial below is
-      // byte-identical to before, and a socket that appears between this check and the connect
-      // still takes the ordinary error path.
-      fs.access(socketPath, fs.constants.F_OK, (missing) => {
-        if (settled) return;
-        if (missing) { scheduleRetry(); return; }
-        _connect();
-      });
-    }
-    function _connect() {
-      if (settled) return;
-      let conn;
-      let helloAcked = false;
-      try {
-        conn = net.createConnection(socketPath);
-        activeConn = conn;
-      } catch {
-        scheduleRetry();
-        return;
-      }
-      const decoder = createFrameDecoder({
-        onFrame: (msg) => {
-          if (!helloAcked) {
-            if (msg && msg.type === 'state') {
-              const diskClosureHash = hashClosureFiles(Array.isArray(msg.closureFiles) ? msg.closureFiles : []), hostClosureHash = String(msg.closureHash || '');
-              const compatibility = { ...hostRuntimeCompatibilityDecision({
-                expectedProtocol: protocolVersion, actualProtocol: msg.protocolVersion,
-                expectedFloor: FLOOR_VERSION, actualFloor: msg.floorVersion, diskClosureHash, hostClosureHash,
-              }), hostClosureHash, diskClosureHash };
-              if (!compatibility.compatible) {
-                helloAcked = true;
-                try { conn.destroy(); } catch { /* expected: already gone */ }
-                finishFail(Object.assign(
-                  new Error(`control socket host compatibility mismatch (${compatibility.reason})`),
-                  { code: 'HOST_INCOMPATIBLE', compatibilityReason: compatibility.reason },
-                ));
-                return;
-              }
-              helloAcked = true;
-              try { onState?.(msg, compatibility); } catch { /* expected: caller's onState must not wedge the dial */ }
-              finishOk(conn);
-            }
-            return;
-          }
-          if (typeof onFrame === 'function') onFrame(msg);
-        },
-        onError: () => { try { conn.destroy(); } catch { /* expected: already gone */ } },
-      });
-      conn.on('data', (chunk) => decoder.push(chunk));
-      conn.on('connect', () => {
-        try {
-          conn.write(encodeFrame({ type: 'hello', serverBootId, connectionRole: CONTROL_CONNECTION_ROLE.CONTROLLER, lastSeq: 0, protocolVersion, floorVersion: FLOOR_VERSION }));
-        } catch {
-          try { conn.destroy(); } catch { /* expected: already gone */ }
-        }
-      });
-      conn.on('error', () => { /* expected: close follows error and owns the sole retry */ });
-      conn.on('close', () => { if (!helloAcked) scheduleRetry(); });
-    }
-
-    attempt();
-    armDeadlineWatchdog();
-  });
+  postSocketFrameObserved(conn, obj);
 }
 
 const DEFAULT_START_TIMEOUT_MS = 5000;
@@ -248,6 +96,26 @@ function _sleep(ms) {
 
 const TERMINATE_ACK_TIMEOUT_MS = 1500;
 
+// WP-4 (clock-free-tests-followups-r4-2026-10-24.html §5 R-7, §6.5): stamp the FIRST
+// main-thread touch of a headless message with the receiving thread's own clock, so server.js
+// can price the receiver-loop leg (`frame-posted` -> `frame-arrived`) separately from the work
+// it does after (`mirror-revision`). Read-only instrumentation: the property is NON-enumerable, so
+// the message's shape is unchanged for every consumer that compares, spreads or serializes it (a
+// pool host's `serialized` missing reply is deep-equal to the shared headlessMissingReplies table),
+// and no decision anywhere reads it; server.js reads it off the same object. One helper for all three
+// transports (the dedicated host's IPC channel and control socket both funnel through
+// HostedPtyAdapter._handleChildMessage; the pool's fallback and the legacy worker path call it
+// themselves), so the value means the same thing whichever carried the frame. Returns the
+// message so a call site can chain it into its own emit.
+function _stampMainArrival(message) {
+  if (message && typeof message === 'object') {
+    Object.defineProperty(message, '_mainArrivedAt', {
+      value: Date.now(), enumerable: false, writable: true, configurable: true,
+    });
+  }
+  return message;
+}
+
 // WP-3: bound for adoptHost's dial. Plain const, not a flag -- a boot reconcile
 // pass adopting a handful of hosts is not a hot path.
 //
@@ -405,6 +273,15 @@ class HostedPtyAdapter {
       this.closed = true;
       this._manager?._unregister(this.sessionId, this);
       if (this._hostId) this._manager?._removeHostRecordAsync(this._hostId);
+      // WP-3 (session-stops-followups-2026-10-24.html, D-5): a dedicated host's
+      // death announces itself exactly like the pool's and an adopted host's, so
+      // the constructor's single 'host-exit' listener drops this hostId's frame
+      // clock and server.js's listener drops its readiness-ledger entry. Without it
+      // both outlived the host -- and since a dedicated hostId IS the sessionId (set
+      // in _startDedicated above), the next host for that session inherited the dead
+      // one's ledger misses (final-review fix I6, pool-only until now). Sits AFTER
+      // the `if (this.closed) return;` guard, so it fires once per host.
+      if (this._hostId) this._manager?.emit?.('host-exit', { hostId: this._hostId, kind: 'dedicated' });
       this._emitExitOnce({
         exitCode: Number.isFinite(code) ? code : 1,
         signal: signal || null,
@@ -465,32 +342,30 @@ class HostedPtyAdapter {
 
   _post(message) {
     if (this._pooled) {
-      return this._manager?._postToPool({ ...message, sessionId: message.sessionId || this.sessionId }) || false;
+      // A1: only a truly ABSENT manager refuses here; a present manager keeps its COPY + forwarded scope.
+      if (this._manager === undefined || this._manager === null) { notePostRefusal(message); return false; }
+      const forwarded = { ...message, sessionId: message.sessionId || this.sessionId };
+      return forwardPostObservation(message, forwarded, () => this._manager?._postToPool(forwarded)) || false;
     }
-    if (this.closed) return false;
+    if (this.closed) { notePostRefusal(message); return false; }
     // WP-1 (deliverable 2): once the control flip has succeeded, ALL control +
     // data goes over the socket -- IPC is no longer used to send.
     if (this._transport === 'socket' && this._socketConn && !this._socketConn.destroyed) {
-      try {
-        _writeFrame(this._socketConn, message);
-        return true;
-      } catch (err) {
-        this._events.emit('host-error', err);
-        return false;
-      }
-    }
-    if (!this._child || !this._child.connected) return false;
-    try {
-      this._child.send(message);
-      return true;
-    } catch (err) {
-      this._events.emit('host-error', err);
-      return false;
+      return postSelectedSocket(() => this._socketConn, message, (err) => this._events.emit('host-error', err));
     }
+    // The helper owns the ONE missing/disconnected refusal AND the legacy try/send/host-error boundary.
+    return postIpcFrameObserved(this._child, message, (err) => this._events.emit('host-error', err)).posted;
   }
 
   _handleChildMessage(msg) {
     if (!msg || typeof msg !== 'object') return;
+    // WP-3 (session-stops-mid-job-2026-10-24.html, D-10): every frame a host
+    // sends -- PTY data, exit, threadpool report, serialize reply, control
+    // replies -- proves it alive. Recorded under the SAME hostId the readiness
+    // ledger keys on (lib/ws/state-sync.js derives it via
+    // SessionHostManager.hostIdForSession), so a pooled session records under
+    // its pool's `pool-<pid>`, not under its own sessionId. Cheap: one Map.set.
+    this._manager?._noteHostFrame?.(this._manager?.hostIdForSession?.(this.sessionId) || this._hostId);
     switch (msg.type) {
       case 'ready':
         if (this._hostId) {
@@ -536,7 +411,10 @@ class HostedPtyAdapter {
         });
         return;
       case 'headless-message':
-        this._manager?._emitHeadlessMessage(msg.message || {});
+        // WP-4 (R-7): the first main-thread touch of this frame on BOTH dedicated-host
+        // transports -- the IPC channel's child.on('message') and the control socket's
+        // onFrame --- converge on this switch.
+        this._manager?._emitHeadlessMessage(_stampMainArrival(msg.message || {}));
         return;
       case 'snapshot':
         this._headlessReady = true;
@@ -616,7 +494,19 @@ class HostedPtyAdapter {
   // exists once the host's 'input-ack' frame comes back (see _handleChildMessage's
   // 'input-ack' case and the manager's onInputAck hook). `inputSeq` correlates the two.
   write(data, { inputSeq } = {}) {
-    return this._post({ type: 'input', sessionId: this.sessionId, data: String(data || ''), inputSeq: Number(inputSeq) || 0 }) === true;
+    // A1: the frame is built here exactly as before, then handed to the ACTUAL selected `_post`
+    // through the observation scope, so an observed write can report what THIS route did while the
+    // legacy `=== true` Boolean keeps its exact meaning.
+    const message = { type: 'input', sessionId: this.sessionId, data: String(data || ''), inputSeq: Number(inputSeq) || 0 };
+    return withAdapterPostObservation(this, message, () => this._post(message)) === true;
+  }
+
+  // A1: observe ONE dispatch through the ACTUAL selected writer (never a prototype bypass). The
+  // result is diagnostic data -- `posted` mirrors the selected writer's own legacy result and the
+  // disposition says only how much this module actually saw. It is not byte-write, ack or
+  // no-post proof, and it grants no caller any withdrawal authority.
+  writeObserved(data, { inputSeq } = {}) {
+    return observeAdapterWrite(this, () => this.write(data, { inputSeq }));
   }
 
   resize(cols, rows) {
@@ -793,10 +683,28 @@ class SessionHostManager extends EventEmitter {
     // only, same seam shape as _onDiagnostic -- never a path that kills/respawns/migrates
     // anything on 'stalled' (see _handleThreadpoolFrame below and its AC-0c test).
     this._threadpoolStates = new Map();
+    // WP-3 (session-stops-mid-job-2026-10-24.html, D-10): hostId -> the last
+    // instant ANY frame arrived from that host. This is the readiness ledger's
+    // ONE liveness input (server.js injects `lastFrameAt` into it): a hard
+    // serialize miss on a host whose lastFrameAt is newer than the request was
+    // issued is 'degraded' (readiness), never a kill. Written by
+    // HostedPtyAdapter._handleChildMessage and _handleThreadpoolFrame below on
+    // every received frame; dropped when the manager announces 'host-exit'.
+    this._hostFrameAt = new Map();
+    // WP-3 (session-stops-followups-2026-10-24.html, D-6): the ONE place a host's
+    // frame clock is dropped. Every death path announces itself as
+    // 'host-exit {hostId, kind}' -- pool, adopted (lib/adopted-host-redial.js) and
+    // dedicated (HostedPtyAdapter's child 'exit' handler below) -- so a future death
+    // path is covered by emitting that event alone, and no call site can forget the
+    // clock (the pre-D-6 inline delete at the pool exit left the adopted and
+    // dedicated paths leaking it).
+    this.on('host-exit', ({ hostId } = {}) => { if (hostId) this._hostFrameAt.delete(String(hostId)); });
     this._onThreadpoolReport = typeof options.onThreadpoolReport === 'function' ? options.onThreadpoolReport : null;
     // D-2 (pty-host-threadpool-stranded-waiters-2026-09-25.html): report-only seam for
     // input-ack frames -- server.js's _onHostInputAck. Same shape as onThreadpoolReport.
     this._onInputAck = typeof options.onInputAck === 'function' ? options.onInputAck : null; this._onSessionDiagnostic = typeof options.onSessionDiagnostic === 'function' ? options.onSessionDiagnostic : null; // probe: host-diagnostic rows
+    // WP-0 (D-6): at most one report-only headless-op-overdue diagnostic per (hostId, sid8, seq).
+    this._headlessOpOverdue = createOverdueEdgeTrigger();
   }
 
   createPty(options = {}) {
@@ -1152,12 +1060,18 @@ class SessionHostManager extends EventEmitter {
   // (never a per-tick echo -- the monitor itself already only frames on transition or once
   // per its own report interval, but this dedupes defensively against redelivery), and
   // forwards every frame to the optional onThreadpoolReport hook (server.js's __host__
-  // diagnostic-row writer + golden-signals feed) -- report-only, exactly like _onDiagnostic;
-  // nothing here ever kills/respawns/migrates a host (AC-0c).
+  // diagnostic-row writer + golden-signals feed) -- report-only, exactly like _onDiagnostic; nothing
+  // here kills/respawns/migrates a host (09-25 AC-0c). WP-3 supersedes that for the SUPERVISOR only: server.js's onThreadpoolReport -> hostHealth.recordThreadpool -> evacuateStalledHost evacuates a stalled host (docs/stale-pty-host-evacuation-2026-10-24.html §5 D-3, §9 S-6).
   _handleThreadpoolFrame(hostId, msg) {
     if (!msg || typeof msg !== 'object') return;
+    // WP-3 (D-10): a threadpool report is a frame like any other -- the host's
+    // main thread is alive and talking even when its threadpool is wedged (the
+    // exact 2026-10-24 shape: stalled for 68 min while PTY I/O kept flowing).
+    this._noteHostFrame(hostId);
     const state = msg.state === 'stalled' ? 'stalled' : 'ok';
     const prev = this._threadpoolStates.get(hostId);
+    // WP-0 (D-6): the frame's per-session view, sanitized to strings/numbers and capped at 5.
+    const sessionOps = sanitizeSessionOps(msg.sessionOps, 5);
     const snapshot = {
       hostId,
       pid: Number.isFinite(msg.pid) ? msg.pid : (prev?.pid ?? null),
@@ -1167,12 +1081,22 @@ class SessionHostManager extends EventEmitter {
       requestsPerMin: Number(msg.requestsPerMin) || 0,
       byType: msg.byType && typeof msg.byType === 'object' ? { ...msg.byType } : {},
       probeMs: Number.isFinite(msg.probeMs) ? msg.probeMs : null,
+      sessionOps,
       receivedAt: Date.now(),
     };
     this._threadpoolStates.set(hostId, snapshot);
     if (!prev || prev.state !== state) {
       this.logger.warn?.(`[session-host-pool] threadpool-${state} hostId=${hostId} pid=${snapshot.pid} pendingRequests=${snapshot.pendingRequests} oldestPendingMs=${snapshot.oldestPendingMs}`);
     }
+    // WP-0 (D-6/AC-0c): one report-only diagnostic per (hostId, sid8, seq) at >= 30 s. Never
+    // rejects/times out/reorders an op, and never touches host or session state.
+    for (const hit of this._headlessOpOverdue.next(sessionOps, hostId, (sid8) => {
+      for (const sid of this.hosts.keys()) if (sid.startsWith(sid8)) return sid;
+      return sid8;
+    })) {
+      try { this._onSessionDiagnostic?.(hit.sessionId, 'headless-op-overdue', hit.details); }
+      catch (err) { this.logger.warn?.(`[session-host-pool] onSessionDiagnostic hook threw: ${err?.message || err}`); }
+    }
     if (this._onThreadpoolReport) {
       try { this._onThreadpoolReport(snapshot); }
       catch (err) { this.logger.warn?.(`[session-host-pool] onThreadpoolReport hook threw: ${err?.message || err}`); }
@@ -1236,6 +1160,23 @@ class SessionHostManager extends EventEmitter {
     return null;
   }
 
+  // WP-3 (session-stops-mid-job-2026-10-24.html, D-10): the per-host frame clock.
+  // `_noteHostFrame` is called for every frame a host sends (see
+  // HostedPtyAdapter._handleChildMessage and _handleThreadpoolFrame); `lastFrameAt`
+  // is the public read server.js injects into lib/host-health-ledger.js. One
+  // Map.set per frame -- no allocation beyond that, no event emitted per frame.
+  _noteHostFrame(hostId) {
+    const id = String(hostId || '');
+    if (!id) return;
+    this._hostFrameAt.set(id, Date.now());
+  }
+
+  lastFrameAt(hostId) {
+    const id = String(hostId || '');
+    if (!id) return 0;
+    return this._hostFrameAt.get(id) || 0;
+  }
+
   // WP-1: reconstructs the same shape of record `_shutdownOrphanHost` (server.js)
   // expects -- {hostId, kind, pid, socketPath, sessionIds} -- from this manager's
   // own live routing state, so the revive path never has to block on an async
@@ -1384,11 +1325,17 @@ class SessionHostManager extends EventEmitter {
       // prototype's IPC fallback can never fire) -- redial on write failure
       // (lib/adopted-host-redial.js) instead of failing forever.
       adapter._post = (message) => {
-        if (adapter.closed) return false;
+        if (adapter.closed) { notePostRefusal(message); return false; }
+        // A1: this per-instance override stays the selected route for an adopted host. The helper
+        // owns the WHOLE second-lookup/write/error boundary, so a caught failure falls through to
+        // this adapter's ORIGINAL redial (never lost, never doubled) and only a genuinely missing
+        // socket refuses here.
         if (adapter._socketConn && !adapter._socketConn.destroyed) {
-          try { _writeFrame(adapter._socketConn, message); return true; }
-          catch (err) { adapter._events.emit('host-error', err); } // HANDLE: fall through to redial below
+          if (postSelectedSocket(() => adapter._socketConn, message, (err) => adapter._events.emit('host-error', err))) return true;
+          this._redialAdoptedHost(hostId, socketPath);
+          return false;
         }
+        notePostRefusal(message);
         this._redialAdoptedHost(hostId, socketPath);
         return false;
       };
@@ -1495,12 +1442,12 @@ class SessionHostManager extends EventEmitter {
 
   // WP-3 (fix round 1, P1-2): dispatch for frames arriving on an ADOPTED host's
   // connection -- pooled OR dedicated, both now route here rather than through
-  // _handlePoolMessage's manager-global pool special cases. Scoped by hostId so a
-  // manager that has adopted more than one host at once routes each connection's
-  // frames only to its own adapter(s).
+  // _handlePoolMessage's manager-global pool special cases. Scoped by hostId so a manager that has adopted more
+  // than one host at once routes each connection's frames only to its own adapter(s).
   _routeAdoptedFrame(hostId, msg, originConnection) {
     if (!msg || typeof msg !== 'object') return;
     const sessionId = String(msg.sessionId || '');
+    if (msg.type === 'host-threadpool') { this._handleThreadpoolFrame(hostId, msg); return; } // stale-pty-host-evacuation S-7: host-wide (no sessionId) -- an adopted stalled host must reach the ledger
     if (msg.type === 'shutdown-session-ack') { this._shutdownSessionWaiters.get(sessionId)?.(true); return; }
     if (String(msg.type).startsWith('handoff-')) { handoffOrchestrator.routeFrame(this, hostId, msg); return; }
     const adapter = sessionId ? this.hosts.get(sessionId) : null;
@@ -1778,7 +1725,13 @@ class SessionHostManager extends EventEmitter {
       // drops this hostId. Without it the per-hostId misses outlived the host, and
       // since a hostId is `pool-<pid>`, a LATER host reusing that pid inherited the
       // dead one's miss count and could be killed on its first deadline miss.
-      if (exitingPoolHostId) this.emit('host-exit', { hostId: exitingPoolHostId, kind: 'pool' });
+      if (exitingPoolHostId) {
+        // WP-3 (session-stops-followups-2026-10-24.html, D-5/D-6): announce only --
+        // the constructor's single 'host-exit' listener owns dropping this hostId's
+        // frame clock (with its ledger entry), so a later host reusing the same
+        // `pool-<pid>` id can never inherit it. No inline delete here.
+        this.emit('host-exit', { hostId: exitingPoolHostId, kind: 'pool' });
+      }
       for (const host of Array.from(this.hosts.values())) {
         if (!host._pooled || host._adopted || host.closed || host._hostId !== exitingPoolHostId && host._hostId) continue; // WP-4: a re-pointed adapter no longer belongs to this exiting pool
         host.closed = true;
@@ -1797,26 +1750,14 @@ class SessionHostManager extends EventEmitter {
 
   _postToPool(message) {
     const child = this._ensurePool();
-    if (!child || this._poolClosed) return false;
+    // A1: an absent/closed pool posts nothing -- recorded as a refusal, joined CONSERVATIVELY below.
+    if (!child || this._poolClosed) { notePostRefusal(message); return false; }
     // WP-1 (deliverable 2): once the pool's control flip has succeeded, ALL
     // control + data goes over the socket -- IPC is no longer used to send.
     if (this._poolTransport === 'socket' && this._poolSocketConn && !this._poolSocketConn.destroyed) {
-      try {
-        _writeFrame(this._poolSocketConn, message);
-        return true;
-      } catch (err) {
-        this._emitHostError(message?.sessionId || '', err);
-        return false;
-      }
-    }
-    if (!child.connected) return false;
-    try {
-      child.send(message);
-      return true;
-    } catch (err) {
-      this._emitHostError(message?.sessionId || '', err);
-      return false;
+      return postSelectedSocket(() => this._poolSocketConn, message, (err) => this._emitHostError(message?.sessionId || '', err));
     }
+    return postIpcFrameObserved(child, message, (err) => this._emitHostError(message?.sessionId || '', err)).posted;
   }
   _handlePoolMessage(msg, sourceChild = null) {
     if (sourceChild && sourceChild !== this._poolChild) return;
@@ -1893,7 +1834,9 @@ class SessionHostManager extends EventEmitter {
           return;
         }
       }
-      this._emitHeadlessMessage(inner);
+      // WP-4 (R-7): the pool's own arrival stamp for a frame with no routed adapter above --
+      // same helper, so a pooled frame and a dedicated one answer the same question.
+      this._emitHeadlessMessage(_stampMainArrival(inner));
     } else if (msg.type === 'host-diagnostic') { hostDiagnosticFrame(this, sessionId, msg); // no adapter routed yet (successor restore)
     } else if (msg.type === 'host-error') {
       const err = new Error(msg.message || 'session host pool error');
@@ -1934,7 +1877,10 @@ class HeadlessTerminalRouter extends EventEmitter {
         return;
       }
       if (msg?.type === 'worker-error') this._scheduleStatusRefresh();
-      this.emit('message', msg);
+      // WP-4 (R-7): the legacy worker transport is a third arrival path into the same 'message'
+      // event the two hosted ones feed -- stamp it here so a frame's `_mainArrivedAt` means the
+      // same thing regardless of which transport delivered it.
+      this.emit('message', _stampMainArrival(msg));
     });
     this.legacyWorker.on('error', (err) => this.emit('error', err));
     this.sessionHostManager.on('headless-message', (msg) => this.emit('message', msg));
@@ -2042,5 +1988,5 @@ module.exports = {
   HeadlessTerminalRouter,
   createSessionHostManager,
   createHeadlessTerminalRouter,
-  _internals: { ADOPT_DIAL_TIMEOUT_MS },
+  _internals: { ADOPT_DIAL_TIMEOUT_MS, _stampMainArrival },
 };

package/template/coding-task-manager/lib/session-jobs.js

@@ -175,35 +175,38 @@ function registerSessionJobs(scheduler, deps) {
     }
     return false;
   }
+  // WP-6: the window reports WHY it is quiet -- a short reason string, '' when maintenance may run. Its only
+  // caller uses the value for truthiness, so this is a naming change, not a behaviour change; the transcript
+  // archive job passes the reason through to its own `deferred` log line.
   function _isInStartupMaintenanceQuietWindow() {
-    if (typeof isRestoreInProgress === 'function' && isRestoreInProgress()) return true;
+    if (typeof isRestoreInProgress === 'function' && isRestoreInProgress()) return 'restore_in_progress';
     // Defer while the single serial db-owner worker is degraded under load: piling more
     // maintenance onto a struggling worker deepens the contention cascade that wedges the
     // cold-boot storm. The scheduler re-runs the job once the worker recovers.
-    if (typeof isDbWorkerDegraded === 'function' && isDbWorkerDegraded()) return true;
+    if (typeof isDbWorkerDegraded === 'function' && isDbWorkerDegraded()) return 'db_worker_degraded';
     // Just woke from a process suspension (laptop sleep): the wake backlog (imports/restore/harvest)
     // fires at once and saturates the serial db-owner worker → main-loop freezes. Hold heavy
     // maintenance for a short grace window so the burst drains before we pile more on (mirrors the
     // degraded-worker defer above, but catches the INITIAL wake wave before degradation sets in).
-    if (typeof recentlyResumedFromSleep === 'function' && recentlyResumedFromSleep()) return true;
+    if (typeof recentlyResumedFromSleep === 'function' && recentlyResumedFromSleep()) return 'resumed_from_sleep';
     // isDbWarming() is currently a retired compatibility gate; keep honoring it
     // here so any future SQLite-owned warmup can defer maintenance safely. The
     // fixed startup grace below remains the active maintenance quiet window.
-    if (typeof isDbWarming === 'function' && isDbWarming()) return true;
-    if (typeof canAdmitTierB === 'function' && !canAdmitTierB()) return true;
+    if (typeof isDbWarming === 'function' && isDbWarming()) return 'db_warming';
+    if (typeof canAdmitTierB === 'function' && !canAdmitTierB()) return 'tier_b_refused';
     if (typeof getServerStartedAt === 'function') {
       const startedAt = Number(getServerStartedAt());
       if (Number.isFinite(startedAt) && startedAt > 0 && (Date.now() - startedAt) < STARTUP_MAINTENANCE_GRACE_MS) {
-        return true;
+        return 'startup_grace';
       }
     }
     if (typeof getRestoreCompletedAt === 'function') {
       const completedAt = Number(getRestoreCompletedAt());
       if (Number.isFinite(completedAt) && completedAt > 0 && (Date.now() - completedAt) < STARTUP_MAINTENANCE_GRACE_MS) {
-        return true;
+        return 'restore_grace';
       }
     }
-    return false;
+    return '';
   }
   // Interactive guard: heavy maintenance jobs (the io-pool scans) must not START
   // their synchronous DB/fs work within INTERACTIVE_DEFER_MS of a user keystroke.
@@ -231,6 +234,11 @@ function registerSessionJobs(scheduler, deps) {
     _interactiveDeferSince = 0;
     return true;
   }
+  // WP-6: why `_canRunStartupMaintenance` is holding a heavy job back, in the same words the transcript
+  // archive job logs. '' means nothing is holding it back.
+  function _maintenanceDeferReason() {
+    return _isInStartupMaintenanceQuietWindow() || (_userInteractingNow() ? 'user_typing' : '');
+  }
 
   let sessionMetadataSyncCursor = 0;
   let sessionMetadataSyncTick = 0;
@@ -1104,7 +1112,7 @@ function registerSessionJobs(scheduler, deps) {
     });
   }
 
-  if (deps.runConversationSummaryBackfill) require('./conversation-summary-backfill').registerJob(scheduler, deps.runConversationSummaryBackfill, _canRunStartupMaintenance); if (deps.transcriptGuard && deps.transcriptArchiveEnv) require('./transcript-guard-job').registerArchiveJob(scheduler, deps.transcriptGuard, deps.transcriptArchiveEnv, _canRunStartupMaintenance); // D-19 transcript archive
+  if (deps.runConversationSummaryBackfill) require('./conversation-summary-backfill').registerJob(scheduler, deps.runConversationSummaryBackfill, _canRunStartupMaintenance); if (deps.transcriptGuard && deps.transcriptArchiveEnv) require('./transcript-guard-job').registerArchiveJob(scheduler, deps.transcriptGuard, deps.transcriptArchiveEnv, _canRunStartupMaintenance, _maintenanceDeferReason); // D-19 transcript archive
   // --- message-backfill: maintain legacy session_messages FTS from canonical rows ---
   if (deps.backfillSessionMessages) {
     scheduler.register({

package/template/coding-task-manager/lib/session-lifecycle.js

@@ -728,6 +728,10 @@ function percentile(values, ratio) {
   return sorted[Math.min(sorted.length - 1, Math.max(0, Math.ceil(sorted.length * ratio) - 1))];
 }
 
+// WP-3 (§5 D-8): the skip-reason vocabulary lives in its own module (so server.js can name tokens
+// without growing); re-exported here for the existing importers.
+const { WAKE_SKIP_REASONS } = require('./wake-skip-reasons');
+
 class LifecycleDiagnostics {
   constructor({ maxEvents = 200 } = {}) {
     this.maxEvents = Math.max(1, maxEvents);
@@ -740,6 +744,10 @@ class LifecycleDiagnostics {
     this.events = [];
     this.wake = new Map();
     this.wakeOutcomes = {};
+    // WP-3 (§5 D-6): skip-reason counter for the pre-gate deferred-restore bails -- the ones that
+    // precede _wakeStartedAt and so can never be counted by wakeOutcomes ("65 deferred, zero
+    // wakes" was invisible for exactly this reason).
+    this.wakeSkips = {};
   }
 
   _count(target, key) { target[key] = (target[key] || 0) + 1; }
@@ -818,6 +826,14 @@ class LifecycleDiagnostics {
     this._event({ type: 'wake-outcome', id, provider, outcome, phases: { ...phases } });
   }
 
+  // WP-3 (§5 D-6/D-8): the sibling of recordWakeOutcome for the pre-gate bails. `reason` is a
+  // WAKE_SKIP_REASONS token (CamelCase, machine-readable — the K8s-condition convention); a
+  // caller that still passes a legacy human string is recorded verbatim rather than dropped.
+  recordWakeSkip({ id = '', provider = 'unknown', reason = 'Unclassified' } = {}) {
+    this._count(this.wakeSkips, reason);
+    this._event({ type: 'wake-skip', id, provider, reason });
+  }
+
   snapshot(extra = {}) {
     const wakeLatency = {};
     for (const [provider, entry] of this.wake) {
@@ -834,6 +850,7 @@ class LifecycleDiagnostics {
       shadow: { ...this.shadow },
       pressureTransitions: this.pressureTransitions,
       wakeOutcomes: { ...this.wakeOutcomes },
+      wakeSkips: { ...this.wakeSkips },
       wakeLatency,
       events: [...this.events],
       ...extra,
@@ -844,6 +861,7 @@ class LifecycleDiagnostics {
 module.exports = {
   ActivationGate,
   LifecycleDiagnostics,
+  WAKE_SKIP_REASONS,
   MemoryBudgetController,
   PressureController,
   automaticParkSweepPolicy,