create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/terminal-input-prepared.js

@@ -0,0 +1,563 @@
+'use strict';
+
+// Landing-throughput WP-6 shard S10 (design doc §5 D-10 "move-only", §6 "Shard module
+// seam"): the terminal-input-prepared cluster moves out of server.js VERBATIM into this
+// module behind the same configure(deps) seam as lib/api/session-attach.js and
+// lib/terminal-attach-geometry.js (S6), lib/walle-history-serve.js (S8) and
+// lib/codex-rollout-history.js (S9). It registers NO route and NO socket handler: server.js
+// keeps the two pass-through callers (handleInput, _executeTerminalInputPlan) as
+// terminalInputPrepared._handleInputPrepared(...), plus this configure() seam.
+// Bodies are identical to server.js's declarations except for the `_deps.` prefix on every
+// identifier that used to resolve to a server.js top-level binding (D-10 rule 1), proven by
+// `node bin/move-only-check.js`. No moved body contains an inline `require(...)`, so there
+// is no require rebase here (unlike S1/S3/S6/S8).
+//
+// The module deliberately lives at lib/terminal-input-prepared.js and NOT under lib/ws/:
+// _handleInputPrepared is the keystroke admission/prepare seam, not a ws-router handler.
+//
+// Injected deps, per function:
+//   _wakeDeferredOnInput: _lifecycleClientKind, _recordRuntimeInputOutcome,
+//     _scheduleDeferredRestoreStart, _sendWsJsonBounded, promptSubmissionContract
+//   _runtimeInputMetadataForDeferredMessage: agentSessionKernel
+//   _recordAcceptedInteractiveInputForAnalysis: _analysisWorkerCoordinator,
+//     _lastUserInteractiveInputAt (get/set pair -- the moved body WRITES it)
+//   _handleInputPrepared: CODEX_BULK_INPUT_REDRAW_COALESCE_MS,
+//     CODEX_BULK_INPUT_REDRAW_WINDOW_MS, CTM_CLASSIFY_TAIL_BOUND, INPUT_READY_GATE_ENABLED,
+//     STATUS_EVIDENCE, _approverState, _clearManualApprovalReview, _clearRestoreInterruption,
+//     _clearTerminalInputEchoSuppression, _codexComposerBulkInputData,
+//     _emitOwnerMismatchDiagnostic, _impliedView, _inputMayResolveWaiting,
+//     _isServerWaitingForInput, _markMeaningfulActivity, _markServerSessionTurnOpen,
+//     _markSessionUserPromptInput, _markTerminalNonResolvingInputEcho,
+//     _maybeHandoffPrimaryOnInteract, _ownerDecisionInvalidRequest, _ownerRecovery,
+//     _prepareRestoreReplaySuppressionForInput, _recordInputAbortKeyDiagnostic,
+//     _recordRuntimeInputAcceptedForSession, _recordRuntimeInputOutcome,
+//     _recordRuntimeInputResultForSession, _recordStatusEvidence, _resendBlockedByParkQueue,
+//     _resumePromptNavigationDigits, _runtimeAdapterForSession,
+//     _runtimeAgentSessionIdForSession, _runtimeInputBaseForSession, _sendWsJsonBounded,
+//     _serverRawTerminalInputDecision, _sessionOwnerDecision,
+//     _standupIsBlockingWaitingReason, _standupWaitingReason, _terminalInputEchoTextFromInput,
+//     _terminalProcessGeneration, _updateCodexComposerInputState, _writeInputWithEchoTracking,
+//     _writeLifecyclePty, agentSessionKernel, approvalAgent, approvalSelfAdapt,
+//     approverDebugRings, autoApprovalBuffers, dbModule, detectAgentType, emitHumanSubmit,
+//     enqueueDeferredInput, evaluateResumeGateInput, idleNotifyState, isPureMouseReportInput,
+//     promptSubmissionContract, recordSessionDiagnostic, remoteTerminalTarget, restoreRuntime,
+//     resumePolicyForAttempt, runtimeInputPhaseCache, sessionInputAuthority, sessions,
+//     shouldWakeDeferredOnRawInput, terminalFirstPromptInputMatches,
+//     terminalInputAdmissionFacts
+//
+// Mutable module state (D-10 rule 2 / S9 lesson 7): _lastUserInteractiveInputAt is the ONE
+// server.js binding a moved body WRITES (_recordAcceptedInteractiveInputForAnalysis), so it
+// is injected as a getter/setter pair (S3/S9 precedent, lib/api/session-messages.js) -- never
+// a copy. _ownerRecovery is a server.js `let` reassigned once during boot (server.js:7907),
+// so it is injected as a getter too. Every other dep is a by-value reference; calls between
+// the four moved functions stay direct (no _deps.).
+//
+// One syntax-forced deviation from rule 1 (reported): `dbModule` appears twice as an
+// object-literal SHORTHAND property inside _handleInputPrepared
+// (`{ sessionId: msg.id, dbModule }`). `_deps.dbModule` cannot be written in shorthand
+// position, so those two sites keep the bare identifier, resolved by the module-scope alias
+// below (assigned by configure()). Expanding the shorthand to `dbModule: _deps.dbModule`
+// instead would make move-only-check report `DIFF at ...properties[N].shorthand` (the AST
+// comparison includes the shorthand flag) for a change that is not semantic. dbModule is a
+// server.js `const` (never rebound), so the by-value alias is behaviour-identical.
+
+let _deps = null;
+let dbModule = null; // bare alias for the two shorthand sites above -- see the header note
+
+function configure(deps = {}) {
+  _deps = deps;
+  dbModule = deps.dbModule;
+}
+
+// WP-1 (live-defer-wake-adopted-host-death-2026-10-28.html §5 R-1/R-2): the ONE deferred-wake
+// block -- a raw keystroke on a session whose process died under an open tab (_restoreDeferred,
+// ptyProcess null) schedules the revive and is answered with the existing
+// session_resume_not_ready drop payload, exactly like the non-raw wake site below.
+function _wakeDeferredOnInput(session, ws, msg) {
+  _deps._scheduleDeferredRestoreStart(session, { source: 'input', clientKind: _deps._lifecycleClientKind(ws, msg),
+    cols: msg.cols || session._ptyCols || 120, rows: msg.rows || session._ptyRows || 30,
+    terminalDimsMeasured: msg.terminalDimsMeasured === true,
+  });
+  if (ws?.readyState === 1) _deps._sendWsJsonBounded(ws,
+    _deps.promptSubmissionContract.buildInputDroppedPayload(msg, 'session_resume_not_ready'));
+  return _deps._recordRuntimeInputOutcome(session, msg, 'refused', 'session_resume_not_ready');
+}
+
+function _runtimeInputMetadataForDeferredMessage(msg, source = 'composer') {
+  const clientMessageId = _deps.agentSessionKernel.normalizeClientMessageId(msg?.clientMessageId);
+  return clientMessageId ? {
+    clientMessageId,
+    source: String(msg?.source || source),
+    recordText: String(msg?.recordText !== undefined ? msg.recordText : msg?.data || ''),
+  } : {};
+}
+
+function _recordAcceptedInteractiveInputForAnalysis(now = Date.now()) {
+  _deps._lastUserInteractiveInputAt = now;
+  _deps._analysisWorkerCoordinator.recordAcceptedInput();
+}
+
+async function _handleInputPrepared(ws, msg, existingInput, options = {}) {
+  const recoveryBlock = _deps._ownerRecovery.rejectRequest(ws, msg); if (recoveryBlock) return recoveryBlock;
+  const initialTargetRefusal = _deps.remoteTerminalTarget.terminalInputRefusal(options);
+  if (initialTargetRefusal) return initialTargetRefusal;
+  let session = _deps.sessions.get(msg.id);
+  if (session) {
+    // D-3: a keystroke for a session this socket is not viewing is a client bug -- implied-view
+    // it (see _impliedView) so frames start flowing, but never refuse the keystroke on this
+    // account (that is WP-2's admission concern, unchanged here).
+    if (ws && options.trustedInternal !== true) _deps._impliedView(ws, msg.id, 'input');
+    const rawTerminalInput = options.trustedInternal !== true;
+    const ownerDecision = _deps._sessionOwnerDecision(msg.id);
+    if (!ownerDecision.ok) {
+      if (_deps._ownerDecisionInvalidRequest(ownerDecision)) return;
+      _deps._emitOwnerMismatchDiagnostic(ownerDecision);
+    }
+    // User-input priority: mark the session as human-driven so the auto-approver backs off
+    // (its y/Enter/backspace must not interleave with the user's arrow navigation at a prompt).
+    _deps.approvalAgent.markUserActive(msg.id); if (rawTerminalInput && options.authenticatedRemote !== true && String(msg.data).includes('\r')) _deps.emitHumanSubmit(msg.id); // WP-5 D-13: an Enter keystroke is a human submit
+    if (session._resumeBlocked && !rawTerminalInput) {
+      if (ws?.readyState === 1) {
+        _deps._sendWsJsonBounded(ws, _deps.promptSubmissionContract.buildInputDroppedPayload({
+          id: session.id,
+          clientMessageId: _deps.agentSessionKernel.normalizeClientMessageId(msg?.clientMessageId),
+        }, 'session_resume_blocked'));
+      }
+      return _deps._recordRuntimeInputOutcome(session, msg, 'refused', 'session_resume_blocked');
+    }
+    // Every WebSocket `input` message is a raw PTY attempt, including legacy messages that omit
+    // inputChannel. Only a server-internal caller can supply this out-of-band option; a message
+    // field must never grant a client a semantic-channel bypass.
+    const admissionMessage = options.authenticatedRemote === true
+      ? {
+        ...msg,
+        resumeGeneration: Number(session._launchPlanGeneration || 0),
+        processGeneration: _deps._terminalProcessGeneration(session),
+      }
+      : msg;
+    const terminalAdmissionFacts = _deps.terminalInputAdmissionFacts(
+      session, { ...admissionMessage, inputChannel: rawTerminalInput ? 'terminal' : msg.inputChannel },
+      _deps._terminalProcessGeneration,
+    );
+    const rawDecision = rawTerminalInput
+      ? _deps._serverRawTerminalInputDecision(session, ws, options, msg)
+      : null;
+    const terminalAdmission = rawTerminalInput
+      ? (rawDecision.allowed
+        ? { outcome: 'allowed', allowed: true, reason: 'route_live', complete: true, advisory: [] }
+        : {
+          outcome: 'rejected', allowed: false,
+          reason: rawDecision.reason.replaceAll('-', '_'),
+          complete: true, advisory: [],
+        })
+      : _deps.sessionInputAuthority.admit(session.id, ws, terminalAdmissionFacts);
+    // C-1: a granted-but-stale lease no longer holds the keystroke -- re-seed the owner instead.
+    // Item B: only reseed on an actually-admitted keystroke -- a rejected admission carries no
+    // baseline-stale advisory of its own worth re-arming a reprojection for.
+    if (terminalAdmission.outcome === 'rejected') {
+      // WP-1 (R-1): a raw keystroke to a deferred session wakes it instead of being refused
+      // pty_unavailable -- the raw refusal below would otherwise return before the wake. Only a
+      // genuine pty_unavailable rejection on a writable socket wakes (a read-only secondary
+      // viewer's keystroke must never respawn the session).
+      if (_deps.shouldWakeDeferredOnRawInput({
+        rawTerminalInput,
+        rejectionReason: terminalAdmission.reason,
+        readOnly: rawDecision?.readOnly === true,
+        restoreDeferred: session._restoreDeferred === true,
+        parking: !!session._parking,
+      })) return _wakeDeferredOnInput(session, ws, msg);
+      if (terminalAdmission.complete !== true) {
+        _deps.recordSessionDiagnostic(session.id, 'terminal-input-authority-incomplete', {
+          reason: terminalAdmission.reason,
+          socketGeneration: Number(ws?.socketGeneration || 0),
+        });
+      }
+      _deps.recordSessionDiagnostic(session.id, 'terminal-input-refused', {
+        reason: terminalAdmission.reason,
+        generation: Number(msg.resumeGeneration || 0),
+        processGeneration: Number(msg.processGeneration || 0),
+        expectedGeneration: Number(terminalAdmissionFacts.expectedResumeGeneration || 0),
+        expectedProcessGeneration: Number(terminalAdmissionFacts.expectedProcessGeneration || 0),
+      });
+      if (ws?.readyState === 1) _deps._sendWsJsonBounded(ws,
+        _deps.promptSubmissionContract.buildInputDroppedPayload(msg, `terminal_input_${terminalAdmission.reason}`));
+      return _deps._recordRuntimeInputOutcome(
+        session, msg, 'refused', `terminal_input_${terminalAdmission.reason}`,
+      );
+    }
+    if (session._parking) {
+      if (rawTerminalInput) {
+        if (ws?.readyState === 1) _deps._sendWsJsonBounded(ws,
+          _deps.promptSubmissionContract.buildInputDroppedPayload(msg, 'terminal_input_pty_unavailable'));
+        return _deps._recordRuntimeInputOutcome(session, msg, 'refused', 'terminal_input_pty_unavailable');
+      }
+      _deps._markMeaningfulActivity(session, 'input', Date.now());
+      const inputGeneration = session._parkingInputGeneration
+        || Math.max(1, Number(session._terminalLifecycleCounter || 0) + 1);
+      session._parkingInputGeneration = inputGeneration;
+      session._lifecycleInputInFlight = true;
+      session._parkingInputQueue = _deps.enqueueDeferredInput(
+        session._parkingInputQueue,
+        msg.data,
+        inputGeneration,
+        _runtimeInputMetadataForDeferredMessage(msg),
+      );
+      if (!session._parkingSignalSent) session._parkingAbortRequested = true;
+      return _deps._recordRuntimeInputOutcome(session, msg, 'refused', 'parked');
+    }
+    if (session._restoreDeferred) {
+      return _wakeDeferredOnInput(session, ws, msg);
+    }
+    const resumePolicy = _deps.resumePolicyForAttempt(session._resumeAttemptState);
+    const terminalHandoffReady = terminalAdmission.allowed && rawTerminalInput;
+    if (_deps.INPUT_READY_GATE_ENABLED
+        && !terminalHandoffReady
+        && ['prompt-navigation', 'blocked'].includes(resumePolicy.inputChannel)) {
+      const terminalFirstInput = resumePolicy.inputChannel === 'prompt-navigation'
+        && _deps.terminalFirstPromptInputMatches(
+          session._resumeAttemptState,
+          session._launchPlanGeneration,
+          msg,
+        );
+      const gateChannel = terminalFirstInput ? 'prompt-terminal' : resumePolicy.inputChannel;
+      const channel = resumePolicy.inputChannel === 'prompt-navigation' ? 'prompt-navigation' : 'readiness';
+      const gate = _deps.evaluateResumeGateInput(msg.data, {
+        channel: gateChannel,
+        digits: _deps._resumePromptNavigationDigits(session._resumeAttemptState),
+      });
+      if (gate.droppedMouse > 0) {
+        _deps.recordSessionDiagnostic(session.id, 'input-dropped-mouse', {
+          generation: Number(session._launchPlanGeneration || 0),
+          reports: gate.droppedMouse,
+          chars: String(msg.data || '').length - gate.data.length,
+        });
+      }
+      if (gate.droppedControl > 0) {
+        _deps.recordSessionDiagnostic(session.id, 'input-dropped-control', {
+          generation: Number(session._launchPlanGeneration || 0),
+          sequences: gate.droppedControl,
+        });
+      }
+      if (gate.action === 'drop') {
+        const reason = gate.droppedMouse > 0 ? 'resume_mouse_report' : 'resume_control_sequence';
+        _deps.recordSessionDiagnostic(session.id, 'resume-input-dropped', {
+          chars: String(msg.data || '').length,
+          reason,
+          generation: Number(session._launchPlanGeneration || 0),
+        });
+        if (ws?.readyState === 1) _deps._sendWsJsonBounded(ws,
+          _deps.promptSubmissionContract.buildInputDroppedPayload(msg, reason));
+        return _deps._recordRuntimeInputOutcome(session, msg, 'refused', reason);
+      }
+      if (gate.data !== String(msg.data || '')) msg = { ...msg, data: gate.data, recordText: gate.data };
+      if (gate.action === 'hold') {
+        _deps.recordSessionDiagnostic(session.id, 'terminal-input-refused', {
+          reason: channel,
+          generation: Number(session._launchPlanGeneration || 0),
+          phase: String(session._resumeAttemptState?.phase || ''),
+          chars: gate.data.length,
+        });
+        if (ws?.readyState === 1) _deps._sendWsJsonBounded(ws,
+          _deps.promptSubmissionContract.buildInputDroppedPayload(msg, 'session_resume_not_ready'));
+        return _deps._recordRuntimeInputOutcome(session, msg, 'refused', channel);
+      }
+    }
+    if (!session.ptyProcess) {
+      if (session._resumeAttemptState && _deps.INPUT_READY_GATE_ENABLED) {
+        const gate = _deps.evaluateResumeGateInput(msg.data, { channel: 'blocked' });
+        if (gate.droppedMouse > 0) _deps.recordSessionDiagnostic(session.id, 'input-dropped-mouse', {
+          generation: Number(session._launchPlanGeneration || 0),
+          reports: gate.droppedMouse,
+          chars: String(msg.data || '').length - gate.data.length,
+        });
+        if (!gate.data) {
+          if (ws?.readyState === 1) _deps._sendWsJsonBounded(ws,
+            _deps.promptSubmissionContract.buildInputDroppedPayload(msg, 'resume_mouse_report'));
+          return _deps._recordRuntimeInputOutcome(session, msg, 'refused', 'resume_mouse_report');
+        }
+        if (ws?.readyState === 1) _deps._sendWsJsonBounded(ws,
+          _deps.promptSubmissionContract.buildInputDroppedPayload(msg, 'pty-missing'));
+        return _deps._recordRuntimeInputOutcome(session, msg, 'refused', 'pty-missing');
+      }
+      _deps.recordSessionDiagnostic(session.id, 'input-dropped', {
+        reason: 'pty-missing',
+        chars: String(msg.data || '').length,
+      });
+      if (ws && ws.readyState === 1) {
+        _deps._sendWsJsonBounded(ws, _deps.promptSubmissionContract.buildInputDroppedPayload(msg, 'pty-missing'));
+      }
+      return _deps._recordRuntimeInputOutcome(session, msg, 'refused', 'pty-missing');
+    }
+    // Width arbitration (Phase 3): typing makes THIS client the active device —
+    // hand it the primary role (drive the PTY at its width, get the raw stream) if
+    // the current primary has gone idle, so the device you're using renders
+    // natively. No-op for single-viewer sessions and HTTP-route callers.
+    // Geometry ownership only affects viewport presentation. A failed best-effort handoff must
+    // never invalidate a raw byte already admitted on transport/route/PTY authority.
+    try { _deps._maybeHandoffPrimaryOnInteract(ws, msg.id); } catch {}
+    // Input dedup: macOS IME can cause the browser to send the same keystroke twice
+    // (keydown + composition path). Skip identical input within 10ms.
+    // Keep single printable characters out of dedup entirely: adjacent repeated
+    // letters such as the "ss" in "session" are real input even when browser
+    // scheduling compresses them into the same 10ms window.
+    const now = Date.now();
+    _deps._markMeaningfulActivity(session, 'input', now);
+    const inputData = String(msg.data || '');
+    let durableInputPhase = '';
+    const clientMessageId = _deps.agentSessionKernel.normalizeClientMessageId(msg.clientMessageId);
+    if (clientMessageId) {
+      const durableInputId = `web:${clientMessageId}`;
+      // WP-2 (D-16, S-4): a refused-but-never-queued earlier attempt kept no bytes -- this is a
+      // fresh one (unless it is still sitting in the park queue -- see _resendBlockedByParkQueue).
+      if (existingInput && existingInput.result === 'refused' && !_deps._resendBlockedByParkQueue(session, clientMessageId)) {
+        existingInput = null;
+      }
+      const existingResult = String(existingInput?.result || '');
+      const duplicatePhase = msg.commit === true
+        ? existingResult === 'delivered'
+        : !!existingInput;
+      if (duplicatePhase) {
+        const phase = existingResult === 'delivered'
+          ? 'delivered'
+          : existingResult === 'deferred'
+            ? 'held'
+            : existingResult === 'rejected' || existingResult === 'refused' || existingResult === 'dedup'
+              ? 'refused'
+              : 'accepted';
+        const ack = _deps.agentSessionKernel.recordCanonicalEvent(_deps.dbModule, msg.id, {
+          id: `input:${clientMessageId}:${phase}`, type: `input.${phase}`, role: 'event',
+          data: { clientMessageId, fidelity: msg.fidelity || 'pty', duplicate: true },
+        }, { adapter: _deps._runtimeAdapterForSession(session), agentSessionId: _deps._runtimeAgentSessionIdForSession(session) });
+        if (ack && ws && ws.readyState === 1) _deps._sendWsJsonBounded(ws, {
+          ...ack, type: 'stream-event', eventType: ack.type, ctmSessionId: msg.id,
+          data: { type: ack.type, ...(ack.data || {}), duplicate: true },
+        });
+        return { durableInputPhase: phase };
+      }
+      const runtimeInput = _deps._runtimeInputBaseForSession(msg.id, session, {
+        inputId: durableInputId,
+        source: 'composer', mode: 'inline', action: 'agent-web-input',
+        text: msg.commit === true ? '' : String(msg.recordText !== undefined ? msg.recordText : inputData),
+        attachments: Array.isArray(msg.attachments) ? msg.attachments : [],
+        metadata: { clientMessageId, fidelity: msg.fidelity || 'pty' },
+        appendUserInputEvent: msg.commit !== true,
+      });
+      const phase = msg.commit === true ? 'delivered' : 'accepted';
+      durableInputPhase = phase;
+      if (phase === 'accepted') _deps._recordRuntimeInputAcceptedForSession(msg.id, session, runtimeInput);
+      else _deps._recordRuntimeInputResultForSession(msg.id, session, runtimeInput, 'delivered', 'pty_commit');
+      const ack = _deps.agentSessionKernel.recordCanonicalEvent(_deps.dbModule, msg.id, {
+        id: `input:${clientMessageId}:${phase}`,
+        type: `input.${phase}`,
+        role: 'event',
+        data: { clientMessageId, fidelity: msg.fidelity || 'pty' },
+      }, { adapter: _deps._runtimeAdapterForSession(session), agentSessionId: _deps._runtimeAgentSessionIdForSession(session) });
+      if (ack && ws && ws.readyState === 1) {
+        _deps._sendWsJsonBounded(ws, { ...ack, type: 'stream-event', eventType: ack.type, ctmSessionId: msg.id,
+          data: { type: ack.type, ...(ack.data || {}) } });
+      }
+    }
+    const singlePrintableInput = inputData.length === 1 && inputData >= ' ' && inputData !== '\x7f';
+    if (!singlePrintableInput && !_deps.isPureMouseReportInput(inputData) && msg.data === session._lastInputData && (now - session._lastInputTs) < 10) {
+      // S-16 (WP-3): net-zero at the ceiling -- one diagnostic per session per 10s (sibling
+      // shape: the pty-missing site above pairs recordSessionDiagnostic with
+      // _recordRuntimeInputOutcome too), never per keystroke.
+      if (!session._lastInputDedupDiagAt || now - session._lastInputDedupDiagAt >= 10000) {
+        session._lastInputDedupDiagAt = now;
+        _deps.recordSessionDiagnostic(session.id, 'input-dropped', { reason: 'dedup', chars: inputData.length });
+      }
+      _deps._recordRuntimeInputOutcome(session, msg, 'dedup');
+      return { durableInputPhase };
+    }
+    const prevInputTs = session._lastInputTs || 0;
+    session._lastInputData = msg.data;
+    session._lastInputTs = now;
+    _recordAcceptedInteractiveInputForAnalysis(now);
+    _deps.restoreRuntime.markUserInput(session, now);
+    if (_deps.detectAgentType(session.cmd || '') === 'codex' && _deps._codexComposerBulkInputData(inputData)) {
+      session._codexComposerBulkInputUntil = now + _deps.CODEX_BULK_INPUT_REDRAW_COALESCE_MS;
+      session._codexComposerBulkInputRedrawUntil = now + _deps.CODEX_BULK_INPUT_REDRAW_WINDOW_MS;
+    }
+    _deps._updateCodexComposerInputState(session, msg.data, now);
+    const waitingBeforeInput = _deps._isServerWaitingForInput(msg.id, session);
+    const waitingReasonBeforeInput = _deps._standupWaitingReason(msg.id, session);
+    const promptDismissResetEligible = waitingBeforeInput && !_deps._standupIsBlockingWaitingReason(waitingReasonBeforeInput);
+    const inputEchoText = _deps._terminalInputEchoTextFromInput(inputData).trim();
+    const inputSubmitsPrompt = inputData.includes('\r') || inputData.includes('\n');
+    if (inputSubmitsPrompt || inputData.includes('\x03') || inputData.includes('\x04')) {
+      _deps._clearRestoreInterruption(session, now, inputSubmitsPrompt ? 'terminal-submit' : 'terminal-control');
+    }
+    if (inputSubmitsPrompt) {
+      _deps._markServerSessionTurnOpen(session, now, 'terminal-submit');
+    }
+    if (promptDismissResetEligible && inputEchoText) {
+      session._attentionPendingUserPromptAt = now;
+    }
+    const submittedPromptAfterDismissal = promptDismissResetEligible && inputSubmitsPrompt && (
+      !!inputEchoText ||
+      !!(session._attentionPendingUserPromptAt && (now - session._attentionPendingUserPromptAt) < 10 * 60 * 1000)
+    );
+    const suppression = _deps._prepareRestoreReplaySuppressionForInput(
+      session,
+      msg.id,
+      inputData,
+      {
+        write: _deps.remoteTerminalTarget.guardTargetWrite(
+          options.isTerminalTargetCurrent,
+          data => _deps._writeLifecyclePty(session, data, 'restore-suppressed-input'),
+        ),
+        isTerminalTargetCurrent: options.isTerminalTargetCurrent,
+        isTerminalAttemptCurrent: options.isTerminalAttemptCurrent,
+        metadata: _runtimeInputMetadataForDeferredMessage(msg),
+      },
+    );
+    const suppressionReady = suppression && typeof suppression.then === 'function'
+      ? await suppression
+      : suppression;
+    const postSuppressionRefusal = _deps.remoteTerminalTarget.terminalInputRefusal(options);
+    if (postSuppressionRefusal) return postSuppressionRefusal;
+    if (!suppressionReady) {
+      if (ws?.readyState === 1) {
+        _deps._sendWsJsonBounded(ws,
+          _deps.promptSubmissionContract.buildInputDroppedPayload(msg, 'restore_replay_suppression'));
+      }
+      return _deps._recordRuntimeInputOutcome(session, msg, 'refused', 'restore_replay_suppression');
+    }
+    const resolvesWaiting = _deps._inputMayResolveWaiting(msg.data, session);
+    // User evidence never changes a verdict (D-2); only a submit with echoed text opens a short
+    // probable turn, and an input that answers a wait releases the ledger's wait.
+    _deps._recordStatusEvidence(
+      session,
+      inputSubmitsPrompt
+        ? (inputEchoText ? _deps.STATUS_EVIDENCE.USER_SUBMIT : _deps.STATUS_EVIDENCE.USER_INPUT)
+        : ((inputData === '\x1b' || inputData.includes('\x03')) ? _deps.STATUS_EVIDENCE.USER_INTERRUPT : _deps.STATUS_EVIDENCE.USER_INPUT),
+      Date.now(), // R-11: stamped at record time; `now` predates the suppression await, so a wait raised meanwhile would outlive the keystroke
+      'terminal-input',
+      resolvesWaiting ? { resolvesWait: true } : {},
+    );
+    if (resolvesWaiting) {
+      _deps._clearTerminalInputEchoSuppression(session);
+      session.lastActivity = now;
+      session._waitingForInput = false;
+      session._waitingForInputReason = '';
+      session._waitingForInputMessage = '';
+      session._waitingForInputAt = 0;
+      session._waitFieldsFromHook = false; // N-5
+      session._lastWaitingResolveInputAt = now;
+      session._lastNonResolvingWaitingInputAt = 0;
+      if (submittedPromptAfterDismissal) {
+        _deps._markSessionUserPromptInput(session, now, 'terminal-submit');
+        session._attentionPendingUserPromptAt = 0;
+      }
+      // The user picked a plan option (digit/Esc/Enter) — stop convergence so a
+      // pending re-probe can't re-broadcast the dismissed card.
+      if (typeof session._clearPlanDecisionPending === 'function') session._clearPlanDecisionPending('input-resolved');
+    } else {
+      _deps._markTerminalNonResolvingInputEcho(session, msg.data, now);
+      if (_deps._isServerWaitingForInput(msg.id, session)) {
+        session._lastNonResolvingWaitingInputAt = now;
+      }
+    }
+    const idleState = _deps.idleNotifyState.get(msg.id);
+    if (idleState && resolvesWaiting) {
+      idleState.notified = false;
+      idleState.reason = '';
+      idleState.notifiedAt = 0;
+    }
+    session._inputFrame = (session._inputFrame || 0) + 1;
+    let deferApproveAfterEscalation = false;
+    let deferInterruptSelfAdapt = false;
+
+    // Miss detection: if user manually types "1" or "2" while the approver is in
+    // 'watching' state (not reviewing/cooldown), it MIGHT mean the prompt was missed.
+    // But "1" and "2" appear all the time inside normal typing ("step 1...", "phase 2"),
+    // so we filter out mid-typing bursts. Only log when the keystroke looks SOLO:
+    //   - more than 800ms since the previous keystroke (clean response, not in a flurry)
+    //   - last VTerm snapshot is recent and shows no approval prompt
+    if ((msg.data === '1' || msg.data === '2') && _deps.autoApprovalBuffers.has(msg.id)) {
+      const isSoloKeystroke = (now - prevInputTs) > 800;
+      const buf = _deps.autoApprovalBuffers.get(msg.id);
+      if (isSoloKeystroke && buf && _deps._approverState(buf) === 'watching') {
+        const ring = _deps.approverDebugRings.get(msg.id) || [];
+        const lastSnap = ring[ring.length - 1];
+        if (lastSnap && !lastSnap.hasApproval && (now - lastSnap.ts) < 5000) {
+          console.log(`[shadow-approver:miss] User manually sent "${msg.data}" in session ${msg.id.slice(0, 8)} ` +
+            `— approver didn't detect prompt. Last screen: ${JSON.stringify(lastSnap.debugLines)}`);
+        }
+        // Self-adapt: user manually approved — if we had just escalated this
+        // session, record a positive signal so the maintenance loop / history
+        // scan can promote a narrow auto-approve rule for this class.
+        deferApproveAfterEscalation = true;
+      }
+    }
+
+    // Self-adapt: user interrupted (Ctrl-C) right after we auto-approved via a
+    // learned rule → retire that over-broad rule.
+    if (msg.data === '\x03' && _deps.autoApprovalBuffers.has(msg.id)) {
+      deferInterruptSelfAdapt = true;
+    }
+
+    const selfAdaptActions = [];
+    if (deferApproveAfterEscalation) {
+      selfAdaptActions.push(() => {
+        try {
+          const learned = _deps.approvalSelfAdapt.learnFromApproveAfterEscalation({ sessionId: msg.id, dbModule });
+          if (learned.action === 'rule_created') {
+            console.log(`[shadow-approver:self-adapt] learned auto-approve rule from approve-after-escalation in session ${msg.id.slice(0, 8)} (${learned.label || ''}, risk=${learned.riskLevel})`);
+          } else if (learned.action === 'signal_recorded') {
+            console.log(`[shadow-approver:self-adapt] recorded approve-after-escalation signal for session ${msg.id.slice(0, 8)} (${learned.reason || ''})`);
+          }
+        } catch (e) { console.error('[shadow-approver:self-adapt] approve-signal error:', e.message); }
+      });
+    }
+    if (deferInterruptSelfAdapt) {
+      selfAdaptActions.push(() => {
+        try {
+          const retired = _deps.approvalSelfAdapt.learnFromInterrupt({ sessionId: msg.id, dbModule });
+          if (retired.action === 'disabled') {
+            console.log(`[shadow-approver:self-adapt] retired learned rule ${retired.ruleId} after user interrupt in session ${msg.id.slice(0, 8)} (${retired.label || ''})`);
+          }
+        } catch (e) { console.error('[shadow-approver:self-adapt] interrupt-signal error:', e.message); }
+      });
+    }
+    _deps.runtimeInputPhaseCache.runInputSelfAdaptActions({
+      optimized: _deps.CTM_CLASSIFY_TAIL_BOUND,
+      actions: selfAdaptActions,
+      schedule: setImmediate,
+    });
+
+    // Attribution trail for turn-aborting control bytes (bare ESC / Ctrl-C) —
+    // see lib/turn-abort-key-detect.js. Cheap on every keystroke (two string
+    // equality checks) and only ever records for those two exact payloads,
+    // never for escape-prefixed sequences (arrows, mouse reports, bracketed
+    // paste) and never with the input text itself.
+    try { _deps._recordInputAbortKeyDiagnostic(session, msg.id, ws, inputData, now); } catch {}
+
+    // Only an input that passed every activation/resume/geometry gate may release
+    // the manual-review hold. Clearing it at function entry made a rejected key
+    // look like a provider decision and could strand the still-visible prompt.
+    _deps._clearManualApprovalReview(msg.id, 'terminal input accepted');
+    _deps.approvalAgent.clearSessionDedup(msg.id);
+    _deps._writeInputWithEchoTracking(session, msg.data, 'input', {
+      interactionId: msg.interactionId,
+      interactionStartedAt: msg.interactionStartedAt,
+      serverReceivedAt: Number(msg._typingWsReceivedAt || now),
+      clientId: ws?.clientId || '',
+      socketGeneration: Number(ws?.socketGeneration || 0),
+      agentType: msg.agentType || _deps.detectAgentType(session.cmd || ''),
+    });
+    return { durableInputPhase };
+  }
+  if (ws && ws.readyState === 1) {
+    _deps._sendWsJsonBounded(ws, _deps.promptSubmissionContract.buildInputDroppedPayload(msg, 'session-not-found'));
+  }
+  console.warn(`[input] dropped missing session id=${String(msg?.id || '').slice(0, 8)}`);
+}
+
+module.exports = {
+  configure,
+  _wakeDeferredOnInput,
+  _runtimeInputMetadataForDeferredMessage,
+  _recordAcceptedInteractiveInputForAnalysis,
+  _handleInputPrepared,
+};